MCX — Модульное выполнение кода (Modular Code Execution)

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

MCP-сервер, позволяющий ИИ-агентам выполнять код вместо прямого вызова инструментов.

Основано на статье 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% за счет фильтрации данных внутри среды выполнения.

Установка

# 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/` сканируются по метаданным при запуске, полностью загружаются при первом использовании
Подсказки доменов	Адаптеры сгруппированы по доменам (платежи, базы данных, email и т.д.) для удобства поиска
Тихая автокоррекция	`executeSql` автоматически исправляется на `execute_sql` (из camelCase в snake_case)
Эффективность контекста	Фильтрация происходит в песочнице, модель видит только результаты
Сохранение переменных	Сохранение результатов как `$invoices`, `$customers` для последующего использования
Автосжатие	Устаревшие переменные (>5 мин, >1 КБ) автоматически сжимаются для экономии контекста
Поиск FTS5	Автоиндексация больших выводов, поиск с параметром `intent`
Интеграция FFF	Fast File Finder — SIMD-ускоренный нечеткий поиск, grep по содержимому
Фоновые задачи	`mcx_spawn` для длительных операций, проверка через `mcx_tasks`
Пакетные операции	`mcx_batch` для нескольких операций в одном вызове
Обработка файлов	`mcx_file` для обработки локальных файлов с инъекцией `$file`
Работа с большими файлами	Файлы >50 КБ остаются в песочнице через `storeAs`, запрос через хелперы
Редактирование файлов	`mcx_edit` (строковый/построчный режимы), `mcx_write` — нет требования «сначала прочитать»
Хелперы запросов к файлам	`around()`, `lines()`, `block()`, `grep()`, `outline()` для сохраненных файлов
Получение URL	`mcx_fetch` с преобразованием HTML в markdown (кэш с TTL 24ч)
Управление потоком	Циклы, условия, повторные попытки выполняются как нативный код
Конфиденциальность	Промежуточные данные остаются в песочнице
Безопасность	Изоляция сети, защита от обхода путей, предотвращение инъекций переменных

Инструменты 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 Management 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)