MCX - 模块化代码执行 (Modular Code Execution)

███╗   ███╗ ██████╗██╗  ██╗
████╗ ████║██╔════╝╚██╗██╔╝
██╔████╔██║██║      ╚███╔╝
██║╚██╔╝██║██║      ██╔██╗
██║ ╚═╝ ██║╚██████╗██╔╝ ██╗
╚═╝     ╚═╝ ╚═════╝╚═╝  ╚═╝

MCP 服务器，允许 AI 代理执行代码，而不是直接调用工具。

基于 Anthropic 的代码执行文章。

问题

传统的 MCP 有两个效率低下的地方：

工具定义过载 - 加载所有工具定义会淹没上下文
中间结果臃肿 - 每个 API 响应都会经过模型

解决方案

代理不再直接调用工具，而是编写代码并在沙盒中运行：

const invoices = await api.getInvoices({ limit: 100 });
return {
  count: invoices.length,
  total: sum(invoices, 'amount'),
  byStatus: count(invoices, 'status')
};
// Returns ~50 tokens instead of 50,000

结果：通过在执行环境中过滤数据，减少了 98% 的 Token 使用量。

安装

# Install globally with bun
bun add -g @papicandela/mcx-cli

# Initialize global directory (~/.mcx/)
mcx init

需要 Bun： MCX 使用 Bun 作为运行时。如果尚未安装，请安装 Bun。

快速入门

# 1. Initialize global MCX directory
mcx init

# 2. Generate adapters from API docs
mcx gen ./api-docs.md -n myapi

# 3. Add credentials to ~/.mcx/.env

# 4. Start server
mcx serve

目录结构

~/.mcx/
├── adapters/           # Your adapters
│   ├── supabase.ts     # Supabase Management API
│   ├── chrome-devtools.ts  # Chrome DevTools Protocol
│   └── myapi.ts        # Generated from OpenAPI
├── skills/             # Reusable skills
├── mcx.config.ts       # Auto-loads all adapters
├── .env                # API credentials
└── package.json        # Dependencies

# Runtime (created automatically)
~/.mcx/
├── logs/               # Server logs (mcx logs to view)
└── .cache/             # FTS5 search index

Claude Code 集成

添加到您的 Claude Code 设置（~/.claude.json 或项目的 .mcp.json）中：

{
  "mcpServers": {
    "mcx": {
      "command": "mcx",
      "args": ["serve"]
    }
  }
}

就是这样！MCX 会自动使用 ~/.mcx/ 进行配置和适配器管理。

Claude Code 钩子 (可选)

将原生工具重定向到 MCX 替代方案以获得更好的性能：

~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Grep", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Glob", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Edit", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Write", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Read", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-read-check.js" }] },
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-bash-check.js" }] }
    ]
  }
}

原生工具	MCX 替代方案	优势
`Glob`	`mcx_find`	频率排名、git 状态、邻近度提升
`Grep`	`mcx_grep`	SIMD 加速、模糊搜索
`Edit`	`mcx_edit`	无需“先读取”，支持 CRLF 规范化
`Write`	`mcx_write`	无需“先读取”
`Read` (>50KB)	`mcx_file({ storeAs })`	文件保留在沙盒中，节省 99% Token
`Bash cat/grep/find`	`mcx_file/mcx_grep/mcx_find`	将 shell 命令重定向到 MCX

请参阅钩子集成获取钩子脚本。

主要功能

功能	描述
懒加载	`~/.mcx/adapters/` 中的适配器在启动时进行元数据扫描，首次使用时完全加载
领域提示	适配器按领域（支付、数据库、电子邮件等）分组，以便更好地发现
静默自动更正	`executeSql` 自动更正为 `execute_sql` (驼峰命名转下划线命名)
上下文效率	过滤在沙盒中进行，模型仅查看结果
变量持久化	将结果存储为 `$invoices`、`$customers` 以供后续使用
自动压缩	过期变量（>5分钟，>1KB）自动压缩以节省上下文
FTS5 搜索	自动索引大型输出，使用 `intent` 参数进行搜索
FFF 集成	Fast File Finder - SIMD 加速的模糊搜索，内容 grep
后台任务	`mcx_spawn` 用于长时间运行的操作，使用 `mcx_tasks` 检查
批量操作	`mcx_batch` 用于单次调用中的多个操作
文件处理	`mcx_file` 通过 `$file` 注入处理本地文件
大文件处理	>50KB 的文件通过 `storeAs` 保留在沙盒中，使用辅助函数查询
文件编辑	`mcx_edit` (字符串/行模式), `mcx_write` - 无需“先读取”
文件查询辅助	`around()`, `lines()`, `block()`, `grep()`, `outline()` 用于存储的文件
URL 获取	`mcx_fetch` 支持 HTML 转 Markdown (24小时 TTL 缓存)
控制流	循环、条件、重试作为原生代码运行
隐私	中间数据保留在沙盒中
安全	网络隔离、路径遍历保护、环境注入预防

