# DeepSource MCP Server

[![CI](https://github.com/sapientpants/deepsource-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/sapientpants/deepsource-mcp-server/actions/workflows/ci.yml)
[![DeepSource](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server.svg/?label=code+coverage&show_trend=true&token=9XrIHVVGs9oZ-6fFSOPah2Ws)](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/)
[![DeepSource](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server.svg/?label=active+issues&show_trend=true&token=9XrIHVVGs9oZ-6fFSOPah2Ws)](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/)
[![DeepSource](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server.svg/?label=resolved+issues&show_trend=true&token=9XrIHVVGs9oZ-6fFSOPah2Ws)](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/)
[![npm version](https://img.shields.io/npm/v/deepsource-mcp-server.svg)](https://www.npmjs.com/package/deepsource-mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/deepsource-mcp-server.svg)](https://www.npmjs.com/package/deepsource-mcp-server)
[![License](https://img.shields.io/npm/l/deepsource-mcp-server.svg)](https://github.com/sapientpants/deepsource-mcp-server/blob/main/LICENSE)

A Model Context Protocol (MCP) server that integrates with DeepSource to provide AI assistants with access to code quality metrics, issues, and analysis results.

## Table of Contents

- [Overview](#overview)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuration](#configuration)
- [Available Tools](#available-tools)
- [Usage Examples](#usage-examples)
- [Architecture](#architecture)
- [Development](#development)
- [Troubleshooting & FAQ](#troubleshooting--faq)
- [Contributing](#contributing)
- [License](#license)
- [External Resources](#external-resources)

## Overview

The DeepSource MCP Server enables AI assistants like Claude to interact with DeepSource's code quality analysis capabilities through the Model Context Protocol. This integration allows AI assistants to:

- Retrieve code metrics and analysis results
- Access and filter issues by analyzer, path, or tags
- Check quality status and set thresholds
- Analyze project quality over time
- Access security compliance reports (OWASP, SANS, MISRA-C)
- Monitor dependency vulnerabilities
- Manage quality gates and thresholds

## Quick Start

### 1. Get Your DeepSource API Key

1. Log in to your [DeepSource account](https://app.deepsource.com)
2. Navigate to **Settings** → **API Access**
3. Click **Generate New Token**
4. Copy your API key and keep it secure

### 2. Install in Claude Desktop

1. Open Claude Desktop
2. Go to **Settings** → **Developer** → **Edit Config**
3. Add this configuration to the `mcpServers` section:

```json
{
  "mcpServers": {
    "deepsource": {
      "command": "npx",
      "args": ["-y", "deepsource-mcp-server@latest"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key"
      }
    }
  }
}
```

4. Restart Claude Desktop

### 3. Test Your Connection

Ask Claude: "What DeepSource projects do I have access to?"

If configured correctly, Claude will list your available projects.

## Installation

### NPX (Recommended)

The simplest way to use the DeepSource MCP Server:

```json
{
  "mcpServers": {
    "deepsource": {
      "command": "npx",
      "args": ["-y", "deepsource-mcp-server@latest"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key",
        "LOG_FILE": "/tmp/deepsource-mcp.log",
        "LOG_LEVEL": "INFO",
        "RETRY_MAX_ATTEMPTS": "3",
        "RETRY_BASE_DELAY_MS": "1000",
        "RETRY_MAX_DELAY_MS": "30000",
        "RETRY_BUDGET_PER_MINUTE": "10",
        "CIRCUIT_BREAKER_THRESHOLD": "5",
        "CIRCUIT_BREAKER_TIMEOUT_MS": "30000"
      }
    }
  }
}
```

### Docker

For containerized environments:

```json
{
  "mcpServers": {
    "deepsource": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DEEPSOURCE_API_KEY",
        "-e",
        "LOG_FILE=/tmp/deepsource-mcp.log",
        "-v",
        "/tmp:/tmp",
        "sapientpants/deepsource-mcp-server"
      ],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key"
      }
    }
  }
}
```

### Local Development

For development or customization:

```json
{
  "mcpServers": {
    "deepsource": {
      "command": "node",
      "args": ["/path/to/deepsource-mcp-server/dist/index.js"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key",
        "LOG_FILE": "/tmp/deepsource-mcp.log",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}
```

## Configuration

### Environment Variables

| Variable                     | Required | Default | Description                                                   |
| ---------------------------- | -------- | ------- | ------------------------------------------------------------- |
| `DEEPSOURCE_API_KEY`         | Yes      | -       | Your DeepSource API key for authentication                    |
| `LOG_FILE`                   | No       | -       | Path to log file. If not set, no logs are written             |
| `LOG_LEVEL`                  | No       | `DEBUG` | Minimum log level: `DEBUG`, `INFO`, `WARN`, `ERROR`           |
| `RETRY_MAX_ATTEMPTS`         | No       | `3`     | Maximum number of retry attempts for failed requests          |
| `RETRY_BASE_DELAY_MS`        | No       | `1000`  | Base delay in milliseconds for exponential backoff            |
| `RETRY_MAX_DELAY_MS`         | No       | `30000` | Maximum delay in milliseconds between retries                 |
| `RETRY_BUDGET_PER_MINUTE`    | No       | `10`    | Maximum retries allowed per minute across all operations      |
| `CIRCUIT_BREAKER_THRESHOLD`  | No       | `5`     | Number of failures before circuit breaker opens               |
| `CIRCUIT_BREAKER_TIMEOUT_MS` | No       | `30000` | Time in milliseconds before circuit breaker attempts recovery |

### Performance Considerations

- **Pagination**: Use appropriate page sizes (10-50 items) to balance response time and data completeness
- **Automatic Retry**: The server implements intelligent retry logic with:
  - Exponential backoff with jitter to prevent thundering herd
  - Circuit breaker pattern to prevent cascade failures
  - Retry budget to limit resource consumption
  - Respect for Retry-After headers from the API
- **Rate Limits**: Rate-limited requests (429) are automatically retried with appropriate delays
- **Fault Tolerance**: Transient failures (network, 502, 503, 504) are handled gracefully
- **Caching**: Results are not cached. Consider implementing caching for frequently accessed data

## Available Tools

### 1. projects

List all available DeepSource projects.

**Parameters**: None

**Example Response**:

```json
[
  {
    "key": "https://api-key@app.deepsource.com",
    "name": "my-python-project"
  }
]
```

### 2. project_issues

Get issues from a DeepSource project with filtering and pagination.

| Parameter    | Type     | Required | Description                                          |
| ------------ | -------- | -------- | ---------------------------------------------------- |
| `projectKey` | string   | Yes      | The unique identifier for the DeepSource project     |
| `first`      | number   | No       | Number of items to return (forward pagination)       |
| `after`      | string   | No       | Cursor for forward pagination                        |
| `last`       | number   | No       | Number of items to return (backward pagination)      |
| `before`     | string   | No       | Cursor for backward pagination                       |
| `path`       | string   | No       | Filter issues by file path                           |
| `analyzerIn` | string[] | No       | Filter by analyzers (e.g., ["python", "javascript"]) |
| `tags`       | string[] | No       | Filter by issue tags                                 |

**Example Response**:

```json
{
  "issues": [
    {
      "id": "T2NjdXJyZW5jZTpnZHlqdnlxZ2E=",
      "title": "Avoid using hardcoded credentials",
      "shortcode": "PY-D100",
      "category": "SECURITY",
      "severity": "CRITICAL",
      "file_path": "src/config.py",
      "line_number": 42
    }
  ],
  "totalCount": 15,
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "YXJyYXljb25uZWN0aW9uOjQ="
  }
}
```

### 3. runs

List analysis runs for a project with filtering.

| Parameter    | Type     | Required | Description                                      |
| ------------ | -------- | -------- | ------------------------------------------------ |
| `projectKey` | string   | Yes      | The unique identifier for the DeepSource project |
| `first`      | number   | No       | Number of items to return (forward pagination)   |
| `after`      | string   | No       | Cursor for forward pagination                    |
| `last`       | number   | No       | Number of items to return (backward pagination)  |
| `before`     | string   | No       | Cursor for backward pagination                   |
| `analyzerIn` | string[] | No       | Filter by analyzers                              |

### 4. run

Get details of a specific analysis run.

| Parameter       | Type    | Required | Description                                             |
| --------------- | ------- | -------- | ------------------------------------------------------- |
| `projectKey`    | string  | Yes      | The unique identifier for the DeepSource project        |
| `runIdentifier` | string  | Yes      | The runUid (UUID) or commitOid (commit hash)            |
| `isCommitOid`   | boolean | No       | Whether runIdentifier is a commit hash (default: false) |

### 5. recent_run_issues

Get issues from the most recent analysis run on a branch.

| Parameter    | Type   | Required | Description                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `projectKey` | string | Yes      | The unique identifier for the DeepSource project |
| `branchName` | string | Yes      | The branch name                                  |
| `first`      | number | No       | Number of items to return                        |
| `after`      | string | No       | Cursor for forward pagination                    |

### 6. dependency_vulnerabilities

Get security vulnerabilities in project dependencies.

| Parameter    | Type   | Required | Description                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `projectKey` | string | Yes      | The unique identifier for the DeepSource project |
| `first`      | number | No       | Number of items to return                        |
| `after`      | string | No       | Cursor for forward pagination                    |

**Example Response**:

```json
{
  "vulnerabilities": [
    {
      "id": "VUL-001",
      "package": "requests",
      "version": "2.25.0",
      "severity": "HIGH",
      "cve": "CVE-2021-12345",
      "description": "Remote code execution vulnerability"
    }
  ],
  "totalCount": 3
}
```

### 7. quality_metrics

Get code quality metrics with optional filtering.

| Parameter     | Type     | Required | Description                                      |
| ------------- | -------- | -------- | ------------------------------------------------ |
| `projectKey`  | string   | Yes      | The unique identifier for the DeepSource project |
| `shortcodeIn` | string[] | No       | Filter by metric codes (see below)               |

**Available Metrics**:

- `LCV` - Line Coverage
- `BCV` - Branch Coverage
- `DCV` - Documentation Coverage
- `DDP` - Duplicate Code Percentage
- `SCV` - Statement Coverage
- `TCV` - Total Coverage
- `CMP` - Code Maturity

### 8. update_metric_threshold

Update the threshold for a quality metric.

| Parameter         | Type         | Required | Description                                      |
| ----------------- | ------------ | -------- | ------------------------------------------------ |
| `projectKey`      | string       | Yes      | The unique identifier for the DeepSource project |
| `repositoryId`    | string       | Yes      | The GraphQL repository ID                        |
| `metricShortcode` | string       | Yes      | The metric shortcode (e.g., "LCV")               |
| `metricKey`       | string       | Yes      | The language or context key                      |
| `thresholdValue`  | number\|null | No       | New threshold value, or null to remove           |

### 9. update_metric_setting

Update metric reporting and enforcement settings.

| Parameter             | Type    | Required | Description                                      |
| --------------------- | ------- | -------- | ------------------------------------------------ |
| `projectKey`          | string  | Yes      | The unique identifier for the DeepSource project |
| `repositoryId`        | string  | Yes      | The GraphQL repository ID                        |
| `metricShortcode`     | string  | Yes      | The metric shortcode                             |
| `isReported`          | boolean | Yes      | Whether to report this metric                    |
| `isThresholdEnforced` | boolean | Yes      | Whether to enforce thresholds                    |

### 10. compliance_report

Get security compliance reports.

| Parameter    | Type   | Required | Description                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `projectKey` | string | Yes      | The unique identifier for the DeepSource project |
| `reportType` | string | Yes      | Type of report (see below)                       |

**Available Report Types**:

- `OWASP_TOP_10` - Web application security vulnerabilities
- `SANS_TOP_25` - Most dangerous software errors
- `MISRA_C` - Guidelines for safety-critical C code
- `CODE_COVERAGE` - Code coverage report
- `CODE_HEALTH_TREND` - Quality trends over time
- `ISSUE_DISTRIBUTION` - Issue categorization
- `ISSUES_PREVENTED` - Prevented issues count
- `ISSUES_AUTOFIXED` - Auto-fixed issues count

## Usage Examples

### Monitor Code Quality Trends

Track your project's quality metrics over time:

```
"Show me the code coverage trend for my main branch"
```

This combines multiple tools to:

1. Get recent runs for the main branch
2. Retrieve coverage metrics for each run
3. Display the trend

### Set Up Quality Gates

Implement quality gates for CI/CD:

```
"Set up quality gates: 80% line coverage, 0 critical security issues"
```

This will:

1. Update the line coverage threshold to 80%
2. Configure enforcement for the threshold
3. Check current critical security issues

### Investigate Security Vulnerabilities

Comprehensive security analysis:

```
"Analyze all security vulnerabilities in my project including dependencies"
```

This performs:

1. Dependency vulnerability scan
2. Code security issue analysis
3. OWASP Top 10 compliance check
4. Prioritized remediation suggestions

### Code Review Assistance

Get AI-powered code review insights:

```
"What are the most critical issues in the recent commits to feature/new-api?"
```

This will:

1. Find the most recent run on the branch
2. Filter for critical and high severity issues
3. Group by file and issue type
4. Suggest fixes

### Team Productivity Metrics

Track team code quality metrics:

```
"Show me code quality metrics across all our Python projects"
```

This aggregates:

1. Coverage metrics per project
2. Issue counts by severity
3. Trends over the last month
4. Team performance insights

## Architecture

The DeepSource MCP Server uses modern TypeScript patterns for maintainability and type safety.

### Key Components

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude/AI      │────▶│   MCP Server     │────▶│  DeepSource API │
│  Assistant      │◀────│  (TypeScript)    │◀────│   (GraphQL)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
```

1. **MCP Server Integration** (`src/index.ts`)
   - Registers and implements tool handlers
   - Manages MCP protocol communication
   - Handles errors and logging

2. **DeepSource Client** (`src/deepsource.ts`)
   - GraphQL API communication
   - Authentication and retry logic
   - Response parsing and validation

3. **Type System** (`src/types/`)
   - Branded types for type safety
   - Discriminated unions for state management
   - Zod schemas for runtime validation

### Type Safety Features

#### Branded Types

```typescript
// Prevent mixing different ID types
type ProjectKey = string & { readonly __brand: 'ProjectKey' };
type RunId = string & { readonly __brand: 'RunId' };
```

#### Discriminated Unions

```typescript
type RunState =
  | { status: 'PENDING'; queuePosition?: number }
  | { status: 'SUCCESS'; finishedAt: string }
  | { status: 'FAILURE'; error?: { message: string } };
```

## Development

### Prerequisites

- Node.js 22.19.0 or higher
- pnpm 10.15.1 or higher
- Docker (optional, for container builds)

### Setup

```bash
# Clone the repository
git clone https://github.com/sapientpants/deepsource-mcp-server.git
cd deepsource-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test
```

### Development Commands

**Note**: MCP servers communicate via stdio and cannot be run standalone. Use `pnpm run inspect` for interactive debugging.

| Command                | Description              |
| ---------------------- | ------------------------ |
| `pnpm install`         | Install dependencies     |
| `pnpm run build`       | Build TypeScript code    |
| `pnpm run watch`       | Build in watch mode      |
| `pnpm run clean`       | Remove build artifacts   |
| `pnpm run inspect`     | Debug with MCP Inspector |
| `pnpm test`            | Run all tests            |
| `pnpm test:watch`      | Run tests in watch mode  |
| `pnpm test:coverage`   | Generate coverage report |
| `pnpm run lint`        | Check for linting issues |
| `pnpm run lint:fix`    | Fix linting issues       |
| `pnpm run format`      | Check code formatting    |
| `pnpm run format:fix`  | Fix code formatting      |
| `pnpm run check-types` | TypeScript type checking |
| `pnpm run ci`          | Run full CI pipeline     |

## Troubleshooting & FAQ

### Common Issues

#### Authentication Error

```
Error: Invalid API key or unauthorized access
```

**Solution**: Verify your `DEEPSOURCE_API_KEY` is correct and has necessary permissions.

#### No Projects Found

```
Error: No projects found
```

**Solution**: Ensure your API key has access to at least one project in DeepSource.

#### Rate Limit Exceeded

```
Error: API rate limit exceeded
```

**Solution**: The server implements automatic retry. Wait a moment or reduce request frequency.

#### Pagination Cursor Invalid

```
Error: Invalid cursor for pagination
```

**Solution**: Cursors expire. Start a new pagination sequence from the beginning.

### FAQ

**Q: Which DeepSource plan do I need?**
A: The MCP server works with all DeepSource plans. Some features like security compliance reports may require specific plan features.

**Q: Can I use this with self-hosted DeepSource?**
A: Yes, configure the API endpoint in your environment variables (feature coming in v1.3.0).

**Q: How do I debug issues?**
A: Enable debug logging by setting `LOG_LEVEL=DEBUG` and check the log file specified in `LOG_FILE`.

**Q: Is my API key secure?**
A: The API key is only stored in your local Claude Desktop configuration and is never transmitted except to DeepSource's API.

**Q: Can I contribute custom tools?**
A: Yes! See the [Contributing](#contributing) section for guidelines.

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Workflow

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`pnpm test`)
5. Commit your changes using conventional commits (see below)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Commit Message Convention

This project uses [Conventional Commits](https://www.conventionalcommits.org/) to ensure consistent commit messages. Commits are validated using commitlint.

#### Format

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

#### Types

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only changes
- `style`: Changes that don't affect code meaning (formatting, etc)
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `perf`: Performance improvements
- `test`: Adding missing tests or correcting existing tests
- `build`: Changes that affect the build system or dependencies
- `ci`: Changes to CI configuration files and scripts
- `chore`: Other changes that don't modify src or test files
- `revert`: Reverts a previous commit

#### Examples

```bash
# Feature
git commit -m "feat: add support for filtering issues by severity"

# Bug fix with scope
git commit -m "fix(api): handle null response from DeepSource API"

# Breaking change
git commit -m "feat!: change API response format

BREAKING CHANGE: Response format now uses camelCase instead of snake_case"
```

### Code Standards

- Follow TypeScript best practices
- Maintain test coverage above 80%
- Use meaningful commit messages
- Update documentation for new features

## License

MIT - see [LICENSE](LICENSE) file for details.

## External Resources

- [Model Context Protocol Specification](https://modelcontextprotocol.io)
- [DeepSource Documentation](https://docs.deepsource.com)
- [DeepSource API Reference](https://docs.deepsource.com/docs/api-reference)

---

Made with ❤️ by the DeepSource MCP Server community