# Sparrow MCP - Security Code Analysis Server

A Model Context Protocol (MCP) server that automatically analyzes security vulnerabilities in your code and generates secure code alternatives. This server integrates with Cursor IDE to provide real-time security analysis and secure code generation capabilities.

## ✨ Features

- **Source Code Security Analysis (SAST)**: Automatically analyze security vulnerabilities in various programming languages
- **Open-source Dependency Analysis (SCA)**: Identify open-source library vulnerabilities (CVE) and license compliance issues
- **AI-Powered Briefing**: Get easy-to-understand explanations of analysis results
- **Secure Code Generation**: Automatically generate secure code that fixes discovered vulnerabilities
- **Diff Generation**: Visualize differences between original and secure code
- **Real-time Status Monitoring**: Track analysis progress in real-time
- **Multi-file & Archive Analysis**: Analyze multiple files, folders, or ZIP archives at once

## 📦 Installation

### Prerequisites

- Node.js 18+ and npm
- Sparrow OnDemand API key
- (Optional) LLM API key or local Ollama instance for secure code generation

### Install from npm

```bash
npm install -g @sparrowai/sparrow-mcp
```

Or install locally in your project:

```bash
npm install @sparrowai/sparrow-mcp
```

## ⚙️ Configuration

### Sparrow OnDemand API Setup

1. Sign up for Sparrow OnDemand service
2. Obtain your API key from the dashboard
3. Set the `SPARROW_API_KEY` environment variable in your MCP configuration (see below)

## 🔧 Cursor IDE Configuration

Configure the MCP server in Cursor IDE. The server requires environment variables to be set in the MCP configuration:

**Location**: `~/.cursor/mcp.json` (macOS/Linux) or `%APPDATA%\Cursor\mcp.json` (Windows)

### Recommended: Using npx

```json
{
  "mcpServers": {
    "sparrow-mcp": {
      "command": "npx",
      "args": ["-y", "@sparrowai/sparrow-mcp"],
      "env": {
        "SPARROW_API_KEY": "your-ondemand-token",
        "SPARROW_API_URL": "https://ondemand.sparrowcloud.ai",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "gpt-oss:20b"
      }
    }
  }
}
```

### For Local Installation

If you installed the package locally in your project:

```json
{
  "mcpServers": {
    "sparrow-mcp": {
      "command": "node",
      "args": ["./node_modules/@sparrowai/sparrow-mcp/dist/src/server.js"],
      "env": {
        "SPARROW_API_KEY": "your-ondemand-token",
        "SPARROW_API_URL": "https://ondemand.sparrowcloud.ai",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "gpt-oss:20b"
      }
    }
  }
}
```

### For Global Installation

If you installed the package globally with `npm install -g`, use the absolute path. First, find your global installation path:

```bash
npm root -g
```

Then use the full path in your configuration:

**Windows example:**
```json
{
  "mcpServers": {
    "sparrow-mcp": {
      "command": "node",
      "args": ["C:\\Users\\<username>\\AppData\\Roaming\\npm\\node_modules\\@sparrowai\\sparrow-mcp\\dist\\src\\server.js"],
      "env": {
        "SPARROW_API_KEY": "your-ondemand-token",
        "SPARROW_API_URL": "https://ondemand.sparrowcloud.ai",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "gpt-oss:20b"
      }
    }
  }
}
```

**macOS/Linux example:**
```json
{
  "mcpServers": {
    "sparrow-mcp": {
      "command": "node",
      "args": ["/usr/local/lib/node_modules/@sparrowai/sparrow-mcp/dist/src/server.js"],
      "env": {
        "SPARROW_API_KEY": "your-ondemand-token",
        "SPARROW_API_URL": "https://ondemand.sparrowcloud.ai",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "gpt-oss:20b"
      }
    }
  }
}
```

**Note**: 
- If you're using a local development build, replace `./node_modules/@sparrowai/sparrow-mcp/dist/src/server.js` with `dist/src/server.js` and add `"cwd"` pointing to your project root.
- Replace `"OLLAMA_BASE_URL"` with your actual Ollama server URL (e.g., `http://192.168.30.169:11434` for remote servers).
- Replace `"your-ondemand-token"` with your actual Sparrow OnDemand API key.
- For global installation, replace `<username>` in the Windows path with your actual username, or use `npm root -g` to get the exact path.

### Restart Cursor

After updating the MCP configuration:

1. Save the `mcp.json` file
2. Restart Cursor IDE completely
3. The MCP server should connect automatically

### Verify Connection

To verify that the MCP server is connected:

1. Open Cursor IDE
2. Check the MCP server status in the status bar or settings
3. Try using one of the MCP tools (see Usage section below)

## 🚀 Usage

### Available MCP Tools

The server provides 13 MCP tools for SAST, SCA, progress tracking, results fetching, and secure code generation:

#### 1. `analyze_file_sast`
Analyze a single source code file content for security vulnerabilities.
- **Parameters**: `fileContent` (string, required), `fileName` (string, required), `memo` (string, optional)

