npm - muxed - Versions diffs - 0.2.0 → 0.2.2 - Mend

muxed 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,323 +1,137 @@
-# muxed – MCP Server Daemon & Aggregator CLI
+# muxed
-> Aggregate all your [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers behind a single daemon. Fewer tokens. Faster execution. Better accuracy.
+<div align="center">
-**muxed** is a background daemon and CLI that sits between your AI agent and your MCP servers. It solves the problems that [Anthropic](https://www.anthropic.com/engineering/code-execution-with-mcp) and [Cloudflare](https://blog.cloudflare.com/code-mode/) have been writing about: tool sprawl eating your context window, slow cold starts, and degraded accuracy as you add more servers.
+<strong>MCP tools don't belong in your model's context window.</strong>
-## The Problem
+Offload them to a CLI. Let your agents call tools through shell commands and scripts instead.
-The MCP ecosystem has a scaling problem. Every tool you connect dumps its full schema into the model's context window. A standard setup with 3-4 MCP servers can consume 20-30% of the context before the agent even starts working. Anthropic's research shows this leads to a 98.7% token overhead on intermediate results. Cloudflare found that agents can't reliably handle more than a handful of servers before tool selection accuracy collapses.
+[![npm](https://img.shields.io/npm/v/muxed.svg)](https://www.npmjs.com/package/muxed)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-**More tools = worse results.** Every token spent on MCP tool schemas is a token not spent on your actual task – or on the skills, prompts, and default tools that agents execute deterministically.
+[Docs](https://muxed.ai) · [npm](https://www.npmjs.com/package/muxed)
-## How muxed Fixes This
+</div>
-**muxed** is an optimization layer for your MCP infrastructure:
+---
-- **Fewer tokens in context** – Tools stay in the daemon, not in the prompt. Agents discover tools on-demand with `muxed grep` and `muxed info` instead of loading every schema upfront. Load only what you need, when you need it.
-- **Faster execution** – Servers stay warm in a background daemon. No cold starts, no repeated connection negotiation. Call tools directly via CLI without round-tripping through the model.
-- **More precise tool selection** – By offloading tool management to muxed, your agent's context window stays clean for what actually matters: reasoning, prompts, and the task at hand. Fewer tools in context means the model picks the right one more often.
-- **Chain calls outside the model** – Pipe tool results through scripts and chain `muxed call` commands in bash without every intermediate result flowing through the LLM. This is the same insight behind Anthropic's code execution approach and Cloudflare's Code Mode – but available today as a simple CLI.
-- **Context engineering wins** – When MCP tools are offloaded to muxed, your context window is freed for skills, prompts, and default tools – the things agents execute deterministically with higher priority. Context engineering beats tool bloat: fewer MCP schemas means your carefully crafted instructions actually get followed.
+Every MCP server you connect dumps its full tool schema into the model's context window. A standard setup with 3-4 servers can consume 20-30% of the context before the agent even starts working. More tools in context means worse tool selection, less room for reasoning, and your carefully crafted instructions get drowned out by thousands of tokens of schema JSON. This isn't a model problem. It's an architecture problem.
-### For Agents in Production
+**muxed** fixes this by moving tool management out of the harness and into a CLI. Tools stay in the CLI — agents discover and call them on-demand through shell commands. No schemas in context. Chain tool calls in bash scripts without intermediate results flowing through the LLM. The CLI auto-starts a background process on first command and shuts down after 5 minutes idle.
-When you offload MCP tools to muxed, your agents' context windows free up for what actually gets executed reliably: skills, prompts, and default tools. These have deterministic priority – models always follow them. MCP tools, by contrast, compete for attention in a crowded context and get picked less reliably as you add more. By moving tool management out of the model and into a daemon, you're doing context engineering at the infrastructure level – your carefully crafted instructions get followed instead of being drowned out by 30,000 tokens of tool schemas.
+---
-## Quick Start
+## Use with agents
 ```bash
-# Install globally
-npm install -g muxed
+# Use directly — no install needed
+bunx muxed init         # or: pnpx muxed init / npx muxed init
-# Or use directly with npx
-npx muxed tools
+# Or install globally
+bun install -g muxed    # or: pnpm install -g muxed / npm install -g muxed
+```
-# List all servers and their status
-muxed servers
+<table>
+<tr>
+<td valign="top" width="50%">
-# List all available tools across all servers
-muxed tools
+**CLI** — for Claude Code, Cursor, Codex, any agent that runs shell
-# Call a tool
-muxed call filesystem/read_file '{"path": "/tmp/hello.txt"}'
+```bash
+npx muxed init
+```
+Auto-discovers MCP servers and writes usage instructions to the agent's instructions file. Agents run `npx muxed grep`, `npx muxed info`, and `npx muxed call` directly.
+</td>
+<td valign="top" width="50%">
+**MCP proxy** — for Claude Desktop, any MCP client
+```bash
+npx muxed mcp
+```
+Exposes all aggregated servers as a single MCP server on stdio. Point your client at `npx muxed mcp` and all tools appear as one server.
+</td>
+</tr>
+</table>
+## Quick start
+```bash
+# List all servers and their status
+npx muxed servers
 # Search tools by name or description
-muxed grep "search"
+npx muxed grep "search"
-# The daemon starts automatically and stops after 5 min idle
+# Get a tool's schema
+npx muxed info slack/search_messages
+# Call a tool
+npx muxed call filesystem/read_file '{"path": "/tmp/hello.txt"}'
 ```
 ## Configuration
-Create `muxed.config.json` in your project root (or `~/.config/muxed/config.json` for global config):
+Create `muxed.config.json` in your project root (or `~/.config/muxed/config.json` globally):
 ```json
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
-      "env": {}
-    },
-    "postgres": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-postgres"],
-      "env": { "DATABASE_URL": "postgresql://..." }
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
     },
     "remote-api": {
       "url": "https://mcp.example.com/mcp",
-      "transport": "streamable-http",
-      "headers": { "Authorization": "Bearer ..." }
+      "transport": "streamable-http"
     }
   }
 }
 ```
-The format is intentionally compatible with the `mcpServers` section of `claude_desktop_config.json` – you can reuse your existing config.
-## Architecture
-```
-  muxed call server/tool '{}'
-  ──────────────────────────────────►  ┌──────────────────────┐
-  (Unix socket: ~/.muxed/muxed.sock)    │     muxed daemon      │
-                                      │                      │
-  muxed tools                          │  ServerManager(fs)   │──► [stdio: filesystem]
-  ──────────────────────────────────►  │  ServerManager(pg)   │──► [stdio: postgres]
-                                      │  ServerManager(...)   │──► [HTTP: remote]
-  muxed servers                        │                      │
-  ──────────────────────────────────►  └──────────────────────┘
-                                       (auto-exits after idle)
-```
-**Lazy start**: The daemon spawns automatically when you run any command. No explicit `muxed start` needed.
-**Idle shutdown**: After 5 minutes (configurable) with no requests, the daemon shuts down and cleans up.
-## CLI Reference
-| Command                                         | Description                                          |
-| ----------------------------------------------- | ---------------------------------------------------- |
-| `muxed servers`                                 | List servers with connection status and capabilities |
-| `muxed tools [server]`                          | List available tools (with annotations)              |
-| `muxed info <server/tool>`                      | Tool schema details (inputSchema, outputSchema)      |
-| `muxed call <server/tool> [json]`               | Invoke a tool                                        |
-| `muxed call ... --dry-run`                      | Validate arguments without executing                 |
-| `muxed call ... --fields <paths>`               | Extract specific fields from the response            |
-| `muxed grep <pattern>`                          | Search tool names, titles, and descriptions          |
-| `muxed resources [server]`                      | List resources                                       |
-| `muxed read <server/resource>`                  | Read a resource                                      |
-| `muxed prompts [server]`                        | List prompt templates                                |
-| `muxed prompt <server/prompt> [args]`           | Render a prompt                                      |
-| `muxed completions <type> <name> <arg> <value>` | Argument auto-completions                            |
-| `muxed tasks [server]`                          | List active tasks                                    |
-| `muxed status`                                  | Daemon status, PID, uptime                           |
-| `muxed reload`                                  | Reload config, reconnect changed servers             |
-| `muxed stop`                                    | Stop daemon manually                                 |
-| `muxed init`                                    | Generate config from discovered MCP servers          |
-All commands support `--json` for machine-readable output.
-## Agent-Friendly Features
-### Structured Errors with Recovery Suggestions
-When a tool call fails, muxed returns structured error data with actionable suggestions and fuzzy-matched similar tool names — so agents can self-correct instead of guessing.
-```bash
-muxed call slack/search_msgs '{}' --json
-# {
-#   "code": -32602,
-#   "message": "Tool not found: slack/search_msgs",
-#   "data": {
-#     "code": "TOOL_NOT_FOUND",
-#     "suggestion": "Did you mean: slack/search_messages, slack/search_files? Run 'muxed grep <pattern>' to search available tools.",
-#     "context": { "similarTools": ["slack/search_messages", "slack/search_files"] }
-#   }
-# }
-```
-Error codes include `TOOL_NOT_FOUND`, `SERVER_NOT_FOUND`, `SERVER_NOT_CONNECTED`, `INVALID_FORMAT`, `MISSING_PARAMETER`, `INVALID_ARGUMENTS`, and `TIMEOUT`.
-### Dry-Run Validation
-Validate arguments against a tool's schema without executing the call. Catches mistakes before wasting tokens on failed calls.
-```bash
-muxed call postgres/query '{"sql": "DROP TABLE users"}' --dry-run
-# Validation: passed
-# Warnings:
-#   - Tool is marked as destructive.
-#   - Tool is not marked as idempotent.
-```
-### Response Field Filtering
-Extract only the fields you need from tool responses. Reduces context window consumption when responses are large. Only applies to JSON-parseable outputs — non-JSON text is returned unchanged.
-```bash
-muxed call postgres/query '{"sql": "SELECT * FROM users"}' --fields "rows[].name,rows[].email"
-```
-Supports dot-notation paths (`data.user.name`) and array extraction (`rows[].field`). Works on `structuredContent` and JSON embedded in text content blocks.
+The format is compatible with the `mcpServers` section of `claude_desktop_config.json` — reuse your existing config.
 ## Node.js API
-muxed is also an npm package. Agents can write Node.js scripts that call MCP tools programmatically – with typed results, async/await, and the full npm ecosystem.
 ```typescript
 import { createClient } from 'muxed';
 const client = await createClient();
-// Discover tools
 const tools = await client.grep('search');
-// Call a tool
-const result = await client.call('filesystem/read_file', {
-  path: '/tmp/config.json',
-});
-// Validate before calling (dry-run)
-const check = await client.validate('postgres/query', { sql: 'DROP TABLE users' });
-// check.valid, check.errors, check.warnings
-// Call with field filtering
-const filtered = await client.call('postgres/query', { sql: 'SELECT * FROM users' }, {
-  fields: ['rows[].name', 'rows[].email'],
-});
-// Parallel calls across servers
-const [users, tickets] = await Promise.all([
-  client.call('posthog/query-run', { query: { kind: 'HogQLQuery', query: 'SELECT ...' } }),
-  client.call('intercom/search-conversations', { query: 'billing', limit: 10 }),
-]);
-// Async tasks for long-running operations
-const task = await client.callAsync('analytics/export', { range: '30d' });
-const status = await client.task(task.server, task.taskId);
-```
-Install as a dependency for programmatic use:
-```bash
-npm install muxed
+const result = await client.call('filesystem/read_file', { path: '/tmp/config.json' });
 ```
-The client auto-starts the daemon if it isn't running. Both `import from 'muxed'` and `import from 'muxed/client'` work.
-## Use with AI Coding Agents
-### Claude Code
-Add muxed as a tool source in your Claude Code configuration. The `muxed init` command can auto-discover MCP servers from your `claude_desktop_config.json` and generate an `muxed.config.json`.
-### Cursor / Windsurf / Other Agents
-Any agent that supports MCP can connect to muxed's daemon via the Unix socket or optional HTTP listener.
+Install as a dependency: `bun add muxed` / `pnpm add muxed` / `npm install muxed`
-## Daemon Settings
+## How it works
-```json
-{
-  "daemon": {
-    "idleTimeout": 300000,
-    "connectTimeout": 30000,
-    "requestTimeout": 60000,
-    "http": {
-      "enabled": false,
-      "port": 3100,
-      "host": "127.0.0.1"
-    }
-  }
-}
 ```
-## Key Features
-### Connection Management
-- Automatic reconnection with exponential backoff (1s → 60s)
-- Periodic health checks via `ping()`
-- Stale PID/socket detection and cleanup
-### Full MCP 2025-11-25 Support
-- **Tools** with `title`, `annotations`, `outputSchema`, `structuredContent`
-- **Resources** with text and blob content types
-- **Prompts** with argument rendering
-- **Completions** for argument auto-complete
-- **Tasks** for long-running operations (`--async` flag)
-- **Content types**: text, image, audio, resource links, structured content
-### Transport Support
-- **stdio** – for local MCP servers (default)
-- **Streamable HTTP** – for remote MCP servers
-- **SSE** – legacy support for older servers
-## Replacing mcp-remote
-If you're using `mcp-remote` to connect Claude Desktop or ChatGPT to remote MCP servers, muxed is a drop-in upgrade. Instead of adding N separate `mcp-remote` proxy entries to your config, point at one muxed daemon that manages all your remote (and local) servers – with connection pooling, health checks, auto-reconnect, and a CLI for free.
-```jsonc
-// Before: mcp-remote in claude_desktop_config.json
-{ "command": "npx", "args": ["mcp-remote", "https://mcp.example.com/sse"] }
-// After: muxed.config.json
-{ "url": "https://mcp.example.com/mcp", "transport": "streamable-http" }
+  Agent (Claude Code, Cursor, etc.)
+            |
+       shell commands
+            |
+     ┌──────┴──────┐
+     │  muxed daemon │  ← background process, auto-start/stop
+     │              │
+     │  ServerPool  │
+     │   ├── fs     │──► [stdio: filesystem server]
+     │   ├── pg     │──► [stdio: postgres server]
+     │   └── api    │──► [HTTP: remote server]
+     └──────────────┘
 ```
-## Comparison with Alternatives
-| Feature                               | muxed | mcp-remote | mcp-proxy | MetaMCP | 1MCP    |
-| ------------------------------------- | ----- | ---------- | --------- | ------- | ------- |
-| Background daemon                     | ✅    | ❌         | ❌        | ❌      | ❌      |
-| Lazy start / idle shutdown            | ✅    | ❌         | ❌        | ❌      | ❌      |
-| Multi-server aggregation              | ✅    | ❌         | ✅        | ✅      | ✅      |
-| CLI interface                         | ✅    | ❌         | ❌        | ❌      | ✅      |
-| Auto-reconnect / health checks        | ✅    | ❌         | ❌        | ✅      | ✅      |
-| MCP 2025-11-25                        | ✅    | Partial    | Partial   | Partial | Partial |
-| Task support                          | ✅    | ❌         | ❌        | ❌      |         |
-| Dry-run validation                    | ✅    | ❌         | ❌        | ❌      | ❌      |
-| Structured errors with suggestions    | ✅    | ❌         | ❌        | ❌      | ❌      |
-| Response field filtering              | ✅    | ❌         | ❌        | ❌      | ❌      |
-| Zero config start                     | ✅    | ❌         | ❌        | ❌      |         |
-| Config compatible with Claude Desktop | ✅    | ❌         | ✅        | ❌      |         |
 ## Development
 ```bash
-# Install dependencies
-pnpm install
-# Run in development mode
-pnpm dev
-# Build
-pnpm build
-# Run tests
-pnpm test
-# Type check
-pnpm type-check
-# Format
-pnpm format
+pnpm install && pnpm build
+pnpm dev    # run from source
+pnpm test   # vitest
 ```
-## Contributing
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 ## License
 [MIT](LICENSE) © Georgiy Tarasov
-## Links
-- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
-- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
-- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)