STARWARCLOUD STARWAR.AI
返回市场
MCP代码封装器

MCP代码封装器

作者：paddo2 星标更新：2025-11-10
安装使用来源：spider==github.com

项目介绍

MCP Code Wrapper

License: MIT npm version GitHub issues PRs Welcome

⚠️ 实验性: 该项目正在积极开发中，尚未准备好用于生产环境。API可能会在没有通知的情况下更改。请自行承担风险使用。欢迎贡献和反馈！

将MCP工具定义转换为渐进式发现API（节省上下文96%）

为Model Context Protocol服务器生成自动渐进式工具发现的代码执行包装器。在保持完整的MCP功能的同时，减少上下文使用高达96%。

问题

直接将MCP服务器加载到Claude Code中会用所有工具定义填充上下文：

Chrome DevTools MCP:    17,500 个标记（26个工具）
MSSQL 数据库（×2）:    11,200 个标记（16个工具）
─────────────────────────────────────────────
总计：                  28,700 个标记（占200k上下文的14.5%）

有了3-4个MCP服务器，你在实际工作之前很容易达到50k以上的标记。

解决方案

通过文件系统结构进行渐进式发现

不是一开始就加载所有工具，而是将它们呈现为一个TypeScript API文件系统，Claude可以在需要时探索：

api-universal/
├── index.ts              # 根发现（约100个标记）
├── navigation/           # 6个工具
│   ├── navigate_page.ts  # 需要时才加载
│   └── index.ts
├── debugging/            # 5个工具
└── ...

Claude只读取它需要的内容：

  1. 读取根索引 → 发现类别
  2. 探索类别 → 查看可用工具
  3. 读取特定工具 → 获取文档
  4. 使用API → 通过MCP执行

结果：对于典型的2个工具任务，大约550个标记（与28,700个标记相比）

快速开始

安装

# 通过npx（无需安装）
npx mcp-code-wrapper .                # 当前目录
npx mcp-code-wrapper /path/to/project # 特定项目
npx mcp-code-wrapper --global         # 全局 ~/.claude/ MCPs
npx mcp-code-wrapper --help           # 显示帮助

# 或克隆并本地运行
git clone https://github.com/paddo/mcp-code-wrapper
cd mcp-code-wrapper
pnpm install
pnpm run generate /path/to/project

使用

项目模式（转换项目中的MCPs）：

npx mcp-code-wrapper .                # 当前目录（交互选择）
npx mcp-code-wrapper /path/to/project # 特定目录（交互选择）
npx mcp-code-wrapper . --all          # 生成所有服务器而不提示
npx mcp-code-wrapper . --servers mssql-main,chrome-devtools  # 特定服务器

交互模式（默认）：

  • 显示可用MCP服务器列表
  • 选择要为其生成包装器的服务器
  • 当你只需要特定MCPs时很有用

全部模式（--all标志）：

  • 不提示生成所有MCPs的包装器
  • 对于自动化/脚本很有用

它做了什么：

  1. 在.mcp.json中发现所有MCP服务器
  2. 提示选择服务器（除非使用--all标志）
  3. 在.mcp-wrappers/中生成代码包装器
  4. 为每个MCP创建Claude Code技能
  5. 禁用MCPs（保留执行器的配置）
  6. 更新.gitignore

全局模式（需要显式标志）：

npx mcp-code-wrapper --global

查找~/.claude/mcp.json并在~/.claude/.mcp-wrappers/中生成包装器

生成后

重启Claude Code以加载新技能：

claude -c

⚠️ 重要：当Claude Code重启并提示启用MCPs时，请拒绝/关闭它们。技能使用渐进式发现——MCPs保持禁用状态，并由包装器按需生成。

技能将使用.mcp.json配置按需生成服务器，进行渐进式发现。

验证技能是否已加载

重启后，询问Claude它有哪些技能：

> 你有哪些技能？

我有三个专门的技能：

1. mcp-chrome-devtools - 浏览器自动化和测试
   - 导航页面，填写表单，截屏
   - 检查网络流量，调试JavaScript

2. mcp-mssql-dev - 在'app_dev'数据库上操作
   - 执行SQL查询，读写数据
   - 管理表和模式

