mcp-stdio-mux 0.1.0__tar.gz

mcp_stdio_mux-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+/dist/
+/build/
+*.egg-info/
+.venv/
+.worktrees/
+.ruff_cache/
+.serena/

mcp_stdio_mux-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Muhyidin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_stdio_mux-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: mcp-stdio-mux
+Version: 0.1.0
+Summary: One shared process per MCP server across every AI agent session, app and profile on your machine.
+Project-URL: Homepage, https://github.com/techidin/mcp-stdio-mux
+Project-URL: Issues, https://github.com/techidin/mcp-stdio-mux/issues
+Author: Ahmad Muhyidin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,codex,mcp,model-context-protocol,stdio
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# mcp-stdio-mux
+
+One shared process per MCP server across every AI agent session, app and
+profile on your machine.
+
+Open four Claude Code sessions and each one starts its own copy of every stdio
+MCP server you configured. Add Codex, Cursor, or a second profile and the copies
+multiply. `mcp-stdio-mux` puts one shared backend behind all of them; each
+session reaches it through a 1.2 MB relay instead of a server of its own.
+
+## Install
+
+```bash
+uvx mcp-stdio-mux setup
+```
+
+Setup finds Claude Code (every profile), Claude Desktop, Codex (every profile),
+Gemini CLI, Cursor, Windsurf and OpenCode, shows what it will change, and asks
+once. It installs itself as a `uv` tool so your configs point at a path that
+stays. Restart your agent sessions afterwards.
+
+Without `uv`: `pipx install mcp-stdio-mux && mcp-stdio-mux setup`.
+
+Setup also gives Claude Code and Codex an agent skill, so you can ask an agent
+to "share my MCP servers" or "share the server I just added".
+
+## Measured
+
+Four sessions of one server, every process the sessions caused (relays, daemon,
+backend and its children), macOS 27.2 on Apple silicon with 16 GB, three runs on
+10 November 2026. The unit is `phys_footprint`, the "Memory" column of Activity
+Monitor.
+
+| Server | Without a mux | With mcp-stdio-mux | Saved |
+|---|---|---|---|
+| serena (Python) | 679–757 MB | 202–203 MB | 70–73% |
+| tilth (Node) | 57 MB | 36 MB | 37% |
+
+Each session's own process drops from 12–94 MB to 1.2 MB. The saving grows with
+the number of sessions and with how heavy the server is. Reproduce it with any
+server:
+
+```bash
+python scripts/benchmark.py --sessions 4 -- tilth --mcp
+python scripts/benchmark.py --sessions 4 \
+  --prefix "mcp-stdio-mux run --domain bench --server tilth" -- tilth --mcp
+```
+
+## What setup changes, and what it never touches
+
+- Each local (stdio) server's command in your user-level config files becomes
+  `mcp-stdio-mux run --domain <profile> --server <name> -- <original command>`.
+  The original command stays readable after `--`.
+- Every file is backed up to `~/.local/state/mcp-stdio-mux/backups/` first,
+  written atomically through symlinks with its permissions kept, then read back.
+- Remote (HTTP or SSE) servers, project `.mcp.json` files, and servers you mark
+  `native` are never touched. A file that nothing changes keeps its exact bytes.
+- `mcp-stdio-mux undo` restores each file's exact bytes when the app has not
+  written to it since setup, and removes only the wrapper when it has.
+- Running setup a second time changes nothing that is already shared.
+
+## Who shares with whom
+
+Two sessions share one backend only when all of these match:
+
+| Part | Where it comes from |
+|---|---|
+| Domain | The profile name: `~/.claude-work` and `~/.codex-work` are both `work`; default profiles are `default`. |
+| Command | The exact backend command and arguments. |
+| Credentials | A SHA-256 of the environment variables the config declares. Values are never logged. |
+| Workspace | The git root, for servers bound to the directory they start in. |
+
+Differently named profiles never share unless you map them to one domain.
+
+Each backend also gets a scope:
+
+| Scope | When | Backend |
+|---|---|---|
+| `global` | Default. | One per signature, started in your home directory. |
+| `workspace` | An argument flag names `cwd`, `project`, `workspace` or `root`, an argument is `.`, or the config sets `cwd`. | One per signature and git root. |
+| `session` | The first `tools/list` reply has a tool named like `browser`, `tab`, `page`, `navigate`, `click`, `screenshot`, `session`, `login` or `logout`. | One per session. |
+
+Until a server is classified, a second session waits (up to 20 seconds), so no
+session attaches to a stateful server before the mux knows it is one.
+
+## Configuration
+
+Optional. `~/.config/mcp-stdio-mux/config.toml`:
+
+```toml
+[profiles]
+work = "default"          # let the work profile share with the default one
+
+[servers]
+my-browser = "session"    # by server name or executable name
+heavy-indexer = "native"  # leave it alone; takes effect on the next setup
+```
+
+Scopes are `global`, `workspace`, `session` and `native`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `mcp-stdio-mux status` | Which servers each config shares, and every running backend with its sessions and memory. |
+| `mcp-stdio-mux setup [--dry-run] [--yes]` | Share every stdio server in every detected config. |
+| `mcp-stdio-mux undo [--yes]` | Put every config back and remove the skill. |
+| `mcp-stdio-mux run ...` | What your apps call. You do not run this yourself. |
+
+## How it works
+
+1. The app starts `mcp-stdio-mux run`, a short-lived shim.
+2. The shim finds or starts the daemon for its launch signature (one lock per
+   signature), passes its stdin and stdout to the daemon over the Unix socket
+   (`SCM_RIGHTS`), and replaces itself with `/bin/cat` named
+   `mcp-stdio-mux: <server>`. That relay is the 1.2 MB the app keeps.
+3. The daemon runs the backend in its own process group. It gives each session's
+   JSON-RPC ids and progress tokens a private namespace, answers later
+   `initialize` calls from the first result, and sends server requests (roots,
+   sampling, elicitation) to a session that supports them.
+4. A session ends when the app closes its stdin, kills the relay, or exits. When
+   the last session is gone, the daemon waits five minutes, then stops the
+   backend's whole process group, so `npx` children do not outlive it.
+
+Sockets live in a directory only you can read (`$XDG_RUNTIME_DIR/mcp-stdio-mux`
+or `/tmp/mcp-stdio-mux-<uid>`), and a Unix socket cannot be reached from another
+machine.
+
+## Limits
+
+- macOS and Linux. Windows is not supported.
+- A shared backend inherits environment variables the config does not declare
+  from the session that started it. Declare anything that differs.
+- A server that keeps per-client state but whose tool names do not show it must
+  be marked `session`.
+- When a backend crashes, its in-flight requests fail and are not replayed; the
+  next session start launches a new backend.
+- An app that dies without being reaped by its parent keeps its session until
+  its relay is killed.
+
+## Development
+
+Runtime code is Python 3.11+ standard library only.
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -t .
+ruff format --check src tests scripts && ruff check src tests scripts
+```
+
+## License
+
+MIT

mcp_stdio_mux-0.1.0/README.md

@@ -0,0 +1,152 @@
+# mcp-stdio-mux
+
+One shared process per MCP server across every AI agent session, app and
+profile on your machine.
+
+Open four Claude Code sessions and each one starts its own copy of every stdio
+MCP server you configured. Add Codex, Cursor, or a second profile and the copies
+multiply. `mcp-stdio-mux` puts one shared backend behind all of them; each
+session reaches it through a 1.2 MB relay instead of a server of its own.
+
+## Install
+
+```bash
+uvx mcp-stdio-mux setup
+```
+
+Setup finds Claude Code (every profile), Claude Desktop, Codex (every profile),
+Gemini CLI, Cursor, Windsurf and OpenCode, shows what it will change, and asks
+once. It installs itself as a `uv` tool so your configs point at a path that
+stays. Restart your agent sessions afterwards.
+
+Without `uv`: `pipx install mcp-stdio-mux && mcp-stdio-mux setup`.
+
+Setup also gives Claude Code and Codex an agent skill, so you can ask an agent
+to "share my MCP servers" or "share the server I just added".
+
+## Measured
+
+Four sessions of one server, every process the sessions caused (relays, daemon,
+backend and its children), macOS 27.2 on Apple silicon with 16 GB, three runs on
+10 November 2026. The unit is `phys_footprint`, the "Memory" column of Activity
+Monitor.
+
+| Server | Without a mux | With mcp-stdio-mux | Saved |
+|---|---|---|---|
+| serena (Python) | 679–757 MB | 202–203 MB | 70–73% |
+| tilth (Node) | 57 MB | 36 MB | 37% |
+
+Each session's own process drops from 12–94 MB to 1.2 MB. The saving grows with
+the number of sessions and with how heavy the server is. Reproduce it with any
+server:
+
+```bash
+python scripts/benchmark.py --sessions 4 -- tilth --mcp
+python scripts/benchmark.py --sessions 4 \
+  --prefix "mcp-stdio-mux run --domain bench --server tilth" -- tilth --mcp
+```
+
+## What setup changes, and what it never touches
+
+- Each local (stdio) server's command in your user-level config files becomes
+  `mcp-stdio-mux run --domain <profile> --server <name> -- <original command>`.
+  The original command stays readable after `--`.
+- Every file is backed up to `~/.local/state/mcp-stdio-mux/backups/` first,
+  written atomically through symlinks with its permissions kept, then read back.
+- Remote (HTTP or SSE) servers, project `.mcp.json` files, and servers you mark
+  `native` are never touched. A file that nothing changes keeps its exact bytes.
+- `mcp-stdio-mux undo` restores each file's exact bytes when the app has not
+  written to it since setup, and removes only the wrapper when it has.
+- Running setup a second time changes nothing that is already shared.
+
+## Who shares with whom
+
+Two sessions share one backend only when all of these match:
+
+| Part | Where it comes from |
+|---|---|
+| Domain | The profile name: `~/.claude-work` and `~/.codex-work` are both `work`; default profiles are `default`. |
+| Command | The exact backend command and arguments. |
+| Credentials | A SHA-256 of the environment variables the config declares. Values are never logged. |
+| Workspace | The git root, for servers bound to the directory they start in. |
+
+Differently named profiles never share unless you map them to one domain.
+
+Each backend also gets a scope:
+
+| Scope | When | Backend |
+|---|---|---|
+| `global` | Default. | One per signature, started in your home directory. |
+| `workspace` | An argument flag names `cwd`, `project`, `workspace` or `root`, an argument is `.`, or the config sets `cwd`. | One per signature and git root. |
+| `session` | The first `tools/list` reply has a tool named like `browser`, `tab`, `page`, `navigate`, `click`, `screenshot`, `session`, `login` or `logout`. | One per session. |
+
+Until a server is classified, a second session waits (up to 20 seconds), so no
+session attaches to a stateful server before the mux knows it is one.
+
+## Configuration
+
+Optional. `~/.config/mcp-stdio-mux/config.toml`:
+
+```toml
+[profiles]
+work = "default"          # let the work profile share with the default one
+
+[servers]
+my-browser = "session"    # by server name or executable name
+heavy-indexer = "native"  # leave it alone; takes effect on the next setup
+```
+
+Scopes are `global`, `workspace`, `session` and `native`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `mcp-stdio-mux status` | Which servers each config shares, and every running backend with its sessions and memory. |
+| `mcp-stdio-mux setup [--dry-run] [--yes]` | Share every stdio server in every detected config. |
+| `mcp-stdio-mux undo [--yes]` | Put every config back and remove the skill. |
+| `mcp-stdio-mux run ...` | What your apps call. You do not run this yourself. |
+
+## How it works
+
+1. The app starts `mcp-stdio-mux run`, a short-lived shim.
+2. The shim finds or starts the daemon for its launch signature (one lock per
+   signature), passes its stdin and stdout to the daemon over the Unix socket
+   (`SCM_RIGHTS`), and replaces itself with `/bin/cat` named
+   `mcp-stdio-mux: <server>`. That relay is the 1.2 MB the app keeps.
+3. The daemon runs the backend in its own process group. It gives each session's
+   JSON-RPC ids and progress tokens a private namespace, answers later
+   `initialize` calls from the first result, and sends server requests (roots,
+   sampling, elicitation) to a session that supports them.
+4. A session ends when the app closes its stdin, kills the relay, or exits. When
+   the last session is gone, the daemon waits five minutes, then stops the
+   backend's whole process group, so `npx` children do not outlive it.
+
+Sockets live in a directory only you can read (`$XDG_RUNTIME_DIR/mcp-stdio-mux`
+or `/tmp/mcp-stdio-mux-<uid>`), and a Unix socket cannot be reached from another
+machine.
+
+## Limits
+
+- macOS and Linux. Windows is not supported.
+- A shared backend inherits environment variables the config does not declare
+  from the session that started it. Declare anything that differs.
+- A server that keeps per-client state but whose tool names do not show it must
+  be marked `session`.
+- When a backend crashes, its in-flight requests fail and are not replayed; the
+  next session start launches a new backend.
+- An app that dies without being reaped by its parent keeps its session until
+  its relay is killed.
+
+## Development
+
+Runtime code is Python 3.11+ standard library only.
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -t .
+ruff format --check src tests scripts && ruff check src tests scripts
+```
+
+## License
+
+MIT

