Claudecodetools

MCP工具的代码执行模式

此目录实现了Anthropic的 代码执行模式 用于MCP工具集成，实现 98%的代币节省 与传统的MCP方法相比。

传统MCP的问题

通过以下方式连接MCP服务器时 .claude/mcp.json，所有工具定义都是预先加载的：

• 顺序思维：~2KB架构
• 勇敢的搜寻：~3KB架构
• 火爬：~4KB架构

结果：每个会话500-1000个令牌开销，即使不使用工具。

解决方案：渐进式披露

与其预先加载所有工具，不如使用代码执行：

1. 轻量级注册表 -仅元数据，无代码（registery.json~200字节）
2. 按需加载 -仅在需要时导入工具
3. 代码生成 -生成调用包装器的TypeScript
4. 执行 -通过Claude Code的内置沙盒运行
5. 持续技能 -缓存可重用模式

结果：每个会话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;
}

代币储蓄明细

每次会话

有技能（重复任务）

现实世界的影响：10次使用节省21000个令牌=API调用减少8-12个

安全模型

API密钥保护

• 密钥存储在 .env （忽略）
• 包装器参考 process.env.API_KEY
• 永远不要在包装文件中硬编码密钥

沙箱隔离

• 代码在Claude Code的内置沙盒中执行
• 无法访问父进程内存
• 文件系统访问受控
• 网络访问仅限于包装器API

安全承诺

• 包装器（工具接口，无秘密）
• 技能（生成代码，无秘密）
• 注册表（仅元数据）
• 文档

从不承诺

• API密钥
• 凭证
• 秘密

添加新工具

1. 创建包装器 在 wrappers/{tool-name}-wrapper.ts:

export class MyToolWrapper {
  constructor() {
    // Initialize with env vars
  }

  async doSomething(input: string): Promise {
    // Implementation
  }
}

1. 更新注册表.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"]
}

1. 代码执行测试:

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：

• 简单集成（1-2个工具）
• 客户支持场景
• 直接使用工具
• 没有复杂的工作流程

在以下情况下使用代码执行：

• 复杂的代理任务
• API编排
• 自主操作
• 令牌效率至关重要
• 构建技能库
• 多步骤工作流程

参考文献

• 人类工程学博客：使用MCP执行代码
• 模型上下文协议文档
• Claude代码文档

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美元

贡献

要添加新技能或工具：

1. 按照现有模式编写包装器
2. 更新 registry.json
3. 添加JSDoc文档
4. 通过代码执行进行测试
5. 提交带有示例的PR

许可证

VidGenTF项目的一部分。请参阅根许可证文件。