MCP 工具

工具	描述
`mcx_execute`	执行带有适配器访问权限的代码，自动存储为 `$result`
`mcx_search`	3 种模式：规范探索、FTS5 搜索、适配器/方法搜索
`mcx_batch`	单次调用中的多次执行/搜索（绕过限流）
`mcx_file`	通过 `$file` 注入处理本地文件，或使用 `storeAs` 进行仅存储模式
`mcx_edit`	编辑文件（字符串模式或行模式） - 绕过原生 Edit 的读取要求
`mcx_write`	创建/覆盖文件 - 绕过原生 Write 的读取要求
`mcx_fetch`	获取 URL 并进行 HTML 转 Markdown 和自动索引（24小时缓存）
`mcx_find`	快速模糊文件搜索，具有频率 + 邻近度排名
`mcx_grep`	跨文件的 SIMD 加速内容搜索
`mcx_related`	通过导入/导出分析查找相关文件
`mcx_tree`	在不加载全部内容的情况下导航大型 JSON 结果
`mcx_spawn`	在后台运行代码，立即返回任务 ID
`mcx_tasks`	列出/检查后台任务及其结果
`mcx_list`	列出可用的适配器和技能
`mcx_stats`	会话统计信息（索引内容、变量、网络）
`mcx_doctor`	运行诊断（Bun、SQLite、适配器、沙盒、FFF）
`mcx_upgrade`	获取最新版本的自我升级命令
`mcx_run_skill`	运行已注册的技能

CLI 命令

命令	描述
`mcx serve`	启动 MCP 服务器（默认）
`mcx gen`	从 OpenAPI 规范生成适配器（带 TUI）
`mcx init`	初始化全局 `~/.mcx/` 目录
`mcx update`	更新 CLI 和全局安装
`mcx list`	列出可用的适配器和技能
`mcx run`	直接运行技能
`mcx logs`	查看服务器日志

详情请参阅 CLI 文档。

包含的适配器

适配器	方法	描述
`supabase`	24	Supabase 管理 API（项目、表、函数、密钥）
`chrome-devtools`	25	Chrome DevTools 协议（截图、导航、DOM）

从 OpenAPI 文档生成您自己的适配器：

mcx gen ./api-docs.md -n myapi

内置辅助函数

沙盒中可用的函数：

pick(data, ['id', 'name'])     // Extract fields
first(data, 5)                  // First N items
sum(data, 'amount')             // Sum numeric field
count(data, 'status')           // Count by field
table(data, 10)                 // Markdown table

// Async helpers
await poll(fn, { interval: 2000, maxIterations: 5 })  // Poll until done
await waitFor(fn, { timeout: 30000 })                  // Wait for condition

文件查询辅助函数

当使用 mcx_file({ path, storeAs }) 将文件加载到沙盒中时：

// Load file without returning content to context (99% token savings)
mcx_file({ path: "src/large-file.ts", storeAs: "src" })

// Then query with helpers:
around($src, 150, 10)          // 10 lines around line 150
lines($src, 100, 120)          // Get lines 100-120 (1-indexed, inclusive)
block($src, 150)               // Extract code block by indentation
grep($src, "TODO", 3)          // Search with 3 lines context
outline($src)                  // Extract function/class signatures

文档

CLI 命令 - 详细命令参考
适配器 - 创建和生成适配器
技能 - 可重用操作
配置 - 配置文件参考
编程 API - 在代码中使用 MCX
安全 - 沙盒安全层

开发

git clone https://github.com/schizoidcock/mcx
cd mcx
bun install
bun run build

许可证

MIT

MCX (Modular Code Execution)