DeepSource MCP

DeepSource MCP 服务器

    ](https://www.npmjs.com/package/deepsource-mcp-server) ](https://www.npmjs.com/package/deepsource-mcp-server) 

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

目录

• 概述
• 快速入门
• 安装
• 配置
• 可用工具
• 使用示例
• 建筑学
• 发展
• 故障排除与常见问题解答
• 贡献
• 许可证
• 外部资源

概述

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

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

快速入门

获取您的DeepSource API密钥

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

2. 在Claude桌面安装

1. 打开Claude桌面版
2. 首选 设置 → 开发者 → 编辑配置
3. 将此配置添加到 mcpServers 部分/章节：

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

1. 重启Claude桌面版

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（注：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"
      }
    }
  }
}

配置

环境变量

性能考量

• 分页使用适当的页面大小（10-50个项目）来平衡响应时间和数据完整性
• 自动重试服务器实现了带有以下特性的智能重试逻辑：

- 带抖动的指数退避以防止羊群效应 - 断路器模式以防止级联故障 - 重试预算以限制资源消耗 - 尊重API中的Retry-After头部信息

• 速率限制速率受限的请求（429）会自动重试，并伴有适当的延迟
• 容错性瞬时故障（网络故障、502、503、504）得到妥善处理
• 缓存结果未缓存。建议为频繁访问的数据实现缓存功能

可用工具

1. 项目

列出所有可用的 DeepSource 项目。

参数无

示例回复：

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

2. 项目问题

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

示例回复:

{
  "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. 跑步

对带有过滤条件的项目执行列表分析。

4. 跑

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

5. 最近运行的问题

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

6. 依赖项漏洞

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

示例回复：

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

7. 质量指标

获取代码质量指标，并可选择应用过滤条件。

可用指标：

• LCV - 行覆盖率（或行覆盖）
• BCV - 分支覆盖率
• DCV - 文档覆盖率
• DDP - 代码重复率
• SCV - 语句覆盖
• TCV - 全面覆盖
• CMP - 代码成熟度

8. 更新指标阈值

更新质量指标的阈值。

9. 更新指标设置

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

10. 合规报告

获取安全合规报告。

可用的报告类型：

• OWASP_TOP_10 - 网络应用安全漏洞
• 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协议通信 - 处理错误和日志记录

1. DeepSource 客户端 (src/deepsource.ts）

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

1. 类型系统 (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 用于交互式调试。

故障排除与常见问题解答

常见问题

认证错误

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

解决方案光标已过期。从头开始新的分页序列。

常见问题解答（FAQ）

问：我需要哪个DeepSource计划？ A: MCP服务器与所有DeepSource计划兼容。某些功能，如安全合规报告，可能需要特定计划的功能支持。

问：我可以将此与自托管的DeepSource一起使用吗？ A: 是的，请在您的环境变量中配置API端点（此功能将在v1.3.0中推出）。

问：我该如何调试问题？ A: 通过设置启用调试日志记录 LOG_LEVEL=DEBUG 并检查指定的日志文件 LOG_FILE。

问：我的API密钥安全吗？ A：API密钥仅存储在您的本地Claude Desktop配置中，除发送给DeepSource的API外，绝不会进行传输。

问：我可以贡献自定义工具吗？ A: 是的！看这个 做出贡献 指南部分。

做出贡献

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

开发工作流程

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支（git checkout -b feature/amazing-feature）
3. 做出你的更改
4. 运行测试（pnpm test)
5. 使用规范的提交方式（见下文）提交您的更改
6. 推送到分支（git push origin feature/amazing-feature）
7. 提交一个拉取请求

提交信息规范（或：提交消息约定）

这个项目使用 Conventional Commits（规范提交） 以确保提交信息的一致性。提交信息通过commitlint进行验证。

格式

[optional scope]: 

[optional body]

[optional footer(s)]

类型

• feat新功能
• fix修复漏洞
• docs仅文档发生更改
• style不影响代码含义的更改（格式化等）
• refactor代码更改既未修复错误也未添加功能
• perf性能提升
• test补充缺失的测试或修正现有的测试
• build影响构建系统或依赖项的更改
• ciCI配置文件和脚本的更改
• chore其他不修改源代码或测试文件的更改
• 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 - 查看 许可证 文件中有详细信息。

外部资源

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

______________________________________________________________________

由DeepSource MCP服务器社区用心打造