Agent-almanac analyze-codebase-for-mcp

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/analyze-codebase-for-mcp" ~/.claude/skills/pjt222-agent-almanac-analyze-codebase-for-mcp-0d7f32 && rm -rf "$T"

manifest: i18n/zh-CN/skills/analyze-codebase-for-mcp/SKILL.md

source content

分析代码库以用于 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 服务器，始终将规格与当前实现进行比较。没有差距分析，你可能重复工作或遗漏过时工具