@nimrobo/mcporter-remote 0.1.0

package/docs/cli-generator.md

@@ -0,0 +1,116 @@
+---
+summary: 'Goals and requirements for mcporter generate-cli, including outputs, runtimes, and schema-aware UX.'
+read_when:
+  - 'Changing generate-cli behavior or bundler integrations'
+---
+
+# CLI Generator Plan
+
+Default behavior: generating `<server>.ts` in the working directory if no output path is provided. Bundling is opt-in via `--bundle` and produces a single JS file with shebang; otherwise we emit TypeScript targeting Node.js. Rolldown handles bundling by default unless the runtime resolves to Bun—in that case Bun’s native bundler is selected automatically (still requires `--runtime bun` or Bun auto-detection); `--bundler` lets you override either choice.
+
+## Goal
+Create an `mcporter generate-cli` command that produces a standalone CLI for a single MCP server. The generated CLI should feel like a Unix tool: subcommands map to MCP tools, arguments translate to schema fields, and output can be piped/redirected easily.
+
+## High-Level Requirements
+- **Input**: Identify the target server either by shorthand name or by providing an explicit MCP server definition.
+- **Output**: Emit a TypeScript file (ESM) targeting Node.js by default (`<server>.ts` unless `--output` overrides). Bundling to a standalone JS file happens only when `--bundle` is passed.
+- **Runtime Selection**: Prefer Bun when it is available (`bun --version` succeeds); otherwise fall back to Node.js. Callers can force either runtime via `--runtime bun|node`.
+- **Schema-Aware CLI**: Leverage `createServerProxy` to map positional/flag arguments to MCP tool schemas, including defaults and required validation.
+- **Unix-Friendly Output**: Provide `--output text|json|markdown|raw` flags so results can be piped; default to human-readable text. Include `--timeout` (default 30s) to cap call duration.
+- **Shell Completion (optional)**: Generate completion scripts for bash/zsh/fish if requested.
+- **Documentation**: Update README (or similar) to show how to generate and use the CLI.
+
+## Steps
+1. **Command Scaffolding**
+   - Add `generate-cli` subcommand to the existing CLI.
+   - Parse flags: `--server`, `--name`, `--command`, optional `--description`, plus `--output`, `--runtime=node|bun`, `--bundle`, `--bundler=rolldown|bun`, `--minify`, `--compile`, `--include-tools`, `--exclude-tools`, etc. Runtime auto-detects Bun when available, and the bundler inherits that choice unless overridden.
+   - Optional `--include-tools` / `--exclude-tools` flags allow generating a CLI that exposes only a subset of tools (mutually exclusive).
+2. **Server Resolution**
+   - If `--server` matches a configured name (via `loadServerDefinitions`), use that server definition.
+   - Otherwise, if the value looks like a file path, load a Cursor-style JSON definition from disk.
+   - Otherwise, attempt to parse inline JSON/JSON5.
+   - When `--command` (or the first positional argument) looks like a shell command (contains whitespace), split it into `command` + `args` and treat it as stdio. Otherwise, normalize HTTP selectors (`https://`, `http://`, or `host/path.tool`) so `generate-cli mcp.context7.com/mcp` autoconfigures an HTTP transport.
+   - Validate that a definition is found; prompt on failure.
+3. **Tool Introspection**
+   - Use `listTools(server, { includeSchema: true })` to inspect MCP tool schemas.
+   - For each tool, extract required/optional arguments, types, and defaults.
+4. **Template Generation**
+   - Build a template (probably EJS or string interpolation) that:
+     - Imports `createRuntime` and `createServerProxy`.
+     - Creates a CLI (likely using `commander` or a minimal custom parser) with subcommands per tool.
+     - Bakes in server metadata (command/url, headers, etc.) or references config path if preferred.
+     - Adds output-format handling.
+   - Include `package.json` scaffolding if `--bundle` or `--package` is set.
+5. **Optional Bundling**
+   - If requested, run Rolldown (default when targeting Node) or Bun’s bundler (default when the runtime is Bun, or when `--bundler bun` is passed) to emit a single JS file with shebang (Node or Bun), with optional minification.
+   - When targeting Bun, allow `--compile` to delegate to `bun build --compile` and generate a self-contained binary. Bun bundling requires staging the template inside the package tree so dependencies resolve even when invoked from empty directories.
+   - Otherwise, leave as TypeScript/ESM and document how to run (`node path/to/cli.js` or `bun path/to/cli.ts`).
+6. **Testing**
+   - Add generator unit tests (snapshot the emitted CLI for known schemas).
+   - Add integration tests that run the generated script against a mock MCP server.
+7. **Docs/Examples**
+   - Document usage in README.
+   - Provide an example generated CLI under `examples/generated/<server>.ts` (if we keep an examples directory).
+
+## Notes
+- Generated CLI depends on the latest `commander` for argument parsing.
+- Default timeout for tool calls is 30 seconds, overridable via `--timeout`.
+- Runtime flag remains (`--runtime bun`) to tailor shebang/usage instructions, but Node.js is the default.
+- Generated CLI embeds the resolved server definition and always targets that snapshot (no external `--config` or `--server` overrides at runtime).
+
+## Usage Examples
+
+```bash
+# Minimal: infer the name from the command URL and emit TypeScript (optionally bundle)
+npx mcporter generate-cli \
+  --command https://mcp.context7.com/mcp \
+  --minify
+
+# Provide explicit name/description and compile a Bun binary (falls back to Node if Bun missing)
+npx mcporter generate-cli \
+  --name context7 \
+  --command https://mcp.context7.com/mcp \
+  --description "Context7 docs MCP" \
+  --runtime bun \
+  --compile
+
+chmod +x context7
+./context7
+  # show the embedded help + tool list
+
+# Shareable "one weird trick" for chrome-devtools (no config required)
+npx mcporter generate-cli --command "npx -y chrome-devtools-mcp@latest"
+
+- `--minify` shrinks the bundled output via the selected bundler (output defaults to `<server>.js`).
+- `--compile [path]` implies bundling and invokes `bun build --compile` to create the native executable (Bun only). When you omit the path, the compiled binary inherits the server name.
+- Use `--server '{...}'` when you need advanced configuration (headers, env vars, stdio commands, OAuth metadata).
+- Omit `--name` to let mcporter infer it from the command URL (for example, `https://mcp.context7.com/mcp` becomes `context7`).
+- When targeting an existing config entry, you can skip `--server` and pass the name as a positional argument:
+  `npx mcporter generate-cli linear --bundle dist/linear.js`.
+- When the MCP server is a stdio command, you can also skip `--command` by quoting the inline command as the first positional argument (e.g., `npx mcporter generate-cli "npx -y chrome-devtools-mcp@latest"`).
+- Narrow the CLI to a specific subset of tools with `--include-tools`:
+  `npx mcporter generate-cli linear --include-tools issues_list,issues_create`.
+- Hide debug or admin tools with `--exclude-tools`:
+  `npx mcporter generate-cli linear --exclude-tools debug_tool,admin_reset`.
+```
+
+
+
+## Artifact Metadata & Regeneration
+
+- Every generated artifact embeds its metadata (generator version, resolved server definition, invocation flags). A hidden `__mcporter_inspect` subcommand prints the payload without contacting the MCP server, so binaries remain self-describing even after being copied to another machine.
+- `mcporter inspect-cli <artifact>` shells out to that embedded command and prints a human summary (pass `--json` for raw output). The summary includes a ready-to-run `generate-cli` command you can reuse directly.
+- `mcporter generate-cli --from <artifact>` replays the stored invocation against the latest mcporter build. `--server`, `--runtime`, `--timeout`, `--minify/--no-minify`, `--bundle`, `--compile`, `--output`, and `--dry-run` let you override specific pieces of the stored metadata when necessary.
+- Because the metadata lives inside the artifact, any template, bundle, or compiled binary can be refreshed after a generator upgrade without juggling sidecar files.
+
+
+
+## Status
+- ✅ `generate-cli` subcommand implemented with schema-aware proxy generation.
+- ✅ Inline JSON / file / shorthand server resolution wired up.
+- ✅ Bundling via Rolldown by default (or Bun automatically when the runtime is Bun, with `--bundler` available for overrides) plus optional minification and Bun bytecode compilation.
+- ✅ Integration tests cover bundling, minification, compiled binaries, and metadata/regeneration flows against the mock MCP server.
+
+Next steps:
+1. Add optional shell completion scaffolding if demand arises.
+2. Explore templated TypeScript definitions for generated CLIs to improve editor tooling.

package/docs/cli-reference.md

@@ -0,0 +1,76 @@
+---
+summary: 'Quick reference for mcporter subcommands, their arguments, and shared global flags.'
+read_when:
+  - 'Need a refresher on available CLI commands'
+---
+
+# mcporter CLI Reference
+
+A quick reference for the primary `mcporter` subcommands. Each command inherits
+`--config <file>` and `--root <dir>` to override where servers are loaded from.
+
+## `mcporter list [server]`
+- Without arguments, lists every configured server (with live discovery + brief
+  status).
+- With a server name, prints TypeScript-style signatures for each tool, doc
+  comments, and optional summaries.
+- Hidden alias: `list-tools` (kept for muscle memory; not advertised in help output).
+- Hidden ad-hoc flag aliases: `--sse` for `--http-url`, `--insecure` for `--allow-http` (for plain HTTP testing).
+- Flags:
+  - `--all-parameters` – include every optional parameter in the signature.
+  - `--schema` – pretty-print the JSON schema for each tool.
+  - `--timeout <ms>` – per-server timeout when enumerating all servers.
+
+## `mcporter call <server.tool>`
+- Invokes a tool once and prints the response; supports positional arguments via
+  pseudo-TS syntax and `--arg` flags.
+- Useful flags:
+  - `--server`, `--tool` – alternate way to target a tool.
+  - `--timeout <ms>` – override call timeout (defaults to `CALL_TIMEOUT_MS`).
+  - `--output text|markdown|json|raw` – choose how to render the `CallResult`.
+  - `--save-images <dir>` – persist image content blocks to files under the specified directory.
+  - `--raw-strings` – disable numeric coercion for flag-style and positional values.
+  - `--no-coerce` – disable all flag-style/positional value coercion.
+  - `--tail-log` – stream tail output when the tool returns log handles.
+
+## `mcporter generate-cli`
+- Produces a standalone CLI for a single MCP server (optionally bundling or
+  compiling with Bun).
+- Key flags:
+  - `--server <name>` (or inline JSON) – choose the server definition.
+  - `--command <url|command>` – point at an ad-hoc HTTP endpoint (include `https://` or use `host/path.tool`) or a stdio command (anything with spaces, e.g., `"npx -y chrome-devtools-mcp@latest"`). If you omit `--command`, the first positional argument is inspected: whitespace → stdio, otherwise the parser probes for HTTP/HTTPS and falls back to config names.
+  - `--output <path>` – where to write the TypeScript template.
+  - `--bundle <path>` – emit a bundle (Node/Bun) ready for `bun x`.
+  - `--bundler rolldown|bun` – pick the bundler implementation (defaults to Rolldown unless the runtime resolves to Bun, in which case Bun’s bundler is used automatically; still requires a local Bun install).
+  - `--compile <path>` – compile with Bun (implies `--runtime bun`).
+  - `--include-tools <a,b,c>` – only generate subcommands for the specified tools (exact MCP tool names). It is an error if any requested tool is missing.
+  - `--exclude-tools <a,b,c>` – generate subcommands for every tool except the ones listed. Unknown tool names are ignored. If all tools are excluded, generation fails.
+  - `--include-tools` and `--exclude-tools` are mutually exclusive.
+  - `--timeout <ms>` / `--runtime node|bun` – shared via the generator flag
+    parser so defaults stay consistent.
+  - `--from <artifact>` – reuse metadata from an existing CLI artifact (legacy
+    `regenerate-cli` behavior, must point at an existing CLI).
+  - `--dry-run` – print the resolved `mcporter generate-cli ...` command without
+    executing (requires `--from`).
+  - Positional shorthand: `npx mcporter generate-cli linear` uses the configured
+    `linear` definition; `npx mcporter generate-cli https://example.com/mcp`
+    treats the URL as an ad-hoc server definition.
+
+## `mcporter emit-ts <server>`
+- Emits TypeScript definitions (and optionally a ready-to-use client) describing
+  a server’s tools. This reuses the same formatter as `mcporter list` so doc
+  comments, signatures, and examples stay in sync.
+- Modes:
+  - `--mode types --out <file.d.ts>` (default) – export an interface whose
+    methods return `Promise<CallResult>`, with doc comments and optional
+    summaries.
+  - `--mode client --out <file.ts>` – emit both the interface (`<file>.d.ts`)
+    and a factory that wraps `createServerProxy`, returning objects whose
+    methods resolve to `CallResult`.
+- Other flags:
+  - `--include-optional` (alias `--all-parameters`) – show every optional field.
+  - `--types-out <file>` – override where the `.d.ts` sits when using client
+    mode.
+
+For more detail (behavioral nuances, OAuth flows, etc.), see `docs/spec.md` and
+command-specific docs under `docs/`.

