@nimrobo/mcporter-remote 0.1.0

package/docs/shortcuts.md

@@ -0,0 +1,31 @@
+---
+summary: 'Agent-friendly shortcuts for getting help from configured MCP servers.'
+read_when:
+  - 'You need a quick reminder of which hidden CLI shortcuts explain MCP servers.'
+---
+
+# Agent Shortcuts
+
+These undocumented shortcuts are safe for MCP agents to call when they need a quick description of a server or its tools without memorizing the full `mcporter` CLI surface.
+
+## `pnpm mcp call <server>.help`
+
+- Alias for `pnpm mcporter:call <server>.help`, meant for agents that already rely on the old `pnpm mcp:*` helpers.
+- If `<server>` exposes a `help` tool, the call behaves exactly like any other tool invocation and streams the tool's content.
+- When no `help` tool exists, the CLI automatically falls back to `mcporter list <server>` so the agent still sees the server summary, tool signatures, and copy-pasteable examples.
+- Use `--output json` if the agent prefers machine-readable summaries; the fallback will mirror that flag.
+
+## `mcporter describe <server>`
+
+- Hidden synonym for `mcporter list <server>`; it prints the same schema-rich output without teaching agents about the `list` verb.
+- Works with any selector the `list` command accepts (configured names, ad-hoc `https://` URLs, or `--stdio/--http-url` flags).
+- Pair with `--schema` or `--all-parameters` when an agent needs the full JSON Schema for every tool.
+
+### Recommended Usage
+
+1. Agents wanting prose guidance should run `pnpm mcp call chrome-devtools.help`.
+2. If the server lacks a `help` tool, the command emits a dim hint and then shows the `describe`/`list` output so the agent still learns about the server.
+3. For a guaranteed TypeScript-style summary, skip straight to `mcporter describe chrome-devtools --schema`.
+4. Need the tool menu immediately? Call `pnpm mcp call chrome-devtools.list_tools`—it’s a shortcut for `mcporter list chrome-devtools`.
+
+> Note: `chrome-devtools` currently ships without a `help` tool, so step 1 always triggers the fallback and prints the same schema-rich output you would see from `mcporter list`.

package/docs/spec.md