3. m- mcp-mssql-prod - 在'app_prod'数据库上操作
   - 相同的SQL能力，生产数据库

标记经济学

现实世界示例

之前（直接MCP）：

  • Chrome DevTools: 26个工具 = 17,500个标记
  • 数据库服务器1: 8个工具 = 5,600个标记
  • 数据库服务器2: 8个工具 = 5,600个标记
  • 总计：28,700个标记（占上下文的14.5%）

之后（渐进式发现）：

  • 根索引：约200个标记
  • 2个工具定义：约350个标记
  • 总计：约550个标记
  • 节省：98%（释放了28,150个标记）

可扩展性

工作流使用的工具直接MCP渐进式节省
简单任务2个工具28,700个标记550个标记98%
中等任务5个工具28,700个标记950个标记97%
复杂任务10个工具28,700个标记1,650个标记94%

即使是复杂的工作流程也能节省90%以上的上下文。

这是如何工作的

1. 将MCPs添加到你的项目

// .mcp.json
{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"],
      "env": {}
    },
    "database-server": {
      "type": "stdio",
      "command": "node",
      "args": [".mcp-server/dist/index.js"],
      "env": {
        "DB_HOST": "your-host",
        "DB_NAME": "your-database",
        "DB_USER": "your-user",
        "DB_PASSWORD": "***"
      }
    }
  }
}

2. 生成包装器

npx mcp-code-wrapper /path/to/project

输出：

🔍 在/path/to/project中发现MCP服务器
✅ 找到.mcp.json

📦 发现2个MCP服务器：
   - chrome-devtools
   - database-server

🔧 正在生成包装器：chrome-devtools
   ✅ 7个类别中有26个工具
🎯 创建Claude Code技能包装器...

🔧 正在生成包装器：database-server
   ✅ 1个类别中有8个工具
🎯 创建Claude Code技能包装器...

✅ 为2个MCP服务器生成包装器
📁 输出：/path/to/project/.mcp-wrappers/

🔕 在.mcp.json中禁用2个MCP服务器
🔕 在settings.local.json中禁用MCPs
   MCPs保留在.mcp.json中供执行器参考
   恢复：npx mcp-code-wrapper --restore

⚠️ 重要：重启Claude Code以加载新技能
   运行：claude -c

3. 生成的结构

/path/to/project/
├── .mcp.json                    # MCPs禁用（就地）
├── .mcp-wrappers/               # 生成的代码包装器
│   ├── chrome-devtools/
│   │   ├── navigation/
│   │   │   ├── navigate_page.ts
│   │   │   ├── take_screenshot.ts
│   │   │   └── index.ts
│   │   ├── debugging/
│   │   └── index.ts
│   └── database-server/
│       ├── queries/
│       │   ├── read_data.ts
│       │   ├── insert_data.ts
│       │   └── index.ts
│       └── index.ts
└── .claude/
    ├── settings.local.json      # MCPs禁用（就地）
    └── skills/                  # 自动生成的技能
        ├── mcp-chrome-devtools/
        │   ├── skill.json
        │   └── instructions.md
        └── mcp-database-server/
            ├── skill.json
            └── instructions.md

4. 渐进式发现的实际应用

当你调用一个技能时：

// Claude读取根索引（100个标记）
import * as db from './.mcp-wrappers/database-server/index.ts';
// 发现：{ queries: {...} }

// 探索类别（50个标记）
import * as queries from './.mcp-wrappers/database-server/queries/index.ts';
// 发现：{ read_data, insert_data, ... }

// 读取特定工具（200个标记）
import { read_data } from './.mcp-wrappers/database-server/queries/read_data.ts';
// 获取完整文档和API

// 使用工具
const result = await read_data({ query: 'SELECT * FROM users' });

总计：350个标记（与加载所有工具的5,600个标记相比）

关键特性