package/docs/config.md

@@ -0,0 +1,208 @@
+---
+summary: 'How mcporter discovers, merges, and mutates configuration files (project + home + imports), including OAuth and persistence.'
+read_when:
+  - 'Working on config resolution, imports, or mcporter config subcommands'
+---
+
+# CLI Help Menu Snapshot
+```
+mcporter config
+Usage: mcporter config [options] <command>
+
+Manage configured MCP servers, imports, and ad-hoc discoveries.
+
+Commands:
+  list [options] [filter]        Show merged servers (local + imports + ad-hoc cache)
+  get <name>                     Inspect a single server with resolved source info
+  add [options] <name> [target]  Persist a server definition (URL or stdio command)
+  remove [options] <name>        Delete a local entry or copy from an import
+  import <kind> [options]        Copy entries from cursor/claude/codex/etc. into config
+  login <name|url>               Complete OAuth/auth flows for a server
+  logout <name>                  Clear cached credentials for a server
+  doctor [options]               Validate config files and report common mistakes
+  help [command]                 Show CLI or subcommand help
+
+Global Options:
+  --config <path>                Use an explicit config file (default: config/mcporter.json)
+  --root <dir>                   Set project root for import discovery (default: cwd)
+  --json                         Emit machine-readable output when supported
+  -h, --help                     Display help for mcporter config
+
+Run `mcporter config help add` to see transport flags, ad-hoc persistence tips, and schema docs.
+See https://github.com/sweetistics/mcporter/blob/main/docs/config.md for config anatomy, import precedence, and troubleshooting guidance.
+```
+
+# Configuration Guide
+
+## Overview
+mcporter keeps three configuration buckets in sync: repository-scoped JSON (`config/mcporter.json`), imported editor configs (Cursor, Claude, Codex, Windsurf, OpenCode, VS Code), and ad-hoc definitions supplied on the CLI. This guide explains how those sources merge, how to mutate them with `mcporter config ...`, and the safety rails around OAuth, env interpolation, and persistence.
+
+## Quick Start
+1. Create `config/mcporter.json` at the repo root:
+   ```jsonc
+   {
+     "$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
+     "mcpServers": {
+       "linear": {
+         "description": "Linear issues",
+         "baseUrl": "https://mcp.linear.app/mcp",
+         "headers": { "Authorization": "Bearer ${LINEAR_API_KEY}" }
+       }
+     },
+     "imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]
+   }
+   ```
+   The `$schema` property enables IDE autocomplete and validation. Use the raw GitHub URL for the latest schema, or copy `mcporter.schema.json` locally.
+2. Run `mcporter list linear` (or `mcporter config list linear`) to make sure the runtime can reach it.
+3. Use `mcporter config add shadcn https://www.shadcn.io/api/mcp` to persist another server without editing JSON.
+4. Authenticate any OAuth-backed server with either `mcporter auth <name>` or `mcporter config login <name>`; tokens land under `~/.mcporter/<name>/` unless you override `tokenCacheDir`.
+
+## Config Resolution Order
+
+mcporter now merges home and project config files by default so global servers stay available inside repos. The order depends on how you invoke the CLI:
+
+1. If you pass `--config <file>` (or set `--config` programmatically), only that file is used—no merging.
+2. If `MCPORTER_CONFIG` is set, only that file is used—no merging.
+3. Otherwise, mcporter loads both of these layers (when present):
+   - `~/.mcporter/mcporter.json` or `~/.mcporter/mcporter.jsonc`
+   - `<root>/config/mcporter.json`
+   Entries from the project file override entries with the same name from the home file. Each layer still pulls in its own imports before merging.
+
+All `mcporter config …` mutations still write back to a single file: the explicit path when provided; otherwise the project config path (`<root>/config/mcporter.json`). To edit the home file explicitly, run commands like `mcporter config --config ~/.mcporter/mcporter.json add <name> …` or set `MCPORTER_CONFIG` in your shell profile.
+
+## Discovery & Precedence
+mcporter builds a merged view of all known servers before executing any command. The sources load in this order:
+
+| Priority | Source | Notes |
+| --- | --- | --- |
+| 1 | Explicit `--http-url`, `--stdio`, or bare URL passed to commands | Highest priority, never cached unless `--persist` is supplied. Requires `--allow-http` for plain HTTP URLs. |
+| 2 | `config/mcporter.json` (or the file passed via `--config`) | Default path is `<root>/config/mcporter.json`; missing file returns an empty config so commands continue to work. |
+| 3 | Imports listed in `"imports"` | When you omit `imports`, mcporter loads `['cursor','claude-code','claude-desktop','codex','windsurf','opencode','vscode']`. When you specify a non-empty array, mcporter appends any omitted defaults after your list so shared presets remain available. |
+
+Rules:
+- Later sources never override earlier ones. Local config always wins over imports; ad-hoc descriptors override both for the duration of a command.
+- Each merged server tracks its origin (local path vs. import path), so `mcporter config get <name>` can show you the path before you edit or remove the local copy with `mcporter config remove <name>`.
+- Imports remain read-only until you explicitly copy an entry via `mcporter config import <kind> --copy` or run `mcporter config add --copy-from claude-code:linear` (feature planned alongside the CLI work).
+
+## CLI Workflows
+`mcporter config` is the entry point for reading and writing configuration files. Use the existing ad-hoc flags on `mcporter list|call|auth` when you want ephemeral definitions; once you’re ready to persist them, switch back to `mcporter config add`.
+
+Use `--scope home|project` with `mcporter config add` to pick the write target explicitly. `project` is always the default (creating `config/mcporter.json` if needed); `home` writes to `~/.mcporter/mcporter.json` even when a project config is present. `--persist <path>` still takes precedence when you need a custom file.
+
+### `mcporter config list [filter]`
+- Shows **local** entries by default. Pass `--source import` to list imported editor configs, or `--json` for machine output.
+- Always appends a summary of other config files (paths, counts, sample names) so you know where imported entries live.
+- `filter` accepts a name, glob fragment, or `source:cursor` selector.
+- Adds informational notes when we auto-correct names (same machinery as `mcporter list`).
+
+### `mcporter config get <name>`
+- Prints the resolved definition for a single server, including the on-disk path, inherited headers/env, and transport details.
+- Near-miss names are auto-corrected with the same heuristics as `mcporter list`/`call`, and you’ll see suggestions whenever ambiguity remains.
+- Supports ad-hoc descriptors so you can inspect a URL before persisting it.
+
+### `mcporter config add <name> [target]`
+- Persists a server into the writable config file. Accepts both positional shortcuts (`mcporter config add sentry https://mcp.sentry.dev/mcp`) and flag-driven definitions:
+  - `--transport http|sse|stdio`
+  - `--url` or `--command`/`--stdio`
+  - `--env`, `--header`, `--token-cache-dir`, `--description`, `--tag`, `--client-name`, `--oauth-redirect-url`
+  - `--copy-from importKind:name` to clone settings from an imported entry before editing.
+- `--dry-run` shows the JSON diff without writing, while `--persist <path>` overrides the destination file.
+
+### `mcporter config remove <name>`
+- Removes the local definition. Names sourced exclusively from imports remain untouched until you copy them locally.
+
+### `mcporter config import <kind>`
+- Displays (and optionally copies) entries from editor-specific configs:
+  - `cursor`: `.cursor/mcp.json` in the repo, falling back to `~/.config/Cursor/User/mcp.json` (or `%APPDATA%/Cursor/User` on Windows).
+  - `claude-code`: `<root>/.claude/settings.local.json`, `<root>/.claude/settings.json`, `<root>/.claude/mcp.json`, then `~/.claude/settings.json`, `~/.claude/mcp.json`, `~/.claude.json`. `settings.local.json` is meant for untracked per-developer overrides, while `settings.json` is the shared project config.
+  - `claude-desktop`: platform-specific `Claude/claude_desktop_config.json` paths.
+  - `codex`: `<root>/.codex/config.toml`, then `~/.codex/config.toml`.
+  - `windsurf`: Codeium’s Windsurf config under `%APPDATA%/Codeium/windsurf/mcp_config.json` or `~/.codeium/windsurf/mcp_config.json`.
+  - `opencode`: Honors `OPENCODE_CONFIG` when set, then `<root>/opencode.json(c)`, `OPENCODE_CONFIG_DIR/opencode.json(c)`, and finally `${XDG_CONFIG_HOME:-~/.config}/opencode/opencode.json(c)` (or `%APPDATA%/opencode/opencode.json(c)` on Windows). Both `.json` and `.jsonc` extensions are supported.
+  - `vscode`: `Code/User/mcp.json` (stable + Insiders) inside the OS-appropriate config directory.
+- `--copy` writes selected entries into your local config; `--filter <glob>` narrows the import list; `--path <file>` lets you point at bespoke locations.
+
+### `mcporter config login <name|url>` / `logout`
+- Mirrors `mcporter auth`. `login` completes OAuth (or token provisioning) for either a named server or an ad-hoc URL. When a hosted MCP returns 401/403, mcporter automatically promotes that target to OAuth and re-runs the flow, matching the behavior documented in `docs/adhoc.md`.
+- `--browser none` starts a manual remote-friendly OAuth flow: mcporter prints the authorization URL, does not open a browser, and does not bind a local callback server.
+- Finish manual flows with `mcporter auth complete '<pasted-redirect-url>'`. The pasted callback must contain the same OAuth `state` that mcporter persisted when the flow started.
+- `logout` wipes token caches under `~/.mcporter/<name>/` (or the custom `tokenCacheDir`). Pass `--all` to clear everything.
+
+### `mcporter config doctor`
+- Early validator that checks for simple issues (e.g., OAuth entries missing cache paths). Future iterations will add fixes for Accept headers, duplicate imports, and more.
+
+## Ad-hoc & Persistence
+- `--http-url` and `--stdio` flags live on `mcporter list|call|auth`, keeping `mcporter config` focused on persistent config files.
+- Names default to slugified hostnames or executable/script combos. Supply `--name` to improve reuse; mcporter uses that slug for OAuth caches even before persistence.
+- `--allow-http` is mandatory for cleartext endpoints so we never downgrade transport silently.
+- Add `--persist <path>` (defaulting to `config/mcporter.json` when omitted) to copy the ad-hoc definition into config. We reuse the same serializer as the import pipeline, so copying from Cursor → local config produces identical structure and preserves custom env/header fields.
+- `--env KEY=VAL` entries merge with existing `env` dictionaries if you later persist the same server; nothing is lost when you alternate between CLI flags and JSON edits.
+
+## JSON Schema for IDE Support
+mcporter provides a JSON Schema for config file validation and autocompletion. Add the `$schema` property to your config file:
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
+  "mcpServers": { ... }
+}
+```
+
+For local development, you can reference the schema from the repo root:
+```jsonc
+{
+  "$schema": "../mcporter.schema.json",
+  "mcpServers": { ... }
+}
+```
+
+The schema is auto-generated from the Zod validation schemas using `pnpm generate:schema`.
+
+## Schema Reference
+Top-level structure:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `mcpServers` | object | Map of server names → definitions. Required even if empty. |
+| `imports` | string[] | Optional list of import kinds. Empty array disables imports entirely; omitting the key falls back to the default list. |
+
+Server definition fields (subset of what `RawEntrySchema` accepts):
+
+| Field | Description |
+| --- | --- |
+| `description` | Free-form summary printed by `mcporter list`/`config list`. |
+| `baseUrl` / `url` / `serverUrl` | HTTPS or HTTP endpoint. `http://` requires `--allow-http` in ad-hoc mode but works in config if you explicitly set it. |
+| `command` / `args` | Stdio executable definition (string or array). Arrays are preferred because they avoid shell quoting issues. |
+| `env` | Key/value pairs applied when launching stdio commands. Supports `${VAR}` interpolation and `${VAR:-fallback}` defaults. Existing process env values win over fallbacks. |
+| `headers` | Request headers for HTTP/SSE transports. Values can reference `$env:VAR` or `${VAR}` placeholders, which must be set at runtime or mcporter aborts with a helpful error.
+| `auth` | Currently only `oauth` is recognized. Any other string is ignored (treated as undefined) to avoid stale state from other clients. |
+| `tokenCacheDir` | Directory for OAuth tokens; still honored, but mcporter now keeps a centralized vault in `~/.mcporter/credentials.json` (legacy per-server caches are auto-migrated). Supports `~` expansion. |
+| `clientName` | Optional identifier some servers use for telemetry/audience segmentation. |
+| `oauthRedirectUrl` | Override the default localhost callback. Useful when tunneling OAuth through Codespaces or remote dev boxes. |
+| `oauthScope` | Optional explicit OAuth scope string. If omitted, mcporter lets the MCP SDK derive scope from server/auth metadata. Use this as an escape hatch for providers that require explicit scopes but don’t publish `scopes_supported`. |
+| `oauthCommand.args` | For STDIO servers that ship a custom auth subcommand (e.g., Gmail MCP). mcporter will spawn the stdio command with these args when you run `mcporter auth <name>`, so you don’t need to call `npx ... auth` manually. |
+
+mcporter normalizes headers to include `Accept: application/json, text/event-stream` automatically, matching the runtime’s streaming expectations.
+
+## Imports & Conflict Resolution
+- `pathsForImport(kind, rootDir)` determines every candidate path. mcporter searches the repo first, then user-level directories, and stops at the first file that parses.
+- Entries pulled from imports are treated as read-only snapshots. The merge process keeps the first definition for each name; later sources with the same name are skipped until you override locally.
+- To copy an imported entry, either run `mcporter config import <kind> --copy --filter name` or use `mcporter config add name --copy-from kind:name`. The copy operation writes through the same JSON normalization stack, so the resulting file matches our schema even if the source format was TOML (Codex) or legacy JSON shapes (`servers` vs `mcpServers`).
+
+## Project vs. Machine Layers
+- Keep `config/mcporter.json` under version control. Encourage contributors to add sensitive data via env vars (`${LINEAR_API_KEY}`) rather than inline secrets.
+- Machine-specific additions can live in `~/.mcporter/local.json`; point `mcporter config --config ~/.mcporter/local.json add ...` there when you prefer not to touch the repo. Since the runtime only watches one config at a time, CI jobs should always pass `--config config/mcporter.json` (or run from the repo root) for deterministic behavior.
+- OAuth tokens, cached server metadata, and generated CLIs should remain outside the repo (`~/.mcporter/<name>/`, `dist/`).
+
+## Validation & Troubleshooting
+- `mcporter list --http-url ...` refuses to auto-run OAuth to keep listing commands quick; use `mcporter config login ...` or `mcporter auth ...` to finish credential setup.
+- For remote pods/dev boxes, prefer `mcporter auth <name|url> --browser none`, open the printed URL in your local browser, then paste the failed localhost redirect into `mcporter auth complete`.
+- When env placeholders are missing, commands fail fast with the exact variable name. Add the variable or wrap it in `${VAR:-fallback}` to provide defaults.
+- Use `mcporter config get <name> --show-source` (planned flag) to confirm whether a server came from an import. If a teammate’s Cursor config keeps overriding your local entry, reorder the `imports` array to move Cursor later or set it to `[]` to disable imports entirely.
+- `docs/adhoc.md` covers deeper debugging, including tmux workflows and OAuth promotion logs.
+
+## Outstanding Coverage Items
+- Describe how `--persist` writes through the same import merge pipeline (especially once `mcporter config add --copy-from` ships) so users know exactly which file changes.
+- Call out that `--allow-http` remains required for cleartext URLs even in config mutations, and reiterate that `--env KEY=VAL` merges with on-disk env blocks rather than replacing them entirely.
+- Clarify and illustrate the automatic OAuth promotion path for ad-hoc HTTP entries in both this doc and future `mcporter config login` help output.
+- Flesh out `mcporter config doctor` once the validator is implemented so we can show real output samples and suggested fixes.

