analyze-codebase-for-mcp

pjt222

Aktualisiert Yesterday

2 Ansichten

Entwicklungaiapimcp

Über

Diese Fähigkeit analysiert Codebasen, um Funktionen, APIs und Datenquellen zu identifizieren, die sich für die Bereitstellung als Model Context Protocol (MCP)-Tools eignen, und erstellt strukturierte Spezifikationen. Sie ist nützlich für die Planung von MCP-Servern, die Überprüfung von Code vor der Einbettung für KI-Zugriff oder den Vergleich bestehender Funktionalität mit bereits verfügbaren Tools. Das Tool unterstützt mehrere Programmiersprachen und integriert sich mit scaffold-mcp-server für die Implementierung.

Schnellinstallation

Claude Code

Dokumentation

name: analyze-codebase-for-mcp description: > 分析任意代码库以识别适合作为 MCP 工具暴露的函数、API 和数据源，生成工具规格文档。适用于为现有项目规划 MCP 服务器、在将代码库包装为 AI 可访问工具界面前进行审计、比较代码库的功能与已通过 MCP 暴露的内容，或生成工具规格以交接给 scaffold-mcp-server。 license: MIT allowed-tools: Read Grep Glob Bash metadata: author: Philipp Thoss version: "1.0" domain: mcp-integration complexity: advanced language: multi tags: mcp, analysis, tool-design, codebase locale: zh-CN source_locale: en source_commit: 6f65f316 translator: claude translation_date: "2026-03-17"

分析代码库以用于 MCP

扫描代码库以发现适合作为 MCP 工具暴露的函数、REST 端点、CLI 命令和数据访问模式，然后生成结构化的工具规格文档。

适用场景

为现有项目规划 MCP 服务器，需要了解应暴露哪些内容
在将代码库包装为 AI 可访问工具界面前进行审计
比较代码库的功能与已通过 MCP 暴露的内容
生成工具规格文档以交接给 scaffold-mcp-server
评估第三方库是否值得包装为 MCP 工具

输入

必需：代码库根目录路径
必需：代码库的目标语言（例如 TypeScript、Python、R、Go）
可选：用于对比的现有 MCP 服务器代码（差距分析）
可选：领域焦点（例如"数据分析"、"文件操作"、"API 集成"）
可选：推荐的最大工具数量（默认：20）

步骤

第 1 步：扫描代码库结构

1.1. 使用 Glob 映射目录树，重点关注源目录：

src/**/*.{ts,js,py,R,go,rs} 源文件
**/routes/**、**/api/**、**/controllers/** 端点定义
**/cli/**、**/commands/** CLI 入口点
**/package.json、**/setup.py、**/DESCRIPTION 依赖元数据

1.2. 按角色分类文件：

入口点：主文件、路由处理程序、CLI 命令
核心逻辑：业务逻辑函数、算法、数据转换器
数据访问：数据库查询、文件 I/O、API 客户端
工具函数：辅助函数、格式化器、验证器

1.3. 统计总文件数、代码行数和导出符号以评估项目规模。

预期结果： 带有角色注释的分类文件清单。

失败处理： 如果代码库太大（>10,000 个文件），使用领域焦点输入将扫描范围缩小到特定目录或模块。如果未找到源文件，验证根路径和语言参数。

第 2 步：识别暴露的函数和端点

2.1. 使用 Grep 查找导出函数和公共 API：

TypeScript/JavaScript：export (async )?function、export default、module.exports
Python：不以 _ 开头的函数、@app.route、@router
R：NAMESPACE 中列出的函数或 #' @export roxygen 标签
Go：大写字母开头的函数名（按约定导出）

2.2. 对每个候选函数，提取：

名称：函数或端点名称
签名：带类型和默认值的参数
返回类型：函数的输出
文档：docstring、JSDoc、roxygen、godoc
位置：文件路径和行号

2.3. 对于 REST API，额外提取：

HTTP 方法和路由模式
请求体模式
响应结构
认证要求

2.4. 构建按潜在效用排序的候选列表（公开的、有文档的、类型完整的函数优先）。

预期结果： 包含 20-100 个候选函数/端点及其提取元数据的列表。

失败处理： 如果找到的候选项很少，扩大搜索范围以包含可以公开的内部函数。如果文档稀少，在输出中标记为风险。

第 3 步：评估 MCP 适用性

3.1. 对每个候选项，按 MCP 工具标准评估：

输入契约清晰度：参数是否有良好的类型和文档？能否用 JSON Schema 描述？
输出可预测性：函数是否返回结构化数据（JSON 可序列化）？返回结构是否一致？
副作用：函数是否修改状态（文件、数据库、外部服务）？副作用必须明确标注。
幂等性：操作是否可以安全重试？非幂等工具需要显式警告。
执行时间：是否能在合理超时内完成（< 30 秒）？长时间运行的操作需要异步模式。
错误处理：是否抛出结构化错误还是静默失败？

