DeepSource MCP Server

DeepSource MCP 服务

一个 Model Context Protocol（MCP）服务，可与 DeepSource 集成，让 AI 助手访问代码质量指标、问题和分析结果。

目录

• 概览
• 快速开始
• 安装
• 配置
• 可用工具
• 使用示例
• 架构
• 开发
• 故障排除与常见问题
• 参与贡献
• 许可证
• 外部资源

概览

DeepSource MCP 服务通过 Model Context Protocol，让 Claude 等 AI 助手能够使用 DeepSource 的代码质量分析功能。此集成使 AI 助手能够：

• 获取代码指标和分析结果
• 按分析器、路径或标签访问和筛选问题
• 检查质量状态并设置阈值
• 分析项目质量随时间的变化
• 访问安全合规报告（OWASP、SANS、MISRA-C）
• 监控依赖项漏洞
• 管理质量门禁和阈值

快速开始

1. 获取 DeepSource API 密钥

1. 登录你的 DeepSource 账户
2. 前往 Settings → API Access
3. 点击 Generate New Token
4. 复制 API 密钥并妥善保管

2. 在 Claude Desktop 中安装

1. 打开 Claude Desktop
2. 前往 Settings → Developer → Edit Config
3. 将以下配置添加到 mcpServers 部分：

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

4. 重启 Claude Desktop

3. 测试连接

向 Claude 提问：“我可以访问哪些 DeepSource 项目？”

如果配置正确，Claude 将列出你可用的项目。

安装

NPX（推荐）

使用 DeepSource MCP 服务的最简单方法：

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

适用于容器化环境：

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

本地开发

适用于开发或自定义：

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

配置

环境变量

变量	必需	默认值	说明
DEEPSOURCE_API_KEY	是	-	用于身份验证的 DeepSource API 密钥
LOG_FILE	否	-	日志文件路径。若未设置，则不会写入日志
LOG_LEVEL	否	DEBUG	最低日志级别：DEBUG、INFO、WARN、ERROR
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	熔断器尝试恢复前等待的时间（毫秒）

性能注意事项

• 分页：使用合适的页面大小（10-50 项），以平衡响应时间和数据完整性
• 自动重试：服务会通过以下方式实现智能重试逻辑：
  • 使用带抖动的指数退避，避免惊群效应
  • 使用熔断器模式，避免级联故障
  • 使用重试预算，限制资源消耗
  • 遵循 API 返回的 Retry-After 标头
• 速率限制：受速率限制的请求（429）会自动延迟并重试
• 容错：会妥善处理瞬时故障（网络、502、503、504）
• 缓存：结果不会缓存。对于频繁访问的数据，可考虑实现缓存

可用工具

1. projects

列出所有可用的 DeepSource 项目。

参数：无

示例响应：

[
  {
    "key": "https://[email protected]",
    "name": "my-python-project"
  }
]

2. project_issues

获取 DeepSource 项目中的问题，支持筛选和分页。

参数	类型	必需	说明
projectKey	string	是	DeepSource 项目的唯一标识符
first	number	否	返回的项目数（向前分页）
after	string	否	向前分页的游标
last	number	否	返回的项目数（向后分页）
before	string	否	向后分页的游标
path	string	否	按文件路径筛选问题
analyzerIn	string[]	否	按分析器筛选（例如，["python", "javascript"]）
tags	string[]	否	按问题标签筛选

示例响应：

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

列出项目的分析运行，并支持筛选。

参数	类型	必填	描述
projectKey	string	是	DeepSource 项目的唯一标识符
first	number	否	要返回的条目数（正向分页）
after	string	否	正向分页的游标
last	number	否	要返回的条目数（反向分页）
before	string	否	反向分页的游标
analyzerIn	string[]	否	按分析器筛选

4. run

获取特定分析运行的详细信息。

参数	类型	必填	描述
projectKey	string	是	DeepSource 项目的唯一标识符
runIdentifier	string	是	runUid（UUID）或 commitOid（提交哈希）
isCommitOid	boolean	否	runIdentifier 是否为提交哈希（默认：false）