mcp_stdio_mux-0.1.0/docs/README.md

@@ -0,0 +1,10 @@
+# Documentation
+
+Start with the [README](../README.md) for installation and behaviour.
+
+| Document | What it holds |
+|---|---|
+| [specs/2026-11-10-v0.1-scope.md](specs/2026-11-10-v0.1-scope.md) | The contract for the first public release. |
+| [../skills/mcp-stdio-mux/SKILL.md](../skills/mcp-stdio-mux/SKILL.md) | The agent skill that setup installs. |
+| [../scripts/benchmark.py](../scripts/benchmark.py) | How the README's memory numbers are measured. |
+| [../AGENTS.md](../AGENTS.md) | Rules for contributors and coding agents. |

mcp_stdio_mux-0.1.0/docs/specs/2026-11-10-v0.1-scope.md

@@ -0,0 +1,49 @@
+# v0.1 Scope
+
+Approved on 10 November 2026. This file is the contract for the first public
+release; a change to a criterion is agreed in writing before the code changes.
+
+## Story
+
+As a developer who runs several AI agent apps (Claude Code, Codex, and others),
+each with several profiles, I run one command and every stdio MCP server is
+shared safely across my sessions, so duplicate MCP processes stop eating my RAM.
+
+## Acceptance Criteria
+
+1. **One command.** `uvx mcp-stdio-mux setup` finds every supported app and
+   profile, shows which servers it will route through the mux in which file,
+   and applies after one confirmation. `--yes` skips the question.
+2. **Detection.** Claude Code (every `~/.claude*` profile and
+   `$CLAUDE_CONFIG_DIR`), Claude Desktop, Codex (every `~/.codex*` home and
+   `$CODEX_HOME`), Gemini CLI, Cursor, Windsurf, and OpenCode.
+3. **Profiles stay isolated.** Profiles with the same name share backends across
+   apps (`~/.claude-work` and `~/.codex-work`); differently named profiles never
+   share unless the user maps them to one domain in the config file. Different
+   declared credentials never share.
+4. **User configs are safe.** Every file is backed up before it changes, written
+   atomically, and re-checked after writing. A second `setup` changes nothing.
+   `undo` restores the original bytes when the app has not touched the file
+   since, and unwraps in place when it has. HTTP servers are never touched.
+5. **Lighter shims.** The per-session shim uses at least 50% less memory than the
+   internal runtime it replaces, measured the same way. All ported tests pass.
+   Baseline corrected on 10 November 2026 from 14 MB (a bare import probe) to
+   18.2–18.5 MB `phys_footprint`, measured with `scripts/benchmark.py`, the same
+   tool that measures the new relay.
+6. **Agent skill.** `SKILL.md` lets a user ask an agent to "share my MCP
+   servers": the agent previews, applies after consent, verifies with
+   `mcp-stdio-mux status`, and knows how to undo.
+7. **Release.** macOS and Linux CI pass on Python 3.11 and 3.13, the wheel
+   installs into a clean environment, the private-data scan is clean, and the
+   README carries before/after numbers measured on a real machine.
+
+## Out of Scope
+
+Windows; project files such as a repository's `.mcp.json` (they belong to a
+team); HTTP and SSE servers; request replay after a backend crash; a dashboard;
+re-wrapping new servers without a command (re-run `setup` or ask the skill).
+
+## Definition of Done
+
+Each criterion has evidence in the release pull request; CI is green; the
+owner makes the repository public and registers the PyPI trusted publisher.

