@nimrobo/mcporter-remote 0.1.0

package/docs/hang-debug.md

@@ -0,0 +1,88 @@
+---
+summary: 'Checklist for diagnosing mcporter commands that never exit, using tmux and active-handle dumps.'
+read_when:
+  - 'Seeing the CLI hang after tool completion'
+---
+
+# Debugging Hanging mcporter Calls
+
+When `mcporter call` prints a tool response but the process never exits, it
+usually means Node still has active handles it is waiting on. The most common
+culprit is a child MCP server process that keeps the stdio transport alive.
+
+## Quick Checklist
+
+1. **Run under tmux** – launch the command inside tmux so you can inspect the
+   pane even after Cursor or another agent times out.
+2. **Enable hang diagnostics** – set `MCPORTER_DEBUG_HANG=1` when invoking the
+   CLI. mcporter will dump the active handles/requests after the tool finishes
+   and around the `runtime.close()` call.
+3. **Inspect the handle list** – look for `ChildProcess (pid=…)` entries. If a
+   child remains, mcporter will now unref and force-kill it, but the debug list
+   tells you exactly what was keeping the event loop alive.
+4. **Capture the pane output** – run `tmux capture-pane -p -t <session> -S
+   -200` to save the diagnostic log for later review.
+5. **Retry with `--timeout`** – if the tool itself hangs, use
+   `--timeout <ms>` or `MCPORTER_CALL_TIMEOUT` to fail fast while still
+   gathering diagnostics.
+6. **Clamp OAuth waits** – when the browser-based sign-in never completes,
+   run with `--oauth-timeout <ms>` (or `MCPORTER_OAUTH_TIMEOUT_MS`) so the CLI
+   tears down the pending flow instead of waiting the full minute.
+
+## Example Session
+
+```bash
+tmux new-session -d -s mcphang \
+  'cd /path/to/project && \
+   MCPORTER_DEBUG_HANG=1 \
+   CHROME_DEVTOOLS_MCP_BROWSER_URL=http://127.0.0.1:9222 \
+   pnpm --dir "$HOME/projects/mcporter" exec tsx \
+   "$HOME/projects/mcporter/src/cli.ts" call \
+   --config "$PWD/config/mcporter.json" \
+   --root "$PWD" \
+   chrome-devtools --tool list_pages'
+
+sleep 5
+tmux capture-pane -p -t mcphang -S -200
+```
+
+Sample diagnostic output (abridged):
+
+```
+[mcporter] [debug] after call (object result): 6 active handle(s), 0 request(s)
+[mcporter] [debug] handle => ChildProcess (pid=78480)
+[mcporter] [debug] beginning runtime.close()
+[mcporter] [debug] after runtime.close: 6 active handle(s), 0 request(s)
+[mcporter] [debug] forcibly killed child pid=78480 (runtime.finally)
+```
+
+This confirms the CLI response completed and that the lingering handle was a
+child process, which mcporter will now terminate during shutdown.
+
+## Notes
+
+- The diagnostics only appear when `MCPORTER_DEBUG_HANG=1` is set.
+- Killing residual children is best-effort; if you see repeated `kill-failed`
+  messages, manually terminate the PID listed in the log.
+- Always keep tmux sessions tidy after debugging: `tmux kill-session -t
+  <session>`.
+- The CLI now forces `process.exit(0)` after cleanup by default so Node never
+  lingers on leaked handles. Export `MCPORTER_NO_FORCE_EXIT=1` if you’re
+  debugging and need the process to stay alive.
+- You can still set `MCPORTER_FORCE_EXIT=1` explicitly when you want to force
+  termination even with `MCPORTER_NO_FORCE_EXIT` in play.
+- Stdio servers have their stderr output suppressed by default; set
+  `MCPORTER_STDIO_LOGS=1` to print their logs (they’re also surfaced whenever a
+  child exits with a non-zero status).
+
+## Upstream Tracking
+
+- `@modelcontextprotocol/sdk` **1.21.0** is the latest release pulled into mcporter.
+- Open SDK issues related to stdio shutdown:
+  - [#579 StdioClientTransport does not follow the spec on close](https://github.com/modelcontextprotocol/typescript-sdk/issues/579)
+  - [#780 onerror listeners not removed after client close (stdio)](https://github.com/modelcontextprotocol/typescript-sdk/issues/780)
+  - [#1049 stdio client crashes when spawned server exits unexpectedly](https://github.com/modelcontextprotocol/typescript-sdk/issues/1049)
+
+We keep a local checkout of the SDK under `~/Projects/typescript-sdk/` so we can
+diff against upstream and craft repros/patches quickly. Any mcporter-specific
+workarounds live in `src/sdk-patches.ts` until the upstream fixes land.

package/docs/import.md

@@ -0,0 +1,59 @@
+---
+summary: 'Where mcporter looks for external MCP configs and the formats each import kind understands.'
+read_when:
+  - 'Investigating missing imported servers'
+  - 'Adding or modifying config import kinds'
+---
+
+# Import Reference
+
+mcporter merges your local `config/mcporter.json` with editor- or tool-specific config files so you can reuse servers without copying them manually. This document spells out the supported formats, the directories we scan for each import kind, and how precedence works.
+
+## Import Pipeline
+
+1. `config/mcporter.json` is loaded first (or the file passed to `--config`). If it includes an `"imports"` array, that array defines the exact order we follow. If the array is omitted, we use the default order `["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]`.
+2. For each import kind, we probe the project-relative path (e.g., `.cursor/mcp.json`) and then the per-user path. The first readable file is parsed and converted into mcporter’s normalized schema. Names collide on a “first wins” basis—once an imported name is merged, later imports with the same name are ignored unless the local config defines an override.
+3. Finally, any servers declared inside `mcpServers` take precedence over imports regardless of the order above.
+
+Set `"imports": []` when you want to disable auto-merging entirely, or supply a subset (for example `["cursor", "codex"]`) to reduce the latency of `mcporter list`.
+
+## Supported Formats
+
+- **JSON containers**: Cursor, Claude Code, Windsurf, and VS Code configs use JSON. We accept three shapes:
+  - Root-level dictionary where each key is a server (`{ "my-server": { ... } }`).
+  - `{ "mcpServers": { ... } }` (Cursor-style).
+  - `{ "servers": { ... } }` (older VS Code previews).
+- **TOML container**: Codex uses TOML files with `[mcp_servers.<name>]` tables. Only `.codex/config.toml` is recognized.
+- **Shared fields**: We convert JSON/TOML entries into mcporter’s schema, honoring `baseUrl`, `command` (string or array), `args`, `headers`, `env`, `bearerToken`, `bearerTokenEnv`, `description`, `tokenCacheDir`, `clientName`, and `auth`. Extra properties are ignored.
+
+## Import Support Matrix
+
+| Kind | Typical owner | Format | Project paths | User paths | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `cursor` | Cursor IDE | JSON (`mcpServers`) | `.cursor/mcp.json` | macOS/Linux: `${XDG_CONFIG_HOME:-~/.config}/Cursor/User/mcp.json`<br>Windows: `%APPDATA%/Cursor/User/mcp.json` | Mirrors Cursor’s “MCP Servers” panel. Per-workspace files override the global file when both exist. |
+| `claude-code` | Claude Code (browser) | JSON (`mcpServers`) | `.claude/settings.local.json`, `.claude/settings.json`, `.claude/mcp.json` | `~/.claude/settings.json`, `~/.claude/mcp.json`, `~/.claude.json` | `settings.local.json` (ignored by git) overrides `settings.json`, which is the shared project config; both beat the legacy `mcp.json`. |
+| `claude-desktop` | Claude Desktop | JSON (`mcpServers`) | — | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`<br>Windows: `%APPDATA%/Claude/claude_desktop_config.json`<br>Linux: `~/.config/Claude/claude_desktop_config.json` | Desktop Claude stores all servers per-machine, so there’s no project-relative file. |
+| `codex` | Sweetistics Codex | TOML (`[mcp_servers.*]`) | `.codex/config.toml` | `~/.codex/config.toml` | Only `config.toml` is recognized; the deprecated `mcp.toml` filename is ignored. |
+| `windsurf` | Codeium Windsurf | JSON (`mcpServers`) | — | Windows: `%APPDATA%/Codeium/windsurf/mcp_config.json`<br>macOS/Linux: `~/.codeium/windsurf/mcp_config.json` | Global-only config managed by Codeium. |
+| `opencode` | OpenCode | JSON/JSONC (`mcp`, `mcpServers`, or root map) | `opencode.json`, `opencode.jsonc` | `OPENCODE_CONFIG` override<br>`OPENCODE_CONFIG_DIR/opencode.json(c)`<br>macOS/Linux: `${XDG_CONFIG_HOME:-~/.config}/opencode/opencode.json(c)`<br>Windows: `%APPDATA%/opencode/opencode.json(c)` | Accepts comment-friendly `.jsonc` files and honors OpenCode’s precedence env vars. |
+| `vscode` | VS Code MCP extension | JSON (`mcpServers` or `servers`) | — | macOS: `~/Library/Application Support/Code(/Code - Insiders)/User/mcp.json`<br>Windows: `%APPDATA%/Code(/Code - Insiders)/User/mcp.json`<br>Linux: `~/.config/Code(/Code - Insiders)/User/mcp.json` | We probe both Stable and Insiders directories; the first readable file wins. |
+
+> Tip: mcporter resolves `~` and `$XDG_CONFIG_HOME` inside these paths automatically, so you can rely on the same `imports` list across platforms.
+>
+> Claude tip: keep shared servers in `.claude/settings.json` and stash personal tweaks or credentials in `.claude/settings.local.json`, which Claude auto-ignores in git.
+
+## Default Order & Overrides
+
+- When `config/mcporter.json` omits the `"imports"` key, we load imports in this order: `["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]`.
+- If you set a non-empty `"imports"` array, mcporter appends any missing defaults after your list, so shared presets stay available without extra JSON churn.
+- Set `"imports": []` to disable auto-merging entirely (handy for CI or projects that want deterministic configs).
+
+## Verifying & Troubleshooting
+
+- Run `mcporter list --source import --json` (or pipe through `rg '"source":'`) to confirm the resolved file for each imported server.
+- Use `mcporter list --source import` to limit the output to merged definitions when you’re debugging precedence or verifying first-wins behavior.
+- If a server is defined in multiple tools (e.g., Cursor and OpenCode), the first import in the list wins. Reorder `"imports"` or copy the entry locally via `mcporter config import <kind> --copy` to break ties.
+- When debugging OpenCode, remember that `OPENCODE_CONFIG` beats every other path. Clearing or overriding that env var is often the fastest way to validate changes.
+- When tests need deterministic data, follow `tests/config-imports.test.ts`—it copies fixtures into a fake home directory and asserts the merged server order. Mirror that pattern when adding new import kinds.
+
+Keeping this reference up to date is the best way to prevent “my editor has servers but mcporter can’t see them” bug reports. If you add a new import kind, update this table, add fixtures under `tests/fixtures/imports`, and document the format here.

package/docs/known-issues.md

@@ -0,0 +1,33 @@
+---
+summary: 'Living list of mcporter limitations, hosted MCP quirks, and upstream gaps.'
+read_when:
+  - 'Triaging a bug that might already be documented'
+---
+
+# Known Issues
+
+This file tracks limitations that users regularly run into. Most of these require upstream cooperation or larger refactors—feel free to reference this when triaging bugs.
+
+## Hosted OAuth servers (Supabase, GitHub MCP, etc.)
+- Supabase’s hosted MCP server rejects the standard `mcp:tools` scope and only accepts Supabase-specific scopes (`projects:read`, `database:write`, ...). Because they do not expose OAuth discovery metadata or scope negotiation, mcporter cannot auto-register or complete the flow. Workarounds:
+  - Use Supabase’s supported clients (Cursor, Windsurf).
+  - Self-host their MCP server and configure PAT headers / custom OAuth.
+  - Ask Supabase to accept the MCP scope or publish their scope list.
+- GitHub’s MCP endpoint (`https://api.githubcopilot.com/mcp/`) returns “does not support dynamic client registration” when mcporter attempts to connect. Copilot’s backend expects pre-registered client credentials. Until GitHub publishes a dynamic-registration API (or client secrets), mcporter cannot interact with their hosted server.
+
+## Output schemas missing/buggy on many servers
+- The MCP spec allows servers to omit `outputSchema`. In practice, many hosted MCPs return empty or inconsistent schemas, so features that rely on return types (TypeScript signatures, generated CLIs, `createServerProxy` return helpers) may degrade to `unknown`.
+- Workarounds: inspect the server’s README / manual docs for output details, or wrap the tool via `createServerProxy` and handle the raw envelope manually.
+- Potential improvement: allow user-provided schema overrides (e.g., `mcporter config patch`, CLI flag to load schema JSON) so we can fill gaps on a per-tool basis.
+
+## MCP SDK 1.22.0 inline-stdio regression
+- Upgrading `@modelcontextprotocol/sdk` to 1.22.0 causes `mcporter generate-cli --compile` (and direct runtime `listTools`) to fail against inline STDIO servers with `MCP error -32603: Cannot read properties of undefined (reading 'typeName')`.
+- Repro: `pnpm mcporter generate-cli "node mock-stdio.mjs" --compile /tmp/inline-cli --runtime bun` using the inline stdio harness in `tests/cli-generate-cli.integration.test.ts`.
+- Status: reproduced locally; pinned the SDK to `~1.21.2` until upstream ships a fix.
+
+## Next Steps
+- Implement true scope negotiation (read discovery metadata, allow `--oauth-scope`).
+- Keep lobbying providers for spec-compliant OAuth behavior.
+- Consider adding schema override hooks or auto-caching schema snapshots per tool.
+
+If you run into other recurring pain points, append them here so we can prioritize fixes.

package/docs/livetests.md

@@ -0,0 +1,31 @@
+---
+summary: 'Opt-in live MCP integration tests that hit real hosted servers (off by default in CI).'
+read_when:
+  - 'Running end-to-end validation against hosted MCP servers'
+---
+
+# Live MCP Tests
+
+These tests hit real hosted MCP servers and require outbound HTTP. They are **off by default** to keep CI and local runs deterministic.
+
+## When to run
+- Before releases when you want end-to-end validation against hosted servers.
+- When debugging regressions that only repro against real servers (e.g., DeepWiki).
+
+## How to run
+```bash
+MCP_LIVE_TESTS=1 pnpm test:live
+```
+
+This runs the Vitest suite under `tests/live`, in-band, with longer timeouts.
+
+## Current coverage
+- **DeepWiki** (both wire protocols):
+  - Streamable HTTP: `https://mcp.deepwiki.com/mcp`
+  - SSE: `https://mcp.deepwiki.com/sse`
+  - Test: calls `read_wiki_structure repoName:facebook/react` and asserts a non-empty result.
+
+## Notes
+- Tests are skipped entirely unless `MCP_LIVE_TESTS=1` is set.
+- Ensure network egress is allowed. No secrets are required for the current DeepWiki checks.
+- Keep assertions minimal to reduce flake; these are availability smokes, not full contract tests.

package/docs/local.md

@@ -0,0 +1,73 @@
+---
+summary: 'How to run mcporter directly from the repo (tsx, tsx --watch, built artifacts) without npx.'
+read_when:
+  - 'Setting up a local development loop for this repo'
+---
+
+# Running mcporter Locally
+
+You don’t need `npx` every time—here are the three local entry points we use while developing mcporter itself.
+
+## 1. Direct TypeScript entry (no build step)
+
+All commands can be executed with `tsx` straight from `src/cli.ts`:
+
+```bash
+# list servers (text)
+pnpm exec tsx src/cli.ts list
+
+# list servers as JSON
+pnpm exec tsx src/cli.ts list --json
+
+# call a tool (auto formatted)
+pnpm exec tsx src/cli.ts call context7.resolve-library-id libraryName=react
+
+# call a tool but emit structured JSON on success/failure
+pnpm exec tsx src/cli.ts call context7.resolve-library-id libraryName=react --output json
+
+# auth flow
+pnpm exec tsx src/cli.ts auth vercel
+
+# auth flow with structured JSON status
+pnpm exec tsx src/cli.ts auth vercel --json
+
+# ad-hoc auth
+pnpm exec tsx src/cli.ts auth https://mcp.supabase.com/mcp
+```
+
+These invocations match the `pnpm mcporter:*` scripts and are ideal when you’re iterating on TypeScript without rebuilding.
+
+## 2. Compiled CLI from `dist/`
+
+When you want the same behaviour the published package ships with:
+
+```bash
+pnpm build          # emits dist/...
+node dist/cli.js list
+node dist/cli.js call chrome-devtools.take_snapshot
+```
+
+Set flags exactly as you would in production:
+
+```bash
+MCPORTER_DEBUG_HANG=1 node dist/cli.js list
+MCPORTER_NO_FORCE_EXIT=1 node dist/cli.js call linear.search_documentation query="automations"
+```
+
+## 3. Workspace executables
+
+After `pnpm add mcporter` in your project (or inside this repo), the shim binaries are available:
+
+```bash
+pnpm mcporter:list
+pnpm mcporter:call context7.get-library-docs topic=hooks
+```
+
+## Debug flags recap
+
+- `MCPORTER_DEBUG_HANG=1` – dumps active handles around shutdown (pairs well with tmux; see `docs/hang-debug.md`).
+- `MCPORTER_NO_FORCE_EXIT=1` – keeps the process alive even after cleanup (useful while inspecting debug output).
+- `MCPORTER_FORCE_EXIT=1` – force termination even if the above is set.
+- `MCPORTER_STDIO_LOGS=1` – print the buffered stderr output from stdio MCP servers (handy when debugging noisy backends).
+
+All three entry points honour the same `--config`, `--root`, and `--log-level` flags as the published CLI.

package/docs/logging.md

@@ -0,0 +1,67 @@
+---
+summary: 'Reference for capturing mcporter diagnostics (daemon logs, per-server overrides, env flags).'
+read_when:
+  - 'Need persistent daemon logs or want to trace keep-alive STDIO servers.'
+---
+
+# Logging & Diagnostics
+
+## Daemon logging
+
+The keep-alive daemon can tee its stdout/stderr (and per-server call traces) into a file so you can see crashes or repeated failures without rerunning it in the foreground.
+
+### CLI flags
+
+- `mcporter daemon start --log` — enable logging at the default path `~/.mcporter/daemon/daemon-<config-hash>.log`.
+- `mcporter daemon start --log-file /tmp/mcporter-daemon.log` — write logs to a specific file (path is created if needed).
+- `mcporter daemon start --log-servers chrome-devtools,mobile-mcp` — only emit per-call entries for the listed servers. Without this flag, `--log` records every keep-alive server’s calls.
+
+`mcporter daemon restart` accepts the same logging flags, so you can bounce the daemon without retyping your tracing preferences.
+
+Foreground mode (`mcporter daemon start --foreground --log`) still prints to your terminal; the log file mirrors the same content.
+
+### Environment overrides
+
+Set these before invoking `mcporter` (helpful for scripts/CI):
+
+- `MCPORTER_DAEMON_LOG=1` — enable logging.
+- `MCPORTER_DAEMON_LOG_PATH=/tmp/mcporter-daemon.log` — custom log file.
+- `MCPORTER_DAEMON_LOG_SERVERS=chrome-devtools,playwright` — per-server call filtering.
+
+The CLI flags take precedence; env vars are the fallback.
+
+### Per-server opt-in
+
+Add a logging block inside the server definition (alongside `lifecycle`) when you only want a specific STDIO transport to produce call traces, regardless of global flags:
+
+```json
+"chrome-devtools": {
+  "description": "Chrome DevTools protocol bridge",
+  "command": "npx",
+  "args": ["-y", "chrome-devtools-mcp@latest"],
+  "lifecycle": "keep-alive",
+  "logging": {
+    "daemon": { "enabled": true }
+  }
+}
+```
+
+When combined with `--log`/`MCPORTER_DAEMON_LOG=1`, any server that has `logging.daemon.enabled` emits `callTool start/success/error` lines even if it isn’t listed in `--log-servers`.
+
+### Inspecting logs
+
+- `mcporter daemon status` prints both the socket path and the current log file (if logging is enabled) so you can `tail -f` the output quickly.
+- Each call looks like:
+  ```
+  [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
+  ```
+- Shutdown events and errors are logged the same way (`callTool error … err=...`, `listTools error …`, etc.).
+
+### Defaults & cleanup
+
+Log files live under `~/.mcporter/daemon/` next to the socket/metadata. They’re not rotated automatically yet; delete/rotate them manually if they grow large. Running `mcporter daemon stop` leaves the log intact so you can inspect it after a crash.
+
+## Foreground debugging
+
+When troubleshooting deeply, run `mcporter daemon start --foreground --log` in a dedicated terminal. This keeps the daemon attached (so Ctrl+C stops it) and still writes to the configured log file for later inspection.

package/docs/manual-testing.md

@@ -0,0 +1,78 @@
+---
+summary: 'Tmux-based manual testing recipe for exercising mcporter against real MCP servers.'
+read_when:
+  - 'Need to reproduce a bug or verify CLI output by hand'
+---
+
+# Manual Testing Harness
+
+When we need to sanity-check CLI flows against real MCP servers (or reproduce bugs by hand), use this repeatable harness. Everything runs under `tmux` so long-running commands can be inspected without blocking the current shell.
+
+## Prerequisites
+
+- `pnpm install` ran recently.
+- Credentials exist for any auth-required servers you plan to exercise.
+- `tmux` is installed (we rely on it below).
+
+## Discover live servers
+
+Start every session by listing all configured servers so you can pick a healthy target:
+
+```bash
+tmux new-session -d -s list-all 'pnpm exec tsx src/cli.ts list --timeout 1000 > /tmp/list-all.log 2>&1; sleep 5'
+sleep 2
+cat /tmp/list-all.log
+```
+
+The summary shows which servers are healthy, require auth, or are offline. Choose one of the "healthy" entries (e.g., `shadcn`, `firecrawl`, `obsidian-mcp-tools`) for the manual checks below.
+
+## Test matrix
+
+For each server under test, run the following commands, adjusting `SERVER`, `TOOL`, and arguments as needed. Each command writes to `/tmp` so logs are easy to share.
+
+### List command
+
+```bash
+tmux new-session -d -s list-SERVER \
+  'pnpm exec tsx src/cli.ts list SERVER --timeout 2000 > /tmp/list-SERVER.log 2>&1; sleep 5'
+sleep 2
+cat /tmp/list-SERVER.log
+```
+
+Verify:
+- Header shows the right name/transport and the new metadata line (`tools · duration · transport`).
+- Timeouts produce the footer block: `Tools: <timed out after ...>` and `Reason: ...`.
+
+### Call command
+
+```bash
+tmux new-session -d -s call-SERVER \
+  'pnpm exec tsx src/cli.ts call SERVER.toolName key=value --timeout 2000 > /tmp/call-SERVER.log 2>&1; sleep 5'
+sleep 2
+cat /tmp/call-SERVER.log
+```
+
+Checks:
+- Successful calls print the payload; failures reuse the shared hinting (`SSE error ...`, auto-correct messages, etc.).
+- For HTTP selectors (`https://.../mcp.tool` or `https://.../mcp.tool(args)`), ensure no OAuth prompt appears and the request hits the configured server.
+
+### Auth command
+
+For OAuth servers:
+
+```bash
+tmux new-session -d -s auth-SERVER \
+  'pnpm exec tsx src/cli.ts auth SERVER --reset > /tmp/auth-SERVER.log 2>&1; sleep 5'
+sleep 2
+cat /tmp/auth-SERVER.log
+```
+
+Expectations:
+- If a token cache exists, log should mention the cleared directory.
+- Failed auths emit the unified message (`Failed to authorize 'SERVER': ...`).
+
+## Tips
+
+- To exercise error paths, point at a placeholder endpoint and use `--timeout 1000` (e.g., `https://example.com/mcp.listStuff`).
+- Kill tmux sessions before reusing a name: `tmux kill-session -t session-name`.
+- To watch live output instead of dumping the log at the end, attach via `tmux attach -t session-name` and detach (`Ctrl+B`, then `D`) when done.

package/docs/mcp.md

@@ -0,0 +1,44 @@
+---
+summary: 'High-level overview of mcporter’s runtime, entry points, and reusable helpers.'
+read_when:
+  - 'Onboarding to this repository or explaining mcporter to others'
+---
+
+# mcporter Overview
+
+mcporter is the Sweetistics CLI + runtime for the Model Context Protocol (MCP). It wraps the upstream TypeScript SDK with:
+
+- **Runtime orchestration** – `createRuntime` loads servers from config JSON, editor imports, or ad-hoc flags and handles OAuth retries, transport promotion, and cleanup.
+- **CLI surfaces** – `mcporter list`, `mcporter call`, `mcporter generate-cli`, `mcporter emit-ts`, and `mcporter inspect-cli` expose the runtime features to humans and scripts.
+- **Tooling helpers** – `createServerProxy` maps MCP tools to camelCase methods for Node/Bun scripts and returns `CallResult` helpers (`.text()`, `.markdown()`, `.json()`).
+
+## Primary Commands
+
+- `npx mcporter list [server|--http-url|--stdio]`  
+  Lists tool metadata, renders TypeScript-style signatures, and surfaces copy/pasteable examples (including ad-hoc HTTP selectors).
+- `npx mcporter call server.tool key=value …`  
+  Invokes a tool via either flag syntax or the function-call expression form; add `--output json` to capture structured responses.
+- `npx mcporter generate-cli --server name [--bundle|--compile]`  
+  Emits a standalone CLI for a single MCP server. Bundling defaults to Rolldown unless the runtime resolves to Bun; compiled binaries require Bun.
+- `npx mcporter emit-ts <server> --mode types|client`  
+  Produces `.d.ts` files or typed client factories that mirror the CLI schema output.
+- `npx mcporter inspect-cli dist/server.js`  
+  Reads embedded metadata so you can regenerate a CLI without guesswork.
+
+## Runtime Helpers
+
+Use `createServerProxy(runtime, name)` inside scripts when you want ergonomic camelCase calls instead of kebab-case tool names. The proxy:
+
+1. Validates arguments against the MCP schema.
+2. Automatically merges default values.
+3. Returns a `CallResult` helper so you can render `.text()`, `.markdown()`, or `.json()` without manual parsing.
+
+When you need raw access (custom transports, streaming), use the bare `Client` from `@modelcontextprotocol/sdk` or inspect `runtime.connect(name)` for lower-level control.
+
+## Debug + Support Docs
+
+- **Ad-hoc MCP Servers** (`docs/adhoc.md`) – explains the `--http-url` / `--stdio` flags.
+- **Tool Calling Cheatsheet** (`docs/tool-calling.md`) – shows the two argument styles and when to use each.
+- **Hang Diagnostics** (`docs/hang-debug.md` + `docs/tmux.md`) – run long-lived commands inside tmux and dump active handles if shutdown stalls.
+
+Read these docs (via `pnpm run docs:list`) whenever your task touches the corresponding area. They contain the up-to-date guardrails used across Sweetistics repositories.

package/docs/migration.md

@@ -0,0 +1,77 @@
+---
+summary: 'How to migrate from pnpm mcp:* wrappers to the mcporter package.'
+---
+
+# Migration Guide
+
+This guide walks through replacing the Python-based `pnpm mcp:*` helpers with the new TypeScript runtime and CLI.
+
+## 1. Install
+
+```bash
+pnpm add mcporter
+# or
+yarn add mcporter
+# or
+npm install mcporter
+```
+
+## 2. Update Scripts
+
+- Replace `pnpm mcporter:list` with `npx mcporter list`.
+- Replace `pnpm mcporter:call <server>.<tool> key=value` with `npx mcporter call <server>.<tool> key=value`.
+- Add `--config <path>` if your configuration is not under `./config/mcporter.json`.
+- Optional: set `"imports"` inside `mcporter.json` (for example `[]` to disable auto-imports or `["cursor", "codex"]` to customize the order).
+- Append `--tail-log` to stream the last 20 lines of any log file returned by the tool.
+
+## 3. OAuth Tokens
+
+- Tokens are saved under `~/.mcporter/<server>/` by default.
+- To force a fresh login, delete that directory and rerun the command; the CLI will relaunch the browser.
+- Custom `token_cache_dir` entries in `mcporter.json` continue to work as explicit overrides.
+
+## 4. Programmatic Usage
+
+```ts
+import { createRuntime } from "mcporter";
+
+const runtime = await createRuntime({ configPath: "./config/mcporter.json" });
+const tools = await runtime.listTools("chrome-devtools");
+await runtime.callTool("chrome-devtools", "take_screenshot", { args: { url: "https://x.com" } });
+await runtime.close();
+```
+
+Prefer `createRuntime` for long-lived agents so connections and OAuth tokens can be reused.
+
+## 5. Single Call Helper
+
+```ts
+import { callOnce } from "mcporter";
+
+await callOnce({
+  server: "firecrawl",
+  toolName: "crawl",
+  args: { url: "https://anthropic.com" },
+});
+```
+
+Use `callOnce` for fire-and-forget invocations.
+
+## 6. Environment Variables
+
+- `LINEAR_API_KEY`, `FIRECRAWL_API_KEY`, and similar tokens are read exactly as before via `${VAR}` syntax.
+- `${VAR:-default}` continues to work; empty values are ignored.
+- `$env:VAR` placeholders resolve to raw OS environment variables.
+
+## 7. Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| Browser did not open | Copy the printed OAuth URL manually into a browser. |
+| Authorization hangs | Ensure the callback URL can bind to `127.0.0.1`; firewalls may block it. |
+| Tokens are stale | Delete `~/.mcporter/<server>/tokens.json` and retry. |
+| Stdio command fails | Pass `--root` to point at the repo root so relative paths resolve. |
+
+---
+
+For deeper architectural notes and future work, see [`docs/spec.md`](./spec.md).

package/docs/pnpm-mcp-migration.md

@@ -0,0 +1,15 @@
+---
+summary: 'Mapping from the legacy `pnpm mcp:*` scripts to the modern mcporter CLI.'
+read_when:
+  - 'Helping teammates migrate old pnpm workflows to mcporter'
+---
+
+# Migrating from `pnpm mcp:*`
+
+The legacy `pnpm mcp:*` helpers map directly onto the `mcporter` CLI.
+
+- `pnpm mcporter:list` → `npx mcporter list`
+- `pnpm mcporter:call server.tool key=value` → `npx mcporter call server.tool key=value`
+- New flags: `--schema` surfaces full tool schemas, and `--tail-log` follows log output referenced by responses.
+
+For a step-by-step checklist (including config updates and environment variables) see [`docs/migration.md`](./migration.md).

package/docs/refactor.md

@@ -0,0 +1,76 @@
+---
+summary: 'Status tracker for post-launch refactors, shared utilities, and remaining cleanup tasks.'
+read_when:
+  - 'Scoping engineering work beyond immediate feature changes'
+---
+
+# Next-Step Refactor Checklist
+
+This doc tracks remaining reuse/refactor work now that the original plan is done.
+Each section lists the goal, why it matters, and the concrete steps/tests needed.
+
+## 1. Shared Tool Schema Cache *(Completed)*
+- **Problem**: `generate-cli` and `emit-ts` both fetch & serialize tool schemas
+  independently (and `mcporter list` re-parses them too).
+- **What we did**:
+  1. Added `src/cli/tool-cache.ts` with `loadToolMetadata()` caching tool metadata per runtime/server/options.
+  2. Switched `mcporter list` (single-server path) and `emit-ts` to consume the helper, so both reuse `ToolMetadata`.
+  3. Added `tests/tool-cache.test.ts` + updated emit-ts tests to ensure the helper is covered.
+- **Next**: Consider integrating the cache into `generate-cli` if we ever reuse runtime instances there.
+
+## 2. Unified Flag Parsing for Generator-style Commands *(Completed)*
+- **Problem**: `generate-cli`, the (now legacy) `regenerate-cli` wrapper, and `emit-ts` each
+  reimplemented `--runtime`, `--timeout`, and `--include-optional` handling.
+- **What we did**:
+  1. Added `extractGeneratorFlags()` in `src/cli/generate/flag-parser.ts` to
+     normalize shared flags while mutating `args` in place.
+  2. Updated all three commands to call the helper before parsing
+     command-specific options.
+  3. Added `tests/generator-flag-parser.test.ts` to cover runtime/timeout and
+     optional flags.
+
+## 3. Test Fixture Reuse *(Completed)*
+- **Problem**: Emit-ts/tool-cache/unit tests each defined their own tool/definition
+  fixtures, leading to divergence.
+- **What we did**:
+  1. Added `tests/fixtures/tool-fixtures.ts` (shared definition + tools).
+  2. Updated `tests/emit-ts.test.ts` and `tests/tool-cache.test.ts` to import
+     the shared fixtures (and reuse them via `buildToolMetadata`).
+  3. Ensured the fixture covers required+optional parameters so both suites hit
+     the same edge cases.
+
+## 4. CallResult Helper Extraction *(Completed)*
+- **Problem**: `call-command.ts` and the emit-ts client template both wrapped
+  results with `createCallResult`, but there was no shared helper.
+- **What we did**:
+  1. Added `wrapCallResult()` to `result-utils.ts` and exported it from the
+     package entry.
+  2. Updated `call-command.ts` and the emit-ts template to reuse the helper so
+     they stay in sync.
+  3. Adjusted emit-ts tests to assert the helper is referenced.
+
+## 5. CLI Docs Consolidation *(Completed)*
+- **Problem**: CLI usage guidance was scattered across README, `docs/spec.md`,
+  and various feature docs.
+- **What we did**:
+  1. Added `docs/cli-reference.md` summarizing `list`, `call`, `generate-cli`,
+     and `emit-ts` flags/modes in one place.
+  2. Pointed emit-ts users to that doc so we can converge other references over
+     time (no README/spec churn yet to avoid clobbering parallel work).
+- **Next**: Once the other doc changes land, update README/spec to link to the
+  reference and drop redundant sections.
+
+## 6. Runtime Module Split *(Completed)*
+- **Problem**: `src/runtime.ts` had grown bulky (600+ lines) mixing transport setup, OAuth flow control, and small helpers, making tests and reuse harder.
+- **What we did**:
+  1. Extracted transport construction/retry logic to `src/runtime/transport.ts`.
+  2. Moved OAuth helpers (timeouts, connect retry, errors) to `src/runtime/oauth.ts` and centralized env-parsed timeouts.
+  3. Pulled argument/timeout utilities into `src/runtime/utils.ts`.
+  4. Made reset-policy logic reusable via `src/runtime/errors.ts`.
+  5. Switched tests to import helpers directly instead of using `runtime.__test`.
+  6. Added a targeted transport test to cover SSE fallback and OAuth promotion.
+- **Next**: Keep new helpers in sync as runtime evolves; prefer adding surface to these modules over growing `runtime.ts` again.
+
+---
+Tracking the above here keeps future agents aligned. Update this checklist as
+items ship (mark sections “Completed” when done, or delete the doc once empty).