@@ -0,0 +1,86 @@
+---
+summary: 'Plan for the mcporter package replacing the Sweetistics pnpm MCP helpers.'
+---
+
+# mcporter Roadmap
+
+> Inspired in part by Anthropic’s guidance on MCP code execution agents: https://www.anthropic.com/engineering/code-execution-with-mcp
+
+## Goals
+- Provide a TypeScript runtime + CLI that exposes all MCP servers defined in `~/Projects/sweetistics/config/mcporter.json`.
+- Preserve current one-shot `pnpm mcporter:call` ergonomics while enabling reusable connections for Bun/Node agents.
+- Keep feature parity with the Python helper (env interpolation, stdio wrapping, OAuth caching) and extend test coverage.
+
+## Deliverables
+- `packages/mcporter` (standalone npm package) exporting:
+  - `createRuntime()` for shared connections (list/call tools, resolve resources).
+  - `callOnce()` convenience matching today’s single-call flow.
+  - Typed utilities for env/header resolution and stdio command execution.
+- CLI entry point (`npx mcporter list|call`) built on the same runtime with configurable log levels (`--log-level` flag, `MCPORTER_LOG_LEVEL` env) defaulting to `warn`. Single-server listings must render as TypeScript-style headers: dimmed `/** ... */` doc blocks followed by `function name(...)` signatures, inferred return annotations when schemas expose a `title`, inline enum/format hints, and an optional-parameter summary (`// optional (N): a, b, ...`). Optional fields are hidden by default (unless there are ≤2 of them and <4 required parameters) and the CLI should tell users to run `--all-parameters` whenever anything is suppressed. The CLI should also infer the verb when users omit it: bare server names run `list <server>` (with the same typo-friendly heuristic used by `mcporter list`), while dotted tokens such as `linear.list_issues` dispatch to `call` automatically. Anonymous HTTP MCP servers (e.g., shadcn) must be auto-detected: if an ad-hoc URL returns MCP-shaped JSON even with a non-200 status, mcporter treats it as authenticated instead of launching the OAuth flow. Likewise, `call` must recognise HTTP selectors that inline the tool name (e.g., `https://www.shadcn.io/api/mcp.getComponent(...)`), strip the `.tool` suffix to derive the base server, parse any function-call arguments, and reuse an existing definition when the base URL matches a configured server. Selectors may omit the protocol entirely—we assume HTTPS when no scheme is present and treat hosts that only differ by a leading `www.` as identical for reuse purposes. See [docs/cli-reference.md](./cli-reference.md) for day-to-day usage/flag details.
+- CLI generator (`npx mcporter generate-cli`) that emits standalone CLIs (plain TypeScript or bundled JS) with embedded schemas and Commander-based subcommands, targeting Node or Bun.
+- CLI generator (`npx mcporter generate-cli`) that emits standalone CLIs (plain TypeScript or bundled JS) with embedded schemas and Commander-based subcommands, targeting Node or Bun. It must accept server references by name (positional), JSON, HTTP URL (with optional `.tool` suffix / missing scheme), or inline stdio commands (split into `command` + `args` so invocations like `--command "npx -y chrome-devtools-mcp@latest"` or positional equivalents work without a config entry) just like the main CLI.
+- Test harness using the Sweetistics MCP fixtures to validate every configured server definition.
+- Documentation: README, usage examples, migration guide for replacing `pnpm mcp:*`.
+
+## Architecture Notes
+- Load MCP definitions from JSON (support relative paths + HTTPS).
+- Reuse `@modelcontextprotocol/sdk` transports; invoke stdio servers directly (e.g., call `npx` with env overrides) without an extra wrapper script.
+- Automatically detect OAuth requirements for ad-hoc HTTP servers by retrying failed handshakes and promoting the definition to `auth: "oauth"` when a 401/403 is encountered, then launching the browser flow immediately.
+- Mirror Python helper behavior:
+  - `${VAR}`, `${VAR:-default}`, `$env:VAR` interpolation.
+- Optional OAuth token cache directory handling (defaulting to `~/.mcporter/<server>` when none is provided).
+  - Tool signature + schema fetching for `list`.
+- Provide lazy connection pooling per server to minimize startup cost.
+- Expose a lightweight server proxy (`createServerProxy`) that maps camelCase method accesses to tool names, fills JSON-schema defaults, validates required arguments, and returns a helper (`CallResult`) for extracting text/markdown/JSON without re-parsing the content envelope.
+- Document Cursor-compatible `config/mcporter.json` structure; support env-sourced headers and stdio commands while keeping inline overrides available for scripts.
+
+## Schema-Aware Proxy Strategy
+- Cache tool schemas on first access, persist them under `~/.mcporter/<server>/schema.json` for reuse across processes, and tolerate failures by falling back to raw `callTool`.
+- Allow direct method-style invocations such as `context7.getLibraryDocs("react")` by:
+  - Mapping camelCase properties to kebab-case tool names.
+  - Detecting positional arguments and assigning them to required schema fields in order.
+  - Handling multi-argument tools (e.g., Firecrawl’s `scrape`/`map`) via positional arrays, plain objects, or mixed option bags.
+  - Merging JSON-schema defaults and validating required fields before dispatch.
+- Return `CallResult` objects exposing `.raw`, `.text()`, `.markdown()`, `.json()` helpers for consistent post-processing.
+- Keep implementation generic—no hardcoded knowledge of specific servers—so new MCP servers automatically gain the ergonomic API.
+- Encourage lightweight composition helpers in examples (e.g., resolving then fetching Context7 docs) while keeping library exports generic.
+- Back the proxy with targeted unit tests that cover primitive-only calls, positional tuples + option bags, and error fallbacks when schemas are missing.
+
+## Standalone CLI Generation
+- `generate-cli` should accept inline JSON, file paths, inline stdio commands (either via `--command` or as the first positional argument), or existing config names and produce a ready-to-run CLI that maps tools to Commander subcommands.
+- Embed schemas (via `listTools { includeSchema: true }`) directly in the generated source so repeat executions avoid additional metadata calls.
+- Support optional bundling through esbuild, producing Node-friendly `.cjs` files or Bun-ready `.js` binaries with executable shebangs.
+- Surface flags for output path, runtime target (`node` or `bun`), bundle destination, and per-call timeout (default 30s).
+- Add integration tests asserting the generated CLI can list tools, execute with positional/flag arguments, and hydrate cache files without additional list calls.
+
+## Configuration
+- Single file `config/mcporter.json` mirrors Cursor/Claude schema: `mcpServers` map with entries containing `baseUrl` or `command`+`args`, optional `headers`, `env`, `description`, `auth`, `tokenCacheDir`, and convenience `bearerToken`/`bearerTokenEnv` fields.
+- Optional `imports` array (defaulting to ['cursor', 'claude-code', 'claude-desktop', 'codex', 'windsurf', 'vscode']) controls auto-merging of editor configs; entries earlier in the list win conflicts while local definitions can still override.
+- Provide `configPath` override for scripts/tests; keep inline overrides in examples for completeness but default to file-based configuration.
+- Add fixtures validating HTTP vs. stdio normalization, header/env behavior, and editor config imports (Cursor, Claude Code/Desktop, Codex, Windsurf, VS Code) to ensure priority ordering matches defaults.
+
+## Work Phases
+1. **Scaffold Package**
+   - Init pnpm workspace config, tsconfig, lint/test scaffolding, build script.
+2. **Core Runtime**
+   - Port config parsing + env/header logic.
+   - Implement connection cache, tool invocation, resource helpers.
+3. **CLI Surface**
+- Implement `list` (with optional schema) and `call` commands.
+- Render tool metadata as pseudo-TypeScript declarations: blue `function` signatures, grey doc comments using `@param` lines, inferred return names, and compact optional summaries that collapse longer lists until users pass `--all-parameters`. The default view must still surface at least five parameters (even if they’re optional) before summarising the remainder.
+- Ensure output parity with existing helper.
+- `call` has to parse both `server.tool` tokens and HTTP selectors like `https://host/path.tool(args)`; in the HTTP case we need to peel off the `.tool` suffix, infer/auto-register the ad-hoc server (respecting `--allow-http`), and hydrate arguments from parentheses or trailing `key=value` pairs.
+- Add `generate-cli` for standalone/bundled CLIs with embedded schema caching.
+- Ensure `generate-cli`, `inspect-cli`, and `emit-ts` share the same server-resolution logic as `list/call`, including HTTP URL matching and scheme-less selectors with `.tool` suffixes.
+4. **Testing & Fixtures**
+   - Mock representative MCP servers (stdio + HTTP + OAuth) for integration tests.
+   - Snapshot output for `list` vs. `call`.
+5. **Docs & Migration**
+   - Write README + migration doc.
+   - Update Sweetistics docs to point to the new package.
+
+## Open Questions
+- How aggressively should we parallelize list calls? Current helper serializes to avoid load.
+- Should we bundle a minimal REPL for ad-hoc debugging, or keep CLI focused on list/call?
+- Do we expose streaming/async iterator interfaces for tools returning logs?
+- What UX do we provide for completing OAuth browser flows (automated callback server vs. copy/paste codes)?