3.2. 对每个候选项按 1-5 分评分：

5：纯函数，有类型的 I/O，有文档，快速，无副作用
4：类型完整，有文档，轻微副作用（例如日志记录）
3：合理的 I/O 契约但需要包装（例如返回原始对象）
2：显著副作用或不清晰的契约，需要大幅适配
1：不适合，需要重大重构

3.3. 筛选评分 3 及以上的候选项。将评分 2 的项标记为"未来候选"，需要重构。

预期结果： 评分和筛选后的候选列表，每个都附有适用性理由。

失败处理： 如果大多数候选项评分低于 3，代码库可能需要在 MCP 暴露前进行重构。记录差距并推荐具体改进（添加类型、提取纯函数、包装副作用）。

第 4 步：设计工具规格

4.1. 对每个选定的候选项（评分 >= 3），起草工具规格：

- name: tool_name
  description: >
    One-line description of what the tool does.
  source_function: module.function_name
  source_file: src/path/to/file.ts:42
  parameters:
    param_name:
      type: string | number | boolean | object | array
      description: What this parameter controls
      required: true | false
      default: value_if_optional
  returns:
    type: string | object | array
    description: What the tool returns
  side_effects:
    - description of any side effect
  estimated_latency: fast | medium | slow
  suitability_score: 5

4.2. 将工具按逻辑类别分组（例如"数据查询"、"文件操作"、"分析"、"配置"）。

4.3. 识别工具之间的依赖关系（例如"list_datasets"应在"query_dataset"之前调用）。

4.4. 确定是否需要包装器以：

将复杂参数对象简化为扁平输入
将原始返回值转换为结构化文本或 JSON
添加安全保护（例如数据库函数的只读包装器）

预期结果： 完整的 YAML 工具规格，包含类别、依赖关系和包装器说明。

失败处理： 如果工具规格模糊，回到第 2 步从源代码提取更多细节。如果无法推断参数类型，标记需要人工审核。

第 5 步：生成工具规格文档

5.1. 编写包含以下部分的最终规格文档：

摘要：代码库概述、语言、规模和分析日期
推荐工具：第 4 步的完整规格，按类别分组
未来候选：评分 2 的项及重构建议
排除项：评分 1 的项及排除理由
依赖关系：工具依赖图
实施说明：包装器需求、认证需求、传输建议

5.2. 保存为 mcp-tool-spec.yml（机器可读）和可选的 mcp-tool-spec.md（人类可读摘要）。

5.3. 如果提供了现有 MCP 服务器，包含差距分析部分：

规格中存在但尚未实现的工具
已实现但不在规格中的工具（可能过时）
规格漂移的工具（实现偏离规格）

预期结果： 完整的工具规格文档，可供 scaffold-mcp-server 使用。

失败处理： 如果文档超出合理规模（>200 个工具），分成带有交叉引用的模块。如果代码库没有合适的候选项，生成"就绪评估"文档并附带重构建议。

验证清单

常见问题

暴露过多工具：AI 助手在 10-30 个聚焦工具时表现最佳。优先考虑能力广度而非深度。抵制暴露每个公共函数的冲动
忽视副作用：一个"只读"但也写入日志或缓存的函数仍然有副作用。使用 Grep 仔细审计文件写入、网络调用和数据库变更
假设类型安全：动态语言（Python、R、JavaScript）可能有没有类型注解的函数。从使用模式和测试中推断类型，但在规格中标记不确定性
遗漏认证上下文：在已认证 Web 请求中工作的函数在没有会话上下文的 MCP 调用中可能失败。检查隐式认证依赖，如会话 cookie、JWT 令牌或环境注入的凭证
过度工程化包装器：如果函数需要 50 行包装器才能兼容 MCP，它可能不是好的候选项。优先选择自然映射到工具接口的函数
忽视错误路径：MCP 工具必须返回结构化错误。抛出无类型异常的函数需要错误处理包装器
混淆内部和外部 API：被其他内部代码调用的内部辅助函数是较差的 MCP 候选项。聚焦于为外部使用设计的函数或清晰的边界 API
跳过差距分析：如果提供了现有 MCP 服务器，始终将规格与当前实现进行比较。没有差距分析，你可能重复工作或遗漏过时工具

GitHub Repository

pjt222/agent-almanac

Pfad: i18n/zh-CN/skills/analyze-codebase-for-mcp

agentsagentskillsai-assisted-developmentclaude-codeskillsteams