DeepSource MCP Server

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

Overview
Quick Start
Installation
Configuration
Available Tools
Usage Examples
Architecture
Development
Troubleshooting & FAQ
Contributing
License
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

Log in to your DeepSource account
Navigate to Settings → API Access
Click Generate New Token
Copy your API key and keep it secure

2. Install in Claude Desktop

Open Claude Desktop
Go to Settings → Developer → Edit Config
Add this configuration to the mcpServers section:

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

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:

{
  "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:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "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:

Get recent runs for the main branch
Retrieve coverage metrics for each run
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:

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

Investigate Security Vulnerabilities

Comprehensive security analysis:

"Analyze all security vulnerabilities in my project including dependencies"

This performs:

Dependency vulnerability scan
Code security issue analysis
OWASP Top 10 compliance check
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:

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

Team Productivity Metrics

Track team code quality metrics:

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

This aggregates:

Coverage metrics per project
Issue counts by severity
Trends over the last month
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)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘

MCP Server Integration (src/index.ts)
- Registers and implements tool handlers
- Manages MCP protocol communication
- Handles errors and logging
DeepSource Client (src/deepsource.ts)
- GraphQL API communication
- Authentication and retry logic
- Response parsing and validation
Type System (src/types/)
- Branded types for type safety
- Discriminated unions for state management
- Zod schemas for runtime validation

Type Safety Features

Branded Types

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

Discriminated Unions

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

# 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 section for guidelines.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (pnpm test)
Commit your changes using conventional commits (see below)
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Message Convention

This project uses Conventional Commits 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

# 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 file for details.

External Resources

Made with ❤️ by the DeepSource MCP Server community

DeepSource MCP Server

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

Overview
Quick Start
Installation
Configuration
Available Tools
Usage Examples
Architecture
Development
Troubleshooting & FAQ
Contributing
License
External Resources

Overview

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

Log in to your DeepSource account
Navigate to Settings → API Access
Click Generate New Token
Copy your API key and keep it secure

2. Install in Claude Desktop

Open Claude Desktop
Go to Settings → Developer → Edit Config
Add this configuration to the mcpServers section:

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

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:

{
  "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:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "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:

Get recent runs for the main branch
Retrieve coverage metrics for each run
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:

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

Investigate Security Vulnerabilities

Comprehensive security analysis:

"Analyze all security vulnerabilities in my project including dependencies"

This performs:

Dependency vulnerability scan
Code security issue analysis
OWASP Top 10 compliance check
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:

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

Team Productivity Metrics

Track team code quality metrics:

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

This aggregates:

Coverage metrics per project
Issue counts by severity
Trends over the last month
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)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘

MCP Server Integration (src/index.ts)
- Registers and implements tool handlers
- Manages MCP protocol communication
- Handles errors and logging
DeepSource Client (src/deepsource.ts)
- GraphQL API communication
- Authentication and retry logic
- Response parsing and validation
Type System (src/types/)
- Branded types for type safety
- Discriminated unions for state management
- Zod schemas for runtime validation

Type Safety Features

Branded Types

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

Discriminated Unions

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

# 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 section for guidelines.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (pnpm test)
Commit your changes using conventional commits (see below)
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Message Convention

This project uses Conventional Commits 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

# 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 file for details.

External Resources

Made with ❤️ by the DeepSource MCP Server community

DeepSource MCP Server

DeepSource MCP Server

Table of Contents

Overview

Quick Start

1. Get Your DeepSource API Key

2. Install in Claude Desktop

3. Test Your Connection

Installation

NPX (Recommended)

Docker

Local Development

Configuration

Environment Variables

Performance Considerations

Available Tools

1. projects

2. project_issues

3. runs

4. run

5. recent_run_issues

6. dependency_vulnerabilities

7. quality_metrics

8. update_metric_threshold

9. update_metric_setting

10. compliance_report

Usage Examples

Monitor Code Quality Trends

Set Up Quality Gates

Investigate Security Vulnerabilities

Code Review Assistance

Team Productivity Metrics

Architecture

Key Components

Type Safety Features

Branded Types

Discriminated Unions

Development

Prerequisites

Setup

Development Commands

Troubleshooting & FAQ

Common Issues

Authentication Error

No Projects Found

Rate Limit Exceeded

Pagination Cursor Invalid

FAQ

Contributing

Development Workflow

Commit Message Convention

Format

Types

Examples

Code Standards

License

External Resources

DeepSource MCP Server

Table of Contents

Overview

Quick Start

1. Get Your DeepSource API Key

2. Install in Claude Desktop

3. Test Your Connection

Installation

NPX (Recommended)

Docker

Local Development

Configuration

Environment Variables

Performance Considerations

Available Tools

1. projects

2. project_issues

3. runs

4. run

5. recent_run_issues

6. dependency_vulnerabilities

7. quality_metrics

8. update_metric_threshold