MCP To Skill

MCP to SKILL Converter

将 MCP 源码“转译”为可执行的 Claude Code SKILL 包（脚本模式）。

Conversion Contract

• 输入必须是本地项目目录
• 仅做静态分析，不启动 MCP server
• 生成的每个 tool 都是独立脚本（.mjs 或 .py）
• 生成内容至少包括：
  • SKILL.md
  • scripts/
  • references/tools.md

Workflow

1. 运行 scripts/analyze_mcp.py 分析项目元信息（语言、入口点、依赖、候选源码文件）
2. 根据语言路由：
   • TypeScript/JavaScript → scripts/extract_tools_ts.py
   • Python → scripts/extract_tools_py.py
3. 产出统一 IR（工具中间表示）JSON
4. 运行 scripts/generate_skill.py 生成目标 SKILL 目录
5. 输出转换报告（工具数、成功/失败、产物路径）

Required Output Structure

<output_dir>/<skill_name>/
├── SKILL.md
├── scripts/
│   ├── <tool_1>.<ext>
│   ├── <tool_2>.<ext>
│   └── _helpers.<ext>   # 可选
└── references/
    └── tools.md

Rules for Script Mode

• 不依赖运行中的 MCP server
• 输入通过 CLI 参数（或 stdin JSON）传入
• 输出统一为 JSON 到 stdout
• 失败时输出标准错误信息并返回非零退出码

Usage (inside this skill)

Convert a project

python scripts/analyze_mcp.py --project <mcp_project_dir> --out /tmp/mcp_analysis.json
python scripts/extract_tools_ts.py --analysis /tmp/mcp_analysis.json --out /tmp/mcp_ir.json
# or
python scripts/extract_tools_py.py --analysis /tmp/mcp_analysis.json --out /tmp/mcp_ir.json
python scripts/generate_skill.py --ir /tmp/mcp_ir.json --output <output_dir>

Single command mode

python scripts/mcp2skill.py --project <mcp_project_dir> --output <output_dir>

Validation Checklist

• 识别到 MCP 语言（TS/JS 或 Python）
• 至少提取 1 个工具
• 每个工具都有名称、描述、参数定义
• 每个工具都生成可执行脚本
• 生成的 SKILL.md 包含完整工具说明
• 生成的 references/tools.md 包含参数与示例

Failure Handling

如果无法完整提取工具实现：

1. 仍然生成 SKILL 包骨架
2. 对失败工具生成占位脚本并在注释中标记 TODO: manual port required
3. 在 references/tools.md 列出失败原因和原始源码位置