mcp-to-skill-converter

将任何MCP服务器转换为Claude技能，并节省90%的上下文。

为什么存在这个工具

MCP服务器很棒，但在启动时会将所有工具定义加载到上下文中。对于20多个工具来说，这意味着在Claude开始工作之前，已经有30-50k个令牌被消耗了。

此转换器应用了“渐进式披露”模式（受playwright-skill启发）到任何MCP服务器：

• 启动：约100个令牌（仅元数据）
• 使用时：约5k个令牌（完整指令）
• 执行时：0个令牌（外部运行）

快速入门

# 1. 创建你的MCP配置文件
cat > github-mcp.json << 'EOF'
{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {"GITHUB_TOKEN": "your-token-here"}
}
EOF

# 2. 转换为技能
python mcp_to_skill.py \
  --mcp-config github-m-mp.json \
  --output-dir ./skills/github

# 3. 安装依赖
cd skills/github
pip install mcp

# 4. 复制到Claude
cp -r . ~/.claude/skills/github

完成！Claude现在可以使用最少上下文的GitHub工具了。

功能概述

转换器：

1. 读取你的MCP服务器配置
2. 生成一个技能结构，包括：
   • SKILL.md - 给Claude的指令
   • executor.py - 动态处理MCP调用
   • 配置文件
3. Claude仅加载元数据（约100个令牌）
4. 当需要技能时，加载完整的指令
5. 执行器在外部分离地运行MCP工具

上下文节省

之前（MCP）：

20个工具 = 始终加载30k个令牌
可用上下文：170k / 200k = 85%

之后（技能）：

20个技能 = 2k个令牌元数据
当1个技能激活时：7k个令牌
可用上下文：193k / 200k = 96.5%

实际案例

GitHub MCP服务器（8个工具）：

指标	MCP	技能	节省
空闲	8,000个令牌	100个令牌	98.75%
活跃	8,000个令牌	5,000个令牌	37.5%

兼容性

任何标准MCP服务器：

• ✅ @modelcontextprotocol/server-github
• ✅ @modelcontextprotocol/server-slack
• ✅ @modelcontextprotocol/server-filesystem
• ✅ @modelcontextprotocol/server-postgres
• ✅ 自定义的MCP服务器

使用场景

使用此转换器的情况：

• 你有10个以上的工具
• 上下文空间紧张
• 大多数工具在每次对话中不会被使用
• 工具是独立的

坚持使用MCP的情况：

• 你有1-5个工具
• 需要复杂的OAuth流程
• 需要持久连接
• 跨平台兼容性至关重要

最佳方法：同时使用两者

• 对于核心工具使用MCP
• 对于扩展工具集使用技能

要求

pip install mcp

需要Python 3.8+。

工作原理

┌─────────────────────────────────────┐
│ 你的MCP配置                         │
│ （JSON文件）                         │
└──────────┬──────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│ mcp_to_skill.py                     │
│ - 读取配置                          │
│ - 生成技能结构                      │
└──────────┬──────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│ 生成的技能                         │
│ ├── SKILL.md (100个令牌)           │
│ ├── executor.py (动态调用)         │
│ └── 配置文件                       │
└─────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│ Claude                              │
│ - 仅加载元数据                     │
│ - 需要时加载完整文档              │
│ - 调用执行器进行工具调用          │
└─────────────────────────────────────┘

示例

示例1：GitHub集成

# 创建配置
cat > github.json << 'EOF'
{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {"GITHUB_TOKEN": "ghp_your_token"}
}
EOF

# 转换
python mcp_to_skill.py --mcp-config github.json --output-dir ./skills/github

# 结果：GitHub工具可用，仅需100个令牌，而非8k

示例2：多个服务器

# 转换多个MCP服务器
for config in configs/*.json; do
  name=$(basename "$config" .json)
  python mcp_to_skill.py --mcp-config "$config" --output-dir "./skills/$name"
done

故障排除

"未找到mcp包"

pip install mcp

"MCP服务器无响应"

检查你的配置文件：

• 命令是否正确
• 环境变量是否设置
• 服务器是否可访问

测试生成的技能

cd skills/your-skill

# 列出工具
python executor.py --list

# 描述一个工具
python executor.py --describe tool_name

# 调用一个工具
python executor.py --call '{"tool": "tool_name", "arguments": {...}}'

局限性

• 初期阶段（欢迎反馈）
• 需要mcp Python包
• 一些复杂的认证可能需要调整
• 并非所有MCP服务器都经过测试

贡献

这是一个概念验证。欢迎贡献：

• 使用更多MCP服务器进行测试
• 改善错误处理
• 添加更多示例
• 更好的文档

致谢

灵感来自：

• playwright-skill by @lackeyjb
• Anthropic Skills框架
• Model Context Protocol

许可证

MIT

学习更多

• 详细说明
• Anthropic Skills文档
• MCP规范

---

状态：功能正常但处于初期阶段
反馈：欢迎提交问题和PR
疑问：打开一个问题