mcpblox

# mcpblox A programmable MCP proxy that takes any existing MCP server and a natural language **transform prompt**, and produces a new MCP server whose tools are reshaped by that prompt. - **Rename** tools, **reformat** outputs, **change schemas** - **Hide** tools you don't need - **Compose** multiple upstream tools into new **synthetic tools** - **Chain** instances via Unix pipes into multi-stage transform pipelines All without modifying the original server. ## Installation ```bash # Run directly with npx npx mcpblox --upstream "your-mcp-server" --prompt "your transform" # Or install globally npm install -g mcpblox ``` ## Quick Start ```bash # 1. Proxy an MCP server unchanged (transparent pass-through) mcpblox --upstream "npx @modelcontextprotocol/server-filesystem /tmp" --api-key $ANTHROPIC_API_KEY # 2. Preview what transforms the LLM would apply (no server started) mcpblox \ --upstream "npx @modelcontextprotocol/server-filesystem /tmp" \ --prompt "Rename read_file to cat and hide write_file" \ --api-key $ANTHROPIC_API_KEY \ --dry-run # 3. Run with transforms applied mcpblox \ --upstream "npx @modelcontextprotocol/server-filesystem /tmp" \ --prompt "Rename read_file to cat and hide write_file" \ --api-key $ANTHROPIC_API_KEY # 4. Point any MCP host at http://localhost:8000/mcp curl http://localhost:8000/health # 5. Chain transforms via Unix pipes mcpblox --upstream "npx @modelcontextprotocol/server-filesystem /tmp" --prompt "Hide write_file" \ | mcpblox --prompt "Rename read_file to cat" \ | mcpblox --prompt "Format outputs as markdown" ``` ## How It Works ``` ┌──────────┐ ┌──────────────────────────────────────────┐ ┌───────────┐ │ │ │ mcpblox │ │ │ │ MCP │◄────►│ ┌────────┐ ┌───────────┐ ┌─────────┐ │◄────►│ Upstream │ │ Host │ HTTP │ │Exposed │ │ Transform │ │Upstream │ │stdio/│ MCP │ │ │ │ │Server │──│ Engine │──│Client │ │ HTTP │ Server │ └──────────┘ │ └────────┘ └─────┬─────┘ └─────────┘ │ └───────────┘ │ │ │ │ ┌─────▼─────┐ │ │ │ LLM │ │ │ │ (startup │ │ │ │ codegen) │ │ │ └───────────┘ │ └──────────────────────────────────────────┘ ``` At startup, mcpblox: 1. Connects to the upstream MCP server and discovers its tools 2. Sends your transform prompt + tool definitions to an LLM 3. The LLM produces a **transform plan** (which tools to modify, hide, pass through, or compose into new `synthetic` tools) 4. For each modified tool, the LLM generates JavaScript transform functions 5. Generated code runs in a sandboxed `vm` context (no filesystem/network access) 6. Results are cached — subsequent startups with the same prompt skip the LLM entirely At runtime, tool calls flow through the transform pipeline: input args are transformed, the upstream tool is called, and the output is transformed before returning to the host. Pass-through tools are proxied directly with no overhead. ## CLI Reference ``` mcpblox [options] Upstream (required unless stdin is a pipe): --upstream <command> Upstream MCP server as stdio command e.g., "npx @modelcontextprotocol/server-filesystem /tmp" --upstream-url <url> Upstream MCP server as HTTP/SSE URL --upstream-token <token> Bearer token for HTTP upstream (env: MCP_UPSTREAM_TOKEN) Transform: --prompt <text> Transform prompt (inline) --prompt-file <path> Transform prompt from file LLM: --provider <name> LLM provider: anthropic | openai (default: anthropic) --model <id> LLM model ID (default: claude-sonnet-4-20250514 / gpt-4o) --api-key <key> LLM API key (env: ANTHROPIC_API_KEY | OPENAI_API_KEY) Server: --port <number> HTTP server port (default: 8000, or 0 for OS-assigned when piped) Cache: --cache-dir <path> Cache directory (default: .mcpblox-cache) --no-cache Disable caching, regenerate on every startup Other: --dry-run Show the transform plan as JSON without starting the server --verbose Verbose logging (generated code, cache keys, tool call details) ``` Without `--prompt`, mcpblox runs as a transparent proxy — all tools pass through unchanged. ## Examples **Rename and restructure tools:** ```bash mcpblox \ --upstream "npx @mcp/server-github" \ --prompt "Rename search_repositories to find_repos. For list_issues, add a max_results parameter (default 10) that truncates the output." ``` **Format outputs:** ```bash mcpblox \ --upstream "uvx mcp-server-yfinance" \ --prompt "Format all numeric values in tool outputs with thousand separators and 2 decimal places. Prefix currency values with $." ``` **Hide tools you don't need:** ```bash mcpblox \ --upstream "npx @modelcontextprotocol/server-filesystem /tmp" \ --prompt "Hide write_file, create_directory, and move_file. Only expose read-only tools." ``` **Synthetic tools (compose upstream tools into new ones):** ```bash mcpblox \ --upstream "uvx yfinance-mcp" \ --prompt-file period-returns.txt \ --port 18500 ``` The prompt creates a `get_period_returns` tool that calls `yfinance_get_price_history` four times (for 1-month, 3-month, 6-month, and 12-month periods), parses the results, and returns calculated returns for a given stock ticker — all orchestrated in a single tool call. **Connect to an HTTP/SSE upstream instead of stdio:** ```bash # Proxy an already-running MCP server over HTTP mcpblox --upstream-url http://localhost:3000/mcp --api-key $ANTHROPIC_API_KEY # With bearer token authentication mcpblox --upstream-url http://localhost:3000/mcp \ --upstream-token $MCP_TOKEN \ --prompt "Hide admin tools" \ --api-key $ANTHROPIC_API_KEY ``` **Load a complex prompt from a file:** ```bash mcpblox \ --upstream "uvx yfinance-mcp" \ --prompt-file transforms.txt \ --api-key $ANTHROPIC_API_KEY ``` **Chain instances via Unix pipes:** ```bash # Each instance reads its upstream URL from stdin and writes its own URL to stdout. # Only the first instance needs --upstream. mcpblox --upstream "node stock-server.js" --prompt "Add a max_results param to search" \ | mcpblox --prompt "Format prices as USD with commas" \ | mcpblox --prompt "Add caching hints to descriptions" # Or feed an upstream URL via echo: echo "http://localhost:3000/mcp" \ | mcpblox --prompt "Hide admin tools" \ | mcpblox --prompt "Format outputs as markdown" ``` When stdout is a pipe, mcpblox binds to an OS-assigned port and writes its URL (e.g. `http://localhost:57403/mcp`) to stdout. The next instance reads that URL from stdin. Use `--port` to override the auto-assigned port. **Chain manually with explicit ports:** ```bash # First instance: modify tool schemas mcpblox --upstream "node stock-server.js" --prompt "Add a max_results param to search" --port 8001 & # Second instance: format the output of the first mcpblox --upstream-url http://localhost:8001/mcp --prompt "Format prices as USD with commas" --port 8002 ``` ## Endpoints | Endpoint | Method | Description | |----------|--------|-------------| | `/mcp` | POST | MCP protocol (StreamableHTTP) | | `/health` | GET | Health check — returns `{"status":"ok","tools":<count>}` | ## Caching Transforms are cached to disk in `.mcpblox-cache/` (configurable with `--cache-dir`). The cache key is the hash of your transform prompt combined with the hash of the upstream tool schemas. If either changes, the cache auto-invalidates. Use `--no-cache` to force regeneration. Use `--dry-run` to preview the plan without starting the server. ## Security LLM-generated transform code runs in a restricted Node.js `vm` context with no access to the filesystem, network, process environment, or module system. The sandbox provides only data-manipulation primitives (JSON, Math, String, Array, etc.) with a 5-second execution timeout for input/output transforms and a 30-second timeout for synthetic tool orchestration. Synthetic tool orchestration code receives a `callTool` bridge function that restricts calls to only the upstream tools declared in the tool's plan — it cannot call arbitrary tools or access anything outside the sandbox. Note: Node.js `vm` is not a full security boundary — it's sufficient for LLM-generated code in a trusted-user context, not for arbitrary untrusted input.