@omega.js/mcp-router 0.1.0

package/LICENSE

@@ -0,0 +1,98 @@
+Copyright (c) 2026 ITW Creative Works
+
+Licensor: ITW Creative Works
+Software: @omega.js/mcp-router
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,98 @@
+# @omega.js/mcp-router
+
+One MCP endpoint for a whole session, and it stays cheap.
+
+An MCP client that declares five servers pays for five: every one is launched, every one's full tool schema sits in the context window from the first token. The router flips that around. It is a single stdio MCP server that proxies many **upstream** servers: tool schemas come from a cache on disk, upstream processes are spawned **lazily** on the first tool call that actually needs one, and a session turns upstreams on and off for itself without touching disk or restarting anything.
+
+Tools surface to the client as `<upstream>__<tool>` — inside Claude Code that reads `mcp__mcp-router__chrome-devtools__click`.
+
+A child is as short-lived as its use: it starts on the first call that needs it, and it is closed once nothing has called it for 15 minutes — with everything it started, not just the pid the router holds — after which the next call spawns a fresh one. A call in flight is never closed under, and a call that lands while a close is running is served by a fresh child rather than failing. When the host goes away, by a signal or simply by closing the router's stdin, the router closes every upstream, waits out the grace that kills what they started, and exits.
+
+The omega Claude plugin launches the router straight from the monorepo checkout it ships in, and on a bare clone the bin installs its own dependencies on first launch — no install step for a user, no publish for a dev editing the checkout.
+
+## What ships with it
+
+Four defaults, ready on install day:
+
+| Upstream | What it does | Default |
+|---|---|---|
+| `chrome-devtools` | A private, isolated, throwaway-profile Chrome per session | auto |
+| `chrome-devtools-electron` | Attaches to an already-running omega desktop dev app on `$OMEGA_CDP_PORT` | auto |
+| `chrome-devtools-extension` | Chrome for Testing with the unpacked extension at `$OMEGA_EXTENSION_PATH` pre-loaded | on-demand |
+| `omega-extension` | The extension automation server inside `@omega.js/manager` | auto |
+
+An `on-demand` upstream stays invisible until a session asks for it — that is how a noisy 34-tool server costs nothing until it is wanted.
+
+## The meta-tools (per session, from inside the client)
+
+- `router__list_upstreams` — every upstream, its on-disk enabled state, whether it is locked, whether it is active in this session, its cached tool count, and — when a child is running — that child's `pid` and how long it has been idle (`idle_ms`).
+- `router__enable_upstream {name, env?}` — activate for THIS session, unless the upstream is locked. `env` sets vars on the child (passing it restarts a running child so they take effect).
+- `router__disable_upstream {name}` — deactivate and stop the child. Disk is untouched.
+- `router__refresh_upstream {name}` — spawn once, re-read the tool list, and cache it.
+
+## Config layering
+
+Two layers, and only one of them is ever written:
+
+1. **Bundled defaults** — `servers/<name>/config.json` inside this package. Read-only: for a consumer they live in `node_modules`.
+2. **Your overlay** — `~/.omega/mcp-router/servers/<name>/config.json`, plus `~/.omega/mcp-router/.env` for secrets.
+
+The merge is **shallow and field-level**: an overlay entry's top-level keys win over the bundled entry's, and everything else survives.
+
+```jsonc
+// ~/.omega/mcp-router/servers/chrome-devtools/config.json
+{ "enabled": false }                 // turns the bundled default off, keeps its command + tools cache
+```
+```jsonc
+// ~/.omega/mcp-router/servers/playwright/config.json
+{ "enabled": true, "default": "on-demand", "command": "npx", "args": ["-y", "@playwright/mcp@latest", "--isolated"] }
+```
+```jsonc
+// ~/.omega/mcp-router/servers/playwright/config.json
+{ "enabled": false, "locked": true }  // stays off: every enable is refused, `--force` is the only way past
+```
+
+`"locked": true` holds an upstream off. `omega-mcp enable` refuses it (exit 1, naming the field) unless you pass `--force`, and the per-chat `router__enable_upstream` refuses it with no override at all. Disabling, removing, and refreshing a locked upstream stay allowed: the lock is against waking it, not against turning it off.
+
+A name that only exists in the overlay is simply a private upstream of yours. Nothing you do forks the defaults, and an upgrade of this package never clobbers your overrides.
+
+## The CLI
+
+`omega-mcp` manages the registry. Every command reads the merged view and writes the overlay.
+
+```bash
+omega-mcp list                              # every upstream, its source (bundled / yours), state, tool count
+omega-mcp enable chrome-devtools-extension  # writes {"enabled": true} to your overlay, then caches the schema
+omega-mcp disable chrome-devtools           # writes {"enabled": false}
+omega-mcp enable playwright --force         # the only way past a {"locked": true} entry
+omega-mcp add my-server npx -y my-mcp@latest
+omega-mcp remove my-server                  # a bundled default cannot be removed — disable it instead
+omega-mcp refresh chrome-devtools           # re-fetch and cache the tool schemas
+```
+
+Registering the router with a client is not this CLI's job: the omega Claude plugin declares it once, in its `.mcp.json`.
+
+## Environment
+
+| Variable | What it does |
+|---|---|
+| `OMEGA_CDP_PORT` | The port `chrome-devtools-electron` attaches to (default `9222`) |
+| `OMEGA_EXTENSION_PATH` | The unpacked extension directory `chrome-devtools-extension` loads |
+| `MCP_ROUTER_SERVERS_DIR` | Overrides the overlay servers dir (tests, power users) |
+| `MCP_ROUTER_ENV_FILE` | Overrides the overlay `.env` path |
+| `MCP_ROUTER_SPAWN_TIMEOUT_MS` | How long a cold spawn (or either refresh surface's one-shot: `router__refresh_upstream` and `omega-mcp refresh` share one helper) gets to finish the MCP handshake before it is given up on (default `30000`) |
+| `MCP_ROUTER_IDLE_MS` | How long an upstream's child may sit with no call before the router closes it; the sweep runs at a quarter of it, floored at a second (default `900000`) |
+
+### Placeholders
+
+An upstream's `command`, `args`, and `env` may carry `${NAME}` placeholders, resolved from `~/.omega/mcp-router/.env` first and then the environment — so a token lives in the `.env`, never in a config file. **`${NAME:-default}` takes the same lookups** and falls back to the literal default when they all miss, so an optional value needs no `sh -c` wrapper around the command; other shell forms (`${VAR:+…}`) pass through untouched.
+
+One name is reserved: **`${MCP_ROUTER_ROOT}`** always resolves to this package's root directory, before any `.env` or environment lookup. It is how a bundled upstream points at a launcher script the package ships with, wherever the package is installed.
+
+## Docs
+
+The full guide — architecture, the launchers, the plugin wiring, the noted gaps — is [docs/mcp-router/index.md](../../docs/mcp-router/index.md) in the OMEGA monorepo.
+
+## License
+
+[Elastic License 2.0](LICENSE). The source is free to use and modify; a license key unlocks payments in production deploys and removes the attribution (local dev and test payments are always free); and you may not offer `@omega.js/mcp-router` to third parties as a hosted or managed service.

package/bin/mcp-router.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * The router bin — `npx -y @omega.js/mcp-router` picks the bin whose name
+ * matches the unscoped package name, so THIS is the one the plugin's
+ * .mcp.json launches. Requiring the module starts the stdio server.
+ */
+
+if (!require('../src/ensure-deps.js').ensureDeps()) process.exit(1);
+require('../src/router.js');

package/bin/omega-mcp.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * The management CLI bin — `omega-mcp list|enable|disable|add|remove|refresh`.
+ * Requiring the module runs the command named by argv.
+ */
+
+if (!require('../src/ensure-deps.js').ensureDeps()) process.exit(1);
+require('../src/cli.js').main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@omega.js/mcp-router",
+  "version": "0.1.0",
+  "description": "One lazy MCP endpoint for every OMEGA session \u2014 a stdio server that proxies many upstream MCP servers and surfaces each upstream's tools only once it is activated",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/router.js",
+  "bin": {
+    "mcp-router": "./bin/mcp-router.js",
+    "omega-mcp": "./bin/omega-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "servers/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --require @omega.js/devkit/test/stdout-guard --test test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@omega.js/devkit": "*"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "omega",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude"
+  ],
+  "author": "ITW Creative Works",
+  "license": "Elastic-2.0"
+}