mcp_stdio_mux-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-stdio-mux"
+dynamic = ["version"]
+description = "One shared process per MCP server across every AI agent session, app and profile on your machine."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ahmad Muhyidin" }]
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["mcp", "model-context-protocol", "claude-code", "codex", "ai-agents", "stdio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/techidin/mcp-stdio-mux"
+Issues = "https://github.com/techidin/mcp-stdio-mux/issues"
+
+[project.scripts]
+mcp-stdio-mux = "mcp_stdio_mux.cli:main"
+
+[tool.hatch.version]
+path = "src/mcp_stdio_mux/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_stdio_mux"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/mcp-stdio-mux/SKILL.md" = "mcp_stdio_mux/SKILL.md"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "skills", "docs", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]

mcp_stdio_mux-0.1.0/skills/mcp-stdio-mux/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: mcp-stdio-mux
+description: Use when the user wants MCP servers to stop piling up across agent sessions, asks to share or dedupe MCP server processes to save memory, added a new stdio MCP server after mcp-stdio-mux setup, sees an MCP server fail after setup, or wants to undo mcp-stdio-mux.
+---
+
+# mcp-stdio-mux
+
+`mcp-stdio-mux` makes every session of every agent app (Claude Code, Claude
+Desktop, Codex, Gemini CLI, Cursor, Windsurf, OpenCode) share one process per
+stdio MCP server instead of starting its own copy. It rewrites each server's
+command in the user's own config files, with backups and a full undo.
+
+## Share the user's servers
+
+1. Look before changing anything:
+
+   ```bash
+   mcp-stdio-mux status          # or: uvx mcp-stdio-mux status
+   mcp-stdio-mux setup --dry-run
+   ```
+
+2. Show the user the plan: which apps, profiles, and how many servers. Say that
+   profiles with different names never share (unless mapped in the config), and
+   that remote (HTTP) servers and project `.mcp.json` files are not touched.
+3. Apply only after the user agrees:
+
+   ```bash
+   mcp-stdio-mux setup --yes
+   ```
+
+   If `mcp-stdio-mux` is not on PATH, `uvx mcp-stdio-mux setup --yes` installs it
+   as a tool first, so the configs point at a path that stays.
+4. Tell the user to restart agent sessions; open sessions keep their old servers.
+5. After the restart, `mcp-stdio-mux status` lists each running backend and how
+   many sessions it serves.
+
+Never wrap or unwrap a server by editing a config file by hand; re-run `setup`.
+
+## When the user adds a server later
+
+Run `mcp-stdio-mux setup --dry-run`, show the one new line, then `setup --yes`.
+A second `setup` changes nothing that is already shared.
+
+## When a server misbehaves
+
+- Find its daemon in `mcp-stdio-mux status`; its log is
+  `<runtime dir>/<key>.log` (runtime dir: `$MCP_STDIO_MUX_RUNTIME_DIR`, else
+  `$XDG_RUNTIME_DIR/mcp-stdio-mux`, else `/tmp/mcp-stdio-mux-<uid>`).
+- A server that keeps per-client state (a browser, a login) must not be shared.
+  The mux detects most of them from their tool names. For one it misses, add to
+  `~/.config/mcp-stdio-mux/config.toml`:
+
+  ```toml
+  [servers]
+  my-browser = "session"    # one backend per session
+  # other scopes: "global", "workspace" (one per git root), "native" (leave alone)
+  ```
+
+  Keys are the server name or the executable name. `native` takes effect after
+  `setup` runs again; the other scopes apply at the next session start.
+- To let two differently named profiles share (for example `work` and `default`):
+
+  ```toml
+  [profiles]
+  work = "default"
+  ```
+
+  then run `setup` again.
+
+## Undo
+
+```bash
+mcp-stdio-mux undo --yes
+```
+
+It restores each file's exact bytes when the app has not written to it since
+setup, and removes only the mux wrapper when it has. It also removes this skill.

mcp_stdio_mux-0.1.0/src/mcp_stdio_mux/__init__.py

@@ -0,0 +1,3 @@
+"""Share one stdio MCP server process across agent sessions, apps and profiles."""
+
+__version__ = "0.1.0"

mcp_stdio_mux-0.1.0/src/mcp_stdio_mux/__main__.py

@@ -0,0 +1,3 @@
+from mcp_stdio_mux.cli import main
+
+raise SystemExit(main())