AI导哈

MCP服务封装工具

MCPSkill是一个轻量级Python封装工具，使Claude Code能够通过技能与MCP服务器交互，无需将工具定义加载到上下文中。

  • by jeffjacobsen
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jeffjacobsen/mcpskill

使用说明

MCPSkill - 用于Claude代码技能的直接MCP封装器

一个轻量级的Python封装器，使得Claude Code能够通过技能与MCP（模型上下文协议）服务器进行交互，而无需将工具定义加载到上下文中。

什么是MCPSkill？

MCPSkill在Claude Code的技能系统与MCP服务器之间提供了一个简单的桥梁。它不是将所有MCP工具加载到Claude的上下文（Claude使用的是令牌）中，而是通过一个技能将MCP服务器暴露出来，Claude可以在需要时调用这个技能。

主要优势

  • 零上下文使用MCP 工具定义未加载到 Claude Code 的上下文中
  • 自动激活当相关时，Claude Code 会自动调用该技能
  • 简单配置只需指向一个MCP服务器，无需LLM编排
  • 快速执行直接传递到MCP服务器（无中间LLM）
  • 最小化依赖仅需 mcp， pydantic，以及 pyyaml

建筑

┌─────────────────────────┐
│     Claude Code         │  ← Auto-invokes skill when user mentions MCP
│  (0 tools in context)   │     keywords (filesystem, database, etc.)
└────────┬────────────────┘
         │ Direct Python execution
┌────────▼──────────────────┐
│  orchestrate.py           │  ← Simple CLI wrapper
│  (skill entry point)      │
└────────┬──────────────────┘
         │
┌────────▼──────────────────┐
│  DirectExecutor           │  ← Lists available tools, no LLM
│  (executor.py)            │     orchestration needed
└────────┬──────────────────┘
         │ JSON-RPC via MCP
┌────────▼─────────┐
│ Downstream MCP   │  ← filesystem, database, GitHub, etc.
│    Server        │
└──────────────────┘

何时使用MCPSkill

✅ 在以下情况下使用MCPSkill：

  • 您希望Claude Code能够访问MCP服务器，而无需加载工具模式（或工具架构）
  • MCP服务器拥有简洁且文档齐全的工具
  • 您希望延迟最小，且不产生额外的API费用
  • 您正在使用标准的MCP服务器（文件系统、SQLite等）

❌（表示错误或不正确的意思，具体含义需结合上下文理解） 在以下情况下不要使用MCPSkill：

  • 你需要复杂的多工具协同逻辑
  • 你需要使用中级大型语言模型（LLM）进行推理以选择工具

安装

第一步：安装MCPSkill

cd /path/to/mcpskill
pip install -e .

步骤2：技能已配置完毕

这个技能位于 .claude/skills/mcp-orchestrator/ 在这个存储库中。

用于项目级应用你准备好了！这个技能在这个项目中有效。

适用于全球 （跨所有项目）：

# macOS/Linux
cp -r .claude/skills/mcp-orchestrator ~/.claude/skills/

# Windows
xcopy .claude\skills\mcp-orchestrator %USERPROFILE%\.claude\skills\mcp-orchestrator /E /I

第三步：配置

cd .claude/skills/mcp-orchestrator
cp config.example.yaml config.yaml
# Edit config.yaml for your use case

配置

MCPSkill 使用简单的 YAML 配置文件：

# config.yaml
name: filesystem-assistant
description: "Access filesystem operations via MCP"

downstream:
  command: npx
  args:
    - "-y"
    - "@modelcontextprotocol/server-filesystem"
    - "/Users/username/Documents"
  env: {}  # Optional environment variables for the MCP server

配置示例

文件系统访问

name: filesystem
description: "File and directory operations"

downstream:
  command: npx
  args:
    - "-y"
    - "@modelcontextprotocol/server-filesystem"
    - "/path/to/directory"

SQLite 数据库

name: database
description: "SQLite database queries"

downstream:
  command: npx
  args:
    - "-y"
    - "@modelcontextprotocol/server-sqlite"
    - "/path/to/database.db"

GitHub 集成

name: github
description: "GitHub repository and issue management"

downstream:
  command: npx
  args:
    - "-y"
    - "@modelcontextprotocol/server-github"
  env:
    GITHUB_TOKEN: ${GITHUB_TOKEN}  # Loaded from environment

使用方法

