MCX - Modular Code Execution

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

Servidor MCP que permite a los agentes de IA ejecutar código en lugar de llamar directamente a herramientas.

Basado en el artículo de ejecución de código de Anthropic.

El problema

El MCP tradicional tiene dos ineficiencias:

Sobrecarga de definición de herramientas - Cargar todas las definiciones de herramientas inunda el contexto.
Inflación de resultados intermedios - Cada respuesta de la API pasa a través del modelo.

La solución

En lugar de llamar a las herramientas directamente, el agente escribe código que se ejecuta en un entorno aislado (sandbox):

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

Resultado: 98% de reducción de tokens al filtrar datos dentro del entorno de ejecución.

Instalación

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

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

Requiere Bun: MCX utiliza Bun para el tiempo de ejecución. Instala Bun si aún no lo has hecho.

Inicio rápido

# 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

Estructura de directorios

~/.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

Integración con Claude Code

Añádelo a tus ajustes de Claude Code (~/.claude.json o .mcp.json del proyecto):

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

¡Eso es todo! MCX utiliza automáticamente ~/.mcx/ para la configuración y los adaptadores.

Hooks de Claude Code (Opcional)

Redirige las herramientas nativas a las alternativas de MCX para un mejor rendimiento:

~/.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" }] }
    ]
  }
}

Herramienta nativa	Alternativa MCX	Ventaja
`Glob`	`mcx_find`	Clasificación por frecuencia, estado de git, impulso de proximidad
`Grep`	`mcx_grep`	Acelerado por SIMD, búsqueda difusa
`Edit`	`mcx_edit`	Sin requisito de "leer primero", normalización CRLF
`Write`	`mcx_write`	Sin requisito de "leer primero"
`Read` (>50KB)	`mcx_file({ storeAs })`	El archivo permanece en el sandbox, 99% de ahorro de tokens
`Bash cat/grep/find`	`mcx_file/mcx_grep/mcx_find`	Redirige comandos de shell a MCX

Consulta Integración de Hooks para ver los scripts de hooks.

Características clave

Característica	Descripción
Carga diferida	Los adaptadores de `~/.mcx/adapters/` se escanean por metadatos al inicio y se cargan completamente al primer uso
Sugerencias de dominio	Adaptadores agrupados por dominio (pagos, base de datos, correo electrónico, etc.) para una mejor capacidad de descubrimiento
Autocorrección silenciosa	`executeSql` se autocorrige a `execute_sql` (de camelCase a snake_case)
Eficiencia de contexto	El filtrado ocurre en el sandbox, el modelo solo ve los resultados
Persistencia de variables	Almacena resultados como `$invoices`, `$customers` para uso posterior
Autocompresión	Las variables obsoletas (>5min, >1KB) se comprimen automáticamente para ahorrar contexto
Búsqueda FTS5	Indexa automáticamente grandes salidas, busca con el parámetro `intent`
Integración FFF	Fast File Finder - Búsqueda difusa acelerada por SIMD, grep de contenido
Tareas en segundo plano	`mcx_spawn` para operaciones de larga duración, verifica con `mcx_tasks`
Operaciones por lotes	`mcx_batch` para múltiples operaciones en una sola llamada
Procesamiento de archivos	`mcx_file` para procesar archivos locales con inyección de `$file`
Manejo de archivos grandes	Archivos >50KB permanecen en el sandbox mediante `storeAs`, consulta con ayudantes
Edición de archivos	`mcx_edit` (modos cadena/línea), `mcx_write` - sin requisito de "leer primero"
Ayudantes de consulta de archivos	`around()`, `lines()`, `block()`, `grep()`, `outline()` para archivos almacenados
Obtención de URL	`mcx_fetch` con conversión de HTML a markdown (caché TTL de 24h)
Flujo de control	Bucles, condicionales, reintentos ejecutados como código nativo
Privacidad	Los datos intermedios permanecen en el sandbox
Seguridad	Aislamiento de red, protección contra recorrido de rutas, prevención de inyección de env

Herramientas MCP

Herramienta	Descripción
`mcx_execute`	Ejecuta código con acceso a adaptadores, almacena automáticamente como `$result`
`mcx_search`	3 modos: exploración de especificaciones, búsqueda FTS5, búsqueda de adaptador/método
`mcx_batch`	Múltiples ejecuciones/búsquedas en una sola llamada (evita la limitación de velocidad)
`mcx_file`	Procesa archivos locales con inyección de `$file`, o modo solo almacenamiento con `storeAs`
`mcx_edit`	Edita archivos (modo cadena o modo línea) - evita el requisito de lectura de Edit nativo
`mcx_write`	Crea/sobrescribe archivos - evita el requisito de lectura de Write nativo
`mcx_fetch`	Obtiene URLs con conversión de HTML a markdown e indexación automática (caché de 24h)
`mcx_find`	Búsqueda rápida de archivos difusa con clasificación por frecuencia + proximidad
`mcx_grep`	Búsqueda de contenido acelerada por SIMD en archivos
`mcx_related`	Encuentra archivos relacionados mediante análisis de importaciones/exportaciones
`mcx_tree`	Navega por grandes resultados JSON sin cargar el contenido completo
`mcx_spawn`	Ejecuta código en segundo plano, devuelve el ID de tarea inmediatamente
`mcx_tasks`	Lista/verifica tareas en segundo plano y sus resultados
`mcx_list`	Lista los adaptadores y habilidades disponibles
`mcx_stats`	Estadísticas de sesión (contenido indexado, variables, red)
`mcx_doctor`	Ejecuta diagnósticos (Bun, SQLite, adaptadores, sandbox, FFF)
`mcx_upgrade`	Obtiene el comando de autoactualización para la última versión
`mcx_run_skill`	Ejecuta una habilidad registrada

Comandos CLI

Comando	Descripción
`mcx serve`	Inicia el servidor MCP (predeterminado)
`mcx gen`	Genera adaptadores a partir de especificaciones OpenAPI (con TUI)
`mcx init`	Inicializa el directorio global `~/.mcx/`
`mcx update`	Actualiza la CLI y la instalación global
`mcx list`	Lista los adaptadores y habilidades disponibles
`mcx run`	Ejecuta una habilidad directamente
`mcx logs`	Ver registros del servidor

Consulta la documentación de la CLI para más detalles.

Adaptadores incluidos

Adaptador	Métodos	Descripción
`supabase`	24	API de gestión de Supabase (proyectos, tablas, funciones, secretos)
`chrome-devtools`	25	Protocolo Chrome DevTools (capturas de pantalla, navegación, DOM)

Genera tus propios adaptadores a partir de documentos OpenAPI:

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

Ayudantes integrados

Funciones disponibles en el sandbox:

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

Ayudantes de consulta de archivos

Al usar mcx_file({ path, storeAs }) para cargar archivos en el sandbox:

// 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

Documentación

Comandos CLI - Referencia detallada de comandos
Adaptadores - Creación y generación de adaptadores
Habilidades - Operaciones reutilizables
Configuración - Referencia del archivo de configuración
API programática - Uso de MCX en código
Seguridad - Capas de seguridad del sandbox

Desarrollo

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

Licencia

MIT

MCX (Modular Code Execution)