package/docs/subagent.md

@@ -0,0 +1,39 @@
+---
+summary: 'Multi-agent system directives and coordination rules. Master reference for agent behavior.'
+---
+
+# Claude Subagent Quickstart
+
+## CLI Basics
+- Never invoke subagents through `./runner`—launch them inside tmux directly so the session can persist and bypass the runner timeouts. Example:
+
+  ```bash
+  tmux new-session -d -s claude-haiku 'claude --model haiku'
+  tmux attach -t claude-haiku
+  ```
+
+  Once inside the session, run `/model` to confirm the active alias (`haiku` maps to Claude 3.5 Haiku) and switch models if needed.
+- Need to queue instructions without attaching? Use `bun scripts/agent-send.ts --session <name> -- "your command"` to inject text into a running agent session (single Enter is sent by default).
+- Run Claude through the repo wrapper when you just need help (`./runner claude --help`), but for actual delegation launch Claude inside tmux so the work keeps running after you disconnect.
+- Two modes:
+- Always switch to the fast Haiku model upfront (`claude --model haiku --dangerously-skip-permissions …` or `/model haiku` in-session); it keeps turnaround under the runner’s limits.
+- Two modes:
+  - **One-shot tasks** (single summary, short answer): run `claude --model haiku --dangerously-skip-permissions --print …` in a tmux session, wait with `sleep 30`, then read the output buffer.
+  - **Interactive tasks** (multi-file edits, iterative prompts): start `claude --model haiku --dangerously-skip-permissions` in tmux, send prompts with `tmux send-keys`, and capture completed responses with `tmux capture-pane`. Expect to sleep between turns so Haiku can finish before you scrape the pane.
+- Ralph’s supervisor loop launches Claude the same way (`claude --dangerously-skip-permissions "<prompt>"`) to keep the tmux automation flowing.
+
+## One-Shot Prompts
+- The CLI accepts the prompt as a trailing argument in one-shot mode. Multi-line prompts can be piped: `echo "..." | ./runner claude --print`.
+- Add `--output-format json` when you need structured fields (e.g., summary + bullets) for post-processing.
+- Keep prompts explicit about reading full files: “Read docs/example.md in full and produce a 2–3 sentence summary covering all sections.”
+
+## Bulk Markdown Conversion
+- Produce the markdown inventory first (`pnpm run docs:list`) and feed batches of filenames to your Claude session.
+- For each batch, issue a single instruction like “Rewrite these files with YAML front matter summaries, keep all other content verbatim.” Haiku can loop over multi-file edits when you provide the explicit list.
+- After Claude reports success, diff each file locally (`./runner git diff docs/<file>.md`) before moving to the next batch.
+
+## Ralph Integration Notes
+- Ralph (see `scripts/ralph.ts`) spins up tmux sessions, auto-wakes the worker, and calls Claude as the supervisor via `claude --dangerously-skip-permissions`.
+- Supervisor responses must end with either `CONTINUE`, `SEND: <message>`, or `RESTART`; Ralph parses these tokens to decide the next action.
+- To start Ralph manually: `bun scripts/ralph.ts start --goal "…" [--markdown path]`. Progress is tracked in `.ralph/progress.md` by default.
+- Send ad-hoc instructions to the worker session with `bun scripts/ralph.ts send-to-worker -- "your guidance"`.