安装后，当您提出相关请求时，Claude Code 将自动激活该技能。

示例：文件系统操作

您的请求：

列出/tmp目录中的所有Python文件

发生的事情：

  1. 克劳德在技能描述中认出了“文件系统”
  2. 克劳德呼唤道： python orchestrate.py config.yaml "List all Python files in /tmp"
  3. MCPSkill 连接到文件系统 MCP 服务器
  4. 返回可用的工具及其描述
  5. 克劳德随后可以直接使用MCP工具

示例：数据库查询

您的请求：

显示过去7天内注册的所有用户

发生的事情：

  1. 技能根据配置激活
  2. MCPSkill 连接到 SQLite MCP 服务器
  3. 返回可用的数据库查询工具
  4. 克劳德执行了相应的查询

手动测试

你可以直接在命令行中测试这个技能：

cd .claude/skills/mcp-orchestrator
python orchestrate.py config.yaml "What can you help me with?"

调试

启用调试日志记录：

export MCPSKILL_LOG_LEVEL=DEBUG

然后检查 stderr 输出以获取详细日志。

常见问题

问题： Error: MCPSkill package not found

解决方案:

cd /path/to/mcpskill
pip install -e .

问题： Cannot connect to downstream server

解决方案：

  1. 直接测试MCP服务器命令
  2. 检查是否已安装 Node.js/npm（对于基于 npx 的服务器）
  3. 验证环境变量是否已设置

问题技能未激活

解决方案:

  1. 检查一下 SKILL.md 存在于 .claude/skills/mcp-orchestrator/
  2. 验证描述中是否提到了相关关键词
  3. 在您的请求中明确提及“MCP”或服务器类型
  4. 重启Claude代码

与MCProxy的比较

MCPSkill是MCProxy的简化版，针对Claude Code技能进行了优化：

特性 MCProxy（完整版） MCPSkill（简化版）
MCP服务器模式 ✅ 是 ❌ 否
中级大型语言模型（Intermediate LLM） ✅ 是（可配置） ❌ 否
克劳德编码技能 ✅ 是 ✅ 是（已优化）
代币使用 最小（上下文中为0） 最小（上下文中为0）
延迟 中等（2跳） 低（1跳）
API成本 中等（双大型语言模型） 低（无额外大型语言模型）
配置 复杂（LLM 设置） 简单（仅 MCP 配置）
用例 复杂的编曲 简单的直接访问

项目结构

mcpskill/
├── src/mcpskill/
│   ├── __init__.py
│   ├── client.py       # MCP client for connecting to servers
│   ├── config.py       # YAML configuration loader
│   ├── types.py        # Pydantic models
│   └── executor.py     # Direct tool execution (no LLM)
│
├── .claude/skills/mcp-orchestrator/
│   ├── SKILL.md               # Skill definition for Claude Code
│   ├── README.md              # Skill-specific documentation
│   ├── config.example.yaml    # Example configuration
│   └── orchestrate.py         # Entry point script
│
├── pyproject.toml      # Package configuration
└── README.md           # This file

发展

运行测试

pip install -e ".[dev]"
pytest

代码质量

# Format code
black src/

# Lint
ruff check src/

# Type checking
mypy src/

做出贡献

这是一个简单的示例项目，旨在帮助您入门。请随意进行分支复制并根据您的需求进行修改！

资源

许可证

麻省理工学院（MIT）

常见问题解答（FAQ）

问：这与直接将MCP服务器加载到Claude Code中有什么不同？

**A.**Claude Code可以直接加载MCP服务器，但这会将所有工具定义都置于上下文中（使用令牌）。MCPSkill则将MCP服务器封装在一个技能中，该技能仅在需要时由Claude自动调用，从而保持您的上下文整洁。

问：我需要API密钥来进行编排吗？

**A.**不！MCPSkill不使用中间的大型语言模型，因此你无需提供下游MCP服务器要求之外的任何API密钥。

问：我可以使用多台MCP服务器吗？

**A.**是的，创建多个配置文件，并复制技能文件夹并使用不同的名称（例如。， mcp-filesystem， mcp-database）。 每个都有自己的配置。

问：如果我需要复杂的编排逻辑怎么办？

**A.**使用完整的MCProxy包，其中包含一个用于智能工具路由的中间大型语言模型（LLM）。MCPSkill经过优化，可实现简单、直接的访问。

相关 MCP