README.md•22.2 kB
# DeepSource MCP Server
[](https://github.com/sapientpants/deepsource-mcp-server/actions/workflows/ci.yml)
[](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/)
[](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/)
[](https://app.deepsource.com/gh/sapientpants/deepsource-mcp-server/)
[](https://www.npmjs.com/package/deepsource-mcp-server)
[](https://www.npmjs.com/package/deepsource-mcp-server)
[](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