# Analyze Codebase For MCP

> 分析任意代码库以识别适合作为 MCP 工具暴露的函数、API 和数据源，生成工具规格文档。 适用于为现有项目规划 MCP 服务器、在将代码库包装为 AI 可访问工具界面前进行审计、 比较代码库的功能与已通过 MCP 暴露的内容，或生成工具规格以交接给 scaffold-mcp-server。

- Skill: `pjt222/analyze-codebase-for-mcp-4` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pjt222/analyze-codebase-for-mcp-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/analyze-codebase-for-mcp-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/analyze-codebase-for-mcp-4

---


# 分析代码库以用于 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），起草工具规格：

```yaml
- 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` — 在外部暴露函数前进行安全审计