5. recent_run_issues

获取某个分支最近一次分析运行中的问题。

参数	类型	必填	描述
projectKey	string	是	DeepSource 项目的唯一标识符
branchName	string	是	分支名称
first	number	否	要返回的条目数
after	string	否	正向分页的游标

6. dependency_vulnerabilities

获取项目依赖项中的安全漏洞。

参数	类型	必填	描述
projectKey	string	是	DeepSource 项目的唯一标识符
first	number	否	要返回的条目数
after	string	否	正向分页的游标

示例响应：

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

获取代码质量指标，并可选择筛选条件。

参数	类型	必填	描述
projectKey	string	是	DeepSource 项目的唯一标识符
shortcodeIn	string[]	否	按指标代码筛选（见下文）

可用指标：

• LCV - 行覆盖率
• BCV - 分支覆盖率
• DCV - 文档覆盖率
• DDP - 重复代码百分比
• SCV - 语句覆盖率
• TCV - 总覆盖率
• CMP - 代码成熟度

8. update_metric_threshold

更新质量指标的阈值。

参数	类型	必填	描述
projectKey	string	是	DeepSource 项目的唯一标识符
repositoryId	string	是	GraphQL 仓库 ID
metricShortcode	string	是	指标短代码（例如，“LCV”）
metricKey	string	是	语言或上下文键
thresholdValue	number|null	否	新阈值；设为 null 可移除阈值

9. update_metric_setting

更新指标报告和执行设置。

参数	类型	必填	描述
projectKey	string	是	DeepSource 项目的唯一标识符
repositoryId	string	是	GraphQL 仓库 ID
metricShortcode	string	是	指标简码
isReported	boolean	是	是否报告此指标
isThresholdEnforced	boolean	是	是否执行阈值

10. compliance_report

获取安全合规报告。

参数	类型	必填	描述
projectKey	string	是	DeepSource 项目的唯一标识符
reportType	string	是	报告类型（见下文）

可用报告类型：

• OWASP_TOP_10 - Web 应用安全漏洞
• SANS_TOP_25 - 最危险的软件错误
• MISRA_C - 安全关键型 C 代码指南
• CODE_COVERAGE - 代码覆盖率报告
• CODE_HEALTH_TREND - 质量趋势随时间的变化
• ISSUE_DISTRIBUTION - 问题分类
• ISSUES_PREVENTED - 已阻止的问题数量
• ISSUES_AUTOFIXED - 已自动修复的问题数量

使用示例

监控代码质量趋势

跟踪项目质量指标随时间的变化：

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

这会组合使用多个工具来：

1. 获取主分支的近期运行记录
2. 获取每次运行的覆盖率指标
3. 显示趋势

设置质量门禁

为 CI/CD 实施质量门禁：

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

这会：

1. 将行覆盖率阈值更新为 80%
2. 配置阈值执行规则
3. 检查当前的严重安全问题

调查安全漏洞

全面的安全分析：

"Analyze all security vulnerabilities in my project including dependencies"

这会执行：

1. 依赖项漏洞扫描
2. 代码安全问题分析
3. OWASP Top 10 合规性检查
4. 按优先级排序的修复建议

代码审查辅助

获取 AI 驱动的代码审查洞察：

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

这会：

1. 查找该分支上最近的一次运行
2. 筛选严重和高危问题
3. 按文件和问题类型分组
4. 提出修复建议

团队工作效率指标

跟踪团队代码质量指标：

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

这会汇总：

1. 各项目的覆盖率指标
2. 按严重程度统计的问题数量
3. 过去一个月的趋势
4. 团队绩效洞察

架构

DeepSource MCP 服务采用现代 TypeScript 模式，以便于维护并确保类型安全。

核心组件

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

1. MCP 服务集成（src/index.ts）

   • 注册并实现工具处理程序
   • 管理 MCP 协议通信
   • 处理错误和日志记录

