DeepSource MCP 服务器

一个与 DeepSource 集成的模型上下文协议 (MCP) 服务器，为 AI 助手提供代码质量指标、问题和分析结果的访问权限。

目录

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

概述

DeepSource MCP 服务器使像 Claude 这样的 AI 助手能够通过模型上下文协议与 DeepSource 的代码质量分析功能进行交互。此集成允许 AI 助手：

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

快速开始

1. 获取您的 DeepSource API 密钥

1. 登录到您的 DeepSource 账户
2. 导航至 设置 → API 访问
3. 点击 生成新令牌
4. 复制您的 API 密钥并妥善保管

2. 在 Claude Desktop 中安装

1. 打开 Claude Desktop
2. 转到 设置 → 开发者 → 编辑配置
3. 将以下配置添加到 mcpServers 部分：

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

1. 重启 Claude Desktop

3. 测试连接

询问 Claude: "我有哪些可访问的 DeepSource 项目？"

如果配置正确，Claude 将列出您可访问的项目。

安装

NPX（推荐）

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

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

Docker

对于容器化环境：

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"
}
}
}
}### 本地开发

对于开发或自定义：

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

配置

环境变量

性能考虑

• 分页：使用适当的页面大小（10-50 项）以平衡响应时间和数据完整性
• 速率限制：DeepSource API 有速率限制。服务器实现了带有指数退避的自动重试机制
• 缓存：结果不被缓存。对于频繁访问的数据，请考虑实现缓存

可用工具

1. projects

列出所有可用的 DeepSource 项目。

参数：无

示例响应：
json
[
{
"key": "https://api-key@app.deepsource.com",
"name": "my-python-project"
}
]

2. project_issues

从 DeepSource 项目中获取问题，并支持过滤和分页。

示例响应：
json
{
"issues": [{
"id": "T2NjdXJyZW5jZTpnZHlqdnlxZ2E=",
"title": "避免使用硬编码凭据",
"shortcode": "PY-D100",
"category": "SECURITY",
"severity": "CRITICAL",
"file_path": "src/config.py",
"line_number": 42
}],
"totalCount": 15,
"pageInfo": {
"hasNextPage": true,
"endCursor": "YXJyYXljb25uZWN0aW9uOjQ="
}
}

3. runs

列出项目的分析运行记录，并支持过滤。

4. run

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

5. recent_run_issues

获取分支上最近一次分析运行的问题。

6. dependency_vulnerabilities

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

| 参数 | 类型 | 是否必需 | 描述 ||-----------|------|----------|-------------|
| projectKey | string | 是 | DeepSource 项目的唯一标识符 |
| first | number | 否 | 返回的项目数量 |
| after | string | 否 | 用于向前分页的游标 |

示例响应:
json
{
"vulnerabilities": [{
"id": "VUL-001",
"package": "requests",
"version": "2.25.0",
"severity": "HIGH",
"cve": "CVE-2021-12345",
"description": "远程代码执行漏洞"
}],
"totalCount": 3
}

7. quality_metrics

获取代码质量指标，可选过滤。

可用指标:

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

8. update_metric_threshold

更新质量指标的阈值。

9. update_metric_setting

更新指标报告和强制设置。

10. compliance_report

获取安全合规报告。

可用报告类型:

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

使用示例

监控代码质量趋势

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

"显示我的主分支的代码覆盖率趋势"

这将结合多种工具来：

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

设置质量门限

为 CI/CD 实施质量门限：

"设置质量门限：行覆盖率为 80%，无严重安全问题"

这将：

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

调查安全漏洞

全面的安全分析：

"分析我的项目中的所有安全漏洞，包括依赖项"

这将执行：

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

代码审查辅助

获取 AI 支持的代码审查见解：

"feature/new-api 最近提交中最关键的问题是什么？"

这将：

1. 找到该分支上最近的一次运行
2. 过滤出关键和高严重性问题### 按文件和问题类型分组

建议修复

团队生产力指标

跟踪团队代码质量指标：

"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 模式

类型安全特性

品牌类型

typescript
// 防止混合不同的 ID 类型
type ProjectKey = string & { readonly __brand: ProjectKey };
type RunId = string & { readonly __brand: RunId };

区分联合

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

开发

先决条件

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

设置

bash

克隆仓库

git clone https://github.com/sapientpants/deepsource-mcp-server.git
cd deepsource-mcp-server

安装依赖

pnpm install

构建项目

pnpm run build

运行测试

pnpm test

开发命令

故障排除与常见问题解答

常见问题

认证错误

Error: Invalid API key or unauthorized access

解决方案: 确认您的 DEEPSOURCE_API_KEY 正确且具有必要的权限。

未找到项目

Error: No projects found

解决方案: 确保您的 API 密钥至少可以访问 DeepSource 中的一个项目。

超出 API 速率限制

Error: API rate limit exceeded

解决方案: 服务器实现了自动重试。稍等片刻或减少请求频率。

分页游标无效

Error: Invalid cursor for pagination

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

常见问题解答

问：我需要哪种 DeepSource 计划？
答：MCP 服务器适用于所有 DeepSource 计划。某些功能如安全合规报告可能需要特定计划的功能。

问：我可以将其与自托管的 DeepSource 一起使用吗？
答：是的，在环境变量中配置 API 端点（此功能将在 v1.3.0 版本中提供）。

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

**问：我的 API 密钥是否安全？**A: API 密钥仅存储在您的本地 Claude Desktop 配置中，除了传输到 DeepSource 的 API 之外，不会被传输。

Q: 我可以贡献自定义工具吗？
A: 可以！请参阅贡献部分获取指南。

贡献

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

开发工作流程

1. 叉取仓库
2. 创建一个功能分支 (git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试 (pnpm test)
5. 提交更改 (git commit -m "Add amazing feature")
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打开一个拉取请求

代码标准

• 遵循 TypeScript 最佳实践
• 维护测试覆盖率高于 80%
• 使用有意义的提交信息
• 更新新功能的文档

许可证

MIT - 详见 LICENSE 文件。

外部资源

• 模型上下文协议规范
• DeepSource 文档
• DeepSource API 参考

由 DeepSource MCP Server 社区用心制作 ❤️