MCP工具的代码执行模式
此目录实现了Anthropic的 代码执行模式 用于MCP工具集成，实现 98%的代币节省 与传统的MCP方法相比。
传统MCP的问题
通过以下方式连接MCP服务器时 .claude/mcp.json，所有工具定义都是预先加载的：
- 顺序思维：~2KB架构
- 勇敢的搜寻：~3KB架构
- 火爬：~4KB架构
结果：每个会话500-1000个令牌开销，即使不使用工具。
解决方案：渐进式披露
与其预先加载所有工具，不如使用代码执行：
- 轻量级注册表 -仅元数据，无代码（registery.json~200字节）
- 按需加载 -仅在需要时导入工具
- 代码生成 -生成调用包装器的TypeScript
- 执行 -通过Claude Code的内置沙盒运行
- 持续技能 -缓存可重用模式
结果：每个会话50-100个令牌开销（减少80-90%）
建筑
.claude/tools/
├── registry.json # Lightweight tool metadata (~200 bytes)
├── wrappers/ # Tool interfaces (loaded on-demand)
│ ├── brave-search-wrapper.ts
│ ├── firecrawl-wrapper.ts
│ └── sequential-thinking-wrapper.ts
├── skills/ # Generated persistent code
│ └── README.md
└── README.md # This file运作原理
传统MCP流程
Request → Load all MCP servers (500-1000 tokens) → Call tool → Response代码执行流程
Request → Query registry.json (50 tokens) → Generate code → Execute → Response
↓
Only load needed tool wrapper (on-demand)用法示例
1.查询可用工具
// Read registry.json (minimal tokens)
const registry = JSON.parse(
await Deno.readTextFile('.claude/tools/registry.json')
);
// Find tool by category
const searchTools = registry.tools.filter(t => t.category === 'search');
// Result: [{ name: 'brave-search', file: 'wrappers/brave-search-wrapper.ts', ... }]代币成本：约50个令牌（注册表很小）
2.生成代码以使用工具
// Generate code that imports and uses the wrapper
import { BraveSearchWrapper } from './.claude/tools/wrappers/brave-search-wrapper.ts';
const search = new BraveSearchWrapper();
const results = await search.webSearch('TypeScript best practices', { count: 5 });
console.log(results.results.map(r => r.title));代币成本：~100个令牌（代码生成）
3.通过克劳德代码沙盒执行
Claude Code在其内置的安全沙箱中运行此代码 mcp__ide__executeCode.
代币总成本：约150个代币 传统MCP成本：约1000个代币 储蓄：减少85%
可用工具
勇敢的搜寻
- 类别：搜索
- 能力：网络搜索、图像搜索、安全搜索过滤
- 用例：研究文档、查找代码示例、API参考资料
- 需要:
BRAVE_API_KEY环境变量
火爬
- 类别：刮擦
- 能力：页面抓取到标记、网站爬行、元数据提取
- 用例：提取文档、分析网站、收集内容
- 需要:
FIRECRAWL_API_KEY环境变量
顺序思维
- 类别：推理
- 能力：分解问题，跟踪依赖关系，分析计划
- 用例：计划实施、调试复杂问题、协调任务
- 需要：无API密钥
持久技能
这 skills/ 目录存储会话期间生成的可重用代码模块。
首次使用：生成代码（约2000个令牌） 后续用途：导入技能（约200个代币） 储蓄：重复任务减少90%
示例技能：
// skills/video-prompt-optimizer.ts
export function optimizeVideoPrompt(scenario: string, settings: any): string {
const keywords = {
rotonde: ['roundabout', 'priority', 'yield'],
kruispunt: ['intersection', 'traffic light'],
zebrapad: ['pedestrian crossing', 'priority'],
};
return keywords[scenario]?.join(', ') || scenario;
}代币储蓄明细
每次会话
| 方法 | 代币成本 | 节省 |
|---|---|---|
| 传统MCP | 500-1000个代币 | - |
| 代码执行 | 50-100个令牌 | 80-90% |
有技能（重复任务）
| 方法 | 首次使用 | 后续 | 共10次使用 |
|---|---|---|---|
| 传统 | 2500代币 | 2500代币 | 25000代币 |
| 代码执行 | 2000个令牌 | 200个令牌 | 3800个令牌 |
| 储蓄 | - | 92% | 85% |
现实世界的影响：10次使用节省21000个令牌=API调用减少8-12个
安全模型
API密钥保护
- 密钥存储在
.env（忽略） - 包装器参考
process.env.API_KEY - 永远不要在包装文件中硬编码密钥
沙箱隔离
- 代码在Claude Code的内置沙盒中执行
- 无法访问父进程内存
- 文件系统访问受控
- 网络访问仅限于包装器API
安全承诺
- 包装器（工具接口，无秘密）
- 技能（生成代码，无秘密）
- 注册表（仅元数据）
- 文档
从不承诺
- API密钥
- 凭证
- 秘密
添加新工具
- 创建包装器 在
wrappers/{tool-name}-wrapper.ts:
export class MyToolWrapper {
constructor() {
// Initialize with env vars
}
async doSomething(input: string): Promise {
// Implementation
}
}- 更新注册表.json:
{
"name": "my-tool",
"category": "category-name",
"description": "What this tool does",
"file": "wrappers/my-tool-wrapper.ts",
"capabilities": ["capability1", "capability2"],
"useCases": ["use case 1", "use case 2"],
"requiresEnv": ["MY_TOOL_API_KEY"]
}- 代码执行测试:
import { MyToolWrapper } from './.claude/tools/wrappers/my-tool-wrapper.ts';
const tool = new MyToolWrapper();
const result = await tool.doSomething('test');环境设置
创建 .env 项目根目录中的文件（已被gitignored）：
# MCP Tool API Keys
BRAVE_API_KEY=your-brave-api-key-here
FIRECRAWL_API_KEY=your-firecrawl-api-key-here运行Claude代码前加载环境：
source .env && claude或添加到 ~/.zshrc / ~/.bashrc:
export BRAVE_API_KEY="your-key"
export FIRECRAWL_API_KEY="your-key"比较：MCP与代码执行
| 方面 | 传统MCP | 代码执行 |
|---|---|---|
| 令牌开销 | 每次会话500-1000 | 每次会话50-100 |
| 加载时间 | 所有工具提前 | 仅按需 |
| 可扩展性 | 带工具数量的Bloats | 无限扩展 |
| 持续技能 | 不支持 | 完全支持 |
| 隐私 | 所有结果都在上下文中 | 本地处理 |
| 复杂性 | 仅配置 | 需要沙盒 |
何时使用每个
在以下情况下使用传统MCP：
- 简单集成（1-2个工具）
- 客户支持场景
- 直接使用工具
- 没有复杂的工作流程
在以下情况下使用代码执行：
- 复杂的代理任务
- API编排
- 自主操作
- 令牌效率至关重要
- 构建技能库
- 多步骤工作流程
参考文献
VidGenTF中的令牌效率
对于此视频生成项目：
- 视频生成请求：每个会话约50次工具交互
- 传统MCP：50×500=25000代币开销
- 代码执行：50×50=2500令牌开销
- 节省：22500个令牌=每次会话减少10-15个API调用
100多代视频：
- 传统：2500000代币开销
- 代码执行：250000个令牌开销
- 总节省：2250000个代币=1000-1500个API调用
每百万输入代币3美元（Sonnet 4.5）：
- 成本节约：每100代6.75美元
- 每年节省（1万个视频）：675美元
贡献
要添加新技能或工具：
- 按照现有模式编写包装器
- 更新
registry.json - 添加JSDoc文档
- 通过代码执行进行测试
- 提交带有示例的PR
许可证
VidGenTF项目的一部分。请参阅根许可证文件。