pjt222 分析代码库以用于 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 中列出的函数或
#' @exportroxygen 标签 - 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/Desktoptroubleshoot-mcp-connection— 部署服务器后调试连接review-software-architecture— 工具界面设计的架构审查security-audit-codebase— 在外部暴露函数前进行安全审计