Mx

CLI + local MCP gateway to centralize MCP server configs and manage Playwright pool sessions.

Quickstart (CLI)

Prereqs:

• Bun (bun --version)

Install + register the MCP gateway (Codex + Claude Desktop + Claude Code if present):

• bun install

• bun run setup

Optional env:

• export MX_REGISTRY_PATH=... (override registry path)

• export MX_SOURCE_DIR=... (central source root for registry.json + skills/)

• export MX_PLAYWRIGHT_POOL=... (comma list, or auto to detect Playwright MCPs, or off to disable pooling)

• export MX_INTERACTIONS_DIR=... (store interactions)

Centralize your existing MCP servers (Codex + Claude Code) behind the single Mx entry:

• Dry run: bun run centralize

• Apply changes: bun run centralize -- --apply

Remove Mx and restore direct servers:

• bun run decentralize

Restart Codex / Claude Desktop after setup so they reload the configs.

Standalone binaries (optional)

• bun run build:gateway:exe

• bun run build:manager:exe

Build output lands in apps/gateway/dist/ as Mx-gateway and Mx.

What's implemented

• CLI to centralize upstream MCP servers into ~/.Mx/registry.json and toggle configs in Codex/Claude.

• Gateway that proxies upstream tools, exposes Playwright pool helpers, and can run Codex/Claude CLIs via shell.

• Gateway also exposes an Interactions-like API backed by Claude CLI (tools, background runs, basic multimodal inputs).

• Skills validation + analysis (CLI + MCP tools) and a skills sync helper from MX_SOURCE_DIR/skills.

• Commands sync support for Claude Code (~/.claude/commands) and Codex (~/.codex/prompts) from MX_SOURCE_DIR/commands.

Refactor notes / roadmap: docs/mx-refactor.md Playwright scaling: docs/playwright-pool-scale.md

LLM stdio bridge (local)

The gateway exposes helpers that run the Codex and Claude CLIs via Bun's shell:

• llm_codex_exec (args: args[], stdin optional)

• llm_claude_exec (args: args[], stdin optional)

Shell smoke test (runs --help/--version, and attempts a "hello world" prompt if detected):

• bun run test:llm-shell

• Optional overrides:

  • MX_CODEX_HELLO_ARGS

  • MX_CODEX_HELLO_STDIN

  • MX_CLAUDE_HELLO_ARGS

  • MX_CLAUDE_HELLO_STDIN

  • MX_LLM_TIMEOUT_MS (default 20000)

Interactions API (Claude-backed)

MCP tools:

• interactions_create (supports previous_interaction_id, background, and stream)

• interactions_get

• interactions_delete

Notes:

• background: true requires store: true and returns status: "in_progress" until complete.

• tools/tool_choice are not supported; the Claude CLI manages tools directly.

• Multimodal inputs accept content parts like { type: "image", data, mime_type }.

Smoke test (creates a session, follows up, background run, reads, deletes):

• bun run test:interactions-claude

  • MX_IMAGE_TEST=1 to include an optional image input check.

Playwright parallelism (local)

If you run multiple Playwright MCP servers as upstreams, the pool auto-detects them (or set an explicit list):

• Set MX_PLAYWRIGHT_POOL=auto (default when unset) or MX_PLAYWRIGHT_POOL=playwright1,playwright2

• Call playwright_pool_reserve or playwright_pool_session_start to get an upstreamId

• Use only that prefix for tool calls (e.g. playwright1__browser_navigate)

Smoke test (runs 2 agents in parallel and asserts distinct slots are held concurrently):

• bun run test:playwright-pool

• MX_PLAYWRIGHT_HEADED=1 bun run test:playwright-pool to see browsers

Note: playwright_pool_session_start creates a new tab by default. Reuse the returned sessionId, or pass a stable sessionKey (and/or newTab: false) to avoid tab spam across restarts. Locks auto-expire after 15 minutes of inactivity by default (TTL is refreshed on slot usage).

Operational helpers:

• playwright_pool_status shows lock/pid status and drift vs the registry playwright_pool generator config.

• playwright_pool_session_end defaults to keeping the tab open when a sessionKey was used (pass closeTab: true and/or forget: true to clean up).

Skills validation (CLI)

• bun run skills validate --target both

• bun run skills analyze --target codex

• bun run skills sync --source-dir ~/.Mx/source

Optional manifest:

• ~/.Mx/source/skills/manifest.json controls which top-level skill directories sync to ~/.codex/skills and ~/.claude/skills.

• Unlisted skills default to enabled (override via defaults or explicit skills.<id> entries).

Installer output:

• Gateway binary at ~/.Mx/bin/Mx-gateway

• Codex config: ~/.codex/config.toml

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

• Claude Code CLI: claude mcp add-json Mx --scope user ... (if available)