#### 2. `analyze_files_sast`
Analyze multiple source code files specified by file paths.
- **Parameters**: `filePaths` (array of strings, required), `zipFileName` (string, optional), `memo` (string, optional)

#### 3. `analyze_folder_sast`
Analyze an entire directory for SAST security scanning.
- **Parameters**: `folderPath` (string, required), `zipFileName` (string, optional), `memo` (string, optional)

#### 4. `analyze_zip_sast`
Analyze a ZIP archive containing source code.
- **Parameters**: `zipFilePath` (string, required), `zipFileName` (string, optional), `memo` (string, optional)

#### 5. `analyze_file_sca`
Analyze a single dependency declaration file (e.g., `package.json`, `pom.xml`).
- **Parameters**: `filePath` (string, required), `zipFileName` (string, optional), `memo` (string, optional), `isSbom` (boolean, optional)

#### 6. `analyze_files_sca`
Analyze multiple dependency declaration files at once.
- **Parameters**: `filePaths` (array of strings, required), `zipFileName` (string, optional), `memo` (string, optional), `isSbom` (boolean, optional)

#### 7. `analyze_folder_sca`
Analyze an entire project folder for open-source library vulnerabilities and license issues.
- **Parameters**: `folderPath` (string, required), `zipFileName` (string, optional), `memo` (string, optional), `isSbom` (boolean, optional)

#### 8. `analyze_zip_sca`
Analyze a ZIP archive containing open-source dependencies.
- **Parameters**: `zipFilePath` (string, required), `zipFileName` (string, optional), `memo` (string, optional), `isSbom` (boolean, optional)

#### 9. `track_analysis_progress`
Check analysis progress periodically and report progress notifications.
- **Parameters**: `analysisId` (string, required), `intervalMs` (number, optional, default: 3000)
- **Analysis Stages**: `INIT`, `READY`, `PRE_PROCESS`, `ANALYSIS`, `POST_PROCESS`, `COMPLETE`

#### 10. `get_sast_analysis_results`
Fetch detailed SAST analysis findings, vulnerability list, severity, compliance info, and AI briefing.
- **Parameters**: `analysisId` (string, required)

#### 11. `get_sca_analysis_results`
Fetch detailed SCA analysis findings, component vulnerabilities (CVE), and remediation guidance.
- **Parameters**: `analysisId` (string, required)

#### 12. `download_sbom_files`
Download SBOM files (SPDX, CycloneDX, SWID) generated from completed SCA analysis.
- **Parameters**: `analysisId` (string, required)

#### 13. `generate_secure_code`
Generate security-hardened code, briefing, and diffs based on SAST results.
- **Parameters**: `analysisId` (string, required), `fileContent` (string, required), `fileName` (string, required)

### Typical Workflow

1. **Request Analysis**: Use `analyze_folder_sast` (or `analyze_folder_sca`).
2. **Track Progress**: Monitor analysis progress with `track_analysis_progress`.
3. **Get Results**: Fetch detailed findings with `get_sast_analysis_results` or `get_sca_analysis_results`.
4. **Remediate Code**: Generate secure fixes with `generate_secure_code`.

## 🐛 Troubleshooting

### Common Issues

#### 1. MCP Server Not Connecting

**Symptoms**: The MCP server doesn't appear in Cursor or shows as disconnected.

**Solutions**:
- Verify the `mcp.json` file is in the correct location
- Check that all environment variables are set correctly
- Ensure Node.js is installed and accessible in PATH
- Restart Cursor IDE completely
- Check Cursor's MCP server logs for error messages

#### 2. LLM Connection Issues

**Symptoms**: Secure code generation features fail or report LLM errors.

**Solutions**:
- If using local Ollama: verify Ollama is running (`ollama serve`) and the specified model is downloaded (`ollama list`)
- If using cloud LLM providers (OpenAI, Anthropic, Gemini, AWS Bedrock): verify the respective API key and model environment variables are correctly configured
- Check firewall / network settings

#### 3. Sparrow API Errors

**Symptoms**: Analysis requests fail with API errors.

**Solutions**:
- Verify `SPARROW_API_KEY` is correct and not expired
- Check `SPARROW_API_URL` is correct
- Verify your API key has sufficient permissions
- Check network connectivity to Sparrow API

#### 4. Analysis Timeout

**Symptoms**: Analysis takes too long or times out.

**Solutions**:
- Large files may take longer to analyze
- Check network connectivity
- Verify Sparrow API service status
- Consider analyzing smaller files or folders separately

### Logging

The server logs to both console and log files:

- **Console**: Real-time logs during development
- **Log Files**: 
  - `logs/combined.log`: All logs
  - `logs/error.log`: Error logs only

To enable more detailed logging, add `"LOG_LEVEL": "debug"` to the `"env"` section in your MCP configuration.

## 📝 License

Proprietary (All rights reserved)

## 🔗 Related Links

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Cursor IDE Documentation](https://cursor.sh/docs)
- [Sparrow OnDemand API Documentation](https://ondemand.sparrowcloud.ai/docs)