package/docs/daemon.md

@@ -0,0 +1,95 @@
+---
+summary: 'Design plan for the persistent MCP daemon used to keep long-lived servers (e.g., chrome-devtools) alive.'
+read_when:
+  - 'Implementing daemon/keep-alive behavior or maintaining its CLI commands.'
+---
+
+# MCPorter Daemon Plan
+
+## Goals
+
+- **Invisible keep-alive:** `mcporter call` should transparently start (and reuse) a per-login daemon whenever a configured server requires persistence (e.g., `chrome-devtools`). No extra flags for agents.
+- **Shared state:** Multiple CLI invocations/agents within the same user session must reuse the same warm transport so STDIO servers can hold tabs, cookies, and other stateful context.
+- **Per-login scope:** The daemon lives under the current user account (`~/.mcporter/daemon.sock`) and never crosses user boundaries.
+- **Resilience:** If the daemon or a keep-alive server crashes, the next CLI call restarts it automatically.
+- **Explicit shutdown:** Provide `mcporter daemon stop` to tear everything down (plus `status` for debugging).
+- **Configurable participation:** Only servers marked keep-alive participate; others keep current ephemeral behavior. Support opt-in/out via config/env plus a default allowlist.
+
+## Architecture
+
+- **Daemon process (`mcporter daemon start`):**
+  - Loads the same config as the CLI.
+  - Hosts a long-lived `McpRuntime`.
+  - Listens on a Unix domain socket (per-login path, chmod 600).
+  - Exposes a minimal JSON-RPC interface that mirrors the existing `list/call/resources` APIs so CLI commands can proxy requests.
+  - Lazily connects keep-alive servers on first use and keeps transports open until shutdown or idle timeout.
+
+- **Client shim (CLI side):**
+  - When a command targets a keep-alive server:
+    1. Look for a ready daemon socket; if missing, spawn `mcporter daemon start --detach`.
+    2. Proxy the list/call/auth request over the socket and print the response as usual.
+    3. If the socket handshake fails (daemon crashed mid-call), re-spawn once before surfacing the error.
+  - Non keep-alive servers continue using the local runtime in the current process.
+
+- **Keep-alive detection:**
+  - Extend `ServerDefinition` with `lifecycle?: "ephemeral" | { mode: "keep-alive", idleTimeoutMs?: number }`.
+  - Provide a config-level `defaultKeepAlive` array or `MCPORTER_KEEPALIVE` env var for quick overrides.
+  - Ship a hardcoded allowlist (initially `chrome-devtools`, `mobile-mcp`, `playwright`) so existing configs benefit immediately; users can opt out per server.
+
+## CLI Surface
+
+- `mcporter daemon start [--foreground]`: boot the daemon; default behavior is background (detached) launch that writes its metadata file (`~/.mcporter/daemon.json` with PID/socket).
+- `mcporter daemon status`: show whether the daemon is running, the socket path, uptime, and which servers are currently connected/idle.
+- `mcporter daemon stop`: instruct the daemon to close all transports and remove its socket/metadata; if the daemon is missing, exit 0 with a hint.
+- `mcporter daemon restart`: convenience wrapper that stops the daemon (if it exists), waits for the socket to disappear, and launches a fresh instance while reusing the same logging flags/env overrides.
+- Existing commands (`list`, `call`, `auth`, `emit-ts`, etc.) continue to work; only those touching keep-alive servers will route through the daemon.
+
+## Lifecycle & Fault Handling
+
+- **Auto start:** First call requiring the daemon triggers a lightweight bootstrap (fork/exec via `child_process.spawn` inside the CLI). We ensure the original command waits for the socket to become available (with a short timeout).
+- **Auto restart:** The client shim treats `ECONNREFUSED`/broken pipe as a signal that the daemon died. It retries once by re-launching the daemon before surfacing the error.
+- **Idle timeout:** Each keep-alive server can specify `idleTimeoutMs` (default `null` = never). The daemon tracks last activity timestamps and auto-closes transports (and associated external processes) after the idle window. A global `daemonIdleTimeoutMs` can shut down the entire daemon after long inactivity.
+- **Logging:** Daemon writes structured logs under `~/.mcporter/logs/daemon.log` plus per-server logs for STDIO stderr so users can debug crashing servers.
+
+## Testing Plan
+
+1. **Unit tests**
+   - Config parsing for the new `lifecycle` shape and env overrides.
+   - Daemon controller: socket path resolution, metadata persistence, auto-restart logic.
+2. **Integration tests (Vitest)**
+   - Spin up a fake STDIO MCP server (script under `tests/fixtures/daemon-server.ts`) that increments a counter so we can assert the transport stays alive across multiple CLI invocations.
+   - Verify `mcporter call` auto-starts the daemon, reuses the server, and `mcporter daemon stop` shuts it down.
+   - Simulate daemon crash by killing the background process and ensure the next call restarts it automatically.
+
+## Implementation Steps
+
+1. **Config/schema changes:** Update `src/config.ts` plus fixtures to accept `lifecycle`. Provide helpers like `requiresKeepAlive(definition)`.
+2. **Daemon service:** New module (e.g., `src/daemon/host.ts`) that runs the socket server, wraps `McpRuntime`, and exposes RPC handlers.
+3. **CLI wiring:** Add `daemon` subcommand + option parsing; create a client helper `ensureDaemon()` used by `call/list` paths when a keep-alive server is detected.
+4. **Transport proxying:** Implement request/response translation so CLI commands can await daemon responses as if they were local.
+5. **Auto-detection + env overrides:** Hook into command selectors to decide when to proxy.
+6. **Tests + docs:** Add Vitest coverage, update README/cli reference snippets, and keep this doc synced with actual behavior.
+
+## Logging & Diagnostics
+
+You can capture the daemon’s stdout/stderr (and per-server call traces) when debugging long-lived STDIO servers:
+
+- `mcporter daemon start --log` enables logging with the default path `~/.mcporter/daemon/daemon-<config-hash>.log`. Use `--log-file <path>` to override it.
+- `--log-servers chrome-devtools,mobile-mcp` restricts per-call logging to the listed servers. Without it, `--log` records every keep-alive server’s activity.
+- Environment equivalents:
+  - `MCPORTER_DAEMON_LOG=1` – enable logging.
+  - `MCPORTER_DAEMON_LOG_PATH=/tmp/mcporter-daemon.log` – explicit log file.
+  - `MCPORTER_DAEMON_LOG_SERVERS=chrome-devtools` – only log specified servers.
+- `mcporter daemon status` now prints the socket path and the active log file (if any) so it’s easy to tail.
+- Per-server opt-in: add `"logging": { "daemon": { "enabled": true } }` next to `"lifecycle": "keep-alive"` in a server definition to force detailed call logging for that server (handy when only one or two STDIO transports are noisy). Combined with `--log`/`MCPORTER_DAEMON_LOG`, those entries always emit call start/end/error lines.
+
+Logs include timestamped entries such as:
+
+```
+[daemon] 2025-11-10T15:08:21.123Z callTool start server=chrome-devtools tool=take_snapshot
+[daemon] 2025-11-10T15:08:22.004Z callTool success server=chrome-devtools tool=take_snapshot
+```
+
+Tailing the file (`tail -f ~/.mcporter/daemon/daemon-*.log`) surfaces crashes or repeated failures without needing to re-run the daemon in the foreground.
+
+Once these steps land, agents can freely use persistent MCP servers without juggling multiple Chrome launches, while still retaining an explicit shutdown path.