package/docs/supabase-auth-issue.md

@@ -0,0 +1,53 @@
+---
+summary: 'Notes on OAuth scope expectations for hosted MCP servers (e.g., Supabase) and why mcporter requests currently fail.'
+read_when:
+  - 'Investigating OAuth errors or scope negotiation problems'
+---
+
+# OAuth Notes & Hosted MCP Compatibility
+
+## MCP Spec Expectations
+- The June 18 2025 MCP “Authorization” spec (and the linked OAuth flow document) requires OAuth 2.1 dynamic client registration plus RFC 7235 `WWW-Authenticate` challenges for scope negotiation.
+- Servers SHOULD expose discovery metadata via `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`. Those documents list supported scopes and additional OAuth endpoints.
+- Clients are expected to start with a baseline scope (the spec uses `mcp:tools`) and then re-authenticate with any server-supplied scope hints.
+
+We currently hard-code `mcp:tools` because it is the only scope guaranteed to exist in the MCP reference implementation. We need richer negotiation to support providers that enforce product-specific scopes.
+
+## Hosted Supabase MCP (~Oct 2025)
+Supabase’s hosted MCP server (`https://mcp.supabase.com/mcp`) validates the requested scopes against their management API permissions (`organizations:read`, `projects:read`, `database:write`, `storage:read`, etc.). When mcporter asks for `mcp:tools`, their authorization server rejects the request with HTTP 400 and a body similar to:
+
+```
+{"message":"scope.0: Invalid enum value. Expected 'organizations:read' | 'projects:read' | 'projects:write' | 'database:write' | 'database:read' | 'analytics:read' | 'secrets:read' | 'edge_functions:read' | 'edge_functions:write' | 'environment:read' | 'environment:write' | 'storage:read', received 'mcp:tools'"}
+```
+
+Key takeaways from Supabase’s docs:
+1. Hosted installs rely on dynamic client registration and are currently integrated with Cursor/Windsurf (which embed the Supabase scope list).
+2. Manual authentication is offered for self-hosted/CI workflows (PAT headers or custom OAuth app), but their hosted server still expects Supabase-specific scopes.
+3. There is no public metadata endpoint describing those scopes, so third-party MCP clients cannot opt in automatically.
+
+## mcporter’s Current Behavior
+- We auto-promote ad-hoc HTTP servers to OAuth and retry once when we see 401/403 errors.
+- We surface any server-supplied OAuth error payload so it’s obvious whether the problem is scope-related, a missing token, etc.
+- After the second failure we stop retrying to avoid infinite loops.
+
+This works for providers that use standard MCP scopes (e.g., the MCP example server, Vercel’s MCP), but it fails for Supabase because they reject `mcp:tools` outright.
+
+## Roadmap / Proposed Improvements
+1. **Scope discovery & negotiation**
+   - Fetch `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` when a server advertises OAuth. If `scopes_supported` is present, intersect it with user overrides and use that list instead of `mcp:tools`.
+   - Parse `WWW-Authenticate` challenges on 401/403 responses and restart the authorization flow with the scopes the server demands.
+2. **User overrides**
+   - Add CLI/env controls (`--oauth-scope`, `MCPORTER_OAUTH_SCOPES`) so users can manually supply provider-specific scope strings (comma-separated) when the server doesn’t expose metadata.
+   - Persist these overrides in the server definition (especially for `--persist` ad-hoc runs) so future calls reuse the negotiated scope list.
+3. **Better errors & docs**
+   - When the server rejects `mcp:tools`, suggest either setting custom scopes or following the provider’s manual-auth instructions (e.g., Supabase’s PAT flow).
+   - Link CLI errors to this document so users understand whether the limitation is on our side or the provider’s.
+4. **Provider outreach**
+   - File upstream issues (e.g., Supabase) requesting support for standard MCP scopes or publication of `scopes_supported` metadata, so we can integrate without custom code.
+
+## Workarounds Today
+- Use a supported GUI client (Cursor, Claude Desktop, Windsurf) for Supabase’s hosted MCP—they already ship the necessary scopes.
+- Self-host Supabase MCP and configure PAT headers or your own OAuth client; you can then relax scope validation to include `mcp:tools`.
+- For other providers, consult their docs for discovery metadata. If they list scopes, set them via a future `--oauth-scope` flag once we implement it (tracked in #TODO).
+
+Until Supabase (and other providers with custom scopes) expose metadata or accept the standard scope, mcporter cannot complete their hosted OAuth flow. This is a platform limitation, not a CLI bug.

package/docs/tmux.md

@@ -0,0 +1,30 @@
+---
+summary: 'How to wrap mcporter commands in tmux sessions to monitor hangs and capture output.'
+read_when:
+  - 'Debugging long-running commands or needing persistent logs'
+---
+
+# tmux Hang Diagnostics
+
+Use `tmux` to verify whether a CLI command actually exits or is stalled on open handles. This keeps the main shell free while you inspect logs.
+
+1. Start the command in a detached session:
+   ```bash
+   tmux new-session -ds mcporter-check "pnpm exec tsx src/cli.ts list"
+   ```
+2. Wait a few seconds, then ask tmux if the session is still running:
+   ```bash
+   tmux has-session -t mcporter-check
+   ```
+   - Exit status **1** (`can't find session`) means the process exited normally.
+   - Exit status **0** means the command is still running (or hung) inside the session.
+3. Capture the output without attaching:
+   ```bash
+   tmux capture-pane -pt mcporter-check | tail -n 40
+   ```
+4. Once finished, clean up the session:
+   ```bash
+   tmux kill-session -t mcporter-check
+   ```
+
+This workflow makes it easy to confirm whether `mcporter` commands return promptly after shutdown changes (for example, when debugging lingering MCP stdio servers). Use `MCPORTER_DEBUG_HANG=1` to emit active-handle diagnostics inside the tmux session when necessary. For OAuth flows that keep a session open, set `--oauth-timeout 5000` (or `MCPORTER_OAUTH_TIMEOUT_MS=5000`) so the CLI proves it can exit without waiting a full minute for a browser callback.

package/docs/tool-calling.md

@@ -0,0 +1,73 @@
+---
+summary: 'Cheatsheet for the various mcporter call argument syntaxes and best practices.'
+read_when:
+  - 'Designing or debugging tool invocation UX'
+---
+
+# Tool Calling Cheatsheet
+
+mcporter accepts multiple argument styles so you can match whatever feels most natural in your shell or script. Every style feeds the same validation pipeline (schema-driven type coercion, required-field checks, enum hints), so pick the one that's easiest to type.
+
+## 1. Inferred Call Command
+
+```bash
+mcporter linear.list_issues team=ENG
+mcporter context7.resolve-library-id libraryName:value
+mcporter firecrawl.scrape 'url: "https://example.com"'
+```
+
+- Dotted tokens (`server.tool`) automatically run the `call` command.
+- Trailing arguments can use `key=value`, `key:value`, or `key: value` formats; multi-word values need normal shell quoting.
+- `server=value` / `tool=value` behave like their flag counterparts if you need to override the selector.
+
+## 2. Explicit `call` + Flags
+
+```bash
+mcporter call linear.create_issue --team ENG --title "Bug report"
+mcporter call chrome-devtools.take_snapshot output=markdown
+mcporter call context7.resolve-library-id libraryName: value
+```
+
+- Use `--flag value` when you prefer long-form CLI syntax.
+- Mixed forms are fine: `mcporter call linear.create_issue --team ENG title=value due: tomorrow`.
+- `--args '{"title":"Bug"}'` still ingests JSON payloads directly.
+
+## 3. Function-Call Syntax
+
+```bash
+mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'
+mcporter 'context7.resolve-library-id(libraryName: "react")'
+mcporter 'context7.resolve-library-id("react")'
+```
+
+- Mirrors the pseudo-TypeScript signature printed by `mcporter list`.
+- You may omit labels and rely on the schema order—`mcporter 'context7.resolve-library-id("react")'` maps the first argument to `libraryName` automatically.
+- Supports nested objects/arrays and gives detailed parser errors when the expression is malformed.
+- Wrap the whole expression in quotes so the shell leaves parentheses/commas intact.
+
+## 4. Mixed Server/Tool Overrides
+
+```bash
+mcporter call --server linear resolve_library_id libraryName=value
+mcporter call --tool scrape firecrawl url=https://example.com
+```
+
+- Pass `--server` / `--tool` when you want to reuse cached selectors or the command inference isn’t enough.
+- Anything after the selector uses the same unified key/value parsing.
+
+## 5. Ad-hoc Servers
+
+```bash
+mcporter call https://mcp.deepwiki.com/sse.ask_question repoName=value question:"What's new?"
+mcporter call --http-url https://mcp.example.com/mcp fetch_docs repoName=value
+```
+
+- Bare URLs trigger ad-hoc server registration; you can still use all of the styles above for arguments.
+- Combine with `--stdio "bun run ./server.ts"` (plus `--stdio-arg`, `--env`, `--cwd`) for local transports.
+
+---
+
+**Tips**
+- Use `mcporter list <server>` to see parameter names, return types, and example invocations.
+- Optional fields hide by default; add `--all-parameters` when listing a server to reveal everything.
+- `mcporter auth <server|url>` accepts the same ad-hoc flags, so you can authenticate immediately after a 401 without editing config.

package/docs/windows.md

@@ -0,0 +1,25 @@
+---
+title: Windows & WSL tips
+summary: What to do when pnpm/test flows fail on NTFS-backed worktrees.
+---
+
+## Installing dependencies
+
+* `pnpm install` fails on `/mnt/c` because NTFS/DrvFs blocks `futime`. Clone/sync the repo to `$HOME` (ext4 inside WSL) and run `./runner pnpm install` there instead. Example: `rsync -a --delete --exclude node_modules /mnt/c/Projects/mcporter/ ~/mcporter-wsl/`.
+* Keep `$HOME/.bun/bin` and `$HOME/.local/share/pnpm` on your PATH before invoking `./runner`. Without Bun and pnpm the runner prints the guardrail error and exits.
+* If you *must* work from `/mnt/c`, remount with `metadata` support (`sudo mount -t drvfs C: /mnt/c -o metadata,uid=$(id -u),gid=$(id -g),umask=22,fmask=111`). Otherwise installs, chmods, and copyfile calls will continue to fail.
+
+## Running tests
+
+* Use the ext4 copy (`~/mcporter-wsl`) for `pnpm lint`, `pnpm typecheck`, and the Vitest suites. All tests pass there (71 files / 280 tests, 1 file and 2 tests skipped).
+* Whole-repo `pnpm test` on `/mnt/c` repeatedly times out because Vitest cannot start workers when the node_modules tree belongs to root or sits on NTFS. Copy the repo to ext4 or fix ownership before retrying.
+* When working cross-filesystem, remember to sync the edited source files back to the canonical `/mnt/c/Projects/mcporter` tree (e.g., `rsync -a ~/mcporter-wsl/src/cli/generate/{template,artifacts,fs-helpers}.ts /mnt/c/Projects/mcporter/src/cli/generate/`).
+* The stdio integration suite now vendors two tiny fixtures under `tests/fixtures/stdio-*.mjs` that spin up filesystem/memory MCP servers via `node`. The tests shell out to `process.execPath`, so make sure your PATH resolves `node` correctly (fnm/nvs setups sometimes expose only `node.exe` on Windows). If you need to debug them manually, run `./runner pnpm exec vitest run tests/stdio-servers.integration.test.ts` so the guardrails apply.
+
+## Windows-specific fixes in the repo
+
+* CLI generation now uses `src/cli/generate/fs-helpers.ts`: `markExecutable` ignores `EPERM/EINVAL/ENOSYS/EACCES` so NTFS builds no longer fail when setting executable bits.
+* `safeCopyFile` falls back to a manual read/write when DrvFs blocks `copyFile`, keeping Bun bundling stable on Windows.
+* These helpers only affect Windows/WSL behavior—Linux/macOS paths still perform real `chmod`/`copyFile`.
+* Regenerated CLIs (for example `node dist/cli.js generate-cli context7 --config config/mcporter.json --bundle /mnt/c/Temp/context7-cli.js --runtime node`) now complete successfully even when the bundle lives on `/mnt/c`, and the resulting executable runs with `node /mnt/c/Temp/context7-cli.js --help`.
+* When running `mcporter generate-cli` with `--command ./relative-script.ts`, the CLI no longer tries to normalize the path into an HTTP URL—relative/bare commands are always treated as STDIO transports now, matching the PowerShell/WSL behavior you expect.

package/examples/context7-headlines.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env tsx
+
+/**
+ * Example: fetch the README for a React-adjacent package from Context7
+ * and print only the markdown headlines.
+ */
+
+import { createRuntime, createServerProxy, type CallResult } from "../src/index.js";
+
+async function main(): Promise<void> {
+	const apiKey = process.env.CONTEXT7_API_KEY;
+	const context7Definition = {
+		name: "context7",
+		description: "Context7 documentation MCP",
+		command: {
+			kind: "http" as const,
+			url: new URL("https://mcp.context7.com/mcp"),
+			headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined,
+		},
+	};
+	// Inline definitions can also live in config/mcporter.json if you prefer shared config.
+
+	const mcpRuntime = await createRuntime({ servers: [context7Definition] });
+	try {
+		const context7 = createServerProxy(mcpRuntime, "context7") as Record<string, unknown>;
+		const resolveLibraryId = context7.resolveLibraryId as (
+			args: unknown,
+		) => Promise<CallResult>;
+		const getLibraryDocs = context7.getLibraryDocs as (
+			args: unknown,
+		) => Promise<CallResult>;
+
+		const resolved = await resolveLibraryId("react");
+		const contextId = extractContext7LibraryId(resolved);
+		if (!contextId) {
+			throw new Error("Unable to resolve React documentation ID from Context7.");
+		}
+
+		const docs = await getLibraryDocs(contextId);
+
+		const markdown = docs.markdown() ?? docs.text() ?? "";
+		const headlines = markdown
+			.split("\n")
+			.filter((line) => /^#+\s/.test(line))
+			.join("\n");
+
+		console.log("# Headlines for React");
+		console.log(headlines || "(no headlines found)");
+	} finally {
+		await mcpRuntime.close();
+	}
+}
+
+main().catch((error) => {
+	console.error(error);
+	process.exit(1);
+});
+
+function extractContext7LibraryId(result: CallResult): string | null {
+	const json = result.json<
+		{ candidates?: Array<{ context7CompatibleLibraryID?: string }> } | undefined
+	>();
+	if (json && json.candidates) {
+		for (const candidate of json.candidates) {
+			if (candidate?.context7CompatibleLibraryID) {
+				return candidate.context7CompatibleLibraryID;
+			}
+		}
+	}
+	const textMatch = result.text()?.match(/Context7-compatible library ID:\s*([^\s]+)/);
+	return textMatch?.[1] ?? null;
+}

package/git

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+
+await import('./bin/git');