dynmcp 0.3.1 → 0.4.1

package/README.md

@@ -2,26 +2,20 @@
 
 A proxy MCP that exposes meta-tools so agents can discover and call upstream MCP tools on demand, without loading every tool schema into the context window.
 
-## The Problem
+**Full documentation:** [dynamicmcp.tools](https://dynamicmcp.tools)
 
-Large MCPs routinely expose tens to hundreds of tools. When several are active at once, every tool schema is injected into the context window on every request regardless of relevance — degrading decision quality and consuming tokens unnecessarily. For any given task, only a small subset of tools is actually relevant.
+## Features
 
-## How It Works
+- **Two meta-tools instead of N.** Wraps one or more upstream MCPs and exposes only `discover_tool` and `use_tool` to the agent. Full schemas of irrelevant tools never enter context.
+- **Dynamic discovery of whole MCPs.** Mark MCPs with a `description` in your config and they stay disconnected until the agent calls `load_mcp` — deferring entire MCP catalogs out of context until they are actually needed.
+- **Full-fidelity proxying.** Resources, prompts, completion, logging, notifications, cancellation, progress, and server-initiated requests (sampling, elicitation, roots) pass through unchanged.
+- **Multiple transports for upstreams.** `stdio` child processes, `streamable-http`, and `sse` — all in one config.
+- **JSON or YAML config** with shell-style `${VAR}` and `${VAR:-default}` environment variable interpolation.
+- **Local-only.** Single Node.js process speaking MCP over stdio. No daemon, no remote endpoint.
 
-`dynmcp` sits in front of one or more upstream MCPs and exposes exactly two tools:
+## Getting Started
 
-- **`discover_tool`** — its description contains a compact catalog of every upstream tool (name and one-line summary). Call it with a tool name to get that tool's full schema: description, parameters, types, and required fields.
-- **`use_tool`** — executes a tool by name, proxying the call to the upstream MCP and returning its output unchanged.
-
-The agent workflow: scan the catalog in `discover_tool`'s description to find relevant tools, call `discover_tool` to load the full schema of the one it needs, then call `use_tool` to execute it. Full schemas of tools the agent never needs never enter the context window.
-
-## Usage
-
-Requires Node.js >= 20.
-
-### Single MCP (quick start)
-
-Prefix any MCP invocation with `dynmcp --`:
+### Wrap a single upstream MCP
 
 ```bash
 # Before — tool schemas go straight into context
@@ -31,29 +25,15 @@ npx -y chrome-devtools-mcp@latest
 npx dynmcp@latest -- npx -y chrome-devtools-mcp@latest
 ```
 
-Everything after `--` is the command used to launch the upstream MCP. Tool names are exposed as-is (no namespace prefix).
-
-### Multiple MCPs (config file)
-
-To proxy several MCPs at once, create a config file:
-
-```bash
-# Auto-discover mcp.json or .mcp.json in cwd
-npx dynmcp@latest
-
-# Or specify explicitly
-npx dynmcp@latest --config ./my-config.json
-```
-
-When using a config file, tool names are namespaced as `<mcp-name>/<tool-name>` to avoid collisions.
+Everything after `--` is the command used to launch the upstream MCP. In this mode tool names are exposed as-is (no namespace prefix).
 
-## Config File
+### Proxy multiple MCPs from a config file
 
-The config file declares upstream MCPs under a top-level `mcp` key. Three transport types are supported:
+Create a `mcp.json` in your project root:
 
 ```json
 {
-  "$schema": "https://unpkg.com/dynmcp/schema/mcp-config.json",
+  "$schema": "https://dynamicmcp.tools/config.json",
   "mcp": {
     "chrome-devtools": {
       "transport": "stdio",
@@ -64,127 +44,51 @@ The config file declares upstream MCPs under a top-level `mcp` key. Three transp
       "transport": "stdio",
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
-    },
-    "aws-knowledge": {
-      "transport": "streamable-http",
-      "url": "https://knowledge-mcp.global.api.aws"
-    },
-    "remote-sse": {
-      "transport": "sse",
-      "url": "https://example.com/sse",
-      "headers": {
-        "Authorization": "Bearer my-token"
-      }
     }
   }
 }
 ```
 
-YAML is also supported (use `.yml` or `.yaml` extension).
-
-### Transport Types
-
-| Transport | Fields | Description |
-|---|---|---|
-| `stdio` | `command`, `args?`, `env?` | Spawns the MCP as a child process |
-| `streamable-http` | `url`, `headers?` | Connects to a remote MCP over HTTP |
-| `sse` | `url`, `headers?` | Connects to a remote MCP over Server-Sent Events |
+Then run:
 
-### Config Discovery
-
-When no `--` command is provided, `dynmcp` looks for a config file in this order:
-
-1. Path from `-c` / `--config` flag
-2. `mcp.json` in the current directory
-3. `.mcp.json` in the current directory
+```bash
+# Auto-discover mcp.json or .mcp.json
+npx dynmcp@latest
 
-### Naming Rules
+# Or specify explicitly
+npx dynmcp@latest --config ./my-config.json
+```
 
-MCP names (the keys in the config) must match `^[a-z0-9][a-z0-9-]*$`.
+In config-file mode tool names are namespaced as `<mcp-name>/<tool-name>` to avoid collisions.
 
-## Environment Variable Interpolation
+## Dynamic Discovery
 
-Config files can reference environment variables in any string-typed leaf value using shell-style syntax. This is useful for keeping secrets (bearer tokens, API keys) and host-specific values (paths, ports) out of the config file itself.
+For configs with heavier MCPs you only sometimes need (Chrome DevTools, remote APIs, anything expensive to keep open), give the entry a `description`. That MCP becomes *lazy*: `dynmcp` doesn't open the connection at startup, and the agent only sees a short summary of what the MCP does. When the agent decides it actually needs that MCP, it calls `load_mcp` with the server's name and the connection opens on demand.
 
 ```json
 {
+  "$schema": "https://dynamicmcp.tools/config.json",
   "mcp": {
-    "remote": {
-      "transport": "streamable-http",
-      "url": "${MCP_URL:-https://example.com/mcp}",
-      "headers": {
-        "Authorization": "Bearer ${MCP_TOKEN}"
-      }
+    "filesystem": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "chrome-devtools": {
+      "description": "Chrome browser automation and DevTools control. Navigate pages, take screenshots, inspect the DOM, run JavaScript. Use when you need to interact with or debug a live web page.",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
     }
   }
 }
 ```
 
-### Syntax
-
-| Form | Behavior |
-|---|---|
-| `${VAR}` | Replaced with the value of `VAR`. Hard error at startup if `VAR` is undefined. |
-| `${VAR:-default}` | Replaced with `VAR` if set and non-empty, otherwise the literal `default` (may contain spaces, colons, etc.). |
-| `$${...}` | Escape — emits a literal `${...}` with no interpolation. |
-
-Interpolation only applies to **leaf string values** inside the `mcp` map (and nested objects/arrays within it). Map keys, the top-level `$schema` field, and the top-level `env` field are never interpolated. Partial-string interpolation works — `"Bearer ${TOKEN}"` is valid.
-
-If any referenced variables are missing without a default, `dynmcp` exits at startup with an error listing **all** of them at once (not one at a time).
+`filesystem` connects at startup. `chrome-devtools` stays lazy until the agent loads it. Once loaded, it behaves exactly like an eager MCP for the rest of the session.
 
-### Sources (`env` field)
-
-A top-level `env` field controls where variables are read from:
-
-| Value | Behavior |
-|---|---|
-| `"enable"` (default) | Loads `.env` file (if present) and merges with `process.env`. `.env` values take precedence over `process.env` for the same key. |
-| `"dotenv"` | Loads from `.env` file only. `process.env` is ignored. |
-| `"process"` | Reads from `process.env` only. No `.env` file is loaded. |
-| `"disable"` | Disables interpolation entirely — `${VAR}` is left literal. |
-
-```json
-{
-  "env": "process",
-  "mcp": { /* ... */ }
-}
-```
+See the [Dynamic Discovery guide](https://dynamicmcp.tools/guides/dynamic-discovery/) for the capability caveat, the retry budget, and tips on writing descriptions agents can act on.
 
-### `.env` File Discovery
+---
 
-By default, `dynmcp` looks for a file literally named `.env` in the current working directory. To use a different path, pass `--env` / `-e`:
+Full [docs](https://dynamicmcp.tools) cover environment variable interpolation, all transport options, and the complete CLI reference.
 
-```bash
-dynmcp --env ./secrets.env
-```
-
-Combining `--env` with `env: "disable"` or `env: "process"` is rejected as incoherent (no `.env` would be loaded). If `--env` points to a file that does not exist, `dynmcp` exits with an error.
-
-## CLI Reference
-
-```
-dynmcp [options] [-- <upstream-command> [upstream-args...]]
-```
-
-| Flag | Short | Description |
-|---|---|---|
-| `--version` | `-v` | Print the package version and exit |
-| `--help` | `-h` | Print usage information and exit |
-| `--config <path>` | `-c` | Path to config file (JSON or YAML) |
-| `--env <path>` | `-e` | Path to a custom `.env` file for variable interpolation |
-| `--` | | Everything after is the upstream MCP command (single-MCP mode) |
-
-### Mode Resolution
-
-1. If `--` is present, single-MCP mode is used (config file is ignored).
-2. Otherwise, config file mode is used.
-
-## Development
-
-```bash
-npm install
-npm run build       # Compile to dist/
-npm run typecheck   # Type-check without emitting
-npm run check       # Biome lint + format
-npm test            # Run tests
-```