package/docs/emit-ts.md

@@ -0,0 +1,98 @@
+---
+summary: 'How to generate `.d.ts` files or typed client helpers with mcporter emit-ts.'
+read_when:
+  - 'Adding new emit-ts behavior or troubleshooting generated clients'
+---
+
+# `mcporter emit-ts`
+
+`mcporter emit-ts` turns a configured MCP server into TypeScript artifacts so
+agents, tests, and tooling can consume the server through strongly typed APIs.
+It reuses the same `buildToolDoc()` data that powers `mcporter list`, so doc
+comments, parameter hints, and signatures stay perfectly in sync. For a broader
+overview of every CLI command, see `docs/cli-reference.md`.
+
+```
+mcporter emit-ts <server> --out linear-client.ts \
+  [--mode types|client] \
+  [--include-optional]
+```
+
+- `--mode types` (default) emits a `.d.ts` interface (`LinearTools`) with
+docblocks + promisified signatures. Missing output schemas fall back to
+`CallResult`.
+- `--mode client` emits both the interface (auto-derived `.d.ts`) **and** an
+executable `.ts` helper that wraps `createServerProxy`. Each method returns a
+`CallResult`, and the factory exposes a `close()` helper for runtimes the client
+creates.
+- `--include-optional` mirrors `mcporter list --all-parameters`, ensuring every
+parameter is shown even when optional.
+
+Outputs overwrite existing files automatically so you can regenerate artifacts
+whenever the server schema changes.
+
+## Examples
+
+### 1. Types-only header
+
+```
+mcporter emit-ts linear --out types/linear-tools.d.ts
+```
+
+Produces:
+
+```ts
+import type { CallResult } from 'mcporter';
+
+export interface LinearTools {
+  /**
+   * List comments for a specific Linear issue.
+   *
+   * @param issueId The issue ID
+   */
+  list_comments(params: { issueId: string }): Promise<CallResult>;
+}
+```
+
+Include the file in your agent/project and you can type-check code like
+`const result = await proxy.list_comments({ issueId: '...' });`.
+
+### 2. Client wrappers
+
+```
+mcporter emit-ts linear --mode client --out clients/linear.ts
+```
+
+Generates two files:
+
+- `clients/linear.d.ts` – same interface as the types-only mode.
+- `clients/linear.ts` – imports `createRuntime`, `createServerProxy`, and
+  `createCallResult`, then exposes a `createLinearClient()` factory:
+
+```ts
+const client = await createLinearClient({ configPath: './mcporter.json' });
+const comments = await client.list_comments({ issueId: 'LIN-1234' });
+console.log(comments.text());
+await client.close();
+```
+
+If you pass an existing runtime (`{ runtime }`), the factory reuses it; the
+returned object’s `close()` becomes a no-op.
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `--out <path>` | Required. `.d.ts` target for `types`, `.ts` target for `client`. |
+| `--mode types|client` | Output kind (defaults to `types`). |
+| `--types-out <path>` | Optional override for the `.d.ts` file when `--mode client`. Default: derive from `--out`. |
+| `--include-optional` | Include every parameter (not just the minimum 5 + required). |
+| `--json` | Emit a JSON summary describing the emitted file(s) instead of plain-text logs. |
+
+## Testing
+
+`tests/emit-ts.test.ts` covers:
+
+- Template rendering (doc comments, `Promise<…>` return types, proxy wrappers).
+- End-to-end CLI invocation with a stub runtime, ensuring both `.ts` and `.d.ts`
+  files are written successfully.