✅ 通用：适用于任何MCP服务器（npm、Python、二进制文件、自定义） ✅ 自动发现：自动找到.mcp.json中的所有MCPs ✅ 技能集成：自动生成Claude Code技能 ✅ 配置保留：禁用MCPs但保留执行器的配置 ✅ 标记高效：节省上下文96%以上 ✅ Git安全：自动更新.gitignore以适应生成的代码 ✅ 不提交秘密：环境变量保留在.mcp.json中（不跟踪） ✅ 自动规范化响应：运行时执行器自动解包MCP响应格式

使用案例

1. 多数据库项目

转换多个数据库MCPs而不会造成上下文膨胀：

# 包含3个数据库连接的项目
npx mcp-code-wrapper /path/to/project

# 之前：3个数据库 × 5.6k个标记 = 16.8k个标记
# 之后：根 + 3个工具 = 约800个标记
# 节省：95%

2. 浏览器自动化

使用Chrome DevTools MCP而不加载所有26个工具：

# 之前：17.5k个标记
# 之后（使用2个工具）：650个标记
# 节省：96%

3. 全局MCP管理

一次性转换所有全局MCPs：

npx mcp-code-wrapper --global

# 技能在所有项目中可用
# 全局禁用MCPs
# 在所有会话中节省上下文

高级用法

恢复原始MCPs

移除所有生成的包装器和技能，重新启用MCPs：

# 恢复当前目录
npx mcp-code-wrapper --restore

# 恢复特定项目
npx mcp-code-wrapper --restore /path/to/project

这将：

  • 移除.mcp-wrappers/目录
  • 移除所有mcp-*技能从.claude/skills/
  • 在.mcp.json中重新启用MCPs（删除"disabled": true）
  • 在.claude/settings.local.json中重新启用MCPs

不创建备份文件 - 在配置中就地操作，以避免意外提交秘密。

保持MCPs启用

默认情况下，生成包装器后会禁用MCPs。要保持它们启用：

npx mcp-code-wrapper /path/to/project --no-disable

这将生成包装器，但保持MCPs在.mcp.json和.claude/settings.local.json中处于活动状态。

无提示生成所有

跳过交互式服务器选择并一次性生成所有：

npx mcp-code-wrapper /path/to/project --all

这对于自动化、CI/CD或始终希望所有MCPs被包装的情况很有用。

生成特定服务器

为特定服务器生成包装器而不提示：

npx mcp-code-wrapper /path/to/project --servers mssql-main,chrome-devtools

这在以下情况下很有用：

  • 仅希望特定MCPs被包装
  • 在脚本中自动化包装器生成
  • 仅重新生成一个服务器而不进行交互式提示

为特定MCP生成

# 传统命令模式（用于测试）
pnpm run generate --from-mcp-json /path/to/.mcp.json --server database-server

带自定义环境生成

DB_HOST=your-host DB_NAME=your-database pnpm run generate node /path/to/mcp-server.js

项目结构

mcp-code-wrapper/
├── src/
│   ├── cli.ts                    # npx入口点
│   ├── generator-universal.ts    # 通用MCP生成器
│   ├── executor.ts               # MCP客户端及代码执行器
│   ├── measure-tokens.ts         # 标记比较工具
│   └── index.ts                  # 示例工作流程
├── USAGE.md                      # 详细的使用指南
├── FINDINGS.md                   # 实验分析
├── CONTEXT.md                    # 项目背景
└── UNIVERSAL_GENERATOR.md        # 技术细节

文档

工作流程对比

无代码包装器

会话开始
└─ 加载所有MCP工具定义（28.7k个标记）
   └─ 使用2个工具
      └─ 浪费26.7k个标记在未使用的工具上

有代码包装器

会话开始
└─ 加载技能（50个标记）
   └─ 读取根索引（100个标记）
      └─ 导航到类别（50个标记）
         └─ 读取2个工具文件（350个标记）
            └─ 使用工具
总计：550个标记（节省98%）

要求

  • Node.js 18+
  • Claude Code（用于技能集成）
  • 包含.mcp.json的项目或全局~/.claude/mcp.json

贡献

欢迎贡献！请参阅CONTRIBUTING.md获取指南。

这是一个实验性项目。请参阅CONTEXT.md了解当前状态和下一步计划。

许可

MIT

相关工作

致谢

基于Anthropic的代码执行模式由@paddo构建。