MCX - Modular Code Execution

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

AIエージェントがツールを直接呼び出す代わりにコードを実行できるようにするMCPサーバー。

Anthropicのコード実行に関する記事に基づいています。

課題

従来のMCPには2つの非効率性があります：

ツール定義の過負荷 - すべてのツール定義を読み込むとコンテキストが溢れる
中間結果の肥大化 - すべての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%削減。

インストール

# 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%節約
`Bash cat/grep/find`	`mcx_file/mcx_grep/mcx_find`	シェルコマンドをMCXにリダイレクト

フックスクリプトについてはフック統合を参照してください。

主な機能

機能	説明
遅延読み込み	`~/.mcx/adapters/` のアダプターは起動時にメタデータのみスキャンされ、初回使用時に完全に読み込まれる
ドメインヒント	アダプターはドメイン（決済、データベース、メールなど）ごとにグループ化され、発見しやすくなっている
サイレント自動修正	`executeSql` は自動的に `execute_sql` に修正される（camelCaseからsnake_caseへ）
コンテキスト効率	フィルタリングはサンドボックス内で行われ、モデルには結果のみが表示される
変数永続化	結果を `$invoices` や `$customers` として保存し、後で使用可能
自動圧縮	古い変数（5分以上経過、1KB以上）はコンテキストを節約するために自動圧縮される
FTS5検索	大規模な出力を自動インデックスし、`intent` パラメータで検索可能
FFF統合	Fast File Finder - SIMD加速によるあいまい検索、コンテンツgrep
バックグラウンドタスク	長時間実行される操作には `mcx_spawn` を使用し、`mcx_tasks` で確認可能
バッチ操作	1回の呼び出しで複数の操作を行う `mcx_batch`
ファイル処理	`$file` インジェクションを使用してローカルファイルを処理する `mcx_file`
大容量ファイル処理	50KBを超えるファイルは `storeAs` を介してサンドボックス内に保持され、ヘルパーでクエリ可能
ファイル編集	`mcx_edit`（文字列/行モード）、`mcx_write` - 「先に読み込む」必要なし
ファイルクエリヘルパー	保存されたファイル用の `around()`, `lines()`, `block()`, `grep()`, `outline()`
URL取得	HTMLからMarkdownへの変換を行う `mcx_fetch`（24時間TTLキャッシュ）
制御フロー	ループ、条件分岐、再試行はネイティブコードとして実行
プライバシー	中間データはサンドボックス内に留まる
セキュリティ	ネットワーク分離、パストラバーサル保護、環境変数インジェクション防止

MCPツール

ツール	説明
`mcx_execute`	アダプターアクセス権付きでコードを実行し、自動的に `$result` として保存
`mcx_search`	3つのモード：仕様探索、FTS5検索、アダプター/メソッド検索
`mcx_batch`	1回の呼び出しで複数の実行/検索を行う（スロットリングを回避）
`mcx_file`	`$file` インジェクションでローカルファイルを処理、または `storeAs` で保存専用モード
`mcx_edit`	ファイルを編集（文字列モードまたは行モード） - ネイティブEditの読み込み要件を回避
`mcx_write`	ファイルを作成/上書き - ネイティブWriteの読み込み要件を回避
`mcx_fetch`	HTMLからMarkdownへの変換と自動インデックス付きでURLを取得（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)