2. DeepSource 客户端（src/deepsource.ts）

   • GraphQL API 通信
   • 身份验证和重试逻辑
   • 响应解析和验证

3. 类型系统（src/types/）

   • 用于类型安全的品牌类型
   • 用于状态管理的判别联合类型
   • 用于运行时验证的 Zod 架构

类型安全特性

品牌类型

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

判别联合类型

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

开发

前置条件

• Node.js 22.19.0 或更高版本
• pnpm 10.15.1 或更高版本
• Docker（可选，用于容器构建）

设置

# 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

开发命令

注意：MCP 服务通过 stdio 通信，无法独立运行。请使用 pnpm run inspect 进行交互式调试。

命令	描述
pnpm install	安装依赖
pnpm run build	构建 TypeScript 代码
pnpm run watch	以监视模式构建
pnpm run clean	删除构建产物
pnpm run inspect	使用 MCP Inspector 调试
pnpm test	运行所有测试
pnpm test:watch	以监视模式运行测试
pnpm test:coverage	生成覆盖率报告
pnpm run lint	检查代码规范问题
pnpm run lint:fix	修复代码规范问题
pnpm run format	检查代码格式
pnpm run format:fix	修复代码格式
pnpm run check-types	检查 TypeScript 类型
pnpm run ci	运行完整的 CI 流水线

故障排除与常见问题

常见问题

身份验证错误

Error: Invalid API key or unauthorized access

解决方案：确认你的 DEEPSOURCE_API_KEY 正确无误，并拥有必要的权限。

未找到项目

Error: No projects found

解决方案：确保你的 API 密钥有权访问 DeepSource 中至少一个项目。

超出速率限制

Error: API rate limit exceeded

解决方案：服务端会自动重试。请稍等片刻或降低请求频率。

分页游标无效

Error: Invalid cursor for pagination

解决方案：游标会过期。请从头开始新的分页序列。

常见问题解答

问：我需要哪种 DeepSource 套餐？ 答：此 MCP 服务适用于所有 DeepSource 套餐。安全合规报告等某些功能可能需要特定套餐功能。

问：我可以将它用于可自托管的 DeepSource 吗？ 答：可以，在环境变量中配置 API 端点即可（此功能将在 v1.3.0 中推出）。

问：如何调试问题？ 答：设置 LOG_LEVEL=DEBUG 启用调试日志，并检查 LOG_FILE 指定的日志文件。

问：我的 API 密钥安全吗？ 答：API 密钥仅存储在本地的 Claude Desktop 配置中，除发送到 DeepSource 的 API 外，绝不会传输到其他地方。

问：我可以贡献自定义工具吗？ 答：可以！请参阅贡献部分了解相关指南。

贡献

欢迎贡献！详情请参阅我们的贡献指南。

开发工作流

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 运行测试（pnpm test）
5. 使用约定式提交提交更改（见下文）
6. 将更改推送到分支（git push origin feature/amazing-feature）
7. 创建 Pull Request

提交消息规范

本项目使用 Conventional Commits 确保提交消息格式一致。提交消息会通过 commitlint 验证。

格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型

• feat：新功能
• fix：修复错误
• docs：仅修改文档
• style：不影响代码含义的更改（格式调整等）
• refactor：既不修复错误也不添加功能的代码更改
• perf：性能改进
• test：补充缺失的测试或修正现有测试
• build：影响构建系统或依赖项的更改
• ci：更改 CI 配置文件和脚本
• chore：其他不修改 src 或 test 文件的更改
• revert：撤销之前的提交

示例

# 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"

代码规范

• 遵循 TypeScript 最佳实践
• 将测试覆盖率保持在 80% 以上
• 使用有意义的提交消息
• 为新功能更新文档

许可证

MIT - 详情请参阅 LICENSE 文件。

外部资源

• Model Context Protocol 规范
• DeepSource 文档
• DeepSource API 参考

---

由 DeepSource MCP 服务社区用 ❤️ 打造