---

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 fence_basis_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 个工具），分成带有交叉引用的模块。如果代码库没有合适的候选项，生成"就绪评估"文档并附带重构建议。

验证清单

• 目标代码库中所有源文件已被扫描
• 候选函数已提取名称、签名和返回类型
• 每个候选项有带书面理由的适用性评分
• 工具规格包含带类型的完整参数模式
• 每个工具的副作用已明确记录
• 输出文档是有效的 YAML（任何 YAML 库可解析）
• 工具名称遵循 MCP 约定（snake_case、描述性、唯一）
• 类别和依赖关系形成连贯的工具界面
• 提供现有 MCP 服务器时包含差距分析
• 未来候选部分列出评分 2 项所需的重构步骤

常见问题

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

相关技能

• scaffold-mcp-server — 使用输出规格生成可用的 MCP 服务器
• build-custom-mcp-server — 手动服务器实现参考
• configure-mcp-server — 将生成的服务器连接到 Claude Code/Desktop
• troubleshoot-mcp-connection — 部署服务器后调试连接
• review-software-architecture — 工具界面设计的架构审查
• security-audit-codebase — 在外部暴露函数前进行安全审计