Compare commits
2 Commits
main
...
fix/inspec
| Author | SHA1 | Date | |
|---|---|---|---|
|
9e7db5ddb3 | ||
|
97aa9aea18 |
@ -1,711 +0,0 @@
|
||||
---
|
||||
name: crabbox
|
||||
description: Use the Crabbox wrapper for OpenClaw remote validation across Linux, macOS, Windows, and WSL2, including delegated Blacksmith Testbox proof. Report the actual provider and id.
|
||||
---
|
||||
|
||||
# Crabbox
|
||||
|
||||
Use the Crabbox wrapper when OpenClaw needs remote Linux proof for broad tests,
|
||||
CI-parity checks, secrets, hosted services, Docker/E2E/package lanes, warmed
|
||||
reusable boxes, sync timing, logs/results, cache inspection, or lease cleanup.
|
||||
|
||||
Crabbox is the transport/orchestration surface. The actual backend can be:
|
||||
|
||||
- brokered AWS Crabbox: direct provider, `provider=aws`, lease ids like
|
||||
`cbx_...`, `syncDelegated=false`
|
||||
- Blacksmith Testbox through Crabbox: delegated provider,
|
||||
`provider=blacksmith-testbox`, ids like `tbx_...`, `syncDelegated=true`
|
||||
|
||||
For OpenClaw maintainer broad `pnpm` gates, Blacksmith Testbox through the
|
||||
Crabbox wrapper is acceptable and often preferred when the standing Testbox
|
||||
rules apply. Do not describe those runs as "AWS Crabbox"; report them as
|
||||
Testbox-through-Crabbox with the `tbx_...` id and Actions run.
|
||||
|
||||
Use the repo `.crabbox.yaml` brokered AWS path when the task specifically needs
|
||||
direct AWS Crabbox behavior, persistent direct-provider leases, `--fresh-pr`,
|
||||
`--full-resync`, environment forwarding, capture/download support, or provider
|
||||
comparison. Use `--provider blacksmith-testbox` when the task needs OpenClaw
|
||||
maintainer Testbox proof, prepared CI environment, broad/heavy pnpm gates, or
|
||||
the user asks for Testbox/Blacksmith.
|
||||
|
||||
## First Checks
|
||||
|
||||
- Run from the repo root. Crabbox sync mirrors the current checkout.
|
||||
- Check the wrapper and providers before remote work:
|
||||
|
||||
```sh
|
||||
command -v crabbox
|
||||
../crabbox/bin/crabbox --version
|
||||
pnpm crabbox:run -- --help | sed -n '1,120p'
|
||||
../crabbox/bin/crabbox desktop launch --help
|
||||
../crabbox/bin/crabbox webvnc --help
|
||||
```
|
||||
|
||||
- OpenClaw scripts prefer `../crabbox/bin/crabbox` when present. The user PATH
|
||||
shim can be stale.
|
||||
- Check `.crabbox.yaml` for direct-provider defaults. Omitting `--provider`
|
||||
means brokered AWS today.
|
||||
- The brokered AWS default is a Linux developer image in `eu-west-1`; the repo
|
||||
config pins hot `eu-west-1a/b/c` placement so Fast Snapshot Restore can apply.
|
||||
If warmup drifts well past the minute-scale path, verify image promotion,
|
||||
region/AZ placement, and FSR state before blaming OpenClaw.
|
||||
- For broad OpenClaw maintainer `pnpm` gates, prefer the repo wrapper with
|
||||
`--provider blacksmith-testbox` or the repo Testbox helpers when the standing
|
||||
Testbox policy applies.
|
||||
- Always report the actual provider and id. `cbx_...` means AWS Crabbox;
|
||||
`tbx_...` means Blacksmith Testbox through Crabbox. If the output only says
|
||||
`blacksmith testbox list`, use `blacksmith testbox list --all` before
|
||||
concluding no box exists.
|
||||
- If a warm direct-provider lease smells stale, retry with `--full-resync`
|
||||
(alias `--fresh-sync`) before replacing the lease. This resets the remote
|
||||
workdir, skips the fingerprint fast path, reseeds Git when possible, and
|
||||
uploads the checkout from scratch.
|
||||
- For live/provider bugs, use the configured secret workflow before downgrading
|
||||
to mocks. Copy only the exact needed key into the remote process environment
|
||||
for that one command. Do not print it, do not sync it as a repo file, and do
|
||||
not leave it in remote shell history or logs. If no secret-safe injection path
|
||||
is available, say true live provider auth is blocked instead of silently using
|
||||
a fake key.
|
||||
- Prefer local targeted tests for tight edit loops. Broad gates belong remote.
|
||||
- Do not treat inherited shell env as operator intent. In particular,
|
||||
`OPENCLAW_LOCAL_CHECK_MODE=throttled` from the local shell is not permission
|
||||
to move broad `pnpm check:changed`, `pnpm test:changed`, full `pnpm test`, or
|
||||
lint/typecheck fan-out onto the laptop.
|
||||
- Only use `OPENCLAW_LOCAL_CHECK_MODE=throttled|full` when the user explicitly
|
||||
asks for local proof in the current task. If Testbox is queued or capacity is
|
||||
constrained, report the blocker and keep only targeted local edit-loop checks
|
||||
running.
|
||||
|
||||
## macOS And Windows Targets
|
||||
|
||||
Use these only when the task needs an existing non-Linux host. OpenClaw broad
|
||||
Linux validation uses the repo Crabbox config unless a provider is explicitly
|
||||
requested.
|
||||
|
||||
Native brokered Windows is available for Windows-specific proof. Use the AWS
|
||||
developer image in `us-west-2` on demand; it has the expected OpenClaw developer
|
||||
toolchain and Docker image cache. Keep broad Linux gates on Linux/Testbox unless
|
||||
the bug is Windows-specific:
|
||||
|
||||
```sh
|
||||
../crabbox/bin/crabbox warmup \
|
||||
--provider aws \
|
||||
--target windows \
|
||||
--windows-mode normal \
|
||||
--region us-west-2 \
|
||||
--market on-demand \
|
||||
--timing-json
|
||||
```
|
||||
|
||||
The hydrate workflow assumes Docker should already be baked into Linux images
|
||||
and only installs it as a fallback. Do not add per-run Docker installs to proof
|
||||
commands unless the image probe shows Docker is actually missing.
|
||||
|
||||
When the user explicitly asks for brokered macOS runners, use Crabbox AWS
|
||||
macOS only after confirming the deployed coordinator supports EC2 Mac host
|
||||
lifecycle/image routes and the operator has AWS EC2 Mac Dedicated Host quota
|
||||
and IAM. Prefer `CRABBOX_HOST_ID` for a known Crabbox-managed Dedicated Host,
|
||||
or run the no-spend preflight first:
|
||||
|
||||
```sh
|
||||
crabbox admin hosts quota --provider aws --target macos --region eu-west-1 --type mac2.metal --json
|
||||
crabbox admin hosts allocate --provider aws --target macos --region eu-west-1 --type mac2.metal --dry-run --json
|
||||
CRABBOX_MACOS_TYPES=all scripts/macos-host-region-preflight.sh
|
||||
```
|
||||
|
||||
Do not silently substitute AWS macOS for normal OpenClaw Linux proof. Report
|
||||
paid-host blockers as quota, IAM, coordinator deployment, or host availability
|
||||
instead of falling back to local macOS.
|
||||
|
||||
Crabbox supports static SSH targets:
|
||||
|
||||
```sh
|
||||
../crabbox/bin/crabbox run --provider ssh --target macos --static-host mac-studio.local -- xcodebuild test
|
||||
../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode normal --static-host win-dev.local -- pwsh -NoProfile -Command "dotnet test"
|
||||
../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode wsl2 --static-host win-dev.local -- pnpm test
|
||||
```
|
||||
|
||||
- `target=macos` and `target=windows --windows-mode wsl2` use the POSIX SSH,
|
||||
bash, Git, rsync, and tar contract.
|
||||
- Native Windows uses OpenSSH, PowerShell, Git, and tar; sync is manifest tar
|
||||
archive transfer into `static.workRoot`. Direct native Windows runs support
|
||||
`--script*`, `--env-from-profile`, `--preflight`, and PowerShell `--shell`.
|
||||
- `crabbox actions hydrate/register` are Linux-only today; use plain
|
||||
`crabbox run` loops for static macOS and Windows hosts.
|
||||
- Live proof needs a reachable, operator-managed SSH host. Without one, verify
|
||||
with `../crabbox/bin/crabbox run --help`, config/flag tests, and the Crabbox
|
||||
Go test suite.
|
||||
|
||||
## Direct Brokered AWS Backend
|
||||
|
||||
Use this when the task needs direct AWS Crabbox semantics rather than the
|
||||
prepared Blacksmith Testbox CI environment.
|
||||
|
||||
Changed gate:
|
||||
|
||||
```sh
|
||||
pnpm crabbox:run -- \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed"
|
||||
```
|
||||
|
||||
Full suite:
|
||||
|
||||
```sh
|
||||
pnpm crabbox:run -- \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
|
||||
```
|
||||
|
||||
Focused rerun:
|
||||
|
||||
```sh
|
||||
pnpm crabbox:run -- \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"
|
||||
```
|
||||
|
||||
Read the JSON summary. Useful fields:
|
||||
|
||||
- `provider`: `aws`
|
||||
- `leaseId`: `cbx_...`
|
||||
- `syncDelegated`: `false`
|
||||
- `commandPhases`: populated when the command prints `CRABBOX_PHASE:<name>`
|
||||
- `commandMs` / `totalMs`
|
||||
- `exitCode`
|
||||
|
||||
Crabbox should stop one-shot AWS leases automatically after the run. Verify
|
||||
cleanup when a run fails, is interrupted, or the command output is unclear:
|
||||
|
||||
```sh
|
||||
../crabbox/bin/crabbox list --provider aws
|
||||
```
|
||||
|
||||
## Blacksmith Testbox Through Crabbox
|
||||
|
||||
Use this for OpenClaw maintainer broad/heavy `pnpm` gates when the prepared CI
|
||||
environment is the right proof surface:
|
||||
|
||||
```sh
|
||||
node scripts/crabbox-wrapper.mjs run \
|
||||
--provider blacksmith-testbox \
|
||||
--blacksmith-org openclaw \
|
||||
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
|
||||
--blacksmith-job check \
|
||||
--blacksmith-ref main \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
-- \
|
||||
CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 OPENCLAW_TESTBOX=1 OPENCLAW_TESTBOX_REMOTE_RUN=1 pnpm check:changed
|
||||
```
|
||||
|
||||
Read the JSON summary and the Testbox line. Useful fields:
|
||||
|
||||
- `provider`: `blacksmith-testbox`
|
||||
- `leaseId`: `tbx_...`
|
||||
- `syncDelegated`: `true`
|
||||
- `syncPhases`: delegated/skipped because Blacksmith owns checkout/sync
|
||||
- Actions run URL/id from the Testbox output
|
||||
- `exitCode`
|
||||
|
||||
`blacksmith testbox list` may hide hydrating or ready boxes. Use:
|
||||
|
||||
```sh
|
||||
blacksmith testbox list --all
|
||||
blacksmith testbox status <tbx_id>
|
||||
```
|
||||
|
||||
## Observability Flags
|
||||
|
||||
Use these on debugging runs before inventing ad hoc logging:
|
||||
|
||||
- `--preflight`: prints run context, workspace mode, SSH target, remote user/cwd,
|
||||
and target-specific tool probes. Defaults cover `git`, `tar`, `node`, `npm`,
|
||||
`corepack`, `pnpm`, `yarn`, `bun`, `docker`, plus POSIX
|
||||
`sudo`/`apt`/`bubblewrap` and native Windows
|
||||
`powershell`/`execution_policy`/`longpaths`/`temp`/`pwsh`. Add
|
||||
`--preflight-tools node,bun,docker`, `CRABBOX_PREFLIGHT_TOOLS`, or repo
|
||||
`run.preflightTools` to replace the list. `default` expands built-ins; `none`
|
||||
prints only the workspace summary. Preflight is diagnostic only; install
|
||||
toolchains through Actions hydration, images, devcontainer/Nix/mise/asdf, or
|
||||
the run script. On `blacksmith-testbox`, this prints a delegated-unsupported
|
||||
note because the workflow owns setup.
|
||||
- `CRABBOX_ENV_ALLOW=NAME,...`: forwards only listed local env vars for direct
|
||||
providers and prints `set len=N secret=true` style summaries. On
|
||||
`blacksmith-testbox`, env forwarding is unsupported; put secrets in the
|
||||
Testbox workflow instead.
|
||||
- `--env-from-profile <file>` plus `--allow-env NAME`: loads simple
|
||||
`export NAME=value` / `NAME=value` lines from a local profile without
|
||||
executing it, then forwards only allowlisted names. `--allow-env` is
|
||||
repeatable and comma-separated. Profile values override ambient allowlisted
|
||||
env values for that run. Direct POSIX, WSL2, and native Windows runs are
|
||||
supported; delegated providers are not. Crabbox probes the uploaded profile
|
||||
remotely and prints redacted presence/length metadata before the command.
|
||||
- `--env-helper <name>`: with `--env-from-profile` on POSIX SSH targets,
|
||||
persists `.crabbox/env/<name>` and `.crabbox/env/<name>.env` so follow-up
|
||||
commands on the same lease can run through `./.crabbox/env/<name> <command>`.
|
||||
Use only on leases you control; the profile stays until cleanup, lease reset,
|
||||
or `--full-resync`.
|
||||
- `--script <file>` / `--script-stdin`: upload a local script into
|
||||
`.crabbox/scripts/` and execute it on the remote box. Shebang scripts execute
|
||||
directly on POSIX; scripts without a shebang run through `bash`. Native
|
||||
Windows uploads run through Windows PowerShell, and Crabbox appends `.ps1`
|
||||
when needed. Arguments after `--` become script args.
|
||||
- `--fresh-pr owner/repo#123|URL|number`: skip dirty local sync and create a
|
||||
fresh remote checkout of the GitHub PR. Bare numbers use the current repo's
|
||||
GitHub origin. Add `--apply-local-patch` only when the current local
|
||||
`git diff --binary HEAD` should be applied on top of that PR checkout.
|
||||
- `--full-resync` / `--fresh-sync`: reset a stale direct-provider workdir
|
||||
before syncing. Use after sync fingerprints look wrong, SSH times out before
|
||||
sync, or rsync watchdog output suggests it. It is redundant with
|
||||
`--fresh-pr`, incompatible with `--no-sync`, and unsupported by delegated
|
||||
providers.
|
||||
- `--capture-stdout <path>` / `--capture-stderr <path>`: write remote streams to
|
||||
local files and keep binary/noisy output out of retained logs. Parent
|
||||
directories must already exist. These are direct-provider only.
|
||||
- `--capture-on-fail`: on non-zero direct-provider exits, downloads
|
||||
`.crabbox/captures/*.tar.gz` with `test-results`, `playwright-report`,
|
||||
`coverage`, JUnit XML, and nearby logs. Treat as secret-bearing until reviewed.
|
||||
- `--keep-on-failure`: leave a failed one-shot lease alive for live debugging
|
||||
until idle/TTL expiry. Useful on direct providers and delegated one-shots.
|
||||
- `--timing-json`: final machine-readable timing. Add
|
||||
`echo CRABBOX_PHASE:install`, `CRABBOX_PHASE:test`, etc. in long shell
|
||||
commands; direct providers and Blacksmith Testbox both report them as
|
||||
`commandPhases`.
|
||||
|
||||
Live-provider debug template for direct AWS/Hetzner leases:
|
||||
|
||||
```sh
|
||||
mkdir -p .crabbox/logs
|
||||
pnpm crabbox:run -- --provider aws \
|
||||
--preflight \
|
||||
--allow-env OPENAI_API_KEY,OPENAI_BASE_URL \
|
||||
--timing-json \
|
||||
--capture-stdout .crabbox/logs/live-provider.stdout.log \
|
||||
--capture-stderr .crabbox/logs/live-provider.stderr.log \
|
||||
--capture-on-fail \
|
||||
--shell -- \
|
||||
"echo CRABBOX_PHASE:install; pnpm install --frozen-lockfile; echo CRABBOX_PHASE:test; pnpm test:live"
|
||||
```
|
||||
|
||||
Do not pass `--capture-*`, `--download`, `--checksum`, `--force-sync-large`, or
|
||||
`--sync-only` to delegated providers. Also do not pass `--script*`,
|
||||
`--fresh-pr`, `--full-resync`, or `--env-helper` there. Crabbox rejects these
|
||||
because the provider owns sync or command transport. `--keep-on-failure` is OK
|
||||
for delegated one-shots when you need to inspect a failed lease.
|
||||
|
||||
## Efficient Bug E2E Verification
|
||||
|
||||
Use the smallest Crabbox lane that proves the reported user path, not just the
|
||||
touched code. Aim for one after-fix E2E proof before commenting, closing, or
|
||||
opening a PR for a user-visible bug.
|
||||
|
||||
When the user says "test in Crabbox", do not simply copy tests to the remote
|
||||
box and run them there. Crabbox is for remote real-scenario proof: copy or
|
||||
install OpenClaw as the user would, run the same setup/update/CLI/Gateway/API
|
||||
call that failed, and capture behavior from that entrypoint. For regressions or
|
||||
bug reports, prove the broken state first when feasible, then run the same
|
||||
scenario after the fix.
|
||||
|
||||
Pick the lane by symptom:
|
||||
|
||||
- Docker/setup/install bug: build a package tarball and run the matching
|
||||
`scripts/e2e/*-docker.sh` or package script. This proves npm packaging,
|
||||
install paths, runtime deps, config writes, and container behavior.
|
||||
- Provider/model/auth bug: prefer true live E2E. Use the configured secret
|
||||
workflow, then inject the single needed key into Crabbox if needed. Scrub
|
||||
unrelated provider env vars in the child command so interactive defaults do
|
||||
not drift to another provider. If only a dummy key is used, label the proof
|
||||
narrowly, e.g. "UI/install path only; live provider auth not exercised."
|
||||
- Channel delivery bug: use the channel Docker/live lane when available; include
|
||||
setup, config, gateway start, send/receive or agent-turn proof, and redacted
|
||||
logs.
|
||||
- Gateway/session/tool bug: prefer an end-to-end CLI or Gateway RPC command that
|
||||
creates real state and inspects the resulting files/API output.
|
||||
- Pure parser/config bug: targeted tests may be enough, but still run a
|
||||
Crabbox command when OS, package, Docker, secrets, or service lifecycle could
|
||||
change behavior.
|
||||
|
||||
Efficient flow:
|
||||
|
||||
1. Reproduce or prove the pre-fix symptom from the real user-facing entrypoint
|
||||
when feasible. If the issue cannot be reproduced, capture the exact command
|
||||
and observed behavior instead.
|
||||
2. Patch locally and run narrow local tests for edit speed.
|
||||
3. Run one Crabbox E2E command that starts from the user-facing entrypoint:
|
||||
package install, Docker setup, onboarding, channel add, gateway start, or
|
||||
agent turn as appropriate.
|
||||
4. Record proof as: Testbox id, command, environment shape, redacted secret
|
||||
source, and copied success/failure output.
|
||||
5. If the issue says "cannot reproduce", ask for the missing config/log fields
|
||||
that would distinguish the tested path from the reporter's path.
|
||||
|
||||
Keep it efficient:
|
||||
|
||||
- Reuse existing E2E scripts and helper assertions before writing ad hoc shell.
|
||||
- Use `--script <file>` or `--script-stdin` for multi-line E2E commands instead
|
||||
of quote-heavy `--shell` strings on direct SSH providers.
|
||||
- Use `--fresh-pr <pr>` when validating an upstream PR in isolation from the
|
||||
local dirty tree. Add `--apply-local-patch` only when testing a local fixup on
|
||||
top of that PR.
|
||||
- Use `--full-resync` before replacing a warmed direct-provider lease when the
|
||||
remote workdir or sync fingerprint appears stale.
|
||||
- Use one-shot Crabbox for a single proof; use a reusable Testbox only when
|
||||
several commands must share built images, installed packages, or live state.
|
||||
- Prefer `OPENCLAW_CURRENT_PACKAGE_TGZ` with Docker/package lanes when testing a
|
||||
candidate tarball; prefer the repo's package helper instead of direct source
|
||||
execution when the bug might be packaging/install related.
|
||||
- Keep secrets redacted. It is fine to report key presence, source, and length;
|
||||
never print secret values.
|
||||
- Include `--timing-json` on broad or flaky runs when command duration or sync
|
||||
behavior matters.
|
||||
|
||||
Before/after PR proof on delegated Testbox:
|
||||
|
||||
- For PRs that should prove "broken before, fixed after", compare base and PR
|
||||
on the same Testbox when practical. Fetch both refs, create detached temp
|
||||
worktrees under `/tmp`, install in each, then run the same harness twice.
|
||||
- Do not checkout base/PR refs in the synced repo root. Delegated Testbox sync
|
||||
may leave the root dirty with local files; `git checkout` can abort or mix
|
||||
proof state.
|
||||
- Temp harness files under `/tmp` do not resolve repo packages by default. Put
|
||||
the harness inside the worktree, or in ESM use
|
||||
`createRequire(path.join(process.cwd(), "package.json"))` before requiring
|
||||
workspace deps such as `@lydell/node-pty`.
|
||||
- For full-screen TUI/CLI bugs, a PTY harness is stronger than helper-only
|
||||
assertions. Use a real PTY, wait for visible lifecycle markers, send input,
|
||||
then send control keys and assert process exit/stuck behavior.
|
||||
- When validating a rebased local branch before push, remember delegated sync
|
||||
usually validates synced file content on a detached dirty checkout, not a
|
||||
remote commit object. Record the local head SHA, changed files, Testbox id,
|
||||
and final success markers; after pushing, ensure the pushed SHA has the same
|
||||
file content.
|
||||
- If GitHub CI is still queued but the exact changed content passed Testbox
|
||||
`pnpm check:changed`, `pnpm check:test-types`, and the real E2E proof, it is
|
||||
reasonable to merge once required checks allow it. Note any still-running
|
||||
unrelated shards in the proof comment instead of waiting forever.
|
||||
|
||||
Interactive CLI/onboarding:
|
||||
|
||||
- For full-screen or prompt-heavy CLI flows, run the target command inside tmux
|
||||
on the Crabbox and drive it with `tmux send-keys`; capture proof with
|
||||
`tmux capture-pane`, redacted through `sed`.
|
||||
- Prefer deterministic arrow navigation over search typing for Clack-style
|
||||
searchable selects. Raw `send-keys -l openai` may not trigger filtering in a
|
||||
tmux pane; inspect option order locally or on-box and send exact Down/Enter
|
||||
sequences.
|
||||
- Isolate mutable state with `OPENCLAW_STATE_DIR=$(mktemp -d)`. Plugin npm
|
||||
installs live under that state dir (`npm/node_modules/...`), not under
|
||||
`OPENCLAW_CONFIG_DIR`. Verify downloads by checking the state dir, package
|
||||
lock, and installed package metadata.
|
||||
- To test automatic setup installs against local package artifacts, use
|
||||
`OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1` plus
|
||||
`OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{"plugin-id":"npm-pack:/tmp/plugin.tgz"}'`.
|
||||
Pack with `npm pack`, set an isolated `OPENCLAW_STATE_DIR`, and verify the
|
||||
package under `npm/node_modules`. Overrides are test-only and must not be
|
||||
treated as official/trusted-source installs.
|
||||
- For OpenAI/Codex onboarding proof, the useful markers are the UI line
|
||||
`Installed Codex plugin`, `npm/node_modules/@openclaw/codex`, and the
|
||||
package-lock entry showing the bundled `@openai/codex` dependency. A dummy
|
||||
OpenAI-shaped key can prove only UI/install behavior; it is not live auth.
|
||||
|
||||
## Reuse And Keepalive
|
||||
|
||||
For most Crabbox calls, one-shot is enough. Use reuse only when you need
|
||||
multiple manual commands on the same hydrated box.
|
||||
|
||||
If Crabbox returns a reusable id or you intentionally keep a lease:
|
||||
|
||||
```sh
|
||||
pnpm crabbox:run -- --id <cbx_id-or-slug> --no-sync --timing-json --shell -- "pnpm test <path>"
|
||||
```
|
||||
|
||||
Stop boxes you created before handoff:
|
||||
|
||||
```sh
|
||||
pnpm crabbox:stop -- <id-or-slug>
|
||||
blacksmith testbox stop --id <tbx_id>
|
||||
```
|
||||
|
||||
## Interactive Desktop And WebVNC
|
||||
|
||||
Prefer WebVNC for human inspection because the browser portal can preload the
|
||||
lease VNC password and avoids a native VNC client's copy/paste/password dance.
|
||||
Use native `crabbox vnc` only when WebVNC is unavailable, the browser portal is
|
||||
broken, or the user explicitly wants a local VNC client.
|
||||
|
||||
Common desktop flow:
|
||||
|
||||
```sh
|
||||
../crabbox/bin/crabbox warmup --provider hetzner --desktop --browser --class standard --idle-timeout 60m --ttl 240m
|
||||
../crabbox/bin/crabbox desktop launch --provider hetzner --id <cbx_id-or-slug> --browser --url https://example.com --webvnc --open --take-control
|
||||
```
|
||||
|
||||
Useful WebVNC commands:
|
||||
|
||||
```sh
|
||||
../crabbox/bin/crabbox webvnc --provider hetzner --id <cbx_id-or-slug> --open --take-control
|
||||
../crabbox/bin/crabbox webvnc daemon start --provider hetzner --id <cbx_id-or-slug> --open --take-control
|
||||
../crabbox/bin/crabbox webvnc daemon status --provider hetzner --id <cbx_id-or-slug>
|
||||
../crabbox/bin/crabbox webvnc daemon stop --provider hetzner --id <cbx_id-or-slug>
|
||||
../crabbox/bin/crabbox webvnc status --provider hetzner --id <cbx_id-or-slug>
|
||||
../crabbox/bin/crabbox webvnc reset --provider hetzner --id <cbx_id-or-slug> --open --take-control
|
||||
../crabbox/bin/crabbox desktop doctor --provider hetzner --id <cbx_id-or-slug>
|
||||
../crabbox/bin/crabbox desktop click --provider hetzner --id <cbx_id-or-slug> --x 640 --y 420
|
||||
../crabbox/bin/crabbox desktop paste --provider hetzner --id <cbx_id-or-slug> --text "user@example.com"
|
||||
../crabbox/bin/crabbox desktop key --provider hetzner --id <cbx_id-or-slug> ctrl+l
|
||||
../crabbox/bin/crabbox artifacts collect --id <cbx_id-or-slug> --all --output artifacts/<slug>
|
||||
../crabbox/bin/crabbox artifacts publish --dir artifacts/<slug> --pr <number>
|
||||
```
|
||||
|
||||
`desktop launch --webvnc --open` is usually the nicest one-shot: it starts the
|
||||
browser/app inside the visible session, bridges the lease into the authenticated
|
||||
WebVNC portal, and opens the portal. Keep browsers windowed for human QA; use
|
||||
`--fullscreen` only for capture/video workflows.
|
||||
For human handoff, include `--take-control` so the opened portal viewer gets
|
||||
keyboard/mouse control automatically instead of landing as an observer.
|
||||
|
||||
Human handoff preflight:
|
||||
|
||||
- Do not assume a visible desktop or launched browser means the repo CLI/app is
|
||||
installed, built, or on the interactive terminal's `PATH`.
|
||||
- Before handing WebVNC to a human tester, prove the expected command from the
|
||||
same kept lease and from a neutral directory such as `~`.
|
||||
- If the handoff needs repo-local code, sync/build/link it explicitly on that
|
||||
lease. Source-tree CLIs often need build output before a symlink works.
|
||||
- Prefer a real `command -v <expected-command> && <expected-command> --version`
|
||||
check over a repo-root-only `pnpm ...` command.
|
||||
|
||||
Generic handoff repair pattern:
|
||||
|
||||
```sh
|
||||
../crabbox/bin/crabbox run --id <cbx_id-or-slug> --full-resync --shell -- \
|
||||
"set -euo pipefail
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm build
|
||||
sudo ln -sf \"\$PWD/<cli-entry>\" /usr/local/bin/<expected-command>
|
||||
cd ~
|
||||
command -v <expected-command>
|
||||
<expected-command> --version"
|
||||
```
|
||||
|
||||
## If Crabbox Fails
|
||||
|
||||
Keep the fallback narrow. First decide whether the failure is Crabbox itself,
|
||||
the brokered AWS lease, Blacksmith/Testbox, repo hydration, sync, or the test
|
||||
command.
|
||||
|
||||
Fast checks:
|
||||
|
||||
```sh
|
||||
command -v crabbox
|
||||
../crabbox/bin/crabbox --version
|
||||
pnpm crabbox:run -- --help | sed -n '1,140p'
|
||||
../crabbox/bin/crabbox doctor
|
||||
command -v blacksmith
|
||||
blacksmith --version
|
||||
blacksmith testbox list
|
||||
```
|
||||
|
||||
Common Crabbox-only failures:
|
||||
|
||||
- Provider missing or old CLI: use `../crabbox/bin/crabbox` from the sibling
|
||||
repo, or update/install Crabbox before retrying.
|
||||
- Bad local config: inspect `.crabbox.yaml`, `crabbox config show`, and
|
||||
`crabbox whoami`; normal OpenClaw proof should use brokered AWS without
|
||||
asking for cloud keys.
|
||||
- Slug/claim confusion: use the raw `cbx_...` / `tbx_...` id, or run one-shot
|
||||
without `--id`.
|
||||
- Sync/timing bug: add `--debug --timing-json`; capture the final JSON and the
|
||||
printed Actions URL. Large sync warnings now include top source directories
|
||||
by file count and a hint to update `.crabboxignore` / `sync.exclude`; inspect
|
||||
those before reaching for `--force-sync-large`. Quiet rsync watchdogs and SSH
|
||||
timeouts now print `next_action=` hints; follow them, usually `--full-resync`
|
||||
first and a fresh lease second.
|
||||
- Cleanup uncertainty: run `crabbox list --provider aws`; for explicit
|
||||
Blacksmith runs, use `blacksmith testbox list` and stop only boxes you
|
||||
created.
|
||||
- Testbox queued/capacity pressure: do not retry Blacksmith repeatedly. Rerun
|
||||
once without `--provider` so `.crabbox.yaml` routes to brokered AWS, or report
|
||||
the Blacksmith blocker if Testbox itself is the requested proof.
|
||||
|
||||
If brokered AWS cannot dispatch, sync, attach, or stop, retry once with
|
||||
`--debug` and `--timing-json`:
|
||||
|
||||
```sh
|
||||
pnpm crabbox:run -- --debug --timing-json -- \
|
||||
CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed
|
||||
```
|
||||
|
||||
Full suite:
|
||||
|
||||
```sh
|
||||
pnpm crabbox:run -- --debug --timing-json -- \
|
||||
CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test
|
||||
```
|
||||
|
||||
Auth fallback, only when `blacksmith` says auth is missing:
|
||||
|
||||
```sh
|
||||
blacksmith auth login --non-interactive --organization openclaw
|
||||
```
|
||||
|
||||
Raw Blacksmith footguns:
|
||||
|
||||
- Run from repo root. The CLI syncs the current directory.
|
||||
- Save the returned `tbx_...` id in the session.
|
||||
- Reuse that id for focused reruns; stop it before handoff.
|
||||
- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.
|
||||
- Treat `blacksmith testbox list` as cleanup diagnostics, not a shared reusable
|
||||
queue.
|
||||
|
||||
Use Blacksmith only when the task is specifically about Testbox, brokered AWS
|
||||
is unavailable, or an explicit comparison is needed. If Blacksmith is down or
|
||||
quota-limited, do not keep probing it; stay on brokered AWS and note the
|
||||
delegated-provider outage.
|
||||
|
||||
## Blacksmith Backend Notes
|
||||
|
||||
Crabbox Blacksmith backend delegates setup to:
|
||||
|
||||
- org: `openclaw`
|
||||
- workflow: `.github/workflows/ci-check-testbox.yml`
|
||||
- job: `check`
|
||||
- ref: `main` unless testing a branch/tag intentionally
|
||||
|
||||
The hydration workflow owns checkout, Node/pnpm setup, dependency install,
|
||||
secrets, ready marker, and keepalive. Crabbox owns dispatch, sync, SSH command
|
||||
execution, timing, logs/results, and cleanup.
|
||||
|
||||
Minimal Blacksmith-backed Crabbox run, from repo root:
|
||||
|
||||
```sh
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json -- \
|
||||
CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed
|
||||
```
|
||||
|
||||
Use direct Blacksmith only when Crabbox is the broken layer and you are
|
||||
isolating a Crabbox bug. Prefer direct `blacksmith testbox list` for cleanup
|
||||
diagnostics, not as a reusable work queue.
|
||||
|
||||
Important Blacksmith footguns:
|
||||
|
||||
- Always run from repo root. The CLI syncs the current directory.
|
||||
- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.
|
||||
- If auth is missing and browser auth is acceptable:
|
||||
|
||||
```sh
|
||||
blacksmith auth login --non-interactive --organization openclaw
|
||||
```
|
||||
|
||||
## Brokered AWS
|
||||
|
||||
Use AWS for normal OpenClaw remote proof. The repo `.crabbox.yaml` already
|
||||
selects brokered AWS, so omit `--provider` unless you are testing a different
|
||||
provider deliberately.
|
||||
|
||||
```sh
|
||||
pnpm crabbox:warmup -- --class beast --market on-demand --idle-timeout 90m
|
||||
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
|
||||
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed"
|
||||
pnpm crabbox:stop -- <cbx_id-or-slug>
|
||||
```
|
||||
|
||||
Install/auth for owned Crabbox if needed:
|
||||
|
||||
```sh
|
||||
brew install openclaw/tap/crabbox
|
||||
crabbox login --url https://crabbox.openclaw.ai --provider aws
|
||||
```
|
||||
|
||||
New users should self-resolve broker auth before anyone asks for AWS keys:
|
||||
|
||||
```sh
|
||||
crabbox config show
|
||||
crabbox doctor
|
||||
crabbox whoami
|
||||
```
|
||||
|
||||
- If broker auth is missing, run `crabbox login --url https://crabbox.openclaw.ai --provider aws`.
|
||||
- If the CLI asks for `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or AWS
|
||||
profile setup during normal OpenClaw validation, assume the agent selected
|
||||
the wrong path. Use brokered `crabbox login` or an existing brokered lease
|
||||
before asking the user for cloud credentials.
|
||||
- Ask for AWS keys only for explicit direct-provider/account administration,
|
||||
not for normal brokered OpenClaw proof.
|
||||
- Trusted automation may still use
|
||||
`printf '%s' "$CRABBOX_COORDINATOR_TOKEN" | crabbox login --url https://crabbox.openclaw.ai --provider aws --token-stdin`.
|
||||
|
||||
macOS config lives at:
|
||||
|
||||
```text
|
||||
~/Library/Application Support/crabbox/config.yaml
|
||||
```
|
||||
|
||||
It should include `broker.url`, `broker.token`, and usually `provider: aws`
|
||||
for OpenClaw lanes. Let that config drive normal validation.
|
||||
|
||||
### Interactive Desktop / WebVNC
|
||||
|
||||
For human desktop demos, prefer `webvnc` over native `vnc` and keep the remote
|
||||
desktop visible/windowed. Do not fullscreen the remote browser or hide the XFCE
|
||||
panel/window chrome unless the explicit goal is video/capture output. After
|
||||
launch, verify a screenshot shows the desktop panel plus browser title bar. If
|
||||
Chrome is fullscreen, toggle it back with:
|
||||
|
||||
```sh
|
||||
crabbox run --id <lease> --shell -- 'DISPLAY=:99 xdotool search --onlyvisible --class google-chrome windowactivate key F11'
|
||||
```
|
||||
|
||||
## Diagnostics
|
||||
|
||||
```sh
|
||||
crabbox status --id <id-or-slug> --wait
|
||||
crabbox inspect --id <id-or-slug> --json
|
||||
crabbox sync-plan
|
||||
crabbox history --limit 20
|
||||
crabbox history --lease <id-or-slug>
|
||||
crabbox attach <run_id>
|
||||
crabbox events <run_id> --json
|
||||
crabbox logs <run_id>
|
||||
crabbox results <run_id>
|
||||
crabbox cache stats --id <id-or-slug>
|
||||
crabbox ssh --id <id-or-slug>
|
||||
blacksmith testbox list
|
||||
```
|
||||
|
||||
Use `--debug` on `run` when measuring sync timing.
|
||||
Use `--timing-json` on warmup, hydrate, and run when comparing backends.
|
||||
Use `--market spot|on-demand` only on AWS warmup/one-shot runs.
|
||||
|
||||
## Failure Triage
|
||||
|
||||
- Crabbox cannot find provider: verify `../crabbox/bin/crabbox --help` lists
|
||||
the provider selected by `.crabbox.yaml`; update Crabbox before falling back.
|
||||
- Hydration stuck or failed: open the printed GitHub Actions run URL and inspect
|
||||
the hydration step.
|
||||
- Sync failed: rerun with `--debug`; check changed-file count and whether the
|
||||
checkout is dirty.
|
||||
- Command failed: rerun only the failing shard/file first. Do not rerun a full
|
||||
suite until the focused failure is understood.
|
||||
- Cleanup uncertain: `crabbox list --provider aws`; for explicit Blacksmith
|
||||
runs, use `blacksmith testbox list` and stop owned `tbx_...` leases you
|
||||
created.
|
||||
- Crabbox broken but Blacksmith works: use the direct Blacksmith fallback above,
|
||||
then file/fix the Crabbox issue.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not add OpenClaw-specific setup to Crabbox itself. Put repo setup in the
|
||||
hydration workflow and keep Crabbox generic around lease, sync, command
|
||||
execution, logs/results, timing, and cleanup.
|
||||
@ -1,53 +0,0 @@
|
||||
profile: mcporter-check
|
||||
provider: aws
|
||||
class: standard
|
||||
capacity:
|
||||
market: spot
|
||||
strategy: most-available
|
||||
fallback: on-demand-after-120s
|
||||
hints: true
|
||||
regions:
|
||||
- eu-west-1
|
||||
- eu-west-2
|
||||
- eu-central-1
|
||||
- us-east-1
|
||||
- us-west-2
|
||||
actions:
|
||||
workflow: .github/workflows/crabbox-hydrate.yml
|
||||
job: hydrate
|
||||
ref: main
|
||||
runnerLabels:
|
||||
- crabbox
|
||||
- openclaw
|
||||
- mcporter
|
||||
runnerVersion: latest
|
||||
ephemeral: true
|
||||
aws:
|
||||
region: eu-west-1
|
||||
rootGB: 160
|
||||
sync:
|
||||
delete: true
|
||||
checksum: false
|
||||
gitSeed: true
|
||||
fingerprint: true
|
||||
baseRef: main
|
||||
exclude:
|
||||
- .artifacts
|
||||
- .codex
|
||||
- .DS_Store
|
||||
- coverage
|
||||
- dist
|
||||
- node_modules
|
||||
- bin
|
||||
env:
|
||||
allow:
|
||||
- CI
|
||||
- CGO_*
|
||||
- GOFLAGS
|
||||
- GOWORK
|
||||
- NODE_OPTIONS
|
||||
- PNPM_*
|
||||
- NPM_CONFIG_*
|
||||
ssh:
|
||||
user: crabbox
|
||||
port: '2222'
|
||||
2
.gitattributes
vendored
2
.gitattributes
vendored
@ -1,4 +1,2 @@
|
||||
* text eol=lf
|
||||
*.png binary
|
||||
*.tar.gz binary
|
||||
*.tgz binary
|
||||
|
||||
7
.github/CODEOWNERS
vendored
7
.github/CODEOWNERS
vendored
@ -1,7 +0,0 @@
|
||||
# Protect ownership and automation rules.
|
||||
/.github/CODEOWNERS @openclaw/openclaw-secops
|
||||
/.github/workflows/ @openclaw/openclaw-secops
|
||||
/package.json @openclaw/openclaw-secops
|
||||
/.github/actionlint.yaml @openclaw/openclaw-secops
|
||||
/.agents/skills/ @openclaw/openclaw-secops
|
||||
/.crabbox.yaml @openclaw/openclaw-secops
|
||||
5
.github/actionlint.yaml
vendored
5
.github/actionlint.yaml
vendored
@ -1,5 +0,0 @@
|
||||
self-hosted-runner:
|
||||
labels:
|
||||
- crabbox
|
||||
- openclaw
|
||||
- mcporter
|
||||
60
.github/workflows/ci.yml
vendored
60
.github/workflows/ci.yml
vendored
@ -7,71 +7,19 @@ on:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: ci-${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
|
||||
|
||||
jobs:
|
||||
build:
|
||||
name: build (${{ matrix.os }})
|
||||
timeout-minutes: 15
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
os: [ubuntu-latest, macos-15, windows-latest]
|
||||
os: [ubuntu-latest, macos-latest, windows-latest]
|
||||
runs-on: ${{ matrix.os }}
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 24
|
||||
|
||||
- run: corepack enable
|
||||
- run: corepack prepare pnpm@10.33.2 --activate
|
||||
|
||||
- name: Locate pnpm store
|
||||
id: pnpm-store
|
||||
shell: bash
|
||||
run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- uses: actions/cache@v5
|
||||
with:
|
||||
path: ${{ steps.pnpm-store.outputs.path }}
|
||||
key: ${{ runner.os }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
|
||||
restore-keys: |
|
||||
${{ runner.os }}-pnpm-
|
||||
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v4
|
||||
- run: pnpm install --no-frozen-lockfile
|
||||
- run: pnpm --version
|
||||
- run: pnpm check
|
||||
if: matrix.os != 'macos-15'
|
||||
|
||||
- name: Check without type-aware oxlint
|
||||
if: matrix.os == 'macos-15'
|
||||
run: pnpm format:check && pnpm typecheck
|
||||
|
||||
- name: Verify generated schema is committed
|
||||
if: matrix.os == 'ubuntu-latest'
|
||||
shell: bash
|
||||
run: |
|
||||
pnpm generate:schema
|
||||
pnpm exec oxfmt mcporter.schema.json
|
||||
git diff --exit-code -- mcporter.schema.json
|
||||
|
||||
- name: Build docs site
|
||||
if: matrix.os == 'ubuntu-latest'
|
||||
run: pnpm docs:site
|
||||
|
||||
- run: pnpm build
|
||||
|
||||
- name: Pack npm artifact
|
||||
if: matrix.os == 'ubuntu-latest'
|
||||
run: pnpm pack --pack-destination /tmp
|
||||
|
||||
- run: pnpm test
|
||||
env:
|
||||
FIRECRAWL_API_KEY: test
|
||||
|
||||
126
.github/workflows/crabbox-hydrate.yml
vendored
126
.github/workflows/crabbox-hydrate.yml
vendored
@ -1,126 +0,0 @@
|
||||
name: Crabbox Hydrate
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
crabbox_id:
|
||||
description: 'Crabbox lease ID'
|
||||
required: true
|
||||
type: string
|
||||
ref:
|
||||
description: 'Git ref to hydrate'
|
||||
required: false
|
||||
type: string
|
||||
crabbox_runner_label:
|
||||
description: 'Dynamic Crabbox runner label'
|
||||
required: true
|
||||
type: string
|
||||
crabbox_job:
|
||||
description: 'Hydration job identifier expected by Crabbox'
|
||||
required: false
|
||||
default: 'hydrate'
|
||||
type: string
|
||||
crabbox_keep_alive_minutes:
|
||||
description: 'Minutes to keep the hydrated job alive'
|
||||
required: false
|
||||
default: '90'
|
||||
type: string
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
NODE_VERSION: '24'
|
||||
PNPM_VERSION: '10.33.2'
|
||||
|
||||
jobs:
|
||||
hydrate:
|
||||
name: hydrate
|
||||
runs-on: [self-hosted, crabbox, openclaw, mcporter, '${{ inputs.crabbox_runner_label }}']
|
||||
timeout-minutes: 120
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
ref: ${{ inputs.ref || github.ref }}
|
||||
|
||||
- uses: pnpm/action-setup@v6.0.8
|
||||
with:
|
||||
version: ${{ env.PNPM_VERSION }}
|
||||
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: pnpm
|
||||
|
||||
- name: Prepare pnpm workspace
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git fetch --no-tags --depth=50 origin "+refs/heads/main:refs/remotes/origin/main"
|
||||
pnpm install --frozen-lockfile
|
||||
node --version
|
||||
pnpm --version
|
||||
pnpm --version
|
||||
|
||||
- name: Mark Crabbox ready
|
||||
shell: bash
|
||||
env:
|
||||
CRABBOX_ID: ${{ inputs.crabbox_id }}
|
||||
CRABBOX_JOB: ${{ inputs.crabbox_job }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
job="${CRABBOX_JOB}"
|
||||
if [ -z "$job" ]; then job=hydrate; fi
|
||||
case "$CRABBOX_ID" in
|
||||
''|*[!A-Za-z0-9._-]*)
|
||||
echo "Invalid crabbox_id" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
mkdir -p "$HOME/.crabbox/actions"
|
||||
state="$HOME/.crabbox/actions/${CRABBOX_ID}.env"
|
||||
env_file="$HOME/.crabbox/actions/${CRABBOX_ID}.env.sh"
|
||||
{
|
||||
for key in CI GITHUB_ACTIONS GITHUB_WORKSPACE GITHUB_REPOSITORY GITHUB_RUN_ID GITHUB_RUN_NUMBER GITHUB_RUN_ATTEMPT GITHUB_REF GITHUB_REF_NAME GITHUB_SHA GITHUB_EVENT_NAME GITHUB_ACTOR RUNNER_OS RUNNER_ARCH RUNNER_TEMP RUNNER_TOOL_CACHE PATH; do
|
||||
value="${!key-}"
|
||||
if [ -n "$value" ]; then
|
||||
printf 'export %s=%q\n' "$key" "$value"
|
||||
fi
|
||||
done
|
||||
} > "${env_file}.tmp"
|
||||
mv "${env_file}.tmp" "$env_file"
|
||||
tmp="${state}.tmp"
|
||||
{
|
||||
echo "WORKSPACE=${GITHUB_WORKSPACE}"
|
||||
echo "RUN_ID=${GITHUB_RUN_ID}"
|
||||
echo "JOB=${job}"
|
||||
echo "ENV_FILE=${env_file}"
|
||||
echo "READY_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
||||
} > "$tmp"
|
||||
mv "$tmp" "$state"
|
||||
|
||||
- name: Keep Crabbox job alive
|
||||
shell: bash
|
||||
env:
|
||||
CRABBOX_ID: ${{ inputs.crabbox_id }}
|
||||
CRABBOX_KEEP_ALIVE_MINUTES: ${{ inputs.crabbox_keep_alive_minutes }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
case "$CRABBOX_ID" in
|
||||
''|*[!A-Za-z0-9._-]*)
|
||||
echo "Invalid crabbox_id" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
minutes="${CRABBOX_KEEP_ALIVE_MINUTES}"
|
||||
case "$minutes" in
|
||||
''|*[!0-9]*) minutes=90 ;;
|
||||
esac
|
||||
stop="$HOME/.crabbox/actions/${CRABBOX_ID}.stop"
|
||||
deadline=$(( $(date +%s) + minutes * 60 ))
|
||||
while [ "$(date +%s)" -lt "$deadline" ]; do
|
||||
if [ -f "$stop" ]; then
|
||||
exit 0
|
||||
fi
|
||||
sleep 15
|
||||
done
|
||||
53
.github/workflows/pages.yml
vendored
53
.github/workflows/pages.yml
vendored
@ -1,53 +0,0 @@
|
||||
name: pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- 'scripts/build-docs-site.mjs'
|
||||
- 'scripts/docs-site-assets.mjs'
|
||||
- '.github/workflows/pages.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: pages
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
name: Deploy docs
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
steps:
|
||||
- name: Check out
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Set up Node
|
||||
uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: '24'
|
||||
|
||||
- name: Build docs site
|
||||
run: node scripts/build-docs-site.mjs
|
||||
|
||||
- name: Configure Pages
|
||||
uses: actions/configure-pages@v6
|
||||
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v5
|
||||
with:
|
||||
path: dist/docs-site
|
||||
|
||||
- name: Deploy
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v5
|
||||
63
.github/workflows/update-homebrew-tap.yml
vendored
63
.github/workflows/update-homebrew-tap.yml
vendored
@ -1,63 +0,0 @@
|
||||
name: Update Homebrew Tap
|
||||
|
||||
on:
|
||||
release:
|
||||
types: [published]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
tag:
|
||||
description: 'Release tag to publish to the tap (for example, v0.10.1)'
|
||||
required: true
|
||||
type: string
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
update-homebrew-tap:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Resolve release tag
|
||||
id: release
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
tag="${{ inputs.tag || github.event.release.tag_name }}"
|
||||
if [[ -z "$tag" ]]; then
|
||||
echo "Missing release tag." >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "tag=$tag" >> "$GITHUB_OUTPUT"
|
||||
echo "request_id=mcporter-${tag}-${GITHUB_RUN_ID}" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Dispatch tap update
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
test -n "$GH_TOKEN"
|
||||
gh workflow run update-formula.yml \
|
||||
--repo steipete/homebrew-tap \
|
||||
-f formula=mcporter \
|
||||
-f tag="${{ steps.release.outputs.tag }}" \
|
||||
-f repository=openclaw/mcporter \
|
||||
-f artifact_url='https://github.com/openclaw/mcporter/releases/download/{tag}/mcporter-{version}.tgz' \
|
||||
-f request_id="${{ steps.release.outputs.request_id }}"
|
||||
|
||||
- name: Wait for tap update
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
for _ in {1..20}; do
|
||||
run_id="$(gh run list --repo steipete/homebrew-tap --workflow update-formula.yml --json databaseId,displayTitle --jq '.[] | select(.displayTitle | contains("${{ steps.release.outputs.request_id }}")) | .databaseId' | head -n1)"
|
||||
if [[ -n "$run_id" ]]; then
|
||||
gh run watch "$run_id" --repo steipete/homebrew-tap --exit-status
|
||||
exit 0
|
||||
fi
|
||||
sleep 5
|
||||
done
|
||||
echo "Timed out waiting for tap workflow to appear." >&2
|
||||
exit 1
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
@ -1,5 +1,4 @@
|
||||
node_modules
|
||||
.pnpm-store
|
||||
.DS_Store
|
||||
dist
|
||||
dist-bun
|
||||
|
||||
@ -1,15 +0,0 @@
|
||||
{
|
||||
"$schema": "./node_modules/oxfmt/configuration_schema.json",
|
||||
"useTabs": false,
|
||||
"tabWidth": 2,
|
||||
"printWidth": 120,
|
||||
"singleQuote": true,
|
||||
"jsxSingleQuote": false,
|
||||
"quoteProps": "as-needed",
|
||||
"trailingComma": "es5",
|
||||
"semi": true,
|
||||
"arrowParens": "always",
|
||||
"bracketSameLine": false,
|
||||
"bracketSpacing": true,
|
||||
"ignorePatterns": ["dist", "tmp", "node_modules"]
|
||||
}
|
||||
@ -1,22 +0,0 @@
|
||||
{
|
||||
"$schema": "./node_modules/oxlint/configuration_schema.json",
|
||||
"plugins": ["typescript", "unicorn", "oxc"],
|
||||
"categories": {
|
||||
"correctness": "error",
|
||||
"suspicious": "error",
|
||||
"perf": "error"
|
||||
},
|
||||
"rules": {
|
||||
"no-await-in-loop": "off",
|
||||
"oxc/no-async-endpoint-handlers": "off",
|
||||
"typescript/no-unsafe-type-assertion": "off",
|
||||
"typescript/no-unnecessary-type-assertion": "off",
|
||||
"typescript/no-unnecessary-type-conversion": "off",
|
||||
"typescript/no-unnecessary-type-parameters": "off",
|
||||
"typescript/no-unnecessary-template-expression": "off",
|
||||
"unicorn/prefer-add-event-listener": "off"
|
||||
},
|
||||
"env": {
|
||||
"builtin": true
|
||||
}
|
||||
}
|
||||
34
AGENTS.md
34
AGENTS.md
@ -6,18 +6,15 @@ Shared guardrails distilled from the various `~/Projects/*/AGENTS.md` files (sta
|
||||
Usage: In repo copies, the shared content lives inside `<shared>…</shared>` and the tool list inside `<tools>…</tools>`. Keep those tagged blocks identical across repos; anything outside them is repo-local and can be customized freely.
|
||||
|
||||
## Codex Global Instructions
|
||||
|
||||
- Keep the system-wide Codex guidance at `~/.codex/AGENTS.md` (the Codex home; override via `CODEX_HOME` if needed) so every task inherits these rules by default.
|
||||
|
||||
## General Guardrails
|
||||
|
||||
### Intake & Scoping
|
||||
|
||||
- Open the local agent instructions plus any `docs:list` summaries at the start of every session. Re-run those helpers whenever you suspect the docs may have changed.
|
||||
- Review any referenced tmux panes, CI logs, or failing command transcripts so you understand the most recent context before writing code.
|
||||
|
||||
### Tooling & Command Wrappers
|
||||
|
||||
- Use the command wrappers provided by the workspace (`./runner …`, `scripts/committer`, `pnpm mcp:*`, etc.). Skip them only for trivial read-only shell commands if that’s explicitly allowed.
|
||||
- Stick to the package manager and runtime mandated by the repo (pnpm-only, bun-only, swift-only, go-only, etc.). Never swap in alternatives without approval.
|
||||
- When editing shared guardrail scripts (runners, committer helpers, browser tools, etc.), mirror the same change back into the `agent-scripts` folder so the canonical copy stays current.
|
||||
@ -26,34 +23,29 @@ Usage: In repo copies, the shared content lives inside `<shared>…</shared>` an
|
||||
- Keep the project’s `AGENTS.md` `<tools></tools>` block in sync with the full tool list from `TOOLS.md` so downstream repos get the latest tool descriptions.
|
||||
|
||||
### tmux & Long Tasks
|
||||
|
||||
- Run any command that could hang (tests, servers, log streams, browser automation) inside tmux using the repository’s preferred entry point.
|
||||
- Do not wrap tmux commands in infinite polling loops. Run the job, sleep briefly (≤30 s), capture output, and surface status at least once per minute.
|
||||
- Document which sessions you create and clean them up when they are no longer needed unless the workflow explicitly calls for persistent watchers.
|
||||
|
||||
### Build, Test & Verification
|
||||
|
||||
- Before handing off work, run the full “green gate” for that repo (lint, type-check, tests, doc scripts, etc.). Follow the same command set humans run—no ad-hoc shortcuts.
|
||||
- Leave existing watchers running unless the owner tells you to stop them; keep their tmux panes healthy if you started them.
|
||||
- Treat every bug fix as a chance to add or extend automated tests that prove the behavior.
|
||||
- When someone asks to “fix CI,” use the GitHub CLI (`gh`) to inspect, rerun, and unblock failing workflows on GitHub until they are green.
|
||||
|
||||
### Code Quality & Naming
|
||||
|
||||
- Refactor in place. Never create duplicate files with suffixes such as “V2”, “New”, or “Fixed”; update the canonical file and remove obsolete paths entirely.
|
||||
- Favor strict typing: avoid `any`, untyped dictionaries, or generic type erasure unless absolutely required. Prefer concrete structs/enums and mark public concurrency surfaces appropriately.
|
||||
- Keep files at a manageable size. When a file grows unwieldy, extract helpers or new modules instead of letting it bloat.
|
||||
- Match the repo’s established style (commit conventions, formatting tools, component patterns, etc.) by studying existing code before introducing new patterns.
|
||||
|
||||
### Git, Commits & Releases
|
||||
|
||||
- Invoke git through the provided wrappers, especially for status, diffs, and commits. Only commit or push when the user asks you to do so.
|
||||
- To resolve a rebase, `git add`/`git commit` is allowed.
|
||||
- Follow the documented release or deployment checklists instead of inventing new steps.
|
||||
- Do not delete or rename unfamiliar files without double-checking with the user or the repo instructions.
|
||||
|
||||
### Documentation & Knowledge Capture
|
||||
|
||||
- Update existing docs whenever your change affects them, including front-matter metadata if the repo’s `docs:list` tooling depends on it.
|
||||
- Whenever doing a large refactor, track work in `docs/refactor/<title><date>.md`, update it as you go, and delete it when the work is finished.
|
||||
- Only create new documentation when the user or local instructions explicitly request it; otherwise, edit the canonical file in place.
|
||||
@ -61,19 +53,16 @@ Usage: In repo copies, the shared content lives inside `<shared>…</shared>` an
|
||||
- Routine test additions don’t require changelog entries; reserve changelog lines for user-visible behavior changes.
|
||||
|
||||
### Troubleshooting & Observability
|
||||
|
||||
- Design workflows so they are observable without constant babysitting: use tmux panes, CI logs, log-tail scripts, MCP/browser helpers, and similar tooling to surface progress.
|
||||
- If you get stuck, consult external references (web search, official docs, Stack Overflow, etc.) before escalating, and record any insights you find for the next agent.
|
||||
- Keep any polling or progress loops bounded to protect hang detectors and make it obvious when something stalls.
|
||||
|
||||
### Stack-Specific Reminders
|
||||
|
||||
- Start background builders or watchers using the automation provided by the repo (daemon scripts, tmux-based dev servers, etc.) instead of running binaries directly.
|
||||
- Use the official CLI wrappers for browser automation, screenshotting, or MCP interactions rather than crafting new ad-hoc scripts.
|
||||
- Respect each workspace’s testing cadence (e.g., always running the main `check` script after edits, never launching forbidden dev servers, keeping replies concise when requested).
|
||||
|
||||
## Swift Projects
|
||||
|
||||
- Kick off the workspace’s build daemon or helper before running any Swift CLI or app; rely on the provided wrapper to rebuild targets automatically instead of launching stale binaries.
|
||||
- Validate changes with `swift build` and the relevant filtered test suites, documenting any compiler crashes and rewriting problematic constructs immediately so the suite can keep running.
|
||||
- Keep concurrency annotations (`Sendable`, actors, structured tasks) accurate and prefer static imports over dynamic runtime lookups that break ahead-of-time compilation.
|
||||
@ -81,7 +70,6 @@ Usage: In repo copies, the shared content lives inside `<shared>…</shared>` an
|
||||
- When encountering toolchain instability, capture the repro steps in the designated troubleshooting doc and note any required cache cleans (DerivedData, SwiftPM caches) you perform.
|
||||
|
||||
## TypeScript Projects
|
||||
|
||||
- Use the package manager declared by the workspace (often `pnpm` or `bun`) and run every command through the same wrapper humans use; do not substitute `npm`/`yarn` or bypass the runner.
|
||||
- Start each session by running the repo’s doc-index script (commonly a `docs:list` helper), then keep required watchers (`lint:watch`, `test:watch`, dev servers) running inside tmux unless told otherwise.
|
||||
- Treat `lint`, `typecheck`, and `test` commands (e.g., `pnpm run check`, `bun run typecheck`) as mandatory gates before handing off work; surface any failures with their exact command output.
|
||||
@ -113,24 +101,4 @@ Edit guidance: keep the actual tool list inside this `<tools></tools>` block so
|
||||
- `firecrawl`: MCP-powered site fetcher to Markdown; run `npx mcporter firecrawl`.
|
||||
- `XcodeBuildMCP`: MCP wrapper around Xcode tooling; run `npx mcporter XcodeBuildMCP`.
|
||||
- `gh`: GitHub CLI for PRs, CI logs, releases, repo queries; run `gh help`.
|
||||
</tools>
|
||||
|
||||
# Repo Notes
|
||||
|
||||
- Live Deepwiki tests are opt-in; run with `MCP_LIVE_TESTS=1 ./runner pnpm exec vitest run tests/live/deepwiki-live.test.ts` when you need real endpoint coverage.
|
||||
- The skipped OAuth-promotion case in `tests/runtime-transport.test.ts` can be validated by temporarily unskipping it (Vitest does not support `--runInBand`). Remove any temporary helper files after running.
|
||||
|
||||
# Triage Scale
|
||||
|
||||
- Default pace: take time; read more code; prefer high-certainty answers over fast guesses.
|
||||
- Default fix style: prefer the clean refactor/fix boundary over a tiny shim when it reduces future bugs without much added complexity.
|
||||
- Autonomy yes: bug fixes with repro/root cause, bounded performance wins, small CLI/UI/UX polish, docs fixes, tests for these.
|
||||
- Ask first: new features/commands, broad behavior changes, new config/API surface, dependencies/build tooling, architecture shifts, unclear product calls.
|
||||
- Vision: if the repo has `VISION.md`, read it before triage; use it to decide what is automatic vs needs discussion.
|
||||
- PR/issue work: one ticket at a time. Ask whether the PR is the best option; push back or make a better PR when cleaner.
|
||||
- Research: read adjacent code deeply; use web/official docs when behavior, APIs, or dependencies are uncertain.
|
||||
- Verification: add focused regression tests; run full green gate; end-to-end/live test whenever possible.
|
||||
- Live credentials: if a live test needs access, look for exact keys via `$one-password`; if unavailable, stop and ask for help before fixing/landing.
|
||||
- No unverifiable autonomous fixes: if you cannot prove the fix live or with equivalent local proof, ask before proceeding.
|
||||
- Review: use `$codex-review` before push/land for non-trivial code; keep going until no accepted/actionable findings remain.
|
||||
- Landing: update PR/description as needed, push branch or create PR, watch CI to green, then land. After land, checkout `main`, pull `--ff-only`, verify clean.
|
||||
</tools>
|
||||
|
||||
309
CHANGELOG.md
309
CHANGELOG.md
@ -1,333 +1,74 @@
|
||||
# mcporter Changelog
|
||||
|
||||
## [0.12.1] - 2026-06-18
|
||||
|
||||
- Add `key=@path` and `--key @path` call arguments for exact UTF-8 file values, with `@@` escaping for literal leading `@`. (Issue #212, thanks @andr-ec)
|
||||
|
||||
### Config
|
||||
|
||||
- Skip imported server entries with unresolvable editor-specific environment placeholders, and allow later valid duplicates to take effect without relaxing validation for local config. (PR #209, thanks @Loveacup)
|
||||
|
||||
### OAuth
|
||||
|
||||
- Treat corrupt cached OAuth tokens and client metadata as missing so connections can re-authenticate, while keeping corrupt callback state data fail-closed. (Issue #207, thanks @KrasimirKralev)
|
||||
|
||||
### Tooling / Dependencies
|
||||
|
||||
- Refresh development dependencies and security overrides, including Vite, esbuild, and Hono.
|
||||
|
||||
## [0.12.0] - 2026-06-10
|
||||
|
||||
### OAuth
|
||||
|
||||
- Add cache-friendly `disableOAuth` support across headless runtime, CLI, daemon, proxy, and `callOnce` paths so callers can suppress interactive OAuth without losing connection reuse. (Issues #197, #199, #201, thanks @feniix)
|
||||
- Recover cleanly from renamed OAuth server entries, invalid refresh tokens, and stale dynamic client registrations without reusing unrelated same-URL credentials.
|
||||
- Prevent concurrent OAuth vault updates from briefly exposing empty lock files and losing credential entries under load.
|
||||
|
||||
## [Unreleased]
|
||||
### CLI
|
||||
|
||||
- Add per-server Streamable HTTP paths for `mcporter serve` at `/mcp/<server>`, exposing one keep-alive server with original tool names while preserving aggregate `/mcp` namespacing. (PR #194, thanks @zm2231)
|
||||
- Add `mcporter record` and `mcporter replay` helpers for capturing and replaying MCP JSON-RPC traffic, with server filters and daemon-safe manual env setup. (PR #192, thanks @LDMB123)
|
||||
- Prevent direct daemon starts from rebinding over an already-running healthy daemon, avoiding orphaned keep-alive processes during foreground or launch races. (PR #195, thanks @zm2231)
|
||||
- Return a non-zero exit code for explicit `mcporter list <unknown-server>` failures while preserving aggregate list health checks by default. (Issue #203, thanks @theo674)
|
||||
- Reconcile keep-alive daemon metadata with the responding process and serialize daemon startup across parallel clients, preventing duplicate orphaned daemons. (Issue #191, thanks @dtmsyi)
|
||||
- Keep CloudBase MCP alive by default so device-code authentication can finish polling and persist credentials after returning `AUTH_PENDING`. (PR #193, thanks @sevzq)
|
||||
- Keep daemon-managed stdio servers warm across repeated `mcporter list` requests instead of treating non-interactive tool listing as a throwaway process. (Issue #188, thanks @robertoronderosjr)
|
||||
|
||||
### Tooling / Dependencies
|
||||
|
||||
- Refresh development dependencies and satisfy the stricter `oxlint` check.
|
||||
|
||||
## [0.11.3] - 2026-05-21
|
||||
|
||||
- Fall back to `~/.mcporter/mcporter.json[c]` when `XDG_CONFIG_HOME` points at an empty mcporter config directory, preventing embedders from accidentally hiding the user server registry. (Issue #184, thanks @ChrisBot2026)
|
||||
|
||||
## [0.11.2] - 2026-05-21
|
||||
|
||||
### CLI
|
||||
|
||||
- Add `mcporter list --status`, `--exit-code`, and `--quiet` for concise server health checks without introducing a separate health command.
|
||||
- Make `generate-cli --bundle` artifacts deterministic by removing bundle-only paths/timestamps from embedded metadata and sorting generated tool/schema output. (Issue #180, thanks @imroc)
|
||||
- Let daemon-managed OAuth servers reuse cached credentials for tool calls and tool listing after token expiry. (PR #182 / issue #181, thanks @bradhallett)
|
||||
- Avoid restarting browser OAuth when an already-connected server has a still-valid cached access token. (Issue #179, thanks @jaigew and @StanAngeloff)
|
||||
- Add the documented top-level `daemonIdleTimeoutMs` config to shut down inactive keep-alive daemons. (Issue #174, thanks @jarek083)
|
||||
|
||||
## [0.11.1] - 2026-05-14
|
||||
|
||||
### CLI
|
||||
|
||||
- Make `generate-cli --runtime node --bundle <name>.mjs` emit an ES module bundle with a local `require` shim, fixing `.mjs` artifacts that previously crashed at startup.
|
||||
- Classify generated `.mjs` and `.cjs` outputs as bundle artifacts in embedded metadata instead of reporting them as binaries.
|
||||
- Avoid leaving implicit `<server>.ts` template files in the current directory when generating bundle-only artifacts without `--output`.
|
||||
- Print generated CLI help with a trailing newline so subsequent shell output no longer glues onto the help footer.
|
||||
- Point generated CLI metadata and npm package metadata at `openclaw/mcporter`.
|
||||
- Document the existing `generate-cli --timeout`, `--minify`, and `--no-minify` flags in `generate-cli --help`.
|
||||
- Suppress expected Rolldown unresolved-import warnings for Node built-ins during successful generated CLI bundling.
|
||||
|
||||
## [0.11.0] - 2026-05-14
|
||||
|
||||
### Config
|
||||
|
||||
- Support `auth: "refreshable_bearer"` with explicit `refresh` settings so cached OAuth tokens can be refreshed before HTTP connects or injected into stdio env vars. (Issue #173, thanks @tokyo-s)
|
||||
- Add `httpFetch: "node-http1"` for HTTP MCP servers whose providers reject Node's built-in `fetch`, and auto-apply it to Sunsama's endpoint. (Issue #158, thanks @mattash)
|
||||
- Resolve `${VAR}` and `${VAR:-fallback}` placeholders across string-valued server config fields such as `baseUrl`, `command`/`args`, `tokenCacheDir`, and pre-registered OAuth fields while keeping headers/env/bearer-token placeholders lazy until runtime. (PR #161 / issue #157, thanks @zxyasfas)
|
||||
- Add `mcporter vault set <server>` and `mcporter vault clear <server>` so headless deployments can seed or clear OAuth vault credentials without reproducing mcporter's internal vault-key format. (Issue #156)
|
||||
|
||||
### CLI
|
||||
|
||||
- Add `mcporter serve`, exposing daemon-managed keep-alive servers as one MCP bridge with readable `server__tool` names for stdio and Streamable HTTP clients. (PR #172, thanks @zm2231)
|
||||
- Prefer MCP `structuredContent` nested inside JSON-RPC result envelopes so `mcporter call --output json` stays parseable for dual text/structured tool responses. (Issue #168, thanks @mar-zh)
|
||||
- Serialize read-modify-write config and OAuth vault updates, and write JSON/cache metadata atomically to avoid lost entries under parallel invocations. (Issue #167, thanks @alexminza)
|
||||
- Patch `chrome-devtools-mcp --autoConnect` launches at runtime so `mcporter call chrome-devtools.list_pages` can keep using a logged-in Chrome profile while upstream DevTools-window detection can hang on busy profiles.
|
||||
|
||||
### OAuth
|
||||
|
||||
- Add headless OAuth login support via `--no-browser`, `--browser none`, and `MCPORTER_OAUTH_NO_BROWSER`, emitting parseable authorization URLs for remote auth flows. (PR #171 / issue #169, thanks @feniix)
|
||||
- Proactively complete OAuth for configured HTTP servers that allow unauthenticated `initialize`/`listTools` but require credentials for tool calls, and close the local callback server promptly after browser authorization. (PR #159, thanks @Spacefish)
|
||||
- Refresh expired cached OAuth access tokens during non-interactive `mcporter list` without opening a browser or clearing cached credentials when refresh fails. (Issue #166, thanks @chrisabad)
|
||||
|
||||
## [0.10.2] - 2026-05-09
|
||||
|
||||
### CLI
|
||||
|
||||
- Keep keep-alive daemon retry diagnostics on stderr so `mcporter call --output json` stdout stays parseable after a daemon recovery. (PR #163 / issue #160, thanks @clawSean)
|
||||
- Increase the default OAuth browser wait from 60 seconds to 5 minutes so hosted MCP sign-ins have enough time for account and permission review.
|
||||
- Skip the redundant daemon `status` preflight for warm keep-alive access, cutting one socket round-trip from each routed list/call/resource request while preserving stale-config and dead-daemon recovery.
|
||||
- Route explicit default keep-alive calls like `chrome-devtools.list_pages` through a daemon-only fast path, avoiding full runtime startup on warm calls.
|
||||
- Further reduce warm keep-alive call startup by avoiding runtime/config schema imports on CLI boot and using a narrower daemon call path for simple explicit calls.
|
||||
- Keep single-server `mcporter list` non-interactive by reusing cached OAuth without launching new auth flows, and clamp oversized OAuth startup errors so HTML responses do not flood stdout/stderr.
|
||||
- Label non-timeout `mcporter list <server>` failures as unavailable instead of timed out.
|
||||
- Return concise/structured `mcporter resource` errors for servers that do not implement MCP resources instead of dumping SDK stack traces.
|
||||
- Refresh Context7 examples for the live `resolve-library-id` and `query-docs` schemas.
|
||||
- Make `generate-cli --help`, `inspect-cli --help`, and `emit-ts --help` print command help before flag parsing.
|
||||
- Auto-correct near-miss tool names when a server reports an unknown tool as MCP `isError` content instead of throwing.
|
||||
- Keep auto-correct diagnostics on stderr for `mcporter call --output json/raw` so stdout stays parseable.
|
||||
- Make generated CLIs keep `--output json` parseable for plain text MCP results by falling back to the raw JSON envelope.
|
||||
|
||||
### Config
|
||||
|
||||
- Preserve existing stdio executable paths that contain spaces instead of
|
||||
splitting them as inline command strings, so app bundle helpers like Hopper's
|
||||
MCP server can be configured directly.
|
||||
|
||||
### Tooling
|
||||
|
||||
- Build `dist/` once before the Vitest suite instead of letting parallel integration tests rebuild it mid-run.
|
||||
|
||||
## [0.10.1] - 2026-05-04
|
||||
|
||||
### CLI
|
||||
|
||||
- Fix Bun-compiled standalone binaries so `generate-cli --compile` can compile generated CLIs from empty directories by staging the matching published `mcporter` package dependencies when no local package tree is available.
|
||||
|
||||
### Tests
|
||||
|
||||
- Add an opt-in standalone Bun release-binary smoke for the empty-directory generated CLI compile path.
|
||||
|
||||
## [0.10.0] - 2026-05-04
|
||||
|
||||
### CLI
|
||||
|
||||
- Return a non-zero exit code when MCP tool results are marked `isError`, and preserve that status through the forced-exit cleanup path. (PR #154 / issue #153, thanks @jlapenna)
|
||||
- Give forced-exit cleanup a short stdout/stderr flush window so large JSON output is not truncated when `mcporter` is run from `child_process`. (PR #151 / issue #145, thanks @yuhp)
|
||||
- Treat `key:=value` as a compatibility alias for `key=value`, avoiding malformed keys such as `price:`. (PR #150 / issue #100, thanks @solomonneas)
|
||||
- Restore `mcporter call --key value` / `--key=value` tool arguments, including JSON array/object coercion, `--json -` stdin payloads, schema-aware bare string-to-array wrapping, and kebab-case to camelCase field mapping. (Issues #119 and #126)
|
||||
- Quote generated `emit-ts` members for tool names that are not valid TypeScript identifiers. (PR #149 / issue #30, thanks @solomonneas)
|
||||
- Resolve relative stdio args in generated CLI bundles against the generated script location instead of the caller's current directory. (PR #148 / issue #56, thanks @solomonneas)
|
||||
- Print OAuth manual-completion URLs at the default warning log level so headless users can copy them. (PR #143 / issue #139, thanks @stainlu)
|
||||
- Support repeatable `--header KEY=value` flags for ad-hoc HTTP servers and persisted ad-hoc entries. (Issue #117)
|
||||
- Let generated CLIs use `--raw` without also passing required flags, and parse array flags containing JSON object items. (Issues #102 and #103)
|
||||
- Preserve `auth: "oauth"` when an ad-hoc HTTP server is OAuth-promoted and saved with `--persist`. (Issue #82)
|
||||
- Let non-interactive `mcporter list` use existing OAuth token caches for HTTP servers even when older configs are missing `auth: "oauth"`. (Issue #137)
|
||||
- Fail OAuth flows immediately when the server never creates an authorization URL, instead of waiting for a browser callback that cannot arrive. (Issue #115)
|
||||
- Support `mcporter list server.tool --schema` to print a single tool's schema instead of the whole server. (Issue #116)
|
||||
- Surface MCP server `instructions` from the initialize response in single-server `mcporter list` text and JSON output. (Issue #76)
|
||||
- Add compact `mcporter list <server> --brief` / `--signatures` output for scanning signatures without doc blocks, examples, or schemas. (PR #144, thanks @yuhp)
|
||||
- Launch Bun-compiled macOS daemon children through `nohup` so Homebrew binaries can start keep-alive daemons in the background on macOS 26. (Issue #66)
|
||||
- Let generated CLIs use the keep-alive daemon for embedded servers with `lifecycle: "keep-alive"`, preserving stdio server state across separate generated-CLI invocations. (Issue #101)
|
||||
- Add `mcporter resource <server> [uri]` for listing and reading MCP resources, including keep-alive daemon routing. (Issue #134)
|
||||
|
||||
### Config
|
||||
|
||||
- Honor XDG Base Directory env vars for mcporter-owned config, data, cache, and state paths while preserving the legacy `~/.mcporter` fallback when XDG vars are unset. `MCPORTER_DAEMON_DIR`, `MCPORTER_CONFIG`, `--config`, and per-server `tokenCacheDir` remain explicit overrides. (Issue #155)
|
||||
- Support pre-registered OAuth clients via `oauthClientId`/`oauthClientSecretEnv` and token endpoint auth method overrides for providers without dynamic client registration. (Issue #132)
|
||||
- Respect configured stdio `cwd` values, including relative paths resolved from the config file and `~` home expansion. (PR #147 / issue #146, thanks @solomonneas)
|
||||
|
||||
### Tooling / Dependencies
|
||||
|
||||
- Updated `zod` to 4.4.3.
|
||||
|
||||
## [0.9.0] - 2026-04-18
|
||||
|
||||
### CLI
|
||||
|
||||
- Add per-server exact-name tool filtering with `allowedTools` and `blockedTools`, including config serialization and runtime call/list enforcement. (Rebuild of PR #39, thanks @tonylampada)
|
||||
- Escalate stuck stdio child-process shutdowns after close timeouts instead of treating the timeout as a clean exit. (PR #39, thanks @tonylampada)
|
||||
- Quote OAuth browser URLs when launching `cmd.exe` on Windows, preserving query parameters such as `redirect_uri`. (PR #136, thanks @cosminilie)
|
||||
- Document OAuth-protected server config setup with `mcporter config add --auth oauth` and `mcporter auth`. (PR #34, thanks @prateek)
|
||||
- Respect schema-declared string parameters when coercing numeric-looking `mcporter call` key=value arguments, so Slack timestamps like `thread_ts` stay strings. (PR #141, thanks @Hamzaa6296)
|
||||
|
||||
## [0.8.1] - 2026-03-29
|
||||
|
||||
### CLI
|
||||
|
||||
- Bun-compiled/Homebrew binaries now embed the package version before boot, so `mcporter --version` reports the real release (for example `0.8.1`) instead of falling back to `0.0.0-dev`.
|
||||
|
||||
### Tests
|
||||
|
||||
- Added regression coverage for the Bun compile wrapper so future release builds keep the embedded runtime version intact.
|
||||
|
||||
### Tooling / Dependencies
|
||||
|
||||
- npm publishes now use an explicit package allowlist, so local release tarballs/checksum files do not get bundled into the published package.
|
||||
|
||||
## [0.8.0] - 2026-03-29
|
||||
|
||||
### CLI
|
||||
|
||||
- Preserve OAuth flow vs post-auth transport failures so invalid OAuth/provider errors surface directly, while real legacy 404/405 transport mismatches still fall back to SSE correctly. (PR #97, thanks @mavam)
|
||||
- Ignore static `Authorization` headers once OAuth is active so imported editor configs cannot override fresh OAuth tokens. (PR #123, thanks @ahonn)
|
||||
- Keep `mcporter call --output json` parseable by emitting valid JSON even when the command falls back to raw output. (PR #128, thanks @armanddp)
|
||||
- Render `resource` content blocks in call output helpers instead of dropping them, including markdown resources and JSON text payloads. (PR #124, thanks @mvanhorn)
|
||||
- Preserve full JSON/error payloads when `data` is just one field instead of collapsing the response to `data` alone. (PR #106, thanks @AielloChan)
|
||||
- Generated CLIs now parse object-valued flags as JSON and render object placeholders/examples with JSON-shaped help text, so tools like Jira `fields` no longer receive raw strings. (PR #114, thanks @v2nic)
|
||||
- Deduplicate concurrent keep-alive daemon restarts per server so repeated fatal errors only force-close the cached daemon transport once before retrying. (PR #125, thanks @zm2231)
|
||||
- `mcporter config add` now accepts plural `--args` as an alias for repeated stdio arguments, matching common CLI muscle memory. (PR #93, thanks @Jah-yee)
|
||||
- Preserve default imports when `mcporter config add` writes a config file, instead of forcing `"imports": []`.
|
||||
- OAuth: avoid crashing on headless Linux when `xdg-open` is unavailable; clear stale dynamic-port client registrations; close callback server if stale-client persistence reads fail. (PR #72, thanks @mgonto)
|
||||
- Added optional `oauthScope`/`oauth_scope` config override as an escape hatch for providers that require explicit scopes.
|
||||
- OAuth wait/redirect now share one deferred to eliminate authorization race windows and preserve stable close-path errors, including wait-before-redirect and repeated-redirect flows. (PR #70, thanks @monotykamary)
|
||||
- `createCallResult().json()` now collects all parseable JSON entries from MCP content arrays (single item stays backward-compatible), and raw inspect depth now stays readable without unbounded traversal. (PR #91, thanks @Blankdlh)
|
||||
- Added `--raw-strings` (numeric coercion off) and `--no-coerce` (all coercion off) for `mcporter call` argument parsing so IDs/codes can stay literal strings. (PR #59, thanks @nobrainer-tech)
|
||||
- Added `CallResult.images()` plus opt-in `mcporter call --save-images <dir>` so image content blocks can be persisted without changing existing stdout output contracts. (PR #61, thanks @daniella-11ways)
|
||||
- OAuth transport retries now classify HTTP 405 as HTTP (not auth) and OAuth promotion applies to configured HTTP servers too, so post-auth fallback flows no longer drop credentials on 405-only endpoints. (PR #48, thanks @caseyg)
|
||||
- Config loading now parses project and explicit config files as JSONC, so `mcporter.json` / `mcporter.jsonc` can include comments and trailing commas. (PR #42, thanks @aryasaatvik)
|
||||
- Added generated `mcporter.schema.json` plus `pnpm generate:schema` for IDE autocomplete/validation, including `$schema` and `oauthScope`/`oauth_scope` coverage. (PR #43, thanks @aryasaatvik)
|
||||
|
||||
### Tooling / Dependencies
|
||||
|
||||
- Updated dependencies to latest releases (including MCP SDK, Rolldown RC, Zod, Biome, Oxlint, Vitest, Bun types).
|
||||
- Synced `biome.json` schema URL to Biome `2.4.5`.
|
||||
|
||||
## [0.7.3] - 2025-12-29
|
||||
|
||||
### CLI
|
||||
|
||||
- Fixed generated CLIs to read Commander.js option values via camelCased properties so snake_case tool schemas map correctly. (Thanks @rawwerks, PR #28)
|
||||
- Coerce generated CLI array arguments based on JSON Schema item types (including integer arrays). (Thanks @rawwerks, PR #27)
|
||||
- `mcporter generate-cli` supports `--include-tools` / `--exclude-tools` to generate CLIs for a subset of server tools. (Thanks @zackleman, PR #24)
|
||||
|
||||
### Tests
|
||||
|
||||
- Added regression coverage for typed array parsing in generated CLIs.
|
||||
- Added regression coverage for snake_case, camelCase, and numeric option names in generated CLIs.
|
||||
- Increased the Bun bundler integration-test timeout to reduce flakes on slower runners.
|
||||
|
||||
### Tooling / Dependencies
|
||||
|
||||
- Updated dependency set (SDK, Rolldown, Zod, Biome, Oxlint, Bun types).
|
||||
- Synced the Biome schema URL to the current CLI version.
|
||||
|
||||
## [0.7.1] - 2025-12-08
|
||||
|
||||
### Daemon
|
||||
|
||||
- Track config file mtimes for every loaded layer (home + project or explicit) in daemon metadata and auto-restart when any layer changes, so newly added keep-alive servers are picked up without manual restarts. Includes regression tests for stale-daemon detection.
|
||||
|
||||
## [0.7.0] - 2025-12-06
|
||||
|
||||
### CLI
|
||||
|
||||
- Centralized OAuth credentials in a shared vault (`~/.mcporter/credentials.json`) while still honoring per-server `tokenCacheDir` when present; legacy per-server caches are migrated automatically.
|
||||
- Centralized OAuth credentials in a shared vault (`~/.mcporter/.credentials.json`) while still honoring per-server `tokenCacheDir` when present; legacy per-server caches are migrated automatically.
|
||||
- `mcporter auth --reset` now clears the vault and legacy caches without crashing on corrupted credential files, making re-auth reliable for servers like Gmail.
|
||||
- StdIO servers that expose a separate auth subcommand (e.g., Gmail MCP) can now declare `oauthCommand.args`; `mcporter auth <server>` will spawn that helper and wait for browser completion, so Gmail auth now works without running npx manually.
|
||||
- Raw output now prints full strings without Node’s 10k-character truncation (`util.inspect` uses `maxStringLength: null`), so large MCP responses and plans are preserved end-to-end.
|
||||
- Added regression coverage to ensure future raw output changes cannot reintroduce truncation.
|
||||
|
||||
## [0.6.6] - 2025-11-28
|
||||
|
||||
### CLI
|
||||
|
||||
- Prevented ENOENT crashes when no config file exists anywhere by only passing an explicit `--config`/`MCPORTER_CONFIG` path to the runtime; implicit defaults now fall back cleanly across list/config/daemon flows.
|
||||
|
||||
## [0.6.5] - 2025-11-26
|
||||
|
||||
### CLI
|
||||
|
||||
- `mcporter call|auth|list help/--help` now print the command-specific usage text instead of attempting to run a server, matching the footer’s “mcporter <command> --help” hint.
|
||||
- Added a hidden `list-tools` alias for `mcporter list` to preserve older muscle memory and avoid “Unknown MCP server” errors when copied from legacy docs.
|
||||
- Ad-hoc HTTP flows now accept `--insecure` as a hidden synonym for `--allow-http`, making plain-HTTP testing flags match common intuition. `--sse` also aliases `--http-url` to keep older examples working.
|
||||
|
||||
### Security / Dependencies
|
||||
|
||||
- Override transitive `body-parser` to 2.2.1 (CVE-2025-13466) via pnpm overrides.
|
||||
|
||||
## [0.6.4] - 2025-11-25
|
||||
|
||||
### CLI
|
||||
|
||||
- `mcporter list` now uses cached OAuth access tokens (if present) for the all-servers view without opening browser windows, so previously authorized servers no longer show spurious “auth required” in non-interactive listings.
|
||||
- `pnpm test --filter <pattern>` now works by translating to a Vitest file pattern, avoiding the prior “Unknown option --filter” error.
|
||||
|
||||
## [0.6.3] - 2025-11-22
|
||||
|
||||
### Runtime & CLI
|
||||
|
||||
- Updated to `@modelcontextprotocol/sdk` 1.22.0; inline stdio test server now uses Zod schemas to remain compatible with the SDK’s JSON Schema conversion path.
|
||||
|
||||
### Runtime
|
||||
|
||||
- `listTools` now follows SDK pagination, looping through `nextCursor` so long catalogs return complete tool lists.
|
||||
|
||||
### Configuration
|
||||
|
||||
- Claude imports now preserve root-fallback parsing for legacy `.claude.json` and `.claude/mcp.json` files while treating `.claude/settings*.json` as container-only configs, preventing metadata fields like `statusLine` from being misdetected as MCP servers.
|
||||
- Added regression coverage for Claude settings and mcp.json imports to guard the root-fallback behavior.
|
||||
|
||||
## [0.6.2] - 2025-11-18
|
||||
|
||||
### Runtime
|
||||
|
||||
- Propagate `--timeout` / `MCPORTER_CALL_TIMEOUT` into MCP tool calls (SDK `timeout`, `resetTimeoutOnProgress`, `maxTotalTimeout`) so long-running requests are no longer capped by the SDK’s 60s default.
|
||||
|
||||
### CLI
|
||||
|
||||
- `mcporter generate-cli` once again treats single-token `--command` values (e.g., `./scripts/server.ts`) as STDIO transports instead of trying to coerce them into HTTP URLs, restoring the pre-0.6.1 behavior for ad-hoc scripts.
|
||||
- Global flag parsing moved into `cli-factory` for consistent log-level/oauth-timeout handling across commands.
|
||||
- `daemon` host/client hardened and covered with new tests; idle eviction and restart paths verified.
|
||||
|
||||
### Configuration
|
||||
|
||||
- Reintroduced support for `OPENCODE_CONFIG_DIR` so OpenCode imports continue to honor the documented directory override alongside `OPENCODE_CONFIG`.
|
||||
- Platform-aware defaults for Cursor/Claude/Windsurf/VS Code/OpenCode configs now dedupe paths and include Windows-specific locations.
|
||||
|
||||
### Platform resilience (Windows/WSL)
|
||||
|
||||
- Added `fs-helpers` that treat chmod/copy failures on NTFS/DrvFs as best-effort so CLI generation keeps working on WSL mounts.
|
||||
- Documented Windows/WSL workflows: install/test from ext4 copies, remount guidance for /mnt/c, and syncing tips.
|
||||
|
||||
### StdIO MCP coverage
|
||||
|
||||
- Added stdio e2e tests using in-repo filesystem & memory MCP fixtures to ensure list/call works via execPath.
|
||||
|
||||
### Content extraction
|
||||
|
||||
- `createCallResult` now reads nested `raw.content`/`raw.structuredContent` so tools that wrap responses render text/markdown/json correctly; new unit tests cover text joining, markdown, and JSON.
|
||||
|
||||
## [0.6.1] - 2025-11-17
|
||||
|
||||
### CLI
|
||||
|
||||
- `mcporter list --verbose` now surfaces every config path that registers the target server (primary first, then duplicates) in both text and JSON output, making it easier to trace where a name is coming from.
|
||||
- JSON list payloads include a new `sources` array when `--verbose` is set, mirroring the on-screen path list for programmatic consumers.
|
||||
- Verbose source listings now tag the import kind (cursor/vscode/codex, etc.) and explicitly label the primary entry vs. shadowed duplicates.
|
||||
|
||||
### Runtime
|
||||
|
||||
## [0.6.0] - 2025-11-16
|
||||
|
||||
### Configuration
|
||||
|
||||
- Default config resolution now layers the system config (`~/.mcporter/mcporter.json[c]`) before the project config (`config/mcporter.json`), so globally installed MCP servers remain available inside repos while allowing per-project overrides.
|
||||
- `--config` and `MCPORTER_CONFIG` continue to select a single file without merging for explicit workflows.
|
||||
- `mcporter config add --scope home|project` lets you choose the write target explicitly (project remains the default; `--persist <path>` still wins when provided).
|
||||
@ -335,19 +76,16 @@
|
||||
## [0.5.11] - 2025-11-16
|
||||
|
||||
### Code generation & metadata
|
||||
|
||||
- Quick start examples in generated CLIs now derive from actual embedded tools (up to three), showing real command names/flags instead of generic placeholders.
|
||||
|
||||
## [0.5.10] - 2025-11-16
|
||||
|
||||
### Code generation & metadata
|
||||
|
||||
- Generated CLIs now present the canonical kebab-cased tool names in help while accepting underscore aliases at runtime, eliminating the “unknown command” errors when copying names directly from server tool lists.
|
||||
|
||||
## [0.5.9] - 2025-11-15
|
||||
|
||||
### CLI
|
||||
|
||||
- `mcporter list` suppresses raw STDIO stderr dumps when enumerating all configured servers, keeping the summary output readable while still surfacing per-server health statuses.
|
||||
- `mcporter config <subcommand> --help` (and `mcporter config help <subcommand>`) now display detailed usage, flags, and examples for every config subcommand instead of returning a placeholder message. Inline `--help` tokens are intercepted before executing the command, so flows like `mcporter config add --help` no longer throw usage errors.
|
||||
- `mcporter config doctor` prints the project and system config paths before reporting diagnostics, making it obvious which files were inspected when tracking down configuration issues.
|
||||
@ -355,20 +93,17 @@
|
||||
## [0.5.8] - 2025-11-15
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- STDIO transports now interpolate `${VAR}`/`$env:VAR` tokens in the configured command and arguments before spawning child processes, so chrome-devtools inherits the live `CHROME_DEVTOOLS_URL` value instead of receiving the literal placeholder.
|
||||
- Keep-alive detection skips any STDIO server whose command/args reference `CHROME_DEVTOOLS_URL`, ensuring daemon mode relaunches chrome-devtools for each Oracle browser session instead of pinning a stale port.
|
||||
- Command arguments that escape placeholders as `\${VAR}` (common when using `String.raw` in TypeScript config helpers) now trim the backslash after interpolation so downstream servers receive clean URLs.
|
||||
|
||||
### CLI
|
||||
|
||||
- Ad-hoc STDIO invocations that start with `npx -y <package>` now infer the npm package name (stripping versions and ignoring arguments after `--`) instead of producing slugs like `npx-y`, so repeated `mcporter list|call` runs automatically reuse a readable server key without passing `--name`.
|
||||
- Quoted inline commands such as `mcporter list "npx -y xcodebuildmcp"` now auto-detect the ad-hoc STDIO transport, so you can skip `--stdio` entirely when probing MCP packages via `npx`.
|
||||
|
||||
## [0.5.7] - 2025-11-14
|
||||
|
||||
### CLI
|
||||
|
||||
- Added `mcporter daemon restart`, a stop+start convenience that reuses logging flags so agents can bounce the keep-alive daemon with a single command.
|
||||
- Added `list_tools` as a hidden shortcut for `mcporter list <server>`, so `chrome-devtools.list_tools` (and similar selectors) print the tool catalog instantly without requiring a real MCP tool.
|
||||
- Warn when colon-style arguments omit a value (e.g., `command:`) and suggest quoting/`--args` JSON so agents don’t accidentally send `undefined` to STDIO servers.
|
||||
@ -376,63 +111,53 @@
|
||||
## [0.5.6] - 2025-11-11
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Reset cached keep-alive connections whenever STDIO transports hit fatal errors (timeouts, closed pipes, daemon restarts, etc.), so chrome-devtools automatically recovers after you close Chrome instead of requiring `mcporter daemon stop`.
|
||||
- Daemon-routed calls now log a restart notice and automatically retry once after closing the stale transport, providing self-healing behavior when Chrome or other keep-alive servers crash mid-call.
|
||||
|
||||
## [0.5.5] - 2025-11-11
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Added hidden agent shortcuts: `mcporter describe <server>` now aliases `mcporter list`, and calling `<server>.help` automatically falls back to the list output when a server lacks a `help` tool (also wired into the legacy `pnpm mcp call` path) so agents always get a readable summary.
|
||||
|
||||
## [0.5.4] - 2025-11-10
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Propagate the CLI’s per-call timeout (defaults to 60s or `--timeout`) through the keep-alive daemon, so chrome-devtools and other persistent STDIO servers stop as soon as the caller times out.
|
||||
- `Runtime.callTool` now honors `timeoutMs` directly, ensuring TanStack MCP clients and the CLI share a single source of truth for cancellation even outside the daemon.
|
||||
- Ad-hoc STDIO servers launched via `mcporter call "npx …"` (or `--stdio`) inherit the same keep-alive heuristics and canonical names as config-defined entries, so `MCPORTER_DISABLE_KEEPALIVE=chrome-devtools` and similar overrides work without passing `--name`.
|
||||
|
||||
### Tests
|
||||
|
||||
- Added regression coverage (`tests/daemon-client-timeout.test.ts`, `tests/runtime-call-timeout.test.ts`, and updated keep-alive suites) to guard timeout propagation and canonical keep-alive detection.
|
||||
|
||||
## [0.5.3] - 2025-11-10
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Fixed Claude imports so `mcporter list` merges project-scoped servers from `.claude.json` (matching the current workspace) and ignores metadata-only keys like `tipsHistory`/`cachedStatsigGates`, resolving GitHub issues #6 and #7.
|
||||
- OpenCode imports now read only the documented `mcp` container (no root-level fallback), matching the current OpenCode schema and preventing stray metadata from being misinterpreted as servers.
|
||||
|
||||
## [0.5.2] - 2025-11-10
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- `mcporter call "<stdio command>" ...` now auto-detects ad-hoc STDIO servers, so you can skip `--stdio/--stdio-arg` entirely and just quote the command you want to run.
|
||||
- When a server exposes exactly one tool, `mcporter call` infers it automatically (and prints a dim log), letting one-tool servers like Vercel Domains run with only their arguments.
|
||||
- STDIO transports now inherit your current shell environment by default, so ad-hoc commands see the same variables as your terminal; keep `--env KEY=value` for explicit overrides.
|
||||
|
||||
### Fixes
|
||||
|
||||
- `mcporter config list` and `mcporter config doctor` no longer crash when the project config is missing or contains malformed JSON; we log a single warning and keep going, matching the behavior of the top-level `mcporter list`.
|
||||
|
||||
## [0.5.1] - 2025-11-10
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Added a per-login daemon that auto-starts when keep-alive MCP servers (e.g., Chrome DevTools, Mobile MCP, Playwright) are invoked. The daemon keeps STDIO transports alive across agents, exposes `mcporter daemon <start|status|stop>`, and supports idle shutdown plus manual restarts.
|
||||
- Keep-alive detection now honors the `lifecycle` config flag/env overrides and also inspects STDIO command signatures, so renaming `chrome-devtools` (or other stateful servers) no longer disables the daemon accidentally.
|
||||
- Introduced daemon logging controls (`mcporter daemon start --log|--log-file`, `--log-servers`, `MCPORTER_DAEMON_LOG*` env vars, and per-server `logging.daemon.enabled`). `mcporter daemon status` reports the active log path, and a new `tests/daemon.integration.test.ts` suite keeps the end-to-end flow covered.
|
||||
|
||||
### Fixes
|
||||
|
||||
- `mcporter list` (and every CLI entry point) once again treats missing project configs as empty instead of throwing ENOENT, matching the 0.4.x behavior when you run the CLI outside a repo.
|
||||
|
||||
## [0.5.0] - 2025-11-10
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- **Daemonized keep-alive servers.** A new per-login daemon automatically spins up whenever keep-alive MCP servers (Chrome DevTools, Mobile MCP, Playwright, etc.) are invoked. It keeps STDIO transports warm across agents, exposes `mcporter daemon <start|status|stop>`, supports idle shutdowns/manual restarts, and respects the `lifecycle` config flag plus STDIO command metadata so renamed servers stay eligible.
|
||||
- Fixed `createKeepAliveRuntime` so the daemon wrapper’s `listTools` implementation matches the base `Runtime` signature; `pnpm build` (and any command that shells out to `pnpm build`) succeeds again.
|
||||
- Cursor imports now cover both workspace and user `.cursor/mcp.json` files plus the platform-specific `Cursor/User/mcp.json` directories, and the VS Code/Windsurf walkers dedupe paths so editor-managed MCP servers are auto-discovered consistently across macOS, Linux, and Windows.
|
||||
@ -441,76 +166,63 @@
|
||||
## [0.4.5] - 2025-11-10
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Fixed the npm `bin` entry so it points to `dist/cli.js` without a leading `./`, keeping the executable in the published tarball and restoring `npx mcporter` functionality. Also bumped the embedded runtime version to 0.4.4 so the CLI reports the correct release.
|
||||
- Added `MCPORTER_CONFIG` plus a home-directory fallback (`~/.mcporter/mcporter.json[c]`) so the CLI automatically finds your system-wide config when a project file is missing.
|
||||
|
||||
### Docs
|
||||
|
||||
- Consolidated the external MCP import matrix into `docs/import.md`, removing the short-lived `docs/mcp-import.md` duplication, and clarified the release checklist to stop immediately on failing tests or lint warnings.
|
||||
|
||||
## [0.4.3] - 2025-11-10
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Added OpenCode imports (project `opencode.json[c]`, `OPENCODE_CONFIG_DIR`, user config, and the `OPENCODE_CONFIG` override) plus JSONC parsing so `mcporter list/config` can auto-discover servers defined in OpenCode.
|
||||
- Claude Code imports now honor `.claude/settings.local.json` and `.claude/settings.json` ahead of the legacy `mcp.json`, and we skip entries that lack a URL/command (e.g., permissions blocks) so malformed settings no longer break the merge.
|
||||
|
||||
### Docs
|
||||
|
||||
- Documented the full import matrix (including OpenCode + Claude settings hierarchy) directly in `docs/import.md` and `docs/config.md`.
|
||||
|
||||
## [0.4.2] - 2025-11-09
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- `mcporter list` (and other commands that load imports) now skip empty or malformed Claude Desktop / Cursor / Codex config files instead of throwing, so a blank `claude_desktop_config.json` no longer blocks the rest of the imports.
|
||||
- Bundled sample config adds the Mobile Next MCP definition, making it available out of the box when you run `mcporter list` before customizing your own config.
|
||||
|
||||
## [0.4.1] - 2025-11-08
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Fixed the fallback when `config/mcporter.json` is missing so `mcporter list` continues to import Cursor/Claude/Codex/etc. configs even when you run the CLI outside a repo that defines its own config, matching the 0.3.x behavior.
|
||||
- Added regression coverage that exercises the “no config file” path to ensure future changes keep importing user-level MCP servers.
|
||||
|
||||
## [0.4.0] - 2025-11-08
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- `mcporter config list` now displays only local entries by default, appends a color-aware summary of every imported config (path, counts, sample names), and still lets you pass `--source import`/`--json` for the merged view.
|
||||
- `mcporter config get`, `remove`, and `logout` now use the same fuzzy matching/suggestion logic as `mcporter list`/`call`, auto-correcting near-miss names and emitting “Did you mean …?” hints when ambiguity remains.
|
||||
|
||||
## [0.3.6] - 2025-11-08
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- `mcporter list` now prints copy/pasteable examples for ad-hoc servers by repeating the HTTP URL (with quoting) so the commands shown under `Examples:` actually work before you persist the definition.
|
||||
|
||||
### Code generation
|
||||
|
||||
- Staged the actual dependency directories (`commander`, `mcporter`) directly into the Bun bundler workspace so `npx mcporter generate-cli "npx -y chrome-devtools-mcp" --compile` succeeds even when npm hoists dependencies outside the package (fixes the regression some users still saw with 0.3.5).
|
||||
|
||||
## [0.3.5] - 2025-11-08
|
||||
|
||||
### Code generation
|
||||
|
||||
- Ensure the Bun bundler resolves `commander`/`mcporter` even when `npx mcporter generate-cli … --compile` runs inside an empty temp directory by symlinking mcporter’s own `node_modules` into the staging workspace before invoking `bun build`. This keeps the “one weird trick” workflow working post-0.3.4 without requiring extra installs.
|
||||
|
||||
## [0.3.4] - 2025-11-08
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Added a global `--oauth-timeout <ms>` flag (and the matching `MCPORTER_OAUTH_TIMEOUT_MS` override) so long-running OAuth handshakes can be shortened during debugging; the runtime now logs a clear warning and tears down the flow once the limit is reached, ensuring `mcporter list/call/auth` always exit.
|
||||
|
||||
### Docs
|
||||
|
||||
- Documented the new OAuth timeout flag/env var across the README and tmux/hang-debug guides so release checklists and manual repro steps call out the faster escape hatch.
|
||||
|
||||
## [0.3.3] - 2025-11-07
|
||||
|
||||
### Code generation
|
||||
|
||||
- When a server definition omits `description`, `mcporter generate-cli` now asks the MCP server for its own `instructions`/`serverInfo.title` during tool discovery and embeds that value, so generated CLIs introduce themselves with the real server description instead of the generic “Standalone CLI…” fallback.
|
||||
- Embedded tool listings inside generated CLIs now show each command’s flag signature (no `usage:` prefix) separated by blank lines, and per-command `--help` output inherits the same colorized usage/option styling as the main `mcporter` binary for readability on rich TTYs.
|
||||
- Added a `--bundler rolldown|bun` flag to `mcporter generate-cli`, defaulting to Rolldown but allowing Bun’s bundler (when paired with `--runtime bun`) for teams that want to stay entirely inside the Bun toolchain. The generator now records the chosen bundler in artifact metadata and enforces the Bun-only constraint so reproduction via `--from` stays deterministic.
|
||||
@ -520,63 +232,54 @@
|
||||
## [0.3.2] - 2025-11-07
|
||||
|
||||
### CLI
|
||||
|
||||
- Embedded the CLI version so Homebrew/Bun builds respond to `mcporter --version` even when `package.json` is unavailable.
|
||||
- Revamped `mcporter --help` to mirror the richer list/call formatting (name + summary rows, grouped sections, quick-start examples, and ANSI colors when TTYs are detected).
|
||||
- Fixed `mcporter list` so it no longer errors when `config/mcporter.json` is absent—fresh installs now run without creating config files, and a regression test guards the optional-config flow.
|
||||
- Generated standalone CLIs now print the full help menu (same grouped layout as the main CLI) when invoked without arguments, matching the behavior of `mcporter` itself.
|
||||
|
||||
### Code generation
|
||||
|
||||
- Generated binaries now default to the current working directory (using the inferred server name) when `--compile` is provided without a path, and automatically append a numeric suffix when the target already exists.
|
||||
- Standalone CLIs inherit the improved help layout (color-aware title, grouped command summaries, embedded tool listings, and quick-start snippets) so generated artifacts read the same way as the main CLI.
|
||||
- Swapped the bundler from esbuild to Rolldown for both JS and Bun targets, removing the fragile per-architecture esbuild binaries while keeping aliasing for local dependencies and honoring `--minify` via Rolldown’s native minifier.
|
||||
- Improved `generate-cli` so inline stdio commands (e.g., `"npx chrome-devtools-mcp"`) parse correctly even when invoked from empty directories.
|
||||
|
||||
### Code generation
|
||||
|
||||
- `readPackageMetadata()` now tolerates missing `package.json` files; when invoked from a directory without a manifest it falls back to mcporter’s own version string, so `generate-cli` works even when you call it via `npx` in an empty folder.
|
||||
|
||||
## [0.3.1] - 2025-11-07
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Short-circuited global `--help` / `--version` handling so these flags no longer fall through command inference and always print immediately, regardless of which command the user typed first.
|
||||
- Added regression coverage for the new shortcuts and kept the existing `runCli` helper exported so tests (and downstream tools) can exercise argument parsing without forking the entire process.
|
||||
|
||||
### Code generation & metadata
|
||||
|
||||
- Fixed `mcporter generate-cli --bundle/--compile` in empty directories by aliasing `commander`/`mcporter` imports to the CLI’s own installation so esbuild always resolves dependencies. Verified with a new fixture that bundles from temp dirs without `node_modules` (fixes #1).
|
||||
- Added an end-to-end integration test that runs `node dist/cli.js generate-cli` twice—once for bundling and once for `--compile`—as well as a GitHub Actions step that installs Bun so CI exercises the compiled binary path on every PR.
|
||||
|
||||
|
||||
## [0.3.0] - 2025-11-06
|
||||
|
||||
### CLI & runtime
|
||||
|
||||
- Added configurable log levels (`--log-level` / `MCPORTER_LOG_LEVEL`) that default to `warn`, promoting noisy transport fallbacks to warnings so critical issues still surface.
|
||||
- Forced the CLI to exit cleanly after shutdown (opt out with `MCPORTER_NO_FORCE_EXIT`) and patched `StdioClientTransport` so stdio MCP servers no longer leave Node handles hanging; stderr from stdio servers is buffered and replayed via `MCPORTER_STDIO_LOGS=1` or whenever a server exits with a non-zero status.
|
||||
|
||||
### Discovery, calling, and ad-hoc workflows
|
||||
|
||||
- Rebuilt `mcporter list`: spinner updates stream live, summaries print only after discovery completes, and single-server views now render TypeScript-style doc blocks, inline examples, inferred return hints, and compact `// optional (N): …` summaries. The CLI guarantees at least five parameters before truncating, introduced a single `--all-parameters` switch (replacing the `--required-only` / `--include-optional` pair), and shares its formatter with `mcporter generate-cli` so signatures are consistent everywhere.
|
||||
- Verb inference and parser upgrades let bare server names dispatch to `list`, dotted invocations jump straight to `call`, colon-delimited flags (`key:value` / `key: value`) sit alongside `key=value`, and the JavaScript-like call syntax now supports unlabeled positional arguments plus typo correction heuristics when tool names are close but not exact.
|
||||
- Ad-hoc workflows are significantly safer: `--http-url` / `--stdio` definitions (with `--env`, `--cwd`, `--name`, `--persist`) work across `list`, `call`, and `auth`, mcporter reuses existing config entries when a URL matches (preserving OAuth tokens / redirect URIs), and `mcporter auth <url>` piggybacks on the same resolver to persist entries or retry when a server flips modes mid-flight.
|
||||
- Hardened OAuth detection automatically promotes ad-hoc HTTP servers that return 401/403 to `auth: "oauth"`, broadens the unauthorized heuristic for Supabase/Vercel/GitHub-style responses, and performs a one-time retry whenever a server switches into OAuth mode while you are connecting.
|
||||
|
||||
### Code generation & metadata
|
||||
|
||||
- Generated CLIs now embed their metadata (generator version, resolved server definition, invocation flags) behind a hidden `__mcporter_inspect` command. `mcporter inspect-cli` / `mcporter generate-cli --from <artifact>` read directly from the artifact, while legacy `.metadata.json` sidecars remain as a fallback for older binaries.
|
||||
- Shared the TypeScript signature formatter between `mcporter list` and `mcporter generate-cli`, ensuring command summaries, CLI hints, and generator help stay pixel-perfect and are backed by new snapshot/unit tests.
|
||||
- Introduced `mcporter emit-ts`, a codegen command that emits `.d.ts` tool interfaces or ready-to-run client wrappers (`--mode types|client`, `--include-optional`) using the same doc/comment data that powers the CLI, so agents/tests can consume MCP servers with strong TypeScript types.
|
||||
- `mcporter generate-cli` now accepts inline stdio commands via `--command "npx -y package@latest"` or by quoting the command as the first positional argument, automatically splits the command/args, infers a friendly name from scripts or package scopes, and documents the chrome-devtools one-liner in the README; additional unit tests cover HTTP, stdio, scoped package, and positional shorthand flows.
|
||||
|
||||
### Documentation & references
|
||||
|
||||
- Added `docs/tool-calling.md`, `docs/call-syntax.md`, and `docs/call-heuristic.md` to capture every invocation style (flags, function expressions, inferred verbs) plus the typo-correction rules.
|
||||
- Expanded the ad-hoc/OAuth story across `README.md`, `docs/adhoc.md`, `docs/local.md`, `docs/known-issues.md`, and `docs/supabase-auth-issue.md`, detailing when servers auto-promote to OAuth, how retries behave, and how to persist generated definitions safely.
|
||||
- Updated the README, CLI reference, and generator docs to cover the new `--all-parameters` flag, list formatter, metadata embedding, the `mcporter emit-ts` workflow, and refreshed branding so the CLI and docs consistently introduce the project as **MCPorter**.
|
||||
- Tightened `docs/RELEASE.md` with a zero-warning policy so `pnpm check`, `pnpm test`, `npm pack --dry-run`, and friends must run clean before publishing.
|
||||
- `mcporter call` now rejects unknown long flags like `--source` instead of silently treating them as positional tool arguments; use `key=value`, `--args`, or `--` for literal `--value` positionals (PR #35, thanks @beverm2391).
|
||||
|
||||
## [0.2.0] - 2025-11-06
|
||||
|
||||
@ -597,28 +300,22 @@
|
||||
## [0.1.0]
|
||||
|
||||
- Initial release.
|
||||
|
||||
## [0.6.2] - 2025-11-18
|
||||
|
||||
### Platform resilience (Windows/WSL)
|
||||
|
||||
- Added `fs-helpers` that treat chmod/copy failures on NTFS/DrvFs as best-effort so CLI generation keeps working on WSL mounts.
|
||||
- Documented Windows/WSL workflows: install/test from ext4 copies, remount guidance for /mnt/c, and syncing tips.
|
||||
|
||||
### CLI/runtime
|
||||
|
||||
- Global flag parsing moved into `cli-factory` for consistent log-level/oauth-timeout handling across commands.
|
||||
- `daemon` host/client hardened and covered with new tests; idle eviction and restart paths verified.
|
||||
- Imports now include platform-aware defaults for Cursor/Claude/Windsurf/VS Code/OpenCode configs with path dedupe.
|
||||
|
||||
### StdIO MCP coverage
|
||||
|
||||
- Added stdio e2e tests using in-repo filesystem & memory MCP fixtures to ensure list/call works via execPath.
|
||||
|
||||
### Content extraction
|
||||
|
||||
- `createCallResult` now reads nested `raw.content`/`raw.structuredContent` so tools that wrap responses render text/markdown/json correctly; new unit tests cover text joining, markdown, and JSON.
|
||||
|
||||
### Docs
|
||||
|
||||
- New `docs/windows.md` with WSL/NTFS tips; added to docs index.
|
||||
|
||||
2
LICENSE
2
LICENSE
@ -1,6 +1,6 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Peter Steinberger
|
||||
Copyright (c) 2025 Peter Steinberger
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
||||
233
README.md
233
README.md
@ -1,5 +1,4 @@
|
||||
# MCPorter 🧳 - Call MCPs from TypeScript or as CLI
|
||||
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.png" alt="MCPorter header banner" width="1100">
|
||||
</p>
|
||||
@ -17,26 +16,16 @@ MCPorter helps you lean into the "code execution" workflows highlighted in Anthr
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
- **Zero-config discovery.** `createRuntime()` merges your home config (`~/.mcporter/mcporter.json[c]`, or `$XDG_CONFIG_HOME/mcporter/mcporter.json[c]` when set) first, then `config/mcporter.json`, plus Cursor/Claude/Codex/Windsurf/OpenCode/VS Code imports, expands `${ENV}` placeholders, and pools connections so you can reuse transports across multiple calls.
|
||||
- **Zero-config discovery.** `createRuntime()` merges your home config (`~/.mcporter/mcporter.json[c]`) first, then `config/mcporter.json`, plus Cursor/Claude/Codex/Windsurf/OpenCode/VS Code imports, expands `${ENV}` placeholders, and pools connections so you can reuse transports across multiple calls.
|
||||
- **One-command CLI generation.** `mcporter generate-cli` turns any MCP server definition into a ready-to-run CLI, with optional bundling/compilation and metadata for easy regeneration.
|
||||
- **Typed tool clients.** `mcporter emit-ts` emits `.d.ts` interfaces or ready-to-run client wrappers so agents/tests can call MCP servers with strong TypeScript types without hand-writing plumbing.
|
||||
- **Friendly composable API.** `createServerProxy()` exposes tools as ergonomic camelCase methods, automatically applies JSON-schema defaults, validates required arguments, and hands back a `CallResult` with `.text()`, `.markdown()`, `.json()`, `.images()`, and `.content()` helpers.
|
||||
- **Record/replay fixtures.** `mcporter record` captures MCP JSON-RPC traffic as NDJSON, and `mcporter replay` serves the same responses deterministically for offline debugging and redacted repros.
|
||||
- **Friendly composable API.** `createServerProxy()` exposes tools as ergonomic camelCase methods, automatically applies JSON-schema defaults, validates required arguments, and hands back a `CallResult` with `.text()`, `.markdown()`, `.json()`, and `.content()` helpers.
|
||||
- **OAuth and stdio ergonomics.** Built-in OAuth caching, log tailing, and stdio wrappers let you work with HTTP, SSE, and stdio transports from the same interface.
|
||||
- **Ad-hoc connections.** Point the CLI at _any_ MCP endpoint (HTTP or stdio) without touching config, then persist it later if you want. Hosted MCPs that expect a browser login (Supabase, Vercel, etc.) are auto-detected—just run `mcporter auth <url>` and the CLI promotes the definition to OAuth on the fly. See [docs/adhoc.md](docs/adhoc.md).
|
||||
|
||||
## What's New in 0.11.0
|
||||
|
||||
- **Bridge mode.** `mcporter serve` exposes daemon-managed keep-alive servers as one MCP bridge with readable `server__tool` names.
|
||||
- **Headless OAuth.** `--no-browser`, vault seeding, cached-token refresh, and `auth: "refreshable_bearer"` cover non-interactive deployments.
|
||||
- **HTTP compatibility.** `httpFetch: "node-http1"` keeps providers that reject Node's built-in `fetch` working.
|
||||
- **Safer writes.** Config, OAuth vault, JSON output, and cache metadata writes are serialized/atomic so parallel agents stop stepping on each other.
|
||||
- **Release confidence.** `0.11.0` is published on npm and Homebrew, and live/published install smokes are green.
|
||||
- **Ad-hoc connections.** Point the CLI at *any* MCP endpoint (HTTP or stdio) without touching config, then persist it later if you want. Hosted MCPs that expect a browser login (Supabase, Vercel, etc.) are auto-detected—just run `mcporter auth <url>` and the CLI promotes the definition to OAuth on the fly. See [docs/adhoc.md](docs/adhoc.md).
|
||||
|
||||
## Quick Start
|
||||
|
||||
MCPorter auto-discovers the MCP servers you already configured in Cursor, Claude Code/Desktop, Codex, or local overrides. You can try it immediately with `npx`--no installation required. Need a full command reference (flags, modes, return types)? Check out [docs/cli-reference.md](docs/cli-reference.md).
|
||||
|
||||
### Call syntax options
|
||||
|
||||
```bash
|
||||
@ -45,11 +34,9 @@ npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'
|
||||
|
||||
# Function-call style (matches signatures from `mcporter list`)
|
||||
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'
|
||||
|
||||
# Literal positional values that start with `--`
|
||||
npx mcporter call server.tool -- --raw-value
|
||||
```
|
||||
|
||||
|
||||
### List your MCP servers
|
||||
|
||||
```bash
|
||||
@ -61,7 +48,6 @@ npx mcporter list --stdio "bun run ./local-server.ts" --env TOKEN=xyz
|
||||
```
|
||||
|
||||
- Add `--json` to emit a machine-readable summary with per-server statuses (auth/offline/http/error counts) and, for single-server runs, the full tool schema payload.
|
||||
- Add `--status` for a concise single-server status check without tool docs, `--exit-code` to fail when any checked server is unhealthy, or `--quiet` for silent health gates.
|
||||
- Add `--verbose` to show every config source that registered the server name (primary first), both in text and JSON list output.
|
||||
|
||||
You can now point `mcporter list` at ad-hoc servers: provide a URL directly or use the new `--http-url/--stdio` flags (plus `--env`, `--cwd`, `--name`, or `--persist`) to describe any MCP endpoint. Until you persist that definition, you still need to repeat the same URL/stdio flags for `mcporter call`—the printed slug only becomes reusable once you merge it into a config via `--persist` or `mcporter config add` (use `--scope home|project` to pick the write target). Follow up with `mcporter auth https://…` (or the same flag set) to finish OAuth without editing config. Full details live in [docs/adhoc.md](docs/adhoc.md).
|
||||
@ -128,8 +114,8 @@ Required parameters always show; optional parameters stay hidden unless (a) ther
|
||||
### Context7: fetch docs (no auth required)
|
||||
|
||||
```bash
|
||||
npx mcporter call context7.resolve-library-id query="React hooks docs" libraryName=react
|
||||
npx mcporter call context7.query-docs libraryId=/reactjs/react.dev query="useEffect cleanup"
|
||||
npx mcporter call context7.resolve-library-id libraryName=react
|
||||
npx mcporter call context7.get-library-docs context7CompatibleLibraryID=/websites/react_dev topic=hooks
|
||||
```
|
||||
|
||||
### Linear: search documentation (requires `LINEAR_API_KEY`)
|
||||
@ -143,7 +129,6 @@ LINEAR_API_KEY=sk_linear_example npx mcporter call linear.search_documentation q
|
||||
```bash
|
||||
npx mcporter call chrome-devtools.take_snapshot
|
||||
npx mcporter call 'linear.create_comment(issueId: "LNR-123", body: "Hello world")'
|
||||
npx mcporter call linear.create_comment issueId=LNR-123 body=@comment.md
|
||||
npx mcporter call https://mcp.linear.app/mcp.list_issues assignee=me
|
||||
npx mcporter call shadcn.io/api/mcp.getComponent component=vortex # protocol optional; defaults to https
|
||||
npx mcporter call linear.listIssues --tool listIssues # auto-corrects to list_issues
|
||||
@ -161,16 +146,9 @@ Helpful flags:
|
||||
- `--oauth-timeout <ms>` -- shorten/extend the OAuth browser wait; same as `MCPORTER_OAUTH_TIMEOUT_MS` / `MCPORTER_OAUTH_TIMEOUT`.
|
||||
- `--tail-log` -- stream the last 20 lines of any log files referenced by the tool response.
|
||||
- `--output <format>` or `--raw` -- control formatted output (defaults to pretty-printed auto detection).
|
||||
- `--save-images <dir>` (on `mcporter call`) -- save MCP image content blocks to files in the given directory (opt-in; stdout output shape stays unchanged).
|
||||
- `--raw-strings` (on `mcporter call`) -- keep numeric-looking argument values (for `key=value`, `key:value`, and trailing positional values) as strings.
|
||||
- `--no-coerce` (on `mcporter call`) -- keep all `key=value` and positional values as raw strings (disables bool/null/number/JSON coercion).
|
||||
- `key=@path` / `--key @path` (on `mcporter call`) -- read a named argument as exact UTF-8 text from a file; use `@@` for a literal leading `@`.
|
||||
- `--` (on `mcporter call`) -- stop flag parsing so the remaining tokens stay literal positional values, even when they start with `--`.
|
||||
- `--json` (on `mcporter list`) -- emit JSON summaries/counts instead of text. Multi-server runs report per-server statuses, counts, and connection issues; single-server runs include the full tool metadata.
|
||||
- `--status`, `--exit-code`, `--quiet` (on `mcporter list`) -- run concise server health checks through the existing list flow; `--quiet` suppresses output and exits 1 if anything checked is unhealthy.
|
||||
- `--output json/raw` (on `mcporter call`) -- when a connection fails, MCPorter prints the usual colorized hint and also emits a structured `{ server, tool, issue }` envelope so scripts can handle auth/offline/http errors programmatically.
|
||||
- `--json` (on `mcporter auth`) -- emit the same structured connection envelope whenever OAuth/transport setup fails, instead of throwing an error. With `--no-browser`, it emits auth-start JSON containing `authorizationUrl` and `redirectUrl`.
|
||||
- `--no-browser` / `--browser none` (on `mcporter auth` or `mcporter config login`) -- suppress browser launch and print the OAuth authorization URL for headless workflows; `MCPORTER_OAUTH_NO_BROWSER=1` / `true` / `yes` enables the same behavior.
|
||||
- `--json` (on `mcporter auth`) -- emit the same structured connection envelope whenever OAuth/transport setup fails, instead of throwing an error.
|
||||
- `--json` (on `mcporter emit-ts`) -- print a JSON summary describing the emitted files (mode + output paths) instead of text logs—handy when generating artifacts inside scripts.
|
||||
- `--all-parameters` -- show every schema field when listing a server (default output shows at least five parameters plus a summary of the rest).
|
||||
- `--http-url <https://…>` / `--stdio "command …"` -- describe an ad-hoc MCP server inline. STDIO transports now inherit your current shell environment automatically; add `--env KEY=value` only when you need to inject/override variables alongside `--cwd`, `--name`, or `--persist <config.json>`. These flags now work with `mcporter auth` too, so `mcporter auth https://mcp.example.com/mcp` just works.
|
||||
@ -178,7 +156,7 @@ Helpful flags:
|
||||
|
||||
> Tip: You can skip the verb entirely—`mcporter firecrawl` automatically runs `mcporter list firecrawl`, and dotted tokens like `mcporter linear.list_issues` dispatch to the call command (typo fixes included).
|
||||
|
||||
Timeouts default to 30 s; override with `MCPORTER_LIST_TIMEOUT` or `MCPORTER_CALL_TIMEOUT` when you expect slow startups. OAuth browser handshakes get a separate 5 minute grace period; pass `--oauth-timeout <ms>` (or export `MCPORTER_OAUTH_TIMEOUT_MS`) when you need the CLI to bail out faster while you diagnose stubborn auth flows.
|
||||
Timeouts default to 30 s; override with `MCPORTER_LIST_TIMEOUT` or `MCPORTER_CALL_TIMEOUT` when you expect slow startups. OAuth browser handshakes get a separate 60 s grace period; pass `--oauth-timeout <ms>` (or export `MCPORTER_OAUTH_TIMEOUT_MS`) when you need the CLI to bail out faster while you diagnose stubborn auth flows.
|
||||
|
||||
### Try an MCP without editing config
|
||||
|
||||
@ -201,17 +179,17 @@ npx mcporter call --stdio "bun run ./local-server.ts" --name local-tools
|
||||
- Stop it anytime with `mcporter daemon stop`, pre-warm with `mcporter daemon start`, or bounce it via `mcporter daemon restart` after tweaking configs/env.
|
||||
- All other servers stay ephemeral; add `"lifecycle": "keep-alive"` to a server entry (or set `MCPORTER_KEEPALIVE=name`) when you want the daemon to manage it. You can also set `"lifecycle": "ephemeral"` (or `MCPORTER_DISABLE_KEEPALIVE=name`) to opt out.
|
||||
- The daemon only manages named servers that come from your config/imports. Ad-hoc STDIO/HTTP targets invoked via `--stdio …`, `--http-url …`, or inline function-call syntax remain per-process today; persist them into `config/mcporter.json` (or use `--persist`) if you need them to participate in the shared daemon.
|
||||
- `mcporter serve --stdio` exposes every daemon-managed keep-alive server as one MCP stdio bridge for clients such as Claude Code or Codex. Register it once, then call namespaced tools like `chrome-devtools__list_pages`; add `--servers a,b` to limit the bridge or `--http <port>` to serve Streamable HTTP on localhost at `/mcp`. HTTP mode also exposes `/mcp/<server>` for one selected keep-alive server with its original, unprefixed tool names.
|
||||
- Troubleshooting? Run `mcporter daemon start --log` (or `--log-file /tmp/daemon.log`) to tee stdout/stderr into a file, and add `--log-servers chrome-devtools` when you only want call traces for a specific MCP. Per-server configs can also set `"logging": { "daemon": { "enabled": true } }` to force detailed logging for that entry.
|
||||
|
||||
|
||||
## Friendlier Tool Calls
|
||||
|
||||
- **Function-call syntax.** Instead of juggling `--flag value`, you can call tools as `mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'`. The parser supports nested objects/arrays, lets you omit labels when you want to rely on schema order (e.g. `mcporter 'context7.resolve-library-id("React hooks docs", "react")'`), and surfaces schema validation errors clearly. Deep dive in [docs/call-syntax.md](docs/call-syntax.md).
|
||||
- **Function-call syntax.** Instead of juggling `--flag value`, you can call tools as `mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'`. The parser supports nested objects/arrays, lets you omit labels when you want to rely on schema order (e.g. `mcporter 'context7.resolve-library-id("react")'`), and surfaces schema validation errors clearly. Deep dive in [docs/call-syntax.md](docs/call-syntax.md).
|
||||
- **Flag shorthand still works.** Prefer CLI-style arguments? Stick with `mcporter linear.create_issue title=value team=value`, `title=value`, `title:value`, or even `title: value`—the CLI now normalizes all three forms.
|
||||
- **Unknown long flags fail fast.** `mcporter call server.tool --source import` now errors instead of silently turning `--source` into a positional tool argument. Use `source=import`, `--args '{"source":"import"}'`, or insert `--` before literal positional values that begin with `--`.
|
||||
- **Cheatsheet.** See [docs/tool-calling.md](docs/tool-calling.md) for a quick comparison of every supported call style (auto-inferred verbs, flags, function-calls, and ad-hoc URLs).
|
||||
- **Auto-correct.** If you typo a tool name, MCPorter inspects the server’s tool catalog, retries when the edit distance is tiny, and otherwise prints a `Did you mean …?` hint. The heuristic (and how to tune it) is captured in [docs/call-heuristic.md](docs/call-heuristic.md).
|
||||
- **Richer single-server output.** `mcporter list <server>` now prints TypeScript-style signatures, inline comments, return-shape hints, and command examples that mirror the new call syntax. Optional parameters stay hidden by default—add `--all-parameters` or `--schema` whenever you need the full JSON schema. Prefer a tighter scan? `mcporter list <server> --brief` (or `--signatures`) keeps just the compact signatures and optional summaries.
|
||||
- **Richer single-server output.** `mcporter list <server>` now prints TypeScript-style signatures, inline comments, return-shape hints, and command examples that mirror the new call syntax. Optional parameters stay hidden by default—add `--all-parameters` or `--schema` whenever you need the full JSON schema.
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
@ -227,12 +205,6 @@ npx mcporter list
|
||||
pnpm add mcporter
|
||||
```
|
||||
|
||||
### Install globally with npm
|
||||
|
||||
```bash
|
||||
npm install -g mcporter
|
||||
```
|
||||
|
||||
### Homebrew (steipete/tap)
|
||||
|
||||
```bash
|
||||
@ -240,34 +212,34 @@ brew tap steipete/tap
|
||||
brew install steipete/tap/mcporter
|
||||
```
|
||||
|
||||
> The tap publishes alongside npm. If you run into issues with an older tap install, run `brew update` before reinstalling.
|
||||
> The tap publishes alongside MCPorter 0.3.2. If you run into issues with an older tap install, run `brew update` before reinstalling.
|
||||
|
||||
## One-shot calls from code
|
||||
|
||||
```ts
|
||||
import { callOnce } from 'mcporter';
|
||||
import { callOnce } from "mcporter";
|
||||
|
||||
const result = await callOnce({
|
||||
server: 'firecrawl',
|
||||
toolName: 'crawl',
|
||||
args: { url: 'https://anthropic.com' },
|
||||
server: "firecrawl",
|
||||
toolName: "crawl",
|
||||
args: { url: "https://anthropic.com" },
|
||||
});
|
||||
|
||||
console.log(result); // raw MCP envelope
|
||||
```
|
||||
|
||||
`callOnce` automatically discovers the selected server (including Cursor/Claude/Codex/Windsurf/OpenCode/VS Code imports), handles OAuth prompts, and closes transports when it finishes. It is ideal for manual runs or wiring MCPorter directly into an agent tool hook. In headless contexts, pass `disableOAuth: true` to suppress interactive OAuth and rely on cached tokens only — the library equivalent of the CLI's `--no-oauth` flag.
|
||||
`callOnce` automatically discovers the selected server (including Cursor/Claude/Codex/Windsurf/OpenCode/VS Code imports), handles OAuth prompts, and closes transports when it finishes. It is ideal for manual runs or wiring MCPorter directly into an agent tool hook.
|
||||
|
||||
## Compose Automations with the Runtime
|
||||
|
||||
```ts
|
||||
import { createRuntime } from 'mcporter';
|
||||
import { createRuntime } from "mcporter";
|
||||
|
||||
const runtime = await createRuntime();
|
||||
|
||||
const tools = await runtime.listTools('context7');
|
||||
const result = await runtime.callTool('context7', 'resolve-library-id', {
|
||||
args: { query: 'React hooks docs', libraryName: 'react' },
|
||||
const tools = await runtime.listTools("context7");
|
||||
const result = await runtime.callTool("context7", "resolve-library-id", {
|
||||
args: { libraryName: "react" },
|
||||
});
|
||||
|
||||
console.log(result); // prints JSON/text automatically because the CLI pretty-prints by default
|
||||
@ -281,18 +253,18 @@ Reach for `createRuntime()` when you need connection pooling, repeated calls, or
|
||||
The runtime API is built for agents and scripts, not just humans at a terminal.
|
||||
|
||||
```ts
|
||||
import { createRuntime, createServerProxy } from 'mcporter';
|
||||
import { createRuntime, createServerProxy } from "mcporter";
|
||||
|
||||
const runtime = await createRuntime();
|
||||
const chrome = createServerProxy(runtime, 'chrome-devtools');
|
||||
const linear = createServerProxy(runtime, 'linear');
|
||||
const chrome = createServerProxy(runtime, "chrome-devtools");
|
||||
const linear = createServerProxy(runtime, "linear");
|
||||
|
||||
const snapshot = await chrome.takeSnapshot();
|
||||
console.log(snapshot.text());
|
||||
|
||||
const docs = await linear.searchDocumentation({
|
||||
query: 'automations',
|
||||
page: 0,
|
||||
query: "automations",
|
||||
page: 0,
|
||||
});
|
||||
console.log(docs.json());
|
||||
```
|
||||
@ -301,11 +273,12 @@ Friendly ergonomics baked into the proxy and result helpers:
|
||||
|
||||
- Property names map from camelCase to kebab-case tool names (`takeSnapshot` -> `take_snapshot`).
|
||||
- Positional arguments map onto schema-required fields automatically, and option objects respect JSON-schema defaults.
|
||||
- Results are wrapped in a `CallResult`, so you can choose `.text()`, `.markdown()`, `.json()`, `.images()`, `.content()`, or access `.raw` when you need the full envelope.
|
||||
- Results are wrapped in a `CallResult`, so you can choose `.text()`, `.markdown()`, `.json()`, `.content()`, or access `.raw` when you need the full envelope.
|
||||
|
||||
Drop down to `runtime.callTool()` whenever you need explicit control over arguments, metadata, or streaming options.
|
||||
|
||||
Call `mcporter list <server>` any time you need the TypeScript-style signature, optional parameter hints, and sample invocations that match the CLI's function-call syntax. Add `--brief` or `--signatures` when you only want compact signatures.
|
||||
|
||||
Call `mcporter list <server>` any time you need the TypeScript-style signature, optional parameter hints, and sample invocations that match the CLI's function-call syntax.
|
||||
|
||||
## Generate a Standalone CLI
|
||||
|
||||
@ -333,7 +306,6 @@ Tip: you can drop `--command` when the inline command is the first positional ar
|
||||
- `--output <path>` writes the template somewhere specific.
|
||||
- `--runtime bun|node` picks the runtime for generated code (Bun required for `--compile`).
|
||||
- Add `--compile` to emit a Bun-compiled binary; MCPorter cleans up intermediate bundles when you omit `--bundle`.
|
||||
- Use `--include-tools a,b,c` or `--exclude-tools a,b,c` to generate a CLI for a subset of tools (mutually exclusive).
|
||||
- Use `--from <artifact>` (optionally `--dry-run`) to regenerate an existing CLI using its embedded metadata.
|
||||
- Prefer a positional shorthand if the server already lives in your config/imports:
|
||||
`npx mcporter generate-cli linear --bundle dist/linear.js`.
|
||||
@ -346,10 +318,6 @@ npx mcporter inspect-cli dist/context7.js # human-readable summary
|
||||
npx mcporter generate-cli --from dist/context7.js # replay with latest mcporter
|
||||
```
|
||||
|
||||
Agents should usually get one small skill per MCP server or workflow instead of
|
||||
a generic "all of mcporter" skill. See [docs/agent-skills.md](docs/agent-skills.md)
|
||||
for the pattern and a copyable template.
|
||||
|
||||
## Generate Typed Clients
|
||||
|
||||
Use `mcporter emit-ts` when you want strongly typed tooling without shipping a full CLI. It reuses the same signatures/doc blocks as `mcporter list`, so the generated headers stay in sync with what the CLI shows.
|
||||
@ -373,7 +341,6 @@ See [docs/emit-ts.md](docs/emit-ts.md) for the full flag reference plus inline s
|
||||
## Configuration Reference
|
||||
|
||||
Manage this file with `mcporter config list|get|add|remove|import` when you’d rather avoid hand-editing JSON; see [docs/config.md](docs/config.md) for the full walkthrough.
|
||||
Config files are parsed as JSONC, so inline `//` and `/* ... */` comments plus trailing commas are supported in both `mcporter.json` and `mcporter.jsonc`.
|
||||
|
||||
### Manage configs with `mcporter config`
|
||||
|
||||
@ -388,100 +355,30 @@ Run `mcporter config …` via your package manager (pnpm, npm, npx, etc.) when y
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"mcpServers": {
|
||||
"context7": {
|
||||
"description": "Context7 docs MCP",
|
||||
"baseUrl": "https://mcp.context7.com/mcp",
|
||||
"headers": {
|
||||
"Authorization": "$env:CONTEXT7_API_KEY",
|
||||
},
|
||||
},
|
||||
"chrome-devtools": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"],
|
||||
"env": { "npm_config_loglevel": "error" },
|
||||
},
|
||||
},
|
||||
"imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"],
|
||||
"mcpServers": {
|
||||
"context7": {
|
||||
"description": "Context7 docs MCP",
|
||||
"baseUrl": "https://mcp.context7.com/mcp",
|
||||
"headers": {
|
||||
"Authorization": "$env:CONTEXT7_API_KEY"
|
||||
}
|
||||
},
|
||||
"chrome-devtools": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "chrome-devtools-mcp@latest"],
|
||||
"env": { "npm_config_loglevel": "error" }
|
||||
}
|
||||
},
|
||||
"imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]
|
||||
}
|
||||
```
|
||||
|
||||
What MCPorter handles for you:
|
||||
|
||||
- `${VAR}`, `${VAR:-fallback}`, and `$env:VAR` interpolation for config strings. Secret-bearing `headers`, `env`, and bearer-token placeholders stay lazy and resolve at runtime.
|
||||
- Automatic OAuth token caching in the shared vault (`~/.mcporter/credentials.json`, or `$XDG_DATA_HOME/mcporter/credentials.json` when set) unless you override `tokenCacheDir`.
|
||||
- `${VAR}`, `${VAR:-fallback}`, and `$env:VAR` interpolation for headers and env entries.
|
||||
- Automatic OAuth token caching under `~/.mcporter/<server>/` unless you override `tokenCacheDir`.
|
||||
- Stdio commands inherit the directory of the file that defined them (imports or local config).
|
||||
- Import precedence matches the array order; omit `imports` to use the default `["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]`.
|
||||
- `chrome-devtools-mcp --autoConnect` receives a small compatibility patch while upstream auto-connect can hang on busy Chrome profiles; set `MCPORTER_DISABLE_CHROME_DEVTOOLS_COMPAT=1` to opt out.
|
||||
|
||||
#### OAuth-protected servers
|
||||
|
||||
If an HTTP MCP requires browser login (OAuth), persist it with `--auth oauth` (or set `"auth": "oauth"` in JSON), then run `mcporter auth` once:
|
||||
|
||||
```bash
|
||||
npx mcporter config add notion https://mcp.notion.com/mcp --auth oauth
|
||||
npx mcporter auth notion
|
||||
```
|
||||
|
||||
On headless hosts, use `npx mcporter auth notion --no-browser` to print the authorization URL instead of launching the platform browser. Treat the printed URL as sensitive operational output. Keep the `mcporter auth` process alive until the browser redirects back to the printed `redirectUrl`; process managers that exit or clean up the command after capturing stdout can kill the loopback callback listener before OAuth completes. Run the command from a persistent terminal session, `tmux`, or a supervised background process such as `nohup`, and if you open the URL on another machine, make sure the callback port is reachable through a loopback-only tunnel or a configured `oauthRedirectUrl`.
|
||||
|
||||
Providers that do not support dynamic client registration can use a pre-registered app:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"mcpServers": {
|
||||
"hubspot": {
|
||||
"baseUrl": "https://mcp.hubspot.com/mcp",
|
||||
"auth": "oauth",
|
||||
"oauthClientId": "your-client-id",
|
||||
"oauthClientSecretEnv": "HUBSPOT_CLIENT_SECRET",
|
||||
"oauthTokenEndpointAuthMethod": "client_secret_post",
|
||||
"oauthRedirectUrl": "http://127.0.0.1:3434/callback",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Keep client secrets in environment variables or private machine-local configs,
|
||||
and register the exact `oauthRedirectUrl` with the provider.
|
||||
|
||||
#### Refreshable bearer tokens (non-interactive OAuth)
|
||||
|
||||
For servers with pre-seeded OAuth tokens that need automatic refresh without browser prompts, use `auth: "refreshable_bearer"`. HTTP servers receive `Authorization: Bearer <token>` headers; STDIO servers require `refresh.accessTokenEnv` to inject the token as an environment variable:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"mcpServers": {
|
||||
"example": {
|
||||
"command": "uvx",
|
||||
"args": ["example-mcp-server"],
|
||||
"auth": "refreshable_bearer",
|
||||
"refresh": {
|
||||
"tokenEndpoint": "https://api.example.com/oauth/token",
|
||||
"clientIdEnv": "EXAMPLE_CLIENT_ID",
|
||||
"clientSecretEnv": "EXAMPLE_CLIENT_SECRET",
|
||||
"clientAuthMethod": "client_secret_basic",
|
||||
"refreshSkewSeconds": 300,
|
||||
"accessTokenEnv": "EXAMPLE_ACCESS_TOKEN",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
mcporter refreshes tokens before they expire (default 5 minutes early) using the refresh token from the vault. For keep-alive stdio servers that can't reload credentials after startup, use `"lifecycle": "ephemeral"` or restart the daemon before tokens expire.
|
||||
|
||||
Headless deployments that already have OAuth tokens can seed the vault without
|
||||
reproducing mcporter's internal vault key:
|
||||
|
||||
```bash
|
||||
npx mcporter vault set hubspot --tokens-file ./tokens.json
|
||||
npx mcporter vault set hubspot --stdin < tokens.json
|
||||
npx mcporter vault clear hubspot
|
||||
```
|
||||
|
||||
The JSON payload is `{ "tokens": { ... }, "clientInfo": { ... } }`; `tokens`
|
||||
is required and `clientInfo` is optional.
|
||||
|
||||
Provide `configPath` or `rootDir` to CLI/runtime calls when you juggle multiple config files side by side.
|
||||
|
||||
@ -492,7 +389,7 @@ mcporter reads exactly one primary config per run. The lookup order is:
|
||||
1. The path you pass via `--config` (or programmatic `configPath`).
|
||||
2. The `MCPORTER_CONFIG` environment variable (set it in your shell to apply everywhere).
|
||||
3. `<root>/config/mcporter.json` inside the current project.
|
||||
4. `$XDG_CONFIG_HOME/mcporter/mcporter.json[c]` when `XDG_CONFIG_HOME` is set, falling back to `~/.mcporter/mcporter.json[c]` when no XDG mcporter config exists and the project file is missing.
|
||||
4. `~/.mcporter/mcporter.json` or `~/.mcporter/mcporter.jsonc` if the project file is missing.
|
||||
|
||||
All `mcporter config …` mutations write back to whichever file was selected by that order. To manage a system-wide config explicitly, point the CLI at it:
|
||||
|
||||
@ -502,41 +399,17 @@ mcporter config --config ~/.mcporter/mcporter.json add global-server https://api
|
||||
|
||||
Set `MCPORTER_CONFIG=~/.mcporter/mcporter.json` in your shell profile when you want that file to be the default everywhere (handy for `npx mcporter …` runs).
|
||||
|
||||
mcporter honors XDG Base Directory env vars for its own files when those vars are explicitly set: `XDG_CONFIG_HOME` for home configs, `XDG_DATA_HOME` for the OAuth vault, `XDG_CACHE_HOME` for schema caches, and `XDG_STATE_HOME` for daemon/runtime state. If the matching XDG var is unset or relative, mcporter keeps the legacy `~/.mcporter` path. Config discovery is XDG-first but still probes `~/.mcporter/mcporter.json[c]` when no XDG mcporter config exists, which keeps embedders from hiding the user registry when they set `XDG_CONFIG_HOME` for another tool. Existing explicit overrides still win.
|
||||
|
||||
### Tool Filtering
|
||||
|
||||
Server definitions can hide or block exact tool names with either `allowedTools` or `blockedTools`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"mcpServers": {
|
||||
"slack-readonly": {
|
||||
"baseUrl": "https://example.com/slack/mcp",
|
||||
"allowedTools": ["channels_list", "conversations_history"],
|
||||
},
|
||||
"filesystem-safe": {
|
||||
"command": "npx -y @modelcontextprotocol/server-filesystem ~/Downloads",
|
||||
"blockedTools": ["write_file", "delete_file", "move_file"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`allowedTools` is an allowlist: only listed tools appear in `mcporter list` and can be called. An empty array blocks every tool. `blockedTools` is a blocklist: listed tools are hidden and rejected by `mcporter call`. Use exact tool names only, and choose one mode per server.
|
||||
|
||||
## Testing and CI
|
||||
|
||||
| Command | Purpose |
|
||||
| ------------ | ----------------------------------------------------------------------- |
|
||||
| `pnpm check` | Oxfmt formatting plus Oxlint/tsgolint gate. |
|
||||
| `pnpm build` | TypeScript compilation (emits `dist/`). |
|
||||
| `pnpm test` | Vitest unit and integration suites (streamable HTTP fixtures included). |
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `pnpm check` | Biome formatting plus Oxlint/tsgolint gate. |
|
||||
| `pnpm build` | TypeScript compilation (emits `dist/`). |
|
||||
| `pnpm test` | Vitest unit and integration suites (streamable HTTP fixtures included). |
|
||||
|
||||
CI runs the same trio via GitHub Actions.
|
||||
|
||||
## Related
|
||||
|
||||
- CodexBar 🟦🟩 Keep Codex token windows visible in your macOS menu bar. <https://codexbar.app>.
|
||||
- Trimmy ✂️ “Paste once, run once.” Flatten multi-line shell snippets so they paste and run. <https://trimmy.app>.
|
||||
- Oracle 🧿 Prompt bundler/CLI for multi-model runs (GPT-5.1, Claude, Gemini). <https://github.com/steipete/oracle>.
|
||||
|
||||
32
VISION.md
32
VISION.md
@ -1,32 +0,0 @@
|
||||
# MCPorter Vision
|
||||
|
||||
MCPorter should make any commonly supported MCP server usable from TypeScript, scripts, generated CLIs, and agent workflows with minimal setup.
|
||||
|
||||
## Product Goal
|
||||
|
||||
If an MCP server works in common MCP clients, it should be practical to use through MCPorter too. That includes local stdio servers, hosted HTTP/SSE servers, OAuth-protected providers, imported client configs, and ad-hoc endpoints.
|
||||
|
||||
MCPorter should stay small enough to understand, reliable enough for automation, and clear enough that failures tell the user what to fix next.
|
||||
|
||||
## What Good Work Looks Like
|
||||
|
||||
- Compatibility fixes for commonly used MCP servers, transports, schemas, auth flows, and client config formats.
|
||||
- Bug fixes with a clear reproduction, root cause, and verification path.
|
||||
- Performance work that improves startup, listing, calling, generated CLIs, daemon behavior, or repeated tool use without adding much complexity.
|
||||
- Small UI/UX improvements to CLI output, errors, help text, docs, and generated artifacts.
|
||||
- Refactors that make the correct fix cleaner, easier to test, or easier to maintain.
|
||||
- Tests and live/manual verification for behavior that can realistically be exercised.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Localization.
|
||||
- Major new product areas that are not about making MCP servers easier to discover, call, generate, type, host, or debug through MCPorter.
|
||||
- Broad features that make the product harder to reason about without a strong compatibility or reliability payoff.
|
||||
- Complex provider-specific flows when a small generic MCP/auth/transport improvement would solve the same class of problem.
|
||||
- Cosmetic churn, large rewrites, or dependency/tooling swaps without a concrete user-facing benefit.
|
||||
|
||||
## Triage Rule
|
||||
|
||||
Autonomous work is appropriate when it improves compatibility, correctness, performance, small CLI UX, docs, tests, or maintainability within this vision and can be verified end to end.
|
||||
|
||||
Ask first when the work changes product direction, adds a major feature, increases complexity substantially, needs unavailable live credentials, or cannot be verified with confidence.
|
||||
43
biome.json
Normal file
43
biome.json
Normal file
@ -0,0 +1,43 @@
|
||||
{
|
||||
"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
|
||||
"vcs": {
|
||||
"enabled": true,
|
||||
"clientKind": "git",
|
||||
"useIgnoreFile": true
|
||||
},
|
||||
"javascript": {
|
||||
"formatter": {
|
||||
"quoteStyle": "single",
|
||||
"semicolons": "always",
|
||||
"trailingCommas": "es5"
|
||||
}
|
||||
},
|
||||
"json": {
|
||||
"formatter": {
|
||||
"indentStyle": "space",
|
||||
"indentWidth": 2
|
||||
}
|
||||
},
|
||||
"files": {
|
||||
"ignoreUnknown": false,
|
||||
"maxSize": 1048576,
|
||||
"includes": ["src/**", "tests/**", "docs/**", "scripts/**", "!dist", "!tmp", "!node_modules"]
|
||||
},
|
||||
"formatter": {
|
||||
"enabled": true,
|
||||
"indentStyle": "space",
|
||||
"indentWidth": 2,
|
||||
"lineWidth": 120
|
||||
},
|
||||
"linter": {
|
||||
"enabled": true,
|
||||
"rules": {
|
||||
"recommended": true,
|
||||
"style": {
|
||||
"useConst": "error",
|
||||
"useTemplate": "error",
|
||||
"useBlockStatements": "warn"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -3,7 +3,10 @@
|
||||
"chrome-devtools": {
|
||||
"description": "Chrome DevTools protocol bridge for driving local tabs during debugging or automation.",
|
||||
"command": "npx",
|
||||
"args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"],
|
||||
"args": [
|
||||
"-y",
|
||||
"chrome-devtools-mcp@latest"
|
||||
],
|
||||
"env": {
|
||||
"npm_config_loglevel": "error"
|
||||
}
|
||||
@ -11,7 +14,10 @@
|
||||
"mobile-mcp": {
|
||||
"description": "Mobile Next MCP server for automating iOS/Android simulators and devices.",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@mobilenext/mobile-mcp@latest"],
|
||||
"args": [
|
||||
"-y",
|
||||
"@mobilenext/mobile-mcp@latest"
|
||||
],
|
||||
"env": {
|
||||
"npm_config_loglevel": "error"
|
||||
}
|
||||
@ -41,7 +47,10 @@
|
||||
"obsidian": {
|
||||
"description": "Local Obsidian vault access via obsidian-mcp-server.",
|
||||
"command": "npx",
|
||||
"args": ["-y", "obsidian-mcp-server@latest"],
|
||||
"args": [
|
||||
"-y",
|
||||
"obsidian-mcp-server@latest"
|
||||
],
|
||||
"env": {
|
||||
"OBSIDIAN_API_KEY": "${OBSIDIAN_API_KEY}",
|
||||
"OBSIDIAN_BASE_URL": "${OBSIDIAN_BASE_URL:-https://127.0.0.1:27124}",
|
||||
@ -51,7 +60,15 @@
|
||||
}
|
||||
},
|
||||
"playwright": {
|
||||
"command": "npx @playwright/mcp --browser chrome"
|
||||
"description": "Playwright MCP server for accessibility-driven automation.",
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@playwright/mcp@latest"
|
||||
],
|
||||
"env": {
|
||||
"npm_config_loglevel": "error"
|
||||
}
|
||||
},
|
||||
"vercel": {
|
||||
"description": "Vercel MCP (requires OAuth).",
|
||||
@ -75,7 +92,10 @@
|
||||
"signoz": {
|
||||
"description": "SigNoz Query MCP server (logs, traces, metrics).",
|
||||
"command": "npx",
|
||||
"args": ["-y", "signoz-mcp-server@latest"],
|
||||
"args": [
|
||||
"-y",
|
||||
"signoz-mcp-server@latest"
|
||||
],
|
||||
"env": {
|
||||
"SIGNOZ_URL": "${SIGNOZ_URL:-http://localhost:3301}",
|
||||
"SIGNOZ_TOKEN": "${SIGNOZ_TOKEN:-}",
|
||||
@ -88,9 +108,15 @@
|
||||
"baseUrl": "https://www.shadcn.io/api/mcp"
|
||||
},
|
||||
"iterm": {
|
||||
"description": "iTerm2 terminal bridge via local iterm-mcp",
|
||||
"command": "pnpm",
|
||||
"args": ["--dir", "/Users/steipete/Projects/iterm-mcp", "exec", "node", "build/index.js"],
|
||||
"args": [
|
||||
"--dir",
|
||||
"/Users/steipete/Projects/iterm-mcp",
|
||||
"exec",
|
||||
"node",
|
||||
"build/index.js"
|
||||
],
|
||||
"description": "iTerm2 terminal bridge via local iterm-mcp",
|
||||
"env": {
|
||||
"npm_config_loglevel": "error"
|
||||
}
|
||||
@ -98,11 +124,19 @@
|
||||
"XcodeBuildMCP": {
|
||||
"description": "XcodeBuild MCP server for building, testing, and inspecting Xcode projects and simulators.",
|
||||
"command": "npx",
|
||||
"args": ["-y", "xcodebuildmcp@latest"],
|
||||
"args": [
|
||||
"-y",
|
||||
"xcodebuildmcp@latest"
|
||||
],
|
||||
"env": {
|
||||
"npm_config_loglevel": "error"
|
||||
}
|
||||
}
|
||||
},
|
||||
"imports": ["cursor", "claude-code", "claude-desktop", "codex"]
|
||||
"imports": [
|
||||
"cursor",
|
||||
"claude-code",
|
||||
"claude-desktop",
|
||||
"codex"
|
||||
]
|
||||
}
|
||||
|
||||
@ -1 +0,0 @@
|
||||
mcporter.sh
|
||||
@ -1,25 +1,10 @@
|
||||
---
|
||||
summary: 'Release checklist for mcporter: versioning, tests, build artifacts, npm publish, GitHub release assets, and Homebrew tap updates.'
|
||||
read_when:
|
||||
- 'Cutting a release or updating release automation'
|
||||
---
|
||||
|
||||
# Release Checklist
|
||||
|
||||
> **Runner note:** From the repo root run `export MCP_RUNNER="$PWD/runner"` and use `$MCP_RUNNER <command>` for every shell command listed below unless the step explicitly says otherwise. This keeps the guardrails active even when the checklist jumps between directories.
|
||||
|
||||
> **Helper script:** You can run `./scripts/release.sh <phase>` (gates | artifacts | publish | smoke | tag | all) to execute the steps below with the runner by default. It stops on first error; rerun the next phase after fixing issues.
|
||||
|
||||
> **No-warning policy:** Every command below must finish without warnings (Oxfmt, Oxlint, tsgo, Vitest, npm pack, etc.). Fix issues before continuing; releases cannot ship with outstanding warnings.
|
||||
|
||||
## Definition of “released”
|
||||
|
||||
Shipping a release means **all** of:
|
||||
|
||||
- Tag pushed (`v<version>`).
|
||||
- npm published (`mcporter@<version>` visible via `npm view mcporter version`).
|
||||
- GitHub release published for the tag **with assets + checksums**.
|
||||
- Homebrew tap updated (and verified) after assets propagate.
|
||||
> **No-warning policy:** Every command below must finish without warnings (Biome, Oxlint, tsgo, Vitest, npm pack, etc.). Fix issues before continuing; releases cannot ship with outstanding warnings.
|
||||
|
||||
1. Update version in package.json and src/runtime.ts.
|
||||
2. Run pnpm install to refresh the lockfile if dependencies changed.
|
||||
@ -29,13 +14,13 @@ Shipping a release means **all** of:
|
||||
6. pnpm build:bun
|
||||
7. tar -C dist-bun -czf dist-bun/mcporter-macos-arm64-v<version>.tar.gz mcporter
|
||||
8. shasum -a 256 dist-bun/mcporter-macos-arm64-v<version>.tar.gz | tee dist-bun/mcporter-macos-arm64-v<version>.tar.gz.sha256
|
||||
9. npm pack --pack-destination /tmp && mv /tmp/mcporter-<version>.tgz . # keep the real tarball
|
||||
9. npm pack --pack-destination /tmp && mv /tmp/mcporter-<version>.tgz . # keep the real tarball
|
||||
10. shasum mcporter-<version>.tgz > mcporter-<version>.tgz.sha1 && shasum -a 256 mcporter-<version>.tgz > mcporter-<version>.tgz.sha256
|
||||
11. Verify git status is clean.
|
||||
12. git commit && git push.
|
||||
13. pnpm publish --tag latest _(the runner already has npm credentials configured, so you can run this directly in the release shell; bump `timeout_ms` if needed because prepublish re-runs check/test/build and can take several minutes.)_
|
||||
14. `npm view mcporter version` (and `npm view mcporter time`) to ensure the registry reflects the new release before proceeding. If the new version isn’t visible yet, wait a minute and retry—npm’s replication can lag briefly.
|
||||
15. Sanity-check the “one weird trick” workflow from a **completely empty** directory (no package.json/node_modules) via:
|
||||
11. git commit && git push.
|
||||
12. pnpm publish --tag latest *(the runner already has npm credentials configured, so you can run this directly in the release shell; bump `timeout_ms` if needed because prepublish re-runs check/test/build and can take several minutes.)*
|
||||
13. `npm view mcporter version` (and `npm view mcporter time`) to ensure the registry reflects the new release before proceeding. If the new version isn’t visible yet, wait a minute and retry—npm’s replication can lag briefly.
|
||||
14. Sanity-check the “one weird trick” workflow from a **completely empty** directory (no package.json/node_modules) via:
|
||||
```bash
|
||||
rm -rf /tmp/mcporter-empty && mkdir -p /tmp/mcporter-empty
|
||||
cd /tmp/mcporter-empty
|
||||
@ -44,11 +29,9 @@ Shipping a release means **all** of:
|
||||
./chrome-devtools-mcp --help | head -n 5
|
||||
```
|
||||
Only continue once the CLI compiles and the help banner prints.
|
||||
16. Draft the GitHub release notes using this template (copy/paste and edit). **Title the release `mcporter v<version>` (project name + version) to keep GitHub’s releases list consistent.**
|
||||
|
||||
15. Draft the GitHub release notes using this template (copy/paste and edit):
|
||||
```markdown
|
||||
## Highlights
|
||||
|
||||
- <top feature>
|
||||
- <second feature>
|
||||
- <bugfix or UX callout>
|
||||
@ -56,48 +39,44 @@ Shipping a release means **all** of:
|
||||
SHA256 (mcporter-macos-arm64-v<version>.tar.gz): `<sha from step 8>`
|
||||
SHA256 (mcporter-<version>.tgz): `<sha from npm pack>`
|
||||
```
|
||||
|
||||
Then **create the GitHub release for tag v<version>** and upload all assets:
|
||||
- `mcporter-macos-arm64-v<version>.tar.gz`
|
||||
- `mcporter-macos-arm64-v<version>.tar.gz.sha256` (from step 8; add a `.sha256` file)
|
||||
- `mcporter-<version>.tgz` (from `npm pack`)
|
||||
- `mcporter-<version>.tgz.sha1` and `mcporter-<version>.tgz.sha256`
|
||||
Double-check the uploaded checksums match your local files.
|
||||
Double-check the uploaded checksums match your local files.
|
||||
16. Tag the release (git tag v<version> && git push --tags).
|
||||
17. Post-tag housekeeping: add a fresh "Unreleased" stub to CHANGELOG.md (set to "- Nothing yet.") and start a new version section for the just-released patch if it isn’t already recorded.
|
||||
|
||||
17. Tag the release (git tag v<version> && git push --tags).
|
||||
18. Post-tag housekeeping: add a fresh "Unreleased" stub to CHANGELOG.md (set to "- Nothing yet.") and start a new version section for the just-released patch if it isn’t already recorded.
|
||||
After the release is live, always update the Homebrew tap and re-verify both installers. That flow should be:
|
||||
|
||||
After the release is live, always update the Homebrew tap and re-verify both installers. The tap formula should install the npm `.tgz`, not the Bun-compiled macOS tarball, because `generate-cli --compile` needs the installed package tree so Bun can resolve `mcporter`, `commander`, and related dependencies when compiling from an empty directory. Keep the macOS tarball on the GitHub release as a direct binary asset, but point Homebrew at `mcporter-<version>.tgz`.
|
||||
|
||||
1. Update `steipete/homebrew-tap` -> `Formula/mcporter.rb` with:
|
||||
- URL `https://github.com/openclaw/mcporter/releases/download/v<version>/mcporter-<version>.tgz`
|
||||
- SHA256 from `mcporter-<version>.tgz.sha256`
|
||||
- `require "language/node"`, `depends_on "node"`, and `system "npm", "install", *std_npm_args, "--min-release-age=0"` so same-day releases with fresh npm dependencies can install immediately.
|
||||
Refresh the tap README highlight so Homebrew users see the new version callout.
|
||||
2. Commit and push the tap update.
|
||||
3. Refresh and reinstall from the real tap:
|
||||
1. Uninstall any existing `mcporter` binaries to avoid PATH conflicts:
|
||||
```bash
|
||||
brew update
|
||||
brew reinstall steipete/tap/mcporter
|
||||
brew test steipete/tap/mcporter
|
||||
/opt/homebrew/bin/mcporter --version
|
||||
brew uninstall mcporter || true
|
||||
npm uninstall -g mcporter || true
|
||||
```
|
||||
4. Run a Homebrew-installed empty-directory compile smoke:
|
||||
2. Install from Homebrew, run `brew test` equivalents (`mcporter list --help`), then uninstall so the npm install owns the global `mcporter` binary. If the install fails with a linking conflict (`bin/mcporter already exists`), run `brew link --overwrite mcporter` and rerun the smoke command before uninstalling:
|
||||
```bash
|
||||
rm -rf /tmp/mcporter-brew-smoke && mkdir -p /tmp/mcporter-brew-smoke
|
||||
cd /tmp/mcporter-brew-smoke
|
||||
/opt/homebrew/bin/mcporter generate-cli "npx -y chrome-devtools-mcp" --compile
|
||||
./chrome-devtools-mcp --help | head -n 5
|
||||
brew install steipete/tap/mcporter
|
||||
# If you still have /opt/homebrew/bin/mcporter from npm, fix conflicts with:
|
||||
# brew link --overwrite mcporter
|
||||
mcporter list --help | head -n 5
|
||||
brew uninstall mcporter
|
||||
```
|
||||
5. Install the npm package globally (or leave it to npx) and verify that path too:
|
||||
3. Install the npm package globally (or leave it to npx) and keep that version in place for day-to-day use:
|
||||
```bash
|
||||
npm install -g mcporter@<version>
|
||||
mcporter --version
|
||||
npx --yes mcporter@<version> --version
|
||||
```
|
||||
6. If installing on another Mac, repeat the real tap reinstall and compile smoke there:
|
||||
```bash
|
||||
brew update
|
||||
brew reinstall steipete/tap/mcporter
|
||||
/opt/homebrew/bin/mcporter --version
|
||||
```
|
||||
4. Finally, run a fresh `npx mcporter@<version>` smoke test from an empty temp directory (no runner needed) to ensure the package is usable without global installs.
|
||||
|
||||
17. Update `steipete/homebrew-tap` → `Formula/mcporter.rb` with the new version, tarball URL, and SHA256. Refresh the tap README highlights and changelog snippets so Homebrew users see the new version callouts. (That repo doesn’t include `runner`, so use regular git commands there.)
|
||||
18. Commit and push the tap update.
|
||||
19. Verify the Homebrew flow (after GitHub release assets propagate):
|
||||
```bash
|
||||
brew update
|
||||
brew install steipete/tap/mcporter
|
||||
# If you previously installed mcporter via npm (or another tap) and see a link error,
|
||||
# run `brew link --overwrite mcporter` to replace /opt/homebrew/bin/mcporter with the tap binary.
|
||||
mcporter list --help
|
||||
```
|
||||
|
||||
@ -16,7 +16,6 @@ Two new flag sets let you describe a server on the command line:
|
||||
- `mcporter call --stdio "bun run ./server.ts" --name local-tools`
|
||||
|
||||
You can also pass a bare URL as the selector (`mcporter list https://mcp.linear.app/mcp`) or embed the URL in a `call` expression (`mcporter call 'https://mcp.example.com/tools.generate({ topic: "release" })'`).
|
||||
|
||||
- Add `--json` to `mcporter list …` when you need a machine-readable summary of status counts and per-server failures, use `--output json`/`--output raw` with `mcporter call` to receive structured `{ server, tool, issue }` envelopes whenever a transport error occurs, and run `mcporter auth … --json` to capture the same envelope if OAuth or transport setup fails.
|
||||
|
||||
### Example: HTTP ad-hoc workflow
|
||||
@ -33,7 +32,7 @@ Notice that the second command repeats the URL. Ad-hoc definitions are ephemeral
|
||||
|
||||
## Transport Detection
|
||||
|
||||
- **HTTP(S)**: Providing a URL defaults to the streamable HTTP transport. `https://` works out of the box; `http://` requires `--allow-http` (or the hidden alias `--insecure`) to acknowledge cleartext traffic. The `--sse` flag is a hidden alias for `--http-url` to match older examples. Use repeatable `--header KEY=value` flags for private servers that require headers such as `Authorization`, `X-API-Key`, or tenant selectors.
|
||||
- **HTTP(S)**: Providing a URL defaults to the streamable HTTP transport. `https://` works out of the box; `http://` requires `--allow-http` (or the hidden alias `--insecure`) to acknowledge cleartext traffic. The `--sse` flag is a hidden alias for `--http-url` to match older examples.
|
||||
- **STDIO**: Supplying `--stdio` (with a command string) or `--stdio-bin` (binary + args) selects the stdio transport. Your current shell environment is inherited automatically; use `--env KEY=value` only when you need to inject/override specific variables (and `--cwd` to change directories).
|
||||
- **Conflict guard**: Passing both URL and stdio flags errors out so we don’t guess.
|
||||
|
||||
@ -53,7 +52,7 @@ This name becomes the cache key for OAuth tokens and log preferences, so repeate
|
||||
|
||||
Many hosted MCP servers (Supabase, Vercel, etc.) advertise OAuth capabilities but expect clients to discover this dynamically. When an ad-hoc HTTP server responds with `401/403` during the initial handshake, mcporter now:
|
||||
|
||||
1. **Promotes the definition to OAuth** and spins up the default browser flow—no need to edit config or supply `auth: "oauth"` manually. On headless hosts, pass `--no-browser` (or `--browser none`) to print the authorization URL instead of launching the platform browser.
|
||||
1. **Promotes the definition to OAuth** and spins up the default browser flow—no need to edit config or supply `auth: "oauth"` manually.
|
||||
2. **Persists the change** whenever you pass `--persist`, so future runs remember that the endpoint requires OAuth without repeating the detection step.
|
||||
|
||||
The CLI still avoids surprise prompts during `mcporter list`; the upgrade happens the first time you run `mcporter auth <url>` or any other command that allows OAuth (i.e., not in `--autoAuthorize=false` mode).
|
||||
@ -62,9 +61,7 @@ The CLI still avoids surprise prompts during `mcporter list`; the upgrade happen
|
||||
|
||||
- OAuth flows are allowed; successful tokens store under the inferred name just like regular definitions.
|
||||
- `mcporter auth` accepts the same `--http-url/--stdio` flags (and even bare URLs), so you can immediately re-run `mcporter auth https://…` after a 401 without touching a config file.
|
||||
- Use `mcporter auth <url> --no-browser` for human-in-the-loop headless OAuth. Text mode writes only the authorization URL to stdout; `--json --no-browser` writes `authorizationUrl` plus `redirectUrl` as JSON. Keep that URL out of durable CI logs and support bundles. The `mcporter auth` process must keep running until the browser redirects to `redirectUrl`; process managers that capture stdout and then tear down the command can kill the local callback listener before tokens are saved. Use a persistent terminal, `tmux`, or a supervised background process such as `nohup` when completing OAuth outside an interactive shell.
|
||||
- When opening the URL on a different machine, remember that loopback redirect URLs point at the browser machine unless an SSH tunnel forwards the callback port back to the mcporter process. Use `oauthRedirectUrl` when you need a predictable callback port.
|
||||
- Nothing is written to disk unless you pass `--persist /path/to/config.json`. When set, we merge the generated definition into that file (creating it if necessary) so future runs can rely on the standard config pipeline. Ad-hoc HTTP headers are persisted with the entry, so placeholders such as `--header 'Authorization=$env:MY_TOKEN'` keep working through the normal config header resolver.
|
||||
- Nothing is written to disk unless you pass `--persist /path/to/config.json`. When set, we merge the generated definition into that file (creating it if necessary) so future runs can rely on the standard config pipeline.
|
||||
|
||||
## Safety Nets
|
||||
|
||||
|
||||
@ -1,60 +0,0 @@
|
||||
---
|
||||
summary: 'How to expose mcporter-backed MCP servers to agents through small per-server skills.'
|
||||
read_when:
|
||||
- 'Writing agent skill docs or wiring mcporter into an agent runtime'
|
||||
- 'Triaging requests for a generic mcporter skill'
|
||||
---
|
||||
|
||||
# Agent Skill Pattern
|
||||
|
||||
Prefer one small skill per MCP server or workflow instead of a single generic
|
||||
`mcporter` skill. A focused skill keeps the agent prompt small, names the useful
|
||||
tools directly, and avoids loading schemas for servers that are irrelevant to the
|
||||
current task.
|
||||
|
||||
## Recommended Flow
|
||||
|
||||
1. Add or import the MCP server:
|
||||
|
||||
```bash
|
||||
npx mcporter config add docs https://mcp.context7.com/mcp --scope home
|
||||
```
|
||||
|
||||
2. Inspect the tool surface:
|
||||
|
||||
```bash
|
||||
npx mcporter list docs --brief
|
||||
npx mcporter list docs --schema
|
||||
```
|
||||
|
||||
3. Write a skill that calls only the relevant tools via `mcporter call`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: docs-mcp
|
||||
description: Fetch package and framework docs through the configured docs MCP server.
|
||||
---
|
||||
|
||||
# Docs MCP
|
||||
|
||||
Use `npx mcporter call docs.resolve-library-id query=<task> libraryName=<name>`
|
||||
to resolve a package, then call `npx mcporter call docs.query-docs ...` with
|
||||
the resolved ID and docs query.
|
||||
```
|
||||
|
||||
4. For repeated or shareable workflows, generate a dedicated CLI instead of
|
||||
teaching the agent raw `mcporter call` syntax:
|
||||
|
||||
```bash
|
||||
npx mcporter generate-cli docs --bundle dist/docs-mcp.js
|
||||
```
|
||||
|
||||
## Why Not One Generic Skill?
|
||||
|
||||
A generic skill has to teach the agent how to discover, choose, and call every
|
||||
configured server. That recreates the large-schema context problem MCPorter is
|
||||
trying to avoid. Per-server skills stay small and let the skill author describe
|
||||
the safe, useful workflows for that server.
|
||||
|
||||
Use `allowedTools` or `blockedTools` in `mcporter.json` when a server exposes
|
||||
tools that should not be shown to agents.
|
||||
@ -6,22 +6,19 @@ read_when:
|
||||
|
||||
# Call Command Auto-Correction
|
||||
|
||||
`mcporter call` aims to help when a tool name is _almost_ correct without hiding real mistakes.
|
||||
`mcporter call` aims to help when a tool name is *almost* correct without hiding real mistakes.
|
||||
|
||||
## Confident Matches → Auto-Correct
|
||||
|
||||
- We normalise tool names (strip punctuation, lowercase) and compute a Levenshtein distance.
|
||||
- If the distance is ≤ `max(2, floor(length × 0.3))`, or the names only differ by case/punctuation, we retry automatically.
|
||||
- A dim informational line explains the correction: `[mcporter] Auto-corrected tool call to linear.list_issues (input: linear.listIssues).`
|
||||
|
||||
## Low-Confidence Matches → Suggest
|
||||
|
||||
- When the best candidate falls outside the threshold we keep the original failure.
|
||||
- We still print a hint so the user learns the canonical name: `[mcporter] Did you mean linear.list_issue_statuses?`
|
||||
- No second call is attempted in this case.
|
||||
|
||||
## Edge Cases
|
||||
|
||||
- We only inspect the tool catalog if the server explicitly replied with “Tool … not found”. Other MCP errors surface untouched.
|
||||
- If listing tools itself fails (auth, offline, etc.) we skip both auto-correct and hints.
|
||||
- Behaviour is covered by `tests/cli-call.test.ts`.
|
||||
|
||||
@ -8,11 +8,11 @@ read_when:
|
||||
|
||||
`mcporter call` now understands two complementary styles:
|
||||
|
||||
| Style | Example | Notes |
|
||||
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Flag-based (compatible) | `mcporter call linear.create_comment --issue-id LNR-123 --body "Hi"` | Use `--key value`, `--key=value`, `key=value`, `key:value`, or `key: value` pairs—ideal for shell scripts. |
|
||||
| Function-call (expressive) | `mcporter call 'linear.create_comment(issueId: "LNR-123", body: "Hi")'` | Mirrors the pseudo-TypeScript signature shown by `mcporter list`; unlabeled values map to schema order. |
|
||||
| Structured output | `mcporter call 'linear.create_comment(...)' --output json` | Successful calls emit JSON bodies; failures emit `{ server, tool, issue }` envelopes so automation can react to auth/offline/http errors. |
|
||||
| Style | Example | Notes |
|
||||
|-------|---------|-------|
|
||||
| Flag-based (compatible) | `mcporter call linear.create_comment --issue-id LNR-123 --body "Hi"` | Use `key=value`, `key:value`, or `key: value` pairs—ideal for shell scripts. |
|
||||
| Function-call (expressive) | `mcporter call 'linear.create_comment(issueId: "LNR-123", body: "Hi")'` | Mirrors the pseudo-TypeScript signature shown by `mcporter list`; unlabeled values map to schema order. |
|
||||
| Structured output | `mcporter call 'linear.create_comment(...)' --output json` | Successful calls emit JSON bodies; failures emit `{ server, tool, issue }` envelopes so automation can react to auth/offline/http errors. |
|
||||
|
||||
Both forms share the same validation pipeline, so required parameters, enums, and formats behave identically.
|
||||
|
||||
@ -40,12 +40,11 @@ Key details:
|
||||
- Run `mcporter list <server> --all-parameters` whenever you want the full signature; the footer repeats `Optional parameters hidden; run with --all-parameters to view all fields.` any time truncation occurs.
|
||||
- Return types come from each tool’s output schema, so you’ll see concrete names when providers include `title` metadata (e.g. `DocumentConnection`). When no schema is advertised we omit the `: Type` suffix entirely instead of showing `unknown`.
|
||||
- Each server concludes with a short `Examples:` block that mirrors the preferred function-call syntax.
|
||||
- Run `mcporter list <server> --brief` (or `--signatures`) when you only want the compact signatures and optional summaries without doc blocks or examples.
|
||||
|
||||
## Function-Call Syntax Details
|
||||
|
||||
- **Named arguments preferred**: `issueId: "123"` keeps calls self-documenting. When labels are omitted, mcporter falls back to positional order defined by the tool schema.
|
||||
- **Optional positional fallback**: omit labels when calling `mcporter 'context7.resolve-library-id("React hooks docs", "react")'`—arguments map to the schema order after any explicitly named parameters.
|
||||
- **Optional positional fallback**: omit labels when calling `mcporter 'context7.resolve-library-id("react")'`—arguments map to the schema order after any explicitly named parameters.
|
||||
- **Literals supported**: strings, numbers, booleans, `null`, arrays, and nested objects. For strings containing spaces or commas, wrap the entire call in single quotes to keep the shell happy.
|
||||
- **Error feedback**: invalid keys, unsupported expressions, or parser failures bubble up with actionable messages (`Unsupported argument expression: Identifier`, `Unable to parse call expression: …`).
|
||||
- **Server selection**: You can embed the server in the expression (`linear.create_comment(...)`) or pass it separately (`--server linear create_comment(...)`).
|
||||
@ -61,21 +60,13 @@ Key details:
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `--args '{ "issueId": "LNR-123" }'`, `--json '{ "issueId": "LNR-123" }'`, or `--json -` if you already have JSON payloads.
|
||||
- Use `--args '{ "issueId": "LNR-123" }'` if you already have JSON payloads—nothing changed for that workflow.
|
||||
- The new syntax respects all existing features (timeouts, `--output`, auto-correction).
|
||||
- Required fields show by default; pass `--all-parameters` when you want the full parameter list (or `--schema` for raw JSON schemas).
|
||||
- When in doubt, run `mcporter list <server>` to see the current signature and sample invocation.
|
||||
|
||||
## Flag-Based Syntax Details
|
||||
|
||||
- `--key value`, `--key=value`, `key=value`, `key:value`, `key: value`, and `key:=value` all map to the same named-argument handling, so you can type whichever feels most natural for your shell. Long flag keys convert kebab-case to camelCase (`--save-to-drafts true` becomes `saveToDrafts: true`). The `:=` form is accepted as a compatibility alias for `=`.
|
||||
- By default, arguments keep the same validation pipeline as the function-call syntax—enums, numbers, and booleans are coerced automatically, and missing required fields raise errors.
|
||||
- `--args -` and `--json -` read a JSON object from stdin.
|
||||
- Named flag-style values can read exact UTF-8 text from a file with `key=@path` or `--key @path`. Paths resolve from the current working directory, file contents remain strings without coercion, and `key=@@literal` produces the literal value `@literal`. Function-call strings such as `body: "@literal"` remain literal.
|
||||
- Bare string values supplied via long flags wrap into one-item arrays when the tool schema declares that field as an array.
|
||||
- Numeric-looking `key=value` arguments are restored to their original string spelling when the tool schema declares that parameter as a string, which keeps timestamp-like IDs such as Slack `thread_ts=1234567890.123456` intact.
|
||||
- `--raw-strings` disables numeric coercion for flag-style and positional values so IDs/codes stay literal strings (`code=12345` stays `"12345"`).
|
||||
- `--no-coerce` disables all coercion for flag-style and positional values (`true`, `null`, and JSON-like values remain strings).
|
||||
- Long flags without values fail fast. Insert `--` before literal positional values that start with `--`.
|
||||
- `--save-images <dir>` keeps stdout formatting untouched while writing image content blocks to disk when a tool response includes `type: "image"` entries.
|
||||
- `key=value`, `key:value`, and `key: value` all map to the same named-argument handling, so you can type whichever feels most natural for your shell.
|
||||
- Arguments keep the same validation pipeline as the function-call syntax—enums, numbers, and booleans are coerced automatically, and missing required fields raise errors.
|
||||
- `tool=value`/`tool:value` and `server=value` still act as aliases for `--tool` / `--server` when you need to override the selector.
|
||||
|
||||
@ -9,11 +9,9 @@ read_when:
|
||||
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`.
|
||||
@ -23,11 +21,9 @@ Create an `mcporter generate-cli` command that produces a standalone CLI for a s
|
||||
- **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).
|
||||
- Parse flags: `--server`, `--name`, `--command`, optional `--description`, plus `--output`, `--runtime=node|bun`, `--bundle`, `--bundler=rolldown|bun`, `--minify`, `--compile`, etc. Runtime auto-detects Bun when available, and the bundler inherits that choice unless overridden.
|
||||
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.
|
||||
@ -56,7 +52,6 @@ Create an `mcporter generate-cli` command that produces a standalone CLI for a s
|
||||
- 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.
|
||||
@ -92,13 +87,10 @@ npx mcporter generate-cli --command "npx -y chrome-devtools-mcp@latest"
|
||||
- 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"`).
|
||||
- Generated CLIs preserve `lifecycle: "keep-alive"` for embedded stdio servers. At runtime they create a stable generated config under `~/.mcporter/generated/` (or `$XDG_STATE_HOME/mcporter/generated/` when set), auto-start the daemon as needed, and keep the server process alive across separate generated-CLI invocations.
|
||||
- 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.
|
||||
@ -106,14 +98,14 @@ npx mcporter generate-cli --command "npx -y chrome-devtools-mcp@latest"
|
||||
- `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
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@ -10,91 +10,27 @@ 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, optional summaries, and any server `instructions` returned during
|
||||
MCP initialization.
|
||||
- With `server.tool`, prints just that tool; combine with `--schema` for a single
|
||||
tool schema.
|
||||
- Add `--brief` or `--signatures` with a server or `server.tool` target to keep
|
||||
the server header/instructions and print compact signatures without doc
|
||||
comments, examples, or schemas.
|
||||
- Add `--status` with a server target to print only the concise status row
|
||||
instead of full tool docs.
|
||||
- Add `--exit-code` to make the command exit 1 when any checked server is
|
||||
unhealthy, or `--quiet` to suppress output and imply `--exit-code`.
|
||||
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:
|
||||
- `--brief` – compact single-server output; cannot be combined with `--json`,
|
||||
`--schema`, `--verbose`, or `--all-parameters`.
|
||||
- `--signatures` – alias for `--brief`.
|
||||
- `--all-parameters` – include every optional parameter in the signature.
|
||||
- `--schema` – pretty-print the JSON schema for each tool.
|
||||
- `--status` – check server status only; cannot be combined with `--brief`,
|
||||
`--schema`, or `--all-parameters`.
|
||||
- `--exit-code` – exit 1 when any checked server is unhealthy.
|
||||
- `--quiet` – suppress output and exit 1 when any checked server is unhealthy.
|
||||
- `--timeout <ms>` – per-server timeout when enumerating all servers.
|
||||
- `--no-oauth` – never start an interactive OAuth flow; use cached
|
||||
tokens only while keeping eligible connections pooled.
|
||||
|
||||
## `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.
|
||||
- `--` – stop flag parsing so remaining tokens stay literal positional values.
|
||||
- `--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.
|
||||
- `key=@path` / `--key @path` – read a named UTF-8 string argument from a file; prefix with `@@` for a literal leading `@`.
|
||||
- `--tail-log` – stream tail output when the tool returns log handles.
|
||||
- `--no-oauth` – never start an interactive OAuth flow; use cached
|
||||
tokens only while keeping eligible connections pooled.
|
||||
|
||||
## `mcporter resource <server> [uri]`
|
||||
|
||||
- Lists resources exposed by a server when no URI is provided.
|
||||
- Reads an MCP resource when `uri` is provided and renders text, markdown, JSON,
|
||||
or raw output using the same output formatter as `mcporter call`.
|
||||
- Hidden alias: `resources`.
|
||||
- Useful flags:
|
||||
- `--output auto|text|markdown|json|raw` – choose how to render the response.
|
||||
- `--json` – shortcut for `--output json`.
|
||||
- `--raw` – shortcut for `--output raw`.
|
||||
- `--no-oauth` – never start an interactive OAuth flow; use cached
|
||||
tokens only while keeping eligible connections pooled.
|
||||
|
||||
## `mcporter serve [--servers a,b,c] [--stdio | --http <port>]`
|
||||
|
||||
- Exposes daemon-managed keep-alive servers as one MCP server for clients that
|
||||
consume MCP over stdio or Streamable HTTP.
|
||||
- `tools/list` queries the daemon for each selected server and publishes tools
|
||||
as `server__tool`; `tools/call` strips the prefix and routes the call through
|
||||
the daemon.
|
||||
- In HTTP mode, `/mcp` keeps the aggregate namespaced bridge, while
|
||||
`/mcp/<server>` exposes one selected keep-alive server with its original,
|
||||
unprefixed tool names.
|
||||
- Only configured keep-alive servers participate. Add
|
||||
`"lifecycle": "keep-alive"` to a server definition when you want it managed
|
||||
by the daemon.
|
||||
- Flags:
|
||||
- `--stdio` – serve MCP over stdio; this is the default and is the mode to
|
||||
register with Claude Code, Codex, and similar clients.
|
||||
- `--http <port>` – serve MCP Streamable HTTP on `/mcp` and
|
||||
`/mcp/<server>`, bound to `127.0.0.1` by default.
|
||||
- `--host <host>` – override the HTTP bind host when you intentionally need a
|
||||
non-local listener.
|
||||
- `--servers <csv>` – expose only the listed keep-alive server names.
|
||||
|
||||
## `mcporter generate-cli`
|
||||
|
||||
- Produces a standalone CLI for a single MCP server (optionally bundling or
|
||||
compiling with Bun).
|
||||
- Key flags:
|
||||
@ -104,9 +40,6 @@ A quick reference for the primary `mcporter` subcommands. Each command inherits
|
||||
- `--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
|
||||
@ -118,7 +51,6 @@ A quick reference for the primary `mcporter` subcommands. Each command inherits
|
||||
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.
|
||||
|
||||
189
docs/config.md
189
docs/config.md
@ -1,11 +1,4 @@
|
||||
---
|
||||
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>
|
||||
@ -36,29 +29,25 @@ See https://github.com/sweetistics/mcporter/blob/main/docs/config.md for config
|
||||
# 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}" },
|
||||
},
|
||||
"headers": { "Authorization": "Bearer ${LINEAR_API_KEY}" }
|
||||
}
|
||||
},
|
||||
"imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"],
|
||||
"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 in the shared vault (`~/.mcporter/credentials.json`, or `$XDG_DATA_HOME/mcporter/credentials.json` when set) unless you override `tokenCacheDir`.
|
||||
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
|
||||
|
||||
@ -67,77 +56,57 @@ mcporter now merges home and project config files by default so global servers s
|
||||
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):
|
||||
- `$XDG_CONFIG_HOME/mcporter/mcporter.json[c]` when `XDG_CONFIG_HOME` is set, falling back to `~/.mcporter/mcporter.json[c]` when no XDG mcporter config exists
|
||||
- `~/.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.
|
||||
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.
|
||||
|
||||
mcporter honors XDG Base Directory env vars for its own paths when they are explicitly set to absolute paths:
|
||||
|
||||
| Kind | Env var | mcporter path | Legacy fallback |
|
||||
| ------ | ----------------- | ----------------------------------------------- | -------------------- |
|
||||
| config | `XDG_CONFIG_HOME` | `$XDG_CONFIG_HOME/mcporter/mcporter.json[c]` | `~/.mcporter/...` |
|
||||
| data | `XDG_DATA_HOME` | `$XDG_DATA_HOME/mcporter/credentials.json` | `~/.mcporter/...` |
|
||||
| cache | `XDG_CACHE_HOME` | `$XDG_CACHE_HOME/mcporter/<server>/schema.json` | `~/.mcporter/...` |
|
||||
| state | `XDG_STATE_HOME` | `$XDG_STATE_HOME/mcporter/daemon/...` | `~/.mcporter/daemon` |
|
||||
|
||||
Unset, empty, or relative XDG vars fall back to `~/.mcporter` for backwards compatibility. For config files only, an absolute `XDG_CONFIG_HOME` is XDG-first but still probes `~/.mcporter/mcporter.json[c]` when no XDG mcporter config exists, so embedders that sandbox unrelated tools with `XDG_CONFIG_HOME` do not accidentally hide the user's registry. Explicit overrides still win: `--config`/`MCPORTER_CONFIG` for config files, `tokenCacheDir` for per-server OAuth/schema cache directories, and `MCPORTER_DAEMON_DIR` for daemon files.
|
||||
|
||||
## 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. |
|
||||
| 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 the XDG config path when `XDG_CONFIG_HOME` is set, otherwise `~/.mcporter/mcporter.json`, even when a project config is present. `--persist <path>` still takes precedence when you need a custom file.
|
||||
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`
|
||||
- `--oauth-client-id`, `--oauth-client-secret-env`, `--oauth-token-endpoint-auth-method` for pre-registered OAuth clients.
|
||||
- `--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-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.citeturn0search0
|
||||
- `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`.
|
||||
@ -146,152 +115,62 @@ Use `--scope home|project` with `mcporter config add` to pick the write target e
|
||||
- `--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`.
|
||||
- `--no-browser` suppresses automatic browser launch and prints the authorization URL to stdout so it can be copied from a headless host. `--browser none` is accepted as a compatibility alias, and `MCPORTER_OAUTH_NO_BROWSER=1` / `true` / `yes` enables the same behavior by environment.
|
||||
- In `--json --no-browser` mode, stdout contains a JSON object with `authorizationUrl` and `redirectUrl`; diagnostics stay off stdout so scripts can parse the result. Treat emitted authorization URLs as sensitive operational output.
|
||||
- `logout` wipes the shared vault entry, legacy `~/.mcporter/<name>/` caches, and the custom `tokenCacheDir` when present. Pass `--all` to clear everything.
|
||||
- `--browser none` suppresses automatic browser launch (useful for copying the URL into a remote browser).
|
||||
- `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. Ad-hoc HTTP targets also accept repeatable `--header KEY=value` flags for private endpoints.
|
||||
- `--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.
|
||||
- When an ad-hoc HTTP server returns an OAuth challenge during `list`, `call`, or `auth`, the persisted entry is rewritten with `auth: "oauth"` so later commands use the cached OAuth path instead of retrying unauthenticated HTTP.
|
||||
- `--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.
|
||||
- `--header KEY=VAL` entries merge into the persisted HTTP `headers` object when used with `--persist`; values support the same `$env:VAR`, `${VAR}`, and `${VAR:-fallback}` placeholders as config-file headers.
|
||||
|
||||
## HTTP Compatibility
|
||||
|
||||
HTTP MCP servers normally use Node's built-in `fetch` through the upstream MCP SDK. If a provider rejects that stack but accepts plain Node `https.request` traffic, set `httpFetch: "node-http1"` on the server entry to force an HTTP/1.1 fetch implementation for Streamable HTTP and SSE POST requests:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"mcpServers": {
|
||||
"sunsama": {
|
||||
"baseUrl": "https://api.sunsama.com/mcp",
|
||||
"headers": { "Authorization": "Bearer ${SUNSAMA_TOKEN}" },
|
||||
"httpFetch": "node-http1",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
The Sunsama endpoint is auto-detected and uses this compatibility path by default.
|
||||
|
||||
## 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. |
|
||||
| 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. |
|
||||
| `cwd` | Working directory for stdio servers. A leading `~` is expanded to `$HOME`; relative paths resolve against the config file directory. Defaults to the config file directory when omitted. |
|
||||
| `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` | Recognizes `oauth` and `refreshable_bearer`. `oauth` runs the browser/client OAuth flow for HTTP transports; `refreshable_bearer` refreshes cached bearer tokens non-interactively before connecting. |
|
||||
| `tokenCacheDir` | Directory for OAuth tokens and schema caches; still honored, but mcporter now keeps a centralized vault in `~/.mcporter/credentials.json` or `$XDG_DATA_HOME/mcporter/credentials.json` when set (legacy per-server caches are auto-migrated). Supports `~` expansion. |
|
||||
| `clientName` | Optional identifier some servers use for telemetry/audience segmentation. |
|
||||
| `oauthClientId` | Pre-registered OAuth client id for providers that do not support dynamic client registration. |
|
||||
| `oauthClientSecretEnv` | Environment variable containing the OAuth client secret. Prefer this over committing `oauthClientSecret` directly. |
|
||||
| `oauthTokenEndpointAuthMethod` | Optional token endpoint auth method override, for example `client_secret_post` when the provider requires client credentials in the token request body. |
|
||||
| `oauthRedirectUrl` | Override the default localhost callback. Required for many pre-registered OAuth apps because the provider must allowlist the exact redirect URI. Also 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. |
|
||||
| `refresh` | Explicit token refresh settings for `auth: "refreshable_bearer"`. Supports `tokenEndpoint`, `clientIdEnv`, `clientSecretEnv`, `clientAuthMethod`, `refreshSkewSeconds`, and `accessTokenEnv` (plus snake_case aliases). |
|
||||
| `allowedTools` / `allowed_tools` | Optional exact-name allowlist. Only listed tools appear in `mcporter list` and can be called. An empty array blocks all tools. Cannot be combined with `blockedTools`. |
|
||||
| `blockedTools` / `blocked_tools` | Optional exact-name blocklist. Listed tools are hidden from `mcporter list` and rejected by `mcporter call`. Cannot be combined with `allowedTools`. |
|
||||
| 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. |
|
||||
| `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.
|
||||
String-valued config fields support `${VAR}` and `${VAR:-fallback}` placeholders. Secret-bearing `headers`, `env`, and bearer-token placeholders are preserved in `config get`/`config list` output and resolved only when the transport runs; `*Env` fields name environment variables and are not expanded.
|
||||
|
||||
Top-level `daemonIdleTimeoutMs` (or `daemon_idle_timeout_ms`) shuts down the keep-alive daemon after that many milliseconds without daemon requests. Per-server `lifecycle.idleTimeoutMs` still controls when individual keep-alive transports are closed.
|
||||
|
||||
### Refreshable Bearer Tokens
|
||||
|
||||
Use `auth: "refreshable_bearer"` when you already seeded OAuth tokens with `mcporter vault set <server>` or `tokenCacheDir`, and the server should receive only a fresh bearer token at runtime. HTTP servers get `Authorization: Bearer <token>` when no authorization header is already configured. STDIO servers require `refresh.accessTokenEnv`; mcporter refreshes before spawning the process and injects that env var with the raw access token.
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"example": {
|
||||
"command": "uvx",
|
||||
"args": ["example-mcp-server"],
|
||||
"auth": "refreshable_bearer",
|
||||
"refresh": {
|
||||
"tokenEndpoint": "https://api.example.com/oauth/token",
|
||||
"clientIdEnv": "EXAMPLE_CLIENT_ID",
|
||||
"clientSecretEnv": "EXAMPLE_CLIENT_SECRET",
|
||||
"clientAuthMethod": "client_secret_basic",
|
||||
"refreshSkewSeconds": 300,
|
||||
"accessTokenEnv": "EXAMPLE_ACCESS_TOKEN"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For keep-alive stdio servers, refresh happens before process start. If that process cannot read updated credentials after startup, use `lifecycle: "ephemeral"` or restart the daemon before the injected token expires.
|
||||
|
||||
## 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.
|
||||
- For pre-registered OAuth apps, store the public `oauthClientId` in config and point `oauthClientSecretEnv` at a local environment variable. `oauthClientSecret` is supported for private machine-local configs but should not be committed.
|
||||
- For headless deployments that already have OAuth credentials, run `mcporter vault set <server> --tokens-file <path>` or `mcporter vault set <server> --stdin` with a JSON payload shaped like `{ "tokens": { ... }, "clientInfo": { ... } }`. This lets mcporter compute the vault key from the resolved server definition instead of duplicating that internal format in scripts.
|
||||
- Machine-specific additions can live in `~/.mcporter/local.json` or `$XDG_CONFIG_HOME/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/...` or the matching `XDG_*_HOME/mcporter/...`, plus `dist/`).
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
@ -8,9 +8,9 @@ read_when:
|
||||
|
||||
## 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` or CloudBase device authentication). No extra flags for agents.
|
||||
- **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-config scope:** The daemon lives under the current user account, keyed by config path (`~/.mcporter/daemon/daemon-<config-hash>.sock` on Unix-like systems, or `$XDG_STATE_HOME/mcporter/daemon/...` when set), and never crosses user boundaries.
|
||||
- **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.
|
||||
@ -34,11 +34,11 @@ read_when:
|
||||
- **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 (`chrome-devtools`, `mobile-mcp`, `playwright`, `cloudbase`) so existing configs benefit immediately; users can opt out per server.
|
||||
- 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 under the daemon runtime directory.
|
||||
- `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.
|
||||
@ -47,21 +47,9 @@ read_when:
|
||||
## 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).
|
||||
- **macOS Bun binaries:** Homebrew/Bun-compiled binaries wrap the detached child launch with `nohup` so the background daemon survives the parent CLI exit on macOS 26.
|
||||
- **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 top-level config `daemonIdleTimeoutMs` can shut down the entire daemon after long inactivity.
|
||||
- **Logging:** Daemon writes structured logs under the daemon runtime directory plus per-server logs for STDIO stderr so users can debug crashing servers.
|
||||
|
||||
## Agent Isolation
|
||||
|
||||
By default, multiple agents using the same config path share the same keep-alive daemon. That is deliberate: stateful servers such as browser or device MCPs can keep tabs, sessions, and subprocesses warm across repeated CLI calls.
|
||||
|
||||
If each agent needs independent MCP state, give each agent either:
|
||||
|
||||
- a distinct `--config <path>` / `MCPORTER_CONFIG` value, which produces a distinct daemon socket and metadata file; or
|
||||
- a distinct `MCPORTER_DAEMON_DIR`, which isolates the whole daemon runtime directory even when the config path is shared. This explicit override wins over `XDG_STATE_HOME`.
|
||||
|
||||
Non-keep-alive servers remain process-local and do not use the daemon.
|
||||
- **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
|
||||
|
||||
@ -86,7 +74,7 @@ Non-keep-alive servers remain process-local and do not use the daemon.
|
||||
|
||||
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`, or `$XDG_STATE_HOME/mcporter/daemon/daemon-<config-hash>.log` when `XDG_STATE_HOME` is set. Use `--log-file <path>` to override it.
|
||||
- `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.
|
||||
@ -102,6 +90,6 @@ Logs include timestamped entries such as:
|
||||
[daemon] 2025-11-10T15:08:22.004Z callTool success server=chrome-devtools tool=take_snapshot
|
||||
```
|
||||
|
||||
Tailing the file (`tail -f ~/.mcporter/daemon/daemon-*.log`, or the matching XDG state path) surfaces crashes or repeated failures without needing to re-run the daemon in the foreground.
|
||||
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.
|
||||
|
||||
@ -19,14 +19,14 @@ mcporter emit-ts <server> --out linear-client.ts \
|
||||
```
|
||||
|
||||
- `--mode types` (default) emits a `.d.ts` interface (`LinearTools`) with
|
||||
docblocks + promisified signatures. Missing output schemas fall back to
|
||||
`CallResult`.
|
||||
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.
|
||||
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.
|
||||
parameter is shown even when optional.
|
||||
|
||||
Outputs overwrite existing files automatically so you can regenerate artifacts
|
||||
whenever the server schema changes.
|
||||
@ -81,13 +81,13 @@ 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`). |
|
||||
| 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. |
|
||||
| `--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
|
||||
|
||||
|
||||
@ -21,13 +21,13 @@ culprit is a child MCP server process that keeps the stdio transport alive.
|
||||
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.
|
||||
-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 5 minutes.
|
||||
tears down the pending flow instead of waiting the full minute.
|
||||
|
||||
## Example Session
|
||||
|
||||
@ -65,7 +65,7 @@ child process, which mcporter will now terminate during shutdown.
|
||||
- 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>`.
|
||||
<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.
|
||||
|
||||
@ -24,19 +24,19 @@ Set `"imports": []` when you want to disable auto-merging entirely, or supply a
|
||||
- `{ "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`, `oauthClientId`, `oauthClientSecretEnv`, `oauthTokenEndpointAuthMethod`, and `auth`. Extra properties are ignored.
|
||||
- **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. |
|
||||
| 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.
|
||||
>
|
||||
|
||||
@ -1,70 +0,0 @@
|
||||
---
|
||||
title: Overview
|
||||
permalink: /
|
||||
summary: 'Overview of mcporter as a portable MCP runtime, CLI, generated-CLI toolkit, and typed-client layer.'
|
||||
description: 'mcporter is a TypeScript runtime, CLI, and code-generation toolkit for the Model Context Protocol — built so AI agents and developers can call any MCP server without boilerplate.'
|
||||
---
|
||||
|
||||
## Try it
|
||||
|
||||
mcporter auto-discovers the MCP servers already configured in Cursor, Claude Code/Desktop, Codex, Windsurf, OpenCode, and VS Code. Try it without installing anything:
|
||||
|
||||
```bash
|
||||
# List every MCP server you already have configured.
|
||||
npx mcporter list
|
||||
|
||||
# Inspect a single server with TypeScript-style signatures.
|
||||
npx mcporter list linear --schema
|
||||
|
||||
# Call a tool — colon flags, function-call syntax, or trailing positional values.
|
||||
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'
|
||||
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'
|
||||
|
||||
# Read or list MCP resources.
|
||||
npx mcporter resource docs
|
||||
npx mcporter resource docs file:///path/to/spec.md
|
||||
|
||||
# Mint a standalone CLI for any MCP server, ready to ship.
|
||||
npx mcporter generate-cli linear --bundle dist/linear.js
|
||||
|
||||
# Emit `.d.ts` types or a typed client for agents and tests.
|
||||
npx mcporter emit-ts linear --mode client --out src/linear-client.ts
|
||||
```
|
||||
|
||||
`--json` produces a stable JSON envelope on stdout; human progress, prompts, and warnings always go to stderr so pipes stay parseable.
|
||||
|
||||
## What mcporter does
|
||||
|
||||
mcporter leans into the **code-execution-with-MCP** pattern Anthropic recommends: skip the giant tool-schema prompt, generate a small typed surface, and let the agent or the human call MCP servers like normal functions.
|
||||
|
||||
- **Zero-config discovery.** Reads your home config (`~/.mcporter/mcporter.json[c]`, or `$XDG_CONFIG_HOME/mcporter/mcporter.json[c]`), then `config/mcporter.json`, then imports from Cursor / Claude / Codex / Windsurf / OpenCode / VS Code. `${ENV}` placeholders are expanded; transports are pooled across calls.
|
||||
- **One-command CLI generation.** [`mcporter generate-cli`](cli-generator.md) turns any MCP server into a ready-to-run CLI with embedded schemas, optional Rolldown/Bun bundling, and Bun-compiled binaries.
|
||||
- **Typed clients.** [`mcporter emit-ts`](emit-ts.md) emits `.d.ts` interfaces or a ready-to-run client wrapping `createServerProxy()` so agents call MCP tools with full TypeScript types.
|
||||
- **Friendly composable API.** [`createServerProxy()`](tool-calling.md) maps tools to camelCase methods, applies JSON-schema defaults, validates required arguments, and returns a `CallResult` with `.text()`, `.markdown()`, `.json()`, `.images()`, `.content()` helpers.
|
||||
- **Ad-hoc connections + auto-OAuth.** Point the CLI at any MCP endpoint (HTTP, SSE, stdio) without touching config. Hosted MCPs that need a browser login (Supabase, Vercel, etc.) are auto-detected — `mcporter auth <url>` promotes the definition to OAuth on the fly. See [Ad-hoc connections](adhoc.md).
|
||||
- **MCP bridge for agents.** `mcporter serve` exposes daemon-managed keep-alive servers as one MCP server with namespaced `server__tool` tools, or as per-server HTTP paths that keep original tool names.
|
||||
- **OAuth & stdio ergonomics.** Built-in OAuth caching, token refresh, log tailing, and stdio wrappers — same interface across HTTP, SSE, and stdio transports.
|
||||
|
||||
## Built for agents
|
||||
|
||||
mcporter is designed to be the layer between an MCP server and a coding agent. The pattern we recommend:
|
||||
|
||||
1. Configure the server once (or import from your editor of choice).
|
||||
2. Run [`mcporter emit-ts <server>`](emit-ts.md) to get a `.d.ts` of the tool surface.
|
||||
3. Wire small per-server [agent skills](agent-skills.md) instead of one mega-schema prompt — small prompts, named tools, no unrelated schemas loaded.
|
||||
4. For shareable workflows, generate a standalone CLI with [`mcporter generate-cli`](cli-generator.md).
|
||||
|
||||
Because every transport flows through the same runtime, an agent that knows how to spawn `mcporter call` works with stdio servers, hosted HTTP MCPs, OAuth-gated services, and one-off URLs alike.
|
||||
|
||||
## Why a porter?
|
||||
|
||||
A _porter_ carries luggage between trains. mcporter does the same for MCP servers: it carries tool calls, schemas, OAuth tokens, and stdio handles between your agent (or your terminal) and whichever MCP server happens to be at the other end of the line. You don't have to know the shape of the server ahead of time, and the runtime keeps the connection warm so repeat calls are cheap.
|
||||
|
||||
## Where to next
|
||||
|
||||
- [Install](install.md) — npm, npx, Homebrew, or the standalone Bun-compiled binary.
|
||||
- [Quickstart](quickstart.md) — your first list/call/resource in five minutes.
|
||||
- [Configuration](config.md) — `mcporter.json`, imports, env interpolation, OAuth.
|
||||
- [CLI reference](cli-reference.md) — every subcommand and flag.
|
||||
- [Ad-hoc connections](adhoc.md) — point at any MCP endpoint without editing config.
|
||||
- [Agent skills](agent-skills.md) — exposing servers to agents the right way.
|
||||
@ -1,68 +0,0 @@
|
||||
---
|
||||
summary: 'How to install mcporter — npx, npm, pnpm, Homebrew, or a standalone Bun-compiled binary.'
|
||||
---
|
||||
|
||||
# Install
|
||||
|
||||
mcporter ships as both a published npm package and a Homebrew formula. Most workflows can also run mcporter without installing anything via `npx`.
|
||||
|
||||
## Try without installing
|
||||
|
||||
```bash
|
||||
npx mcporter --version
|
||||
npx mcporter list
|
||||
```
|
||||
|
||||
`npx` keeps the package in your npm cache, so subsequent runs are instant. This is the recommended first step.
|
||||
|
||||
## npm / pnpm / Bun
|
||||
|
||||
Install globally:
|
||||
|
||||
```bash
|
||||
npm install -g mcporter
|
||||
```
|
||||
|
||||
Or add it to a project:
|
||||
|
||||
```bash
|
||||
pnpm add mcporter # or: npm install mcporter / bun add mcporter
|
||||
```
|
||||
|
||||
mcporter targets Node 24+ and works under Bun. The package exposes both an importable runtime (`createRuntime`, `callOnce`, `createServerProxy`) and the `mcporter` CLI binary.
|
||||
|
||||
## Homebrew
|
||||
|
||||
```bash
|
||||
brew install steipete/tap/mcporter
|
||||
```
|
||||
|
||||
The tap publishes alongside npm. If you previously installed from an older tap, run `brew update` before reinstalling so Homebrew picks up the new formula path.
|
||||
|
||||
## Standalone binary
|
||||
|
||||
Each release also ships a Bun-compiled standalone binary you can drop on `$PATH` without a Node toolchain. Grab the asset for your OS/arch from the [GitHub releases page](https://github.com/steipete/mcporter/releases) and `chmod +x` it. The compiled CLI behaves the same as the Node build but boots noticeably faster and bundles its dependencies.
|
||||
|
||||
## Verify
|
||||
|
||||
```bash
|
||||
mcporter --version
|
||||
mcporter list
|
||||
```
|
||||
|
||||
The first invocation will print every MCP server it discovered across your configs (Cursor, Claude Code/Desktop, Codex, Windsurf, OpenCode, VS Code). If nothing shows up, jump to [Configuration](config.md) to add a server.
|
||||
|
||||
## Updating
|
||||
|
||||
- `npm`: `npm install -g mcporter@latest`
|
||||
- `pnpm`: `pnpm up -g mcporter@latest`
|
||||
- `brew`: `brew upgrade steipete/tap/mcporter`
|
||||
- Standalone binary: download a fresh release asset.
|
||||
|
||||
## Uninstall
|
||||
|
||||
- `npm uninstall -g mcporter`
|
||||
- `brew uninstall steipete/tap/mcporter`
|
||||
- Standalone binary: delete the file you copied onto `$PATH`.
|
||||
|
||||
mcporter stores OAuth tokens and cached schemas under `~/.mcporter/` (or `$XDG_CACHE_HOME/mcporter/` when set). Remove that directory if you want a fully clean slate.
|
||||
@ -9,29 +9,23 @@ read_when:
|
||||
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. Configure `oauthClientId`/`oauthClientSecretEnv` only if the provider gives you a usable OAuth app; otherwise use their supported client or token/header workaround.
|
||||
- Some hosted servers reject dynamic client registration before returning any authorization URL. mcporter now fails those flows immediately instead of waiting for a browser callback that cannot arrive. If the provider supports a pre-registered OAuth app, configure `oauthClientId`, `oauthClientSecretEnv`, and the required `oauthTokenEndpointAuthMethod`; otherwise use the provider's supported client or token/header workaround.
|
||||
- `mcporter auth <server> --no-browser` still starts a loopback callback server and must stay alive until the browser redirects back. Process managers that run commands in short-lived process groups can print the authorization URL and then reap the process tree, leaving no listener on the callback port and no saved tokens. Run headless OAuth from a persistent terminal, `tmux`, or `nohup`/a supervisor, and use a configured `oauthRedirectUrl` or loopback tunnel when the browser runs elsewhere.
|
||||
- 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.
|
||||
|
||||
@ -1,20 +1,12 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
@ -22,17 +14,12 @@ MCP_LIVE_TESTS=1 pnpm test:live
|
||||
This runs the Vitest suite under `tests/live`, in-band, with longer timeouts.
|
||||
|
||||
## Current coverage
|
||||
|
||||
- **DeepWiki**:
|
||||
- Streamable HTTP success path: `https://mcp.deepwiki.com/mcp`
|
||||
- Deprecated SSE endpoint classification: `https://mcp.deepwiki.com/sse`
|
||||
- Tests:
|
||||
- call `read_wiki_structure repoName:facebook/react` and assert a non-empty result over Streamable HTTP
|
||||
- assert the legacy SSE endpoint currently returns a structured HTTP `410` issue envelope
|
||||
- **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.
|
||||
- As of 2026-03-29, DeepWiki's hosted `/sse` endpoint responds with HTTP `410`, so the live suite treats that as a compatibility/error-classification smoke rather than a success-path transport check.
|
||||
- Keep assertions minimal to reduce flake; these are availability smokes, not full contract tests.
|
||||
|
||||
@ -20,10 +20,10 @@ pnpm exec tsx src/cli.ts list
|
||||
pnpm exec tsx src/cli.ts list --json
|
||||
|
||||
# call a tool (auto formatted)
|
||||
pnpm exec tsx src/cli.ts call context7.resolve-library-id query="React hooks docs" libraryName=react
|
||||
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 query="React hooks docs" libraryName=react --output json
|
||||
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
|
||||
@ -60,7 +60,7 @@ After `pnpm add mcporter` in your project (or inside this repo), the shim binari
|
||||
|
||||
```bash
|
||||
pnpm mcporter:list
|
||||
pnpm mcporter:call context7.query-docs libraryId=/reactjs/react.dev query=hooks
|
||||
pnpm mcporter:call context7.get-library-docs topic=hooks
|
||||
```
|
||||
|
||||
## Debug flags recap
|
||||
|
||||
@ -12,7 +12,7 @@ The keep-alive daemon can tee its stdout/stderr (and per-server call traces) int
|
||||
|
||||
### CLI flags
|
||||
|
||||
- `mcporter daemon start --log` — enable logging at the default path `~/.mcporter/daemon/daemon-<config-hash>.log`, or `$XDG_STATE_HOME/mcporter/daemon/daemon-<config-hash>.log` when `XDG_STATE_HOME` is set.
|
||||
- `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.
|
||||
|
||||
@ -38,7 +38,7 @@ Add a logging block inside the server definition (alongside `lifecycle`) when yo
|
||||
"chrome-devtools": {
|
||||
"description": "Chrome DevTools protocol bridge",
|
||||
"command": "npx",
|
||||
"args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"],
|
||||
"args": ["-y", "chrome-devtools-mcp@latest"],
|
||||
"lifecycle": "keep-alive",
|
||||
"logging": {
|
||||
"daemon": { "enabled": true }
|
||||
@ -60,7 +60,7 @@ When combined with `--log`/`MCPORTER_DAEMON_LOG=1`, any server that has `logging
|
||||
|
||||
### Defaults & cleanup
|
||||
|
||||
Log files live under `~/.mcporter/daemon/` next to the socket/metadata, or under `$XDG_STATE_HOME/mcporter/daemon/` when `XDG_STATE_HOME` is set. 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.
|
||||
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
|
||||
|
||||
|
||||
@ -40,7 +40,6 @@ 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: ...`.
|
||||
|
||||
@ -54,7 +53,6 @@ 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.
|
||||
|
||||
@ -70,17 +68,9 @@ 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': ...`).
|
||||
|
||||
For headless OAuth URL capture, run the same auth command with `--no-browser`:
|
||||
|
||||
- Text mode stdout should contain exactly one authorization URL line and no logger prefix.
|
||||
- `--json --no-browser` stdout should parse as JSON with `authorizationUrl` and `redirectUrl`.
|
||||
- If completing the flow from another machine over SSH, forward the printed callback port with a loopback-only tunnel; avoid exposing the callback listener publicly.
|
||||
- Treat copied authorization URLs as sensitive and avoid storing them in long-lived logs.
|
||||
|
||||
## Tips
|
||||
|
||||
- To exercise error paths, point at a placeholder endpoint and use `--timeout 1000` (e.g., `https://example.com/mcp.listStuff`).
|
||||
|
||||
@ -18,8 +18,6 @@ mcporter is the Sweetistics CLI + runtime for the Model Context Protocol (MCP).
|
||||
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 resource server [uri]`
|
||||
Lists MCP resources for a server, or reads a specific resource URI and renders text/markdown/JSON/raw output.
|
||||
- `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`
|
||||
@ -35,7 +33,7 @@ Use `createServerProxy(runtime, name)` inside scripts when you want ergonomic ca
|
||||
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. Headless callers that must rely on cached tokens without launching OAuth can pass `disableOAuth: true` to `connect`, `callTool`, `listTools`, resource helpers, and `callOnce`; this suppresses interactive OAuth while keeping eligible connections pooled.
|
||||
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
|
||||
|
||||
|
||||
@ -26,18 +26,18 @@ npm install mcporter
|
||||
|
||||
## 3. OAuth Tokens
|
||||
|
||||
- Tokens are saved in the shared vault under `~/.mcporter/credentials.json` by default, or `$XDG_DATA_HOME/mcporter/credentials.json` when `XDG_DATA_HOME` is set.
|
||||
- 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';
|
||||
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' } });
|
||||
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();
|
||||
```
|
||||
|
||||
@ -46,12 +46,12 @@ Prefer `createRuntime` for long-lived agents so connections and OAuth tokens can
|
||||
## 5. Single Call Helper
|
||||
|
||||
```ts
|
||||
import { callOnce } from 'mcporter';
|
||||
import { callOnce } from "mcporter";
|
||||
|
||||
await callOnce({
|
||||
server: 'firecrawl',
|
||||
toolName: 'crawl',
|
||||
args: { url: 'https://anthropic.com' },
|
||||
server: "firecrawl",
|
||||
toolName: "crawl",
|
||||
args: { url: "https://anthropic.com" },
|
||||
});
|
||||
```
|
||||
|
||||
@ -65,12 +65,12 @@ Use `callOnce` for fire-and-forget invocations.
|
||||
|
||||
## 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 | Run `mcporter auth --reset <server>` or delete the matching vault entry/cache and retry. |
|
||||
| Stdio command fails | Pass `--root` to point at the repo root so relative paths resolve. |
|
||||
| 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. |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,80 +0,0 @@
|
||||
---
|
||||
summary: 'Five-minute walk through listing MCP servers, calling a tool, and emitting a typed client.'
|
||||
---
|
||||
|
||||
# Quickstart
|
||||
|
||||
This walkthrough assumes you already have an MCP server configured in Cursor, Claude Code/Desktop, Codex, Windsurf, OpenCode, or VS Code. If not, copy [`config/mcporter.example.json`](https://github.com/steipete/mcporter/blob/main/config/mcporter.example.json) into `~/.mcporter/mcporter.json` and edit it — see [Configuration](config.md) for the full schema.
|
||||
|
||||
## 1. List the servers mcporter sees
|
||||
|
||||
```bash
|
||||
npx mcporter list
|
||||
```
|
||||
|
||||
You get one row per server with auth status, transport type, and tool count. Add `--json` for machine output, `--quiet` for a silent health gate, or `--verbose` to see which config files registered each server.
|
||||
|
||||
## 2. Inspect a single server
|
||||
|
||||
```bash
|
||||
npx mcporter list linear
|
||||
```
|
||||
|
||||
Single-server output reads like a TypeScript header file: dimmed `/** … */` doc comments above each `function name(...)` signature, with optional parameters summarised so the screen stays scannable. Add flags to drill in:
|
||||
|
||||
- `--brief` (alias `--signatures`) — compact signatures only.
|
||||
- `--all-parameters` — show every optional parameter inline.
|
||||
- `--schema` — pretty-print the JSON schema for each tool.
|
||||
- `--json` — machine-readable schema payload.
|
||||
- `--status` — concise status only, without tool docs.
|
||||
|
||||
`mcporter list shadcn.io/api/mcp.getComponents` works too — bare URLs (with or without a `.tool` suffix or scheme) auto-resolve.
|
||||
|
||||
## 3. Call a tool
|
||||
|
||||
```bash
|
||||
# Colon-delimited flags (shell-friendly).
|
||||
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'
|
||||
|
||||
# Function-call style copy/pasted from `mcporter list`.
|
||||
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'
|
||||
|
||||
# Anything after `--` is a literal positional value.
|
||||
npx mcporter call docs.fetch -- --raw-string-with-leading-dashes
|
||||
```
|
||||
|
||||
Pick the output format with `--output text|markdown|json|raw`. Use `--save-images <dir>` to persist binary content blocks. See [CLI reference](cli-reference.md) for the full flag list.
|
||||
|
||||
## 4. Read MCP resources
|
||||
|
||||
```bash
|
||||
npx mcporter resource docs # list resources
|
||||
npx mcporter resource docs file:///path/to/spec.md # read a resource
|
||||
```
|
||||
|
||||
Output formatting is shared with `mcporter call` (`--output`, `--json`, `--raw`).
|
||||
|
||||
## 5. Generate a standalone CLI
|
||||
|
||||
When you want to share a tool with someone who shouldn't have to learn `mcporter call`:
|
||||
|
||||
```bash
|
||||
npx mcporter generate-cli linear --bundle dist/linear.js
|
||||
node dist/linear.js create-comment --issue-id ENG-123 --body 'Looks good!'
|
||||
```
|
||||
|
||||
Add `--compile <path>` for a Bun-compiled binary, or `--include-tools a,b,c` to ship a subset. Full details in [CLI generator](cli-generator.md).
|
||||
|
||||
## 6. Emit typed clients for agents
|
||||
|
||||
```bash
|
||||
npx mcporter emit-ts linear --mode client --out src/linear-client.ts
|
||||
```
|
||||
|
||||
You get a `.d.ts` interface and a `createServerProxy()`-backed factory. Calls return `CallResult` objects with `.text()`, `.markdown()`, `.json()`, `.images()`, `.content()` helpers — see [Tool calling](tool-calling.md) for the proxy API and [emit-ts](emit-ts.md) for the generator.
|
||||
|
||||
## What next
|
||||
|
||||
- [Configuration](config.md) — `mcporter.json` schema, env interpolation, OAuth fields.
|
||||
- [Ad-hoc connections](adhoc.md) — point at any MCP endpoint without editing config.
|
||||
- [Agent skills](agent-skills.md) — wiring per-server skills into a coding agent.
|
||||
@ -1,52 +0,0 @@
|
||||
---
|
||||
summary: 'How to record MCP JSON-RPC traffic to NDJSON and replay it deterministically for offline debugging.'
|
||||
read_when:
|
||||
- 'Debugging or reproducing MCP-backed tool calls without contacting the live server.'
|
||||
---
|
||||
|
||||
# Record and replay MCP calls
|
||||
|
||||
`mcporter record` captures the JSON-RPC traffic between the runtime and configured MCP servers. `mcporter replay` reads the captured stream and serves the recorded responses back to the same requests without contacting the live MCP server.
|
||||
|
||||
Recordings live under `~/.mcporter/recordings/` as newline-delimited JSON:
|
||||
|
||||
```bash
|
||||
mcporter record demo-session -- mcporter call linear.list_issues limit:5
|
||||
mcporter replay demo-session -- mcporter call linear.list_issues limit:5
|
||||
```
|
||||
|
||||
Recordings contain raw JSON-RPC params and responses. Review and redact them before sharing, attaching to bug reports, or committing them to a repository because tool arguments and results can include credentials, private content, or customer data.
|
||||
|
||||
To record or replay a later command, create the session configuration and export the matching environment variable:
|
||||
|
||||
```bash
|
||||
mcporter record demo-session
|
||||
MCPORTER_RECORD=demo-session mcporter call linear.list_issues limit:5
|
||||
|
||||
mcporter replay demo-session
|
||||
MCPORTER_REPLAY=demo-session mcporter call linear.list_issues limit:5
|
||||
```
|
||||
|
||||
Use `--server` when you only want one server's traffic:
|
||||
|
||||
```bash
|
||||
mcporter record demo-session --server linear -- mcporter call linear.list_issues limit:5
|
||||
mcporter replay demo-session --server linear -- mcporter call linear.list_issues limit:5
|
||||
```
|
||||
|
||||
## File format
|
||||
|
||||
Each line is one JSON-RPC envelope with an added `_meta` object:
|
||||
|
||||
```json
|
||||
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_issues","arguments":{"limit":5}},"_meta":{"dir":"send","server":"linear","ts":"2026-05-16T12:00:00.000Z"}}
|
||||
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"..."}]},"_meta":{"dir":"recv","server":"linear","ts":"2026-05-16T12:00:00.100Z"}}
|
||||
```
|
||||
|
||||
`_meta.dir` is `send`, `recv`, or `lifecycle`. Replay strips `_meta` before delivering a response. Lifecycle events such as transport start and close are recorded for diagnostics but ignored during replay.
|
||||
|
||||
## Deterministic matching
|
||||
|
||||
Replay is strict. For each server, mcporter expects requests to arrive in the same order with the same JSON-RPC method and deeply equal `params`. If the next request differs, replay fails with an error that names the incoming request and the next recorded request it expected.
|
||||
|
||||
This makes recordings useful as reproducible bug fixtures: a replay either follows the captured MCP exchange exactly or fails at the first point where the workflow diverges.
|
||||
@ -9,8 +9,7 @@ read_when:
|
||||
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)_
|
||||
|
||||
## 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**:
|
||||
@ -19,8 +18,7 @@ Each section lists the goal, why it matters, and the concrete steps/tests needed
|
||||
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)_
|
||||
|
||||
## 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**:
|
||||
@ -31,8 +29,7 @@ Each section lists the goal, why it matters, and the concrete steps/tests needed
|
||||
3. Added `tests/generator-flag-parser.test.ts` to cover runtime/timeout and
|
||||
optional flags.
|
||||
|
||||
## 3. Test Fixture Reuse _(Completed)_
|
||||
|
||||
## 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**:
|
||||
@ -42,8 +39,7 @@ Each section lists the goal, why it matters, and the concrete steps/tests needed
|
||||
3. Ensured the fixture covers required+optional parameters so both suites hit
|
||||
the same edge cases.
|
||||
|
||||
## 4. CallResult Helper Extraction _(Completed)_
|
||||
|
||||
## 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**:
|
||||
@ -53,8 +49,7 @@ Each section lists the goal, why it matters, and the concrete steps/tests needed
|
||||
they stay in sync.
|
||||
3. Adjusted emit-ts tests to assert the helper is referenced.
|
||||
|
||||
## 5. CLI Docs Consolidation _(Completed)_
|
||||
|
||||
## 5. CLI Docs Consolidation *(Completed)*
|
||||
- **Problem**: CLI usage guidance was scattered across README, `docs/spec.md`,
|
||||
and various feature docs.
|
||||
- **What we did**:
|
||||
@ -65,8 +60,7 @@ Each section lists the goal, why it matters, and the concrete steps/tests needed
|
||||
- **Next**: Once the other doc changes land, update README/spec to link to the
|
||||
reference and drop redundant sections.
|
||||
|
||||
## 6. Runtime Module Split _(Completed)_
|
||||
|
||||
## 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`.
|
||||
@ -78,6 +72,5 @@ Each section lists the goal, why it matters, and the concrete steps/tests needed
|
||||
- **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).
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 150 KiB |
@ -1,129 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630" role="img" aria-labelledby="title desc">
|
||||
<title id="title">mcporter social card</title>
|
||||
<desc id="desc">mcporter: MCP, made portable. TypeScript runtime, CLI, and code-generation toolkit for the Model Context Protocol.</desc>
|
||||
<defs>
|
||||
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0" stop-color="#0a0c12"/>
|
||||
<stop offset="0.55" stop-color="#10131c"/>
|
||||
<stop offset="1" stop-color="#0c0f17"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="brandSweep" x1="0" y1="0" x2="1" y2="0">
|
||||
<stop offset="0" stop-color="#7c3aed"/>
|
||||
<stop offset="0.45" stop-color="#06b6d4"/>
|
||||
<stop offset="0.85" stop-color="#10b981"/>
|
||||
<stop offset="1" stop-color="#f59e0b"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="logoGrad" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0" stop-color="#7c3aed"/>
|
||||
<stop offset="1" stop-color="#06b6d4"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="panel" x1="0" y1="0" x2="0" y2="1">
|
||||
<stop offset="0" stop-color="#0e121b"/>
|
||||
<stop offset="1" stop-color="#070a10"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="panelBar" x1="0" y1="0" x2="0" y2="1">
|
||||
<stop offset="0" stop-color="#1a1f2c"/>
|
||||
<stop offset="1" stop-color="#0f131c"/>
|
||||
</linearGradient>
|
||||
<radialGradient id="haze" cx="0.18" cy="0.22" r="0.6">
|
||||
<stop offset="0" stop-color="#7c3aed" stop-opacity="0.28"/>
|
||||
<stop offset="0.6" stop-color="#06b6d4" stop-opacity="0.08"/>
|
||||
<stop offset="1" stop-color="#06b6d4" stop-opacity="0"/>
|
||||
</radialGradient>
|
||||
<filter id="shadow" x="-10%" y="-10%" width="120%" height="130%">
|
||||
<feDropShadow dx="0" dy="22" stdDeviation="34" flood-color="#000000" flood-opacity="0.55"/>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<rect width="1200" height="630" fill="url(#bg)"/>
|
||||
<rect width="1200" height="630" fill="url(#haze)"/>
|
||||
|
||||
<!-- Top accent line -->
|
||||
<rect x="0" y="0" width="1200" height="6" fill="url(#brandSweep)"/>
|
||||
|
||||
<!-- Brand mark: stylized suitcase icon -->
|
||||
<g transform="translate(76 76)">
|
||||
<rect x="0" y="0" width="118" height="118" rx="24" fill="url(#logoGrad)"/>
|
||||
<rect x="22" y="42" width="74" height="56" rx="8" fill="#0a0c12"/>
|
||||
<rect x="40" y="28" width="38" height="16" rx="4" fill="#0a0c12"/>
|
||||
<rect x="22" y="58" width="74" height="3" fill="rgba(255,255,255,0.18)"/>
|
||||
<circle cx="59" cy="74" r="6" fill="#a78bfa"/>
|
||||
</g>
|
||||
|
||||
<!-- Title -->
|
||||
<text x="76" y="276" fill="#f5f7fb" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="100" font-weight="800" letter-spacing="-1">mcporter</text>
|
||||
|
||||
<!-- Tagline -->
|
||||
<text x="80" y="338" fill="#cbd5e1" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="34" font-weight="700" letter-spacing="0">MCP, made portable.</text>
|
||||
|
||||
<!-- Description -->
|
||||
<text x="80" y="386" fill="#94a3b8" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="500">TypeScript runtime + CLI for the Model Context Protocol.</text>
|
||||
<text x="80" y="414" fill="#94a3b8" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="500">Discover, call, and generate clients for any MCP server.</text>
|
||||
|
||||
<!-- Multi-color accent bar -->
|
||||
<rect x="80" y="440" width="280" height="4" rx="2" fill="url(#brandSweep)"/>
|
||||
|
||||
<!-- Bottom row: install pill + URL pill -->
|
||||
<g transform="translate(80 478)">
|
||||
<rect x="0" y="0" width="320" height="48" rx="11" fill="#0e121b" stroke="#1f2937"/>
|
||||
<text x="20" y="32" fill="#64748b" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="18" font-weight="500">$</text>
|
||||
<text x="42" y="32" fill="#e6edf3" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="18" font-weight="600">npx mcporter list</text>
|
||||
|
||||
<rect x="340" y="0" width="180" height="48" rx="11" fill="#0e121b" stroke="#1f2937"/>
|
||||
<text x="362" y="32" fill="#a78bfa" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="18" font-weight="600">mcporter.sh</text>
|
||||
</g>
|
||||
|
||||
<!-- Right-side terminal mockup -->
|
||||
<g transform="translate(670 142)" filter="url(#shadow)">
|
||||
<rect x="0" y="0" width="464" height="346" rx="20" fill="url(#panel)" stroke="#1b2030"/>
|
||||
<rect x="0" y="0" width="464" height="42" rx="20" fill="url(#panelBar)"/>
|
||||
<rect x="0" y="22" width="464" height="20" fill="url(#panelBar)"/>
|
||||
<circle cx="24" cy="21" r="6" fill="#ec4899"/>
|
||||
<circle cx="46" cy="21" r="6" fill="#f59e0b"/>
|
||||
<circle cx="68" cy="21" r="6" fill="#10b981"/>
|
||||
<text x="232" y="27" fill="#94a3b8" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="500" text-anchor="middle">mcporter — agent ready</text>
|
||||
|
||||
<!-- Terminal content -->
|
||||
<text x="22" y="80" fill="#a78bfa" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="15" font-weight="600">$ npx mcporter list linear</text>
|
||||
<text x="22" y="108" fill="#64748b" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">/**</text>
|
||||
<text x="22" y="126" fill="#64748b" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13"> * Create a comment on a Linear issue</text>
|
||||
<text x="22" y="144" fill="#64748b" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13"> * @param issueId The issue ID</text>
|
||||
<text x="22" y="162" fill="#64748b" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13"> * @param body Markdown comment body</text>
|
||||
<text x="22" y="180" fill="#64748b" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13"> */</text>
|
||||
<text x="22" y="200" fill="#7dd3fc" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="600">function</text>
|
||||
<text x="100" y="200" fill="#fde68a" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="600">create_comment</text>
|
||||
<text x="226" y="200" fill="#cbd5e1" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">(issueId, body);</text>
|
||||
|
||||
<text x="22" y="234" fill="#a78bfa" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="15" font-weight="600">$ mcporter call linear.create_comment \\</text>
|
||||
<text x="36" y="252" fill="#cbd5e1" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">issueId:ENG-123 body:'lgtm'</text>
|
||||
|
||||
<rect x="22" y="266" width="420" height="60" rx="10" fill="#06090f" stroke="#1f2937"/>
|
||||
<text x="38" y="290" fill="#fbbf24" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">{</text>
|
||||
<text x="54" y="308" fill="#a7f3d0" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">"ok": true, "comment": { "id": "abc123" }</text>
|
||||
<text x="38" y="326" fill="#fbbf24" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">}</text>
|
||||
</g>
|
||||
|
||||
<!-- Capability pills below terminal -->
|
||||
<g transform="translate(670 514)" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="14" font-weight="600">
|
||||
<g>
|
||||
<rect x="0" y="0" width="92" height="30" rx="15" fill="#0e121b" stroke="#262a36"/>
|
||||
<text x="46" y="20" fill="#a78bfa" text-anchor="middle">Runtime</text>
|
||||
</g>
|
||||
<g transform="translate(104 0)">
|
||||
<rect x="0" y="0" width="56" height="30" rx="15" fill="#0e121b" stroke="#262a36"/>
|
||||
<text x="28" y="20" fill="#06b6d4" text-anchor="middle">CLI</text>
|
||||
</g>
|
||||
<g transform="translate(174 0)">
|
||||
<rect x="0" y="0" width="78" height="30" rx="15" fill="#0e121b" stroke="#262a36"/>
|
||||
<text x="39" y="20" fill="#10b981" text-anchor="middle">OAuth</text>
|
||||
</g>
|
||||
<g transform="translate(266 0)">
|
||||
<rect x="0" y="0" width="68" height="30" rx="15" fill="#0e121b" stroke="#262a36"/>
|
||||
<text x="34" y="20" fill="#ec4899" text-anchor="middle">stdio</text>
|
||||
</g>
|
||||
<g transform="translate(348 0)">
|
||||
<rect x="0" y="0" width="64" height="30" rx="15" fill="#0e121b" stroke="#262a36"/>
|
||||
<text x="32" y="20" fill="#f59e0b" text-anchor="middle">HTTP</text>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 8.1 KiB |
14
docs/spec.md
14
docs/spec.md
@ -7,13 +7,11 @@ summary: 'Plan for the mcporter package replacing the Sweetistics pnpm MCP helpe
|
||||
> 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.
|
||||
@ -25,21 +23,19 @@ summary: 'Plan for the mcporter package replacing the Sweetistics pnpm MCP helpe
|
||||
- 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, or XDG paths when configured).
|
||||
- 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` or `$XDG_CACHE_HOME/mcporter/<server>/schema.json` for reuse across processes, and tolerate failures by falling back to raw `callTool`.
|
||||
- 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.
|
||||
@ -51,7 +47,6 @@ summary: 'Plan for the mcporter package replacing the Sweetistics pnpm MCP helpe
|
||||
- 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.
|
||||
@ -59,28 +54,24 @@ summary: 'Plan for the mcporter package replacing the Sweetistics pnpm MCP helpe
|
||||
- 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`.
|
||||
@ -89,7 +80,6 @@ summary: 'Plan for the mcporter package replacing the Sweetistics pnpm MCP helpe
|
||||
- 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?
|
||||
|
||||
@ -5,7 +5,6 @@ summary: 'Multi-agent system directives and coordination rules. Master reference
|
||||
# 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
|
||||
@ -14,7 +13,6 @@ summary: 'Multi-agent system directives and coordination rules. Master reference
|
||||
```
|
||||
|
||||
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:
|
||||
@ -25,19 +23,16 @@ summary: 'Multi-agent system directives and coordination rules. Master reference
|
||||
- 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.
|
||||
|
||||
@ -7,7 +7,6 @@ read_when:
|
||||
# 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.
|
||||
@ -15,7 +14,6 @@ read_when:
|
||||
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:
|
||||
|
||||
```
|
||||
@ -23,13 +21,11 @@ Supabase’s hosted MCP server (`https://mcp.supabase.com/mcp`) validates the re
|
||||
```
|
||||
|
||||
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.
|
||||
@ -37,7 +33,6 @@ Key takeaways from Supabase’s docs:
|
||||
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.
|
||||
@ -51,7 +46,6 @@ This works for providers that use standard MCP scopes (e.g., the MCP example ser
|
||||
- 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).
|
||||
|
||||
@ -13,14 +13,11 @@ Use `tmux` to verify whether a CLI command actually exits or is stalled on open
|
||||
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
|
||||
@ -30,4 +27,4 @@ Use `tmux` to verify whether a CLI command actually exits or is stalled on open
|
||||
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 the full 5 minute default for a browser callback.
|
||||
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.
|
||||
|
||||
@ -30,20 +30,18 @@ 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`.
|
||||
- Use `body=@comment.md` (or `--body @comment.md`) to read an exact UTF-8 string from a file; use `body=@@literal` when the value itself starts with `@`.
|
||||
- `--args '{"title":"Bug"}'` still ingests JSON payloads directly.
|
||||
- Unknown long flags now error instead of silently becoming tool arguments; use `title=value`, `--args`, or `--` before literal positional values beginning with `--`.
|
||||
|
||||
## 3. Function-Call Syntax
|
||||
|
||||
```bash
|
||||
mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'
|
||||
mcporter 'context7.resolve-library-id(query: "React hooks docs", libraryName: "react")'
|
||||
mcporter 'context7.resolve-library-id("React hooks docs", "react")'
|
||||
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 hooks docs", "react")'` maps arguments to the live schema order automatically.
|
||||
- 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.
|
||||
|
||||
@ -70,7 +68,6 @@ mcporter call --http-url https://mcp.example.com/mcp fetch_docs repoName=value
|
||||
---
|
||||
|
||||
**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.
|
||||
|
||||
@ -5,21 +5,21 @@ 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.
|
||||
* `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.
|
||||
* 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.
|
||||
* 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.
|
||||
|
||||
@ -5,62 +5,68 @@
|
||||
* and print only the markdown headlines.
|
||||
*/
|
||||
|
||||
import { createRuntime, createServerProxy, type CallResult } from '../src/index.js';
|
||||
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 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 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 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 docs = await getLibraryDocs(contextId);
|
||||
|
||||
const markdown = docs.markdown() ?? docs.text() ?? '';
|
||||
const headlines = markdown
|
||||
.split('\n')
|
||||
.filter((line) => /^#+\s/.test(line))
|
||||
.join('\n');
|
||||
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();
|
||||
}
|
||||
console.log("# Headlines for React");
|
||||
console.log(headlines || "(no headlines found)");
|
||||
} finally {
|
||||
await mcpRuntime.close();
|
||||
}
|
||||
}
|
||||
|
||||
main().catch((error) => {
|
||||
console.error(error);
|
||||
process.exit(1);
|
||||
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;
|
||||
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;
|
||||
}
|
||||
|
||||
@ -1,170 +0,0 @@
|
||||
#!/usr/bin/env tsx
|
||||
|
||||
/**
|
||||
* Demonstration: `disableOAuth: true` provides cache-friendly OAuth
|
||||
* suppression for headless callers.
|
||||
*
|
||||
* Spins up a local mock MCP server (no real auth), then exercises three
|
||||
* patterns side-by-side and counts the distinct ClientContext objects
|
||||
* the runtime hands out:
|
||||
*
|
||||
* 1. Legacy `maxOAuthAttempts: 0` — uncached (existing contract).
|
||||
* 2. `disableOAuth: true` direct connects — pooled.
|
||||
* 3. The documented headless setup — pre-connect with
|
||||
* `disableOAuth: true`, then 5 `callTool` invocations. Verifies the
|
||||
* pre-connected slot is preserved (no implicit eviction).
|
||||
*
|
||||
* Run: pnpm tsx examples/headless-pooling-demo.ts
|
||||
*
|
||||
* Counting strategy: ClientContext object identity. Each call to
|
||||
* `createClientContext` inside the runtime returns a fresh object;
|
||||
* cached calls return the same object. We track the set of unique
|
||||
* objects and report cardinality.
|
||||
*/
|
||||
|
||||
import type { Server as HttpServer } from 'node:http';
|
||||
import type { AddressInfo } from 'node:net';
|
||||
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
||||
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
|
||||
import express from 'express';
|
||||
import { z } from 'zod';
|
||||
import { createRuntime } from '../src/index.js';
|
||||
|
||||
const INVOCATIONS = 5;
|
||||
|
||||
async function startMockServer(): Promise<{ baseUrl: URL; httpServer: HttpServer }> {
|
||||
const app = express();
|
||||
app.use(express.json());
|
||||
|
||||
const mcp = new McpServer({ name: 'demo', version: '1.0.0' });
|
||||
mcp.registerTool(
|
||||
'add',
|
||||
{
|
||||
title: 'Addition',
|
||||
description: 'Add two numbers',
|
||||
inputSchema: { a: z.number(), b: z.number() },
|
||||
outputSchema: { result: z.number() },
|
||||
},
|
||||
async ({ a, b }) => {
|
||||
const result = { result: a + b };
|
||||
return {
|
||||
content: [{ type: 'text', text: JSON.stringify(result) }],
|
||||
structuredContent: result,
|
||||
};
|
||||
}
|
||||
);
|
||||
|
||||
app.get('/mcp', (_req, res) => res.sendStatus(405));
|
||||
app.post('/mcp', async (req, res) => {
|
||||
const transport = new StreamableHTTPServerTransport({
|
||||
sessionIdGenerator: undefined,
|
||||
enableJsonResponse: true,
|
||||
});
|
||||
res.on('close', () => {
|
||||
transport.close().catch(() => {});
|
||||
});
|
||||
await mcp.connect(transport);
|
||||
await transport.handleRequest(req, res, req.body);
|
||||
});
|
||||
|
||||
const httpServer = app.listen(0, '127.0.0.1');
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
httpServer.once('listening', resolve);
|
||||
httpServer.once('error', reject);
|
||||
});
|
||||
const address = httpServer.address() as AddressInfo;
|
||||
return { baseUrl: new URL(`http://127.0.0.1:${address.port}/mcp`), httpServer };
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
// The mock MCP server below has no `auth: 'oauth'` definition, so the
|
||||
// OAuth flow is not exercised here. This demo focuses on the
|
||||
// cache-behavior fix (the main fix in PR #198). OAuth-suppression
|
||||
// semantics under `disableOAuth: true` are exercised by the unit
|
||||
// tests in `tests/runtime-transport.test.ts` (shouldEstablishOAuth)
|
||||
// and `tests/runtime-integration.test.ts` (cache + eviction).
|
||||
const { baseUrl, httpServer } = await startMockServer();
|
||||
console.log(`[demo] Mock MCP server listening at ${baseUrl}\n`);
|
||||
|
||||
try {
|
||||
// ----- Pattern A: legacy maxOAuthAttempts: 0 (uncached) ------------
|
||||
{
|
||||
const runtime = await createRuntime({
|
||||
servers: [
|
||||
{
|
||||
name: 'demo',
|
||||
description: 'Demo server',
|
||||
command: { kind: 'http', url: baseUrl },
|
||||
},
|
||||
],
|
||||
});
|
||||
const contexts = new Set<unknown>();
|
||||
for (let i = 0; i < INVOCATIONS; i++) {
|
||||
contexts.add(await runtime.connect('demo', { maxOAuthAttempts: 0 }));
|
||||
}
|
||||
console.log(`[demo] Pattern A — legacy maxOAuthAttempts: 0`);
|
||||
console.log(`[demo] ${INVOCATIONS} connect() calls → ${contexts.size} distinct ClientContexts`);
|
||||
console.log(`[demo] Expected: ${INVOCATIONS} (legacy contract: cache disabled when maxOAuthAttempts is set)`);
|
||||
console.log(`[demo] Result: ${contexts.size === INVOCATIONS ? 'OK' : 'UNEXPECTED'}\n`);
|
||||
await runtime.close();
|
||||
}
|
||||
|
||||
// ----- Pattern B: disableOAuth: true on every connect ---------------
|
||||
{
|
||||
const runtime = await createRuntime({
|
||||
servers: [
|
||||
{
|
||||
name: 'demo',
|
||||
description: 'Demo server',
|
||||
command: { kind: 'http', url: baseUrl },
|
||||
},
|
||||
],
|
||||
});
|
||||
const contexts = new Set<unknown>();
|
||||
for (let i = 0; i < INVOCATIONS; i++) {
|
||||
contexts.add(await runtime.connect('demo', { disableOAuth: true }));
|
||||
}
|
||||
console.log(`[demo] Pattern B — disableOAuth: true on every connect`);
|
||||
console.log(`[demo] ${INVOCATIONS} connect() calls → ${contexts.size} distinct ClientContexts`);
|
||||
console.log(`[demo] Expected: 1 (cache reuse under cache-friendly suppression)`);
|
||||
console.log(`[demo] Result: ${contexts.size === 1 ? 'PASS' : 'FAIL'}\n`);
|
||||
await runtime.close();
|
||||
}
|
||||
|
||||
// ----- Pattern C: documented headless setup + 5 callTool ------------
|
||||
{
|
||||
const runtime = await createRuntime({
|
||||
servers: [
|
||||
{
|
||||
name: 'demo',
|
||||
description: 'Demo server',
|
||||
command: { kind: 'http', url: baseUrl },
|
||||
},
|
||||
],
|
||||
});
|
||||
const initial = await runtime.connect('demo', { disableOAuth: true });
|
||||
let sum = 0;
|
||||
for (let i = 0; i < INVOCATIONS; i++) {
|
||||
const result = (await runtime.callTool('demo', 'add', {
|
||||
args: { a: i, b: i + 1 },
|
||||
})) as { structuredContent?: { result: number } };
|
||||
sum += result.structuredContent?.result ?? 0;
|
||||
}
|
||||
const afterCalls = await runtime.connect('demo', { disableOAuth: true });
|
||||
const reused = afterCalls === initial;
|
||||
console.log(`[demo] Pattern C — pre-connect(disableOAuth:true) + ${INVOCATIONS} callTool()`);
|
||||
console.log(`[demo] Sum of ${INVOCATIONS} add() results: ${sum}`);
|
||||
console.log(`[demo] Post-callTool connect() === pre-connect ClientContext: ${reused}`);
|
||||
console.log(`[demo] Expected: true (no implicit eviction from callTool internals)`);
|
||||
console.log(`[demo] Result: ${reused ? 'PASS' : 'FAIL'}\n`);
|
||||
await runtime.close();
|
||||
}
|
||||
} finally {
|
||||
await new Promise<void>((resolve) => httpServer.close(() => resolve()));
|
||||
}
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error(err);
|
||||
process.exit(1);
|
||||
});
|
||||
@ -1,392 +0,0 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"mcpServers": {
|
||||
"type": "object",
|
||||
"propertyNames": {
|
||||
"type": "string"
|
||||
},
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"description": {
|
||||
"description": "Human-readable description of the server",
|
||||
"type": "string"
|
||||
},
|
||||
"baseUrl": {
|
||||
"description": "Base URL for HTTP/SSE transport (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"base_url": {
|
||||
"description": "Base URL for HTTP/SSE transport (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"url": {
|
||||
"description": "Server URL for HTTP/SSE transport",
|
||||
"type": "string"
|
||||
},
|
||||
"serverUrl": {
|
||||
"description": "Server URL for HTTP/SSE transport (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"server_url": {
|
||||
"description": "Server URL for HTTP/SSE transport (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"command": {
|
||||
"description": "Command to spawn for stdio transport (string or array of arguments)",
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"executable": {
|
||||
"description": "Executable path for stdio transport",
|
||||
"type": "string"
|
||||
},
|
||||
"args": {
|
||||
"description": "Arguments to pass to the stdio command",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"cwd": {
|
||||
"description": "Working directory for stdio servers. A leading ~ is expanded to $HOME; relative paths resolve against the config file directory",
|
||||
"type": "string"
|
||||
},
|
||||
"headers": {
|
||||
"description": "HTTP headers for requests. Supports ${VAR}, ${VAR:-fallback}, and $env:VAR placeholders",
|
||||
"type": "object",
|
||||
"propertyNames": {
|
||||
"type": "string"
|
||||
},
|
||||
"additionalProperties": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"env": {
|
||||
"description": "Environment variables for stdio commands. Supports ${VAR} and ${VAR:-fallback} placeholders",
|
||||
"type": "object",
|
||||
"propertyNames": {
|
||||
"type": "string"
|
||||
},
|
||||
"additionalProperties": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"auth": {
|
||||
"description": "Authentication method (e.g., \"oauth\")",
|
||||
"type": "string"
|
||||
},
|
||||
"tokenCacheDir": {
|
||||
"description": "Directory for caching OAuth tokens (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"token_cache_dir": {
|
||||
"description": "Directory for caching OAuth tokens (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"clientName": {
|
||||
"description": "Client identifier for server telemetry (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"client_name": {
|
||||
"description": "Client identifier for server telemetry (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauthClientId": {
|
||||
"description": "Pre-registered OAuth client id (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauth_client_id": {
|
||||
"description": "Pre-registered OAuth client id (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauthClientSecret": {
|
||||
"description": "Pre-registered OAuth client secret (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauth_client_secret": {
|
||||
"description": "Pre-registered OAuth client secret (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauthClientSecretEnv": {
|
||||
"description": "Environment variable containing the OAuth client secret",
|
||||
"type": "string"
|
||||
},
|
||||
"oauth_client_secret_env": {
|
||||
"description": "Environment variable containing the OAuth client secret",
|
||||
"type": "string"
|
||||
},
|
||||
"oauthTokenEndpointAuthMethod": {
|
||||
"description": "OAuth token endpoint auth method, e.g. client_secret_post",
|
||||
"type": "string"
|
||||
},
|
||||
"oauth_token_endpoint_auth_method": {
|
||||
"description": "OAuth token endpoint auth method, e.g. client_secret_post",
|
||||
"type": "string"
|
||||
},
|
||||
"oauthRedirectUrl": {
|
||||
"description": "Custom OAuth redirect URL (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauth_redirect_url": {
|
||||
"description": "Custom OAuth redirect URL (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauthScope": {
|
||||
"description": "OAuth scope override (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauth_scope": {
|
||||
"description": "OAuth scope override (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"oauthCommand": {
|
||||
"description": "Custom OAuth command configuration for stdio servers (camelCase)",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"args": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Arguments for the OAuth command"
|
||||
}
|
||||
},
|
||||
"required": ["args"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"oauth_command": {
|
||||
"description": "Custom OAuth command configuration for stdio servers (snake_case)",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"args": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Arguments for the OAuth command"
|
||||
}
|
||||
},
|
||||
"required": ["args"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"bearerToken": {
|
||||
"description": "Static bearer token for authentication (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"bearer_token": {
|
||||
"description": "Static bearer token for authentication (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"bearerTokenEnv": {
|
||||
"description": "Environment variable name containing the bearer token (camelCase)",
|
||||
"type": "string"
|
||||
},
|
||||
"bearer_token_env": {
|
||||
"description": "Environment variable name containing the bearer token (snake_case)",
|
||||
"type": "string"
|
||||
},
|
||||
"refresh": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"tokenEndpoint": {
|
||||
"description": "OAuth token endpoint used to refresh access tokens",
|
||||
"type": "string"
|
||||
},
|
||||
"token_endpoint": {
|
||||
"description": "OAuth token endpoint used to refresh access tokens",
|
||||
"type": "string"
|
||||
},
|
||||
"clientIdEnv": {
|
||||
"description": "Environment variable containing the OAuth client id",
|
||||
"type": "string"
|
||||
},
|
||||
"client_id_env": {
|
||||
"description": "Environment variable containing the OAuth client id",
|
||||
"type": "string"
|
||||
},
|
||||
"clientSecretEnv": {
|
||||
"description": "Environment variable containing the OAuth client secret",
|
||||
"type": "string"
|
||||
},
|
||||
"client_secret_env": {
|
||||
"description": "Environment variable containing the OAuth client secret",
|
||||
"type": "string"
|
||||
},
|
||||
"clientAuthMethod": {
|
||||
"description": "OAuth token endpoint client auth method",
|
||||
"type": "string"
|
||||
},
|
||||
"client_auth_method": {
|
||||
"description": "OAuth token endpoint client auth method",
|
||||
"type": "string"
|
||||
},
|
||||
"refreshSkewSeconds": {
|
||||
"description": "Refresh before expiry by this many seconds",
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"refresh_skew_seconds": {
|
||||
"description": "Refresh before expiry by this many seconds",
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"accessTokenEnv": {
|
||||
"description": "STDIO env var that receives the refreshed access token",
|
||||
"type": "string"
|
||||
},
|
||||
"access_token_env": {
|
||||
"description": "STDIO env var that receives the refreshed access token",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false,
|
||||
"description": "Refreshable bearer token settings"
|
||||
},
|
||||
"httpFetch": {
|
||||
"description": "HTTP fetch implementation for Streamable HTTP/SSE requests",
|
||||
"type": "string",
|
||||
"enum": ["default", "node-http1"]
|
||||
},
|
||||
"http_fetch": {
|
||||
"description": "HTTP fetch implementation for Streamable HTTP/SSE requests",
|
||||
"type": "string",
|
||||
"enum": ["default", "node-http1"]
|
||||
},
|
||||
"lifecycle": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string",
|
||||
"const": "keep-alive",
|
||||
"description": "Keep the server connection alive"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"const": "ephemeral",
|
||||
"description": "Connect only when needed"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"mode": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string",
|
||||
"const": "keep-alive"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"const": "ephemeral"
|
||||
}
|
||||
],
|
||||
"description": "Connection lifecycle mode"
|
||||
},
|
||||
"idleTimeoutMs": {
|
||||
"description": "Idle timeout in milliseconds before disconnecting",
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
}
|
||||
},
|
||||
"required": ["mode"],
|
||||
"additionalProperties": false
|
||||
}
|
||||
],
|
||||
"description": "Server connection lifecycle: keep-alive maintains persistent connections, ephemeral connects on-demand"
|
||||
},
|
||||
"logging": {
|
||||
"description": "Logging configuration for the server",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"daemon": {
|
||||
"description": "Daemon-specific logging configuration",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"enabled": {
|
||||
"description": "Enable daemon logging for this server",
|
||||
"type": "boolean"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"allowedTools": {
|
||||
"description": "Only these exact tool names are exposed (camelCase)",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"allowed_tools": {
|
||||
"description": "Only these exact tool names are exposed (snake_case)",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"blockedTools": {
|
||||
"description": "These exact tool names are hidden and blocked (camelCase)",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"blocked_tools": {
|
||||
"description": "These exact tool names are hidden and blocked (snake_case)",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"additionalProperties": false,
|
||||
"description": "MCP server definition supporting both HTTP/SSE and stdio transports"
|
||||
},
|
||||
"description": "Map of server names to their configurations"
|
||||
},
|
||||
"daemonIdleTimeoutMs": {
|
||||
"description": "Idle timeout in milliseconds before shutting down an inactive daemon",
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"daemon_idle_timeout_ms": {
|
||||
"description": "Idle timeout in milliseconds before shutting down an inactive daemon",
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"imports": {
|
||||
"description": "Editor configurations to import servers from. Omit to use defaults, or set to [] to disable imports",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"enum": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"],
|
||||
"description": "Supported editor/client configurations to import MCP servers from"
|
||||
}
|
||||
},
|
||||
"$schema": {
|
||||
"type": "string",
|
||||
"description": "JSON Schema URL for IDE validation and autocomplete"
|
||||
}
|
||||
},
|
||||
"required": ["mcpServers"],
|
||||
"additionalProperties": false,
|
||||
"description": "mcporter configuration file schema",
|
||||
"$id": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json"
|
||||
}
|
||||
117
package.json
117
package.json
@ -1,27 +1,13 @@
|
||||
{
|
||||
"name": "mcporter",
|
||||
"version": "0.12.1",
|
||||
"version": "0.6.6",
|
||||
"description": "TypeScript runtime and CLI for connecting to configured Model Context Protocol servers.",
|
||||
"keywords": [
|
||||
"cli",
|
||||
"mcp",
|
||||
"model-context-protocol",
|
||||
"sweetistics"
|
||||
],
|
||||
"license": "MIT",
|
||||
"author": "Sweetistics",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "git+https://github.com/openclaw/mcporter.git"
|
||||
"packageManager": "pnpm@10.22.0",
|
||||
"pnpm": {
|
||||
"overrides": {
|
||||
"body-parser": "2.2.1"
|
||||
}
|
||||
},
|
||||
"bin": {
|
||||
"mcporter": "dist/cli.js"
|
||||
},
|
||||
"files": [
|
||||
"dist",
|
||||
"README.md",
|
||||
"LICENSE"
|
||||
],
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
"module": "dist/index.js",
|
||||
@ -36,78 +22,81 @@
|
||||
"types": "./dist/cli.d.ts"
|
||||
}
|
||||
},
|
||||
"publishConfig": {
|
||||
"access": "public"
|
||||
"bin": {
|
||||
"mcporter": "dist/cli.js"
|
||||
},
|
||||
"scripts": {
|
||||
"mcporter": "tsx src/cli.ts",
|
||||
"mcp": "pnpm exec tsx src/cli.ts",
|
||||
"build": "tsgo -p tsconfig.build.json",
|
||||
"build": "tsc -p tsconfig.build.json",
|
||||
"build:bun": "bun scripts/build-bun.ts",
|
||||
"check": "pnpm format:check && pnpm lint:oxlint && pnpm typecheck",
|
||||
"format": "oxfmt .",
|
||||
"format:check": "oxfmt --check .",
|
||||
"check": "pnpm lint:biome && pnpm lint:oxlint && pnpm typecheck",
|
||||
"lint": "pnpm check",
|
||||
"lint:oxlint": "oxlint --type-aware --tsconfig tsconfig.json --report-unused-disable-directives --deny-warnings --max-warnings=0 --allow eslint/no-underscore-dangle",
|
||||
"lint:biome": "biome check",
|
||||
"lint:oxlint": "oxlint --type-aware --tsconfig tsconfig.json --max-warnings=0",
|
||||
"typecheck": "tsgo --project tsconfig.json --noEmit",
|
||||
"test": "cross-env MCPORTER_TEST_REPORTER=quiet pnpm test:verbose",
|
||||
"test:quiet": "cross-env MCPORTER_TEST_REPORTER=quiet pnpm test:verbose",
|
||||
"test:verbose": "pnpm build && node scripts/test-runner.js",
|
||||
"test:verbose": "node scripts/test-runner.js",
|
||||
"test:live": "MCP_LIVE_TESTS=1 vitest run tests/live",
|
||||
"clean": "rimraf dist",
|
||||
"dev": "tsgo -w -p tsconfig.build.json",
|
||||
"dev": "tsc -w -p tsconfig.build.json",
|
||||
"prepublishOnly": "pnpm check && pnpm test && pnpm build",
|
||||
"docs:list": "pnpm exec tsx scripts/docs-list.ts",
|
||||
"docs:site": "node scripts/build-docs-site.mjs",
|
||||
"generate:schema": "tsx scripts/generate-json-schema.ts",
|
||||
"mcporter:list": "pnpm exec tsx src/cli.ts list",
|
||||
"mcporter:call": "pnpm exec tsx src/cli.ts call",
|
||||
"check:changed": "pnpm run check",
|
||||
"test:changed": "pnpm run test",
|
||||
"crabbox:hydrate": "crabbox actions hydrate",
|
||||
"crabbox:run": "crabbox run",
|
||||
"crabbox:stop": "crabbox stop",
|
||||
"crabbox:warmup": "crabbox warmup"
|
||||
"mcporter:call": "pnpm exec tsx src/cli.ts call"
|
||||
},
|
||||
"dependencies": {
|
||||
"@iarna/toml": "^2.2.5",
|
||||
"@modelcontextprotocol/sdk": "^1.29.0",
|
||||
"acorn": "^8.17.0",
|
||||
"commander": "^15.0.0",
|
||||
"es-toolkit": "^1.48.1",
|
||||
"@modelcontextprotocol/sdk": "^1.24.3",
|
||||
"acorn": "^8.15.0",
|
||||
"commander": "^14.0.2",
|
||||
"es-toolkit": "^1.42.0",
|
||||
"jsonc-parser": "^3.3.1",
|
||||
"ora": "^9.4.1",
|
||||
"rolldown": "1.1.2",
|
||||
"zod": "^4.4.3"
|
||||
"ora": "^9.0.0",
|
||||
"rolldown": "1.0.0-beta.53",
|
||||
"zod": "^4.1.13"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/estree": "^1.0.9",
|
||||
"@biomejs/biome": "^2.3.8",
|
||||
"@types/estree": "^1.0.8",
|
||||
"@types/express": "^5.0.6",
|
||||
"@types/node": "^26.0.0",
|
||||
"@typescript/native-preview": "7.0.0-dev.20260623.1",
|
||||
"@vitest/coverage-v8": "^4.1.9",
|
||||
"bun-types": "^1.3.14",
|
||||
"@types/node": "^24.10.1",
|
||||
"@typescript/native-preview": "7.0.0-dev.20251205.1",
|
||||
"bun-types": "^1.3.3",
|
||||
"cross-env": "^10.1.0",
|
||||
"express": "^5.2.1",
|
||||
"oxfmt": "^0.56.0",
|
||||
"oxlint": "^1.71.0",
|
||||
"oxlint-tsgolint": "^0.23.0",
|
||||
"rimraf": "^6.1.3",
|
||||
"tsx": "^4.22.4",
|
||||
"typescript": "^6.0.3",
|
||||
"vite": "8.0.16",
|
||||
"vitest": "^4.1.9"
|
||||
"oxlint": "^1.31.0",
|
||||
"oxlint-tsgolint": "^0.8.3",
|
||||
"rimraf": "^6.1.2",
|
||||
"tsx": "^4.21.0",
|
||||
"typescript": "^5.9.3",
|
||||
"vitest": "^4.0.15"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=20.11.0"
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/steipete/mcporter"
|
||||
},
|
||||
"keywords": [
|
||||
"mcp",
|
||||
"model-context-protocol",
|
||||
"cli",
|
||||
"sweetistics"
|
||||
],
|
||||
"author": "Sweetistics",
|
||||
"license": "MIT",
|
||||
"publishConfig": {
|
||||
"access": "public"
|
||||
},
|
||||
"devEngines": {
|
||||
"runtime": [
|
||||
{
|
||||
"name": "node",
|
||||
"version": ">=24"
|
||||
"version": ">=20"
|
||||
}
|
||||
]
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=24"
|
||||
},
|
||||
"packageManager": "pnpm@10.33.2"
|
||||
}
|
||||
}
|
||||
|
||||
2865
pnpm-lock.yaml
generated
2865
pnpm-lock.yaml
generated
File diff suppressed because it is too large
Load Diff
@ -1,9 +1,2 @@
|
||||
onlyBuiltDependencies:
|
||||
- esbuild
|
||||
overrides:
|
||||
body-parser: 2.2.1
|
||||
esbuild: 0.28.1
|
||||
hono: 4.12.25
|
||||
ip-address: 10.1.1
|
||||
qs: 6.15.2
|
||||
vite: 8.0.16
|
||||
|
||||
@ -15,10 +15,6 @@ interface Options {
|
||||
readonly output?: string;
|
||||
}
|
||||
|
||||
interface PackageJson {
|
||||
readonly version?: string;
|
||||
}
|
||||
|
||||
// parseArgs walks CLI flags and produces normalized build options.
|
||||
function parseArgs(argv: string[]): Options {
|
||||
let target: string | undefined;
|
||||
@ -61,26 +57,10 @@ function requireValue(flag: string, value: string | undefined): string {
|
||||
return value;
|
||||
}
|
||||
|
||||
function readPackageVersion(projectRoot: string): string {
|
||||
const pkgPath = path.join(projectRoot, 'package.json');
|
||||
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as PackageJson;
|
||||
if (!pkg.version) {
|
||||
throw new Error(`package.json at ${pkgPath} is missing a version`);
|
||||
}
|
||||
return pkg.version;
|
||||
}
|
||||
|
||||
export function createCompiledEntrypoint(projectRoot: string, version: string): string {
|
||||
const cliPath = JSON.stringify(path.join(projectRoot, 'src', 'cli.ts'));
|
||||
const embeddedVersion = JSON.stringify(version);
|
||||
return [`process.env.MCPORTER_VERSION ??= ${embeddedVersion};`, `await import(${cliPath});`, ''].join('\n');
|
||||
}
|
||||
|
||||
// main orchestrates the Bun compile flow for the mcporter binary.
|
||||
async function main(): Promise<void> {
|
||||
const options = parseArgs(process.argv.slice(2));
|
||||
const projectRoot = path.join(fs.realpathSync(path.dirname(new URL(import.meta.url).pathname)), '..');
|
||||
const version = readPackageVersion(projectRoot);
|
||||
const distDir = path.join(projectRoot, 'dist-bun');
|
||||
if (!fs.existsSync(distDir)) {
|
||||
fs.mkdirSync(distDir, { recursive: true });
|
||||
@ -90,10 +70,7 @@ async function main(): Promise<void> {
|
||||
? path.resolve(options.output)
|
||||
: path.join(distDir, options.target ? `mcporter-${options.target}` : 'mcporter');
|
||||
|
||||
const entryPath = path.join(distDir, '.mcporter-build-entry.ts');
|
||||
fs.writeFileSync(entryPath, createCompiledEntrypoint(projectRoot, version), 'utf8');
|
||||
|
||||
const buildArgs = ['build', entryPath, '--compile', '--outfile', outputPath];
|
||||
const buildArgs = ['build', path.join(projectRoot, 'src/cli.ts'), '--compile', '--outfile', outputPath];
|
||||
|
||||
if (options.minify) {
|
||||
buildArgs.push('--minify');
|
||||
@ -107,24 +84,20 @@ async function main(): Promise<void> {
|
||||
|
||||
console.log(`Building mcporter binary → ${outputPath}`);
|
||||
const result = spawnSync('bun', buildArgs, { stdio: 'inherit' });
|
||||
if (result.status !== 0) {
|
||||
throw new Error(`bun build exited with status ${result.status ?? 'unknown'}`);
|
||||
}
|
||||
|
||||
if (process.platform !== 'win32') {
|
||||
fs.chmodSync(outputPath, 0o755);
|
||||
}
|
||||
|
||||
try {
|
||||
if (result.status !== 0) {
|
||||
throw new Error(`bun build exited with status ${result.status ?? 'unknown'}`);
|
||||
}
|
||||
|
||||
if (process.platform !== 'win32') {
|
||||
fs.chmodSync(outputPath, 0o755);
|
||||
}
|
||||
|
||||
try {
|
||||
const sizeBytes = fs.statSync(outputPath).size;
|
||||
const human = formatSize(sizeBytes);
|
||||
console.log(`✅ Built ${outputPath} (${human})`);
|
||||
} catch {
|
||||
console.log(`✅ Built ${outputPath}`);
|
||||
}
|
||||
} finally {
|
||||
fs.rmSync(entryPath, { force: true });
|
||||
const sizeBytes = fs.statSync(outputPath).size;
|
||||
const human = formatSize(sizeBytes);
|
||||
console.log(`✅ Built ${outputPath} (${human})`);
|
||||
} catch {
|
||||
console.log(`✅ Built ${outputPath}`);
|
||||
}
|
||||
}
|
||||
|
||||
@ -141,14 +114,12 @@ function formatSize(bytes: number): string {
|
||||
return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
|
||||
}
|
||||
|
||||
if (import.meta.main) {
|
||||
main().catch((error) => {
|
||||
console.error('mcporter Bun build failed.');
|
||||
if (error instanceof Error) {
|
||||
console.error(error.message);
|
||||
} else {
|
||||
console.error(error);
|
||||
}
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
main().catch((error) => {
|
||||
console.error('mcporter Bun build failed.');
|
||||
if (error instanceof Error) {
|
||||
console.error(error.message);
|
||||
} else {
|
||||
console.error(error);
|
||||
}
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
@ -1,702 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import { css, faviconSvg, js, preThemeScript, themeToggleHtml } from './docs-site-assets.mjs';
|
||||
|
||||
const root = process.cwd();
|
||||
const docsDir = path.join(root, 'docs');
|
||||
const outDir = path.join(root, 'dist', 'docs-site');
|
||||
const repoBase = 'https://github.com/openclaw/mcporter';
|
||||
const repoEditBase = `${repoBase}/edit/main/docs`;
|
||||
const cname = readCname();
|
||||
const siteBase = cname ? `https://${cname}` : '';
|
||||
|
||||
const productName = 'mcporter';
|
||||
const productTagline = 'MCP, made portable.';
|
||||
const productDescription =
|
||||
'TypeScript runtime, CLI, and code-generation toolkit for the Model Context Protocol — built so AI agents and developers can call any MCP server without boilerplate.';
|
||||
const brewInstall = 'npx mcporter list';
|
||||
|
||||
const sections = [
|
||||
['Start', ['index.md', 'install.md', 'quickstart.md', 'config.md']],
|
||||
['CLI', ['cli-reference.md', 'call-syntax.md', 'call-heuristic.md', 'shortcuts.md', 'logging.md']],
|
||||
['Generators', ['cli-generator.md', 'emit-ts.md', 'tool-calling.md']],
|
||||
['Connecting servers', ['adhoc.md', 'import.md', 'local.md', 'daemon.md', 'mcp.md']],
|
||||
['Agents', ['agent-skills.md', 'subagent.md']],
|
||||
[
|
||||
'Operations',
|
||||
[
|
||||
'RELEASE.md',
|
||||
'manual-testing.md',
|
||||
'livetests.md',
|
||||
'hang-debug.md',
|
||||
'windows.md',
|
||||
'tmux.md',
|
||||
'known-issues.md',
|
||||
'supabase-auth-issue.md',
|
||||
],
|
||||
],
|
||||
['Reference', ['spec.md', 'migration.md', 'pnpm-mcp-migration.md', 'refactor.md']],
|
||||
];
|
||||
|
||||
// Skip these from page generation (internal notes etc.). Pages excluded here are
|
||||
// neither rendered nor link-validated.
|
||||
const buildExcludes = [];
|
||||
|
||||
fs.rmSync(outDir, { recursive: true, force: true });
|
||||
fs.mkdirSync(outDir, { recursive: true });
|
||||
|
||||
const allPages = allMarkdown(docsDir).map((file) => {
|
||||
const rel = path.relative(docsDir, file).replaceAll(path.sep, '/');
|
||||
const raw = fs.readFileSync(file, 'utf8');
|
||||
const { frontmatter, body } = parseFrontmatter(raw);
|
||||
const cleaned = stripStrayDirectives(body);
|
||||
const title = frontmatter.title || firstHeading(cleaned) || titleize(path.basename(rel, '.md'));
|
||||
return { file, rel, title, outRel: outPath(rel, frontmatter), markdown: cleaned, frontmatter };
|
||||
});
|
||||
|
||||
const pages = allPages.filter((page) => !buildExcludes.some((re) => re.test(page.rel)));
|
||||
const pageMap = new Map(pages.map((page) => [page.rel, page]));
|
||||
const permalinkMap = new Map();
|
||||
for (const page of pages) {
|
||||
if (page.frontmatter.permalink) {
|
||||
permalinkMap.set(normalizePermalink(page.frontmatter.permalink), page);
|
||||
}
|
||||
}
|
||||
|
||||
const nav = sections
|
||||
.map(([name, rels]) => ({
|
||||
name,
|
||||
pages: rels.map((rel) => pageMap.get(rel)).filter(Boolean),
|
||||
}))
|
||||
.filter((section) => section.pages.length);
|
||||
|
||||
// Catch-all section: any docs/*.md we didn't slot into the curated nav goes
|
||||
// under "More". This keeps every doc reachable without forcing the author to
|
||||
// hand-edit `sections` for every new file.
|
||||
const navRels = new Set(nav.flatMap((s) => s.pages.map((p) => p.rel)));
|
||||
const extras = pages
|
||||
.filter((page) => !navRels.has(page.rel) && page.rel !== 'index.md')
|
||||
.toSorted((a, b) => a.title.localeCompare(b.title));
|
||||
if (extras.length) nav.push({ name: 'More', pages: extras });
|
||||
|
||||
const sectionByRel = new Map();
|
||||
for (const section of nav) for (const page of section.pages) sectionByRel.set(page.rel, section.name);
|
||||
const orderedPages = nav.flatMap((s) => s.pages);
|
||||
|
||||
for (const page of pages) {
|
||||
const html = markdownToHtml(page.markdown, page.rel);
|
||||
const toc = tocFromHtml(html);
|
||||
const idx = orderedPages.findIndex((p) => p.rel === page.rel);
|
||||
const prev = idx > 0 ? orderedPages[idx - 1] : null;
|
||||
const next = idx >= 0 && idx < orderedPages.length - 1 ? orderedPages[idx + 1] : null;
|
||||
const sectionName = sectionByRel.get(page.rel) || 'Reference';
|
||||
const pageOut = path.join(outDir, page.outRel);
|
||||
fs.mkdirSync(path.dirname(pageOut), { recursive: true });
|
||||
fs.writeFileSync(pageOut, layout({ page, html, toc, prev, next, sectionName }), 'utf8');
|
||||
}
|
||||
|
||||
fs.writeFileSync(path.join(outDir, 'favicon.svg'), faviconSvg(), 'utf8');
|
||||
copyStaticAsset('social-card.svg');
|
||||
copyStaticAsset('social-card.png');
|
||||
fs.writeFileSync(path.join(outDir, '.nojekyll'), '', 'utf8');
|
||||
if (cname) fs.writeFileSync(path.join(outDir, 'CNAME'), cname, 'utf8');
|
||||
validateLinks(outDir);
|
||||
fs.writeFileSync(path.join(outDir, 'llms.txt'), llmsTxt(), 'utf8');
|
||||
console.log(`built docs site: ${path.relative(root, outDir)}`);
|
||||
|
||||
function llmsTxt() {
|
||||
const origin = docsOrigin();
|
||||
const source = docsSourceUrl();
|
||||
const name = typeof productName !== 'undefined' ? productName : path.basename(root);
|
||||
const description = typeof productDescription !== 'undefined' ? productDescription : `${name} documentation index.`;
|
||||
const install = docsInstallHint();
|
||||
const docPages = docsLlmsPages().map((page) => `- ${page.title}: ${pageUrl(origin, page.outRel)}`);
|
||||
const lines = [`# ${name}`, '', description, '', 'Canonical documentation:', ...docPages];
|
||||
if (install) {
|
||||
lines.push('', 'Install:', `- ${install}`);
|
||||
}
|
||||
if (source) {
|
||||
lines.push('', `Source: ${source}`);
|
||||
}
|
||||
lines.push(
|
||||
'',
|
||||
'Guidance for agents:',
|
||||
'- Prefer the canonical documentation URLs above over README excerpts or package metadata.',
|
||||
'- Fetch only the pages needed for the current task; this is an index, not a full-site corpus.'
|
||||
);
|
||||
return `${lines.join('\n')}\n`;
|
||||
}
|
||||
|
||||
function docsLlmsPages() {
|
||||
const seen = new Set();
|
||||
const ordered = typeof orderedPages !== 'undefined' ? orderedPages : [];
|
||||
return [...ordered, ...pages].filter((page) => page.outRel && !seen.has(page.outRel) && seen.add(page.outRel));
|
||||
}
|
||||
|
||||
function docsOrigin() {
|
||||
const value =
|
||||
(typeof siteBase !== 'undefined' && siteBase) ||
|
||||
(typeof siteUrl !== 'undefined' && siteUrl) ||
|
||||
(typeof customDomain !== 'undefined' && customDomain ? `https://${customDomain}` : '');
|
||||
return value.replace(/\/$/, '');
|
||||
}
|
||||
|
||||
function docsSourceUrl() {
|
||||
if (typeof repoBase !== 'undefined') return repoBase;
|
||||
if (typeof repoUrl !== 'undefined') return repoUrl;
|
||||
if (typeof repoEditBase !== 'undefined') return repoEditBase.replace(/\/edit\/main\/docs\/?$/, '');
|
||||
return '';
|
||||
}
|
||||
|
||||
function docsInstallHint() {
|
||||
if (typeof installCommand !== 'undefined') return installCommand;
|
||||
if (typeof installLine !== 'undefined') return installLine;
|
||||
if (typeof installCmd !== 'undefined') return installCmd;
|
||||
if (typeof installSnippet !== 'undefined') return installSnippet;
|
||||
if (typeof brewInstall !== 'undefined') return brewInstall;
|
||||
return '';
|
||||
}
|
||||
|
||||
function pageUrl(origin, outRel) {
|
||||
const normalized =
|
||||
outRel === 'index.html'
|
||||
? ''
|
||||
: outRel.replace(/(?:^|\/)index\.html$/, (match) => (match === 'index.html' ? '' : '/'));
|
||||
if (!origin) return normalized || 'index.html';
|
||||
return normalized ? `${origin}/${normalized}` : `${origin}/`;
|
||||
}
|
||||
|
||||
function readCname() {
|
||||
for (const candidate of [path.join(docsDir, 'CNAME'), path.join(root, 'CNAME')]) {
|
||||
if (fs.existsSync(candidate)) return fs.readFileSync(candidate, 'utf8').trim();
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function copyStaticAsset(name) {
|
||||
const source = path.join(docsDir, name);
|
||||
if (fs.existsSync(source)) fs.copyFileSync(source, path.join(outDir, name));
|
||||
}
|
||||
|
||||
function parseFrontmatter(raw) {
|
||||
const match = raw.match(/^---\n([\s\S]*?)\n---\n?/);
|
||||
if (!match) return { frontmatter: {}, body: raw };
|
||||
const fm = {};
|
||||
for (const line of match[1].split('\n')) {
|
||||
const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
|
||||
if (!m) continue;
|
||||
let value = m[2];
|
||||
if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
|
||||
value = value.slice(1, -1);
|
||||
}
|
||||
fm[m[1]] = value;
|
||||
}
|
||||
return { frontmatter: fm, body: raw.slice(match[0].length) };
|
||||
}
|
||||
|
||||
function stripStrayDirectives(body) {
|
||||
return body
|
||||
.replace(/\r\n/g, '\n')
|
||||
.split('\n')
|
||||
.filter((line) => !/^\s*\{:\s*[^}]*\}\s*$/.test(line))
|
||||
.map((line) => line.replace(/\s*\{:\s*[^}]*\}\s*$/, ''))
|
||||
.join('\n');
|
||||
}
|
||||
|
||||
function normalizePermalink(value) {
|
||||
let v = value.trim();
|
||||
if (!v) return '/';
|
||||
if (!v.startsWith('/')) v = `/${v}`;
|
||||
if (v.length > 1 && v.endsWith('/')) v = v.slice(0, -1);
|
||||
return v;
|
||||
}
|
||||
|
||||
function allMarkdown(dir) {
|
||||
return fs
|
||||
.readdirSync(dir, { withFileTypes: true })
|
||||
.flatMap((entry) => {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) return allMarkdown(full);
|
||||
return entry.name.endsWith('.md') ? [full] : [];
|
||||
})
|
||||
.toSorted((a, b) => a.localeCompare(b));
|
||||
}
|
||||
|
||||
function outPath(rel, frontmatter = {}) {
|
||||
if (frontmatter.permalink) {
|
||||
const permalink = normalizePermalink(frontmatter.permalink);
|
||||
if (permalink === '/') return 'index.html';
|
||||
return `${permalink.slice(1)}/index.html`;
|
||||
}
|
||||
if (rel === 'index.md') return 'index.html';
|
||||
if (rel === 'README.md') return 'index.html';
|
||||
if (rel.endsWith('/README.md')) return rel.replace(/README\.md$/, 'index.html');
|
||||
return rel.replace(/\.md$/, '.html');
|
||||
}
|
||||
|
||||
function firstHeading(markdown) {
|
||||
return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim();
|
||||
}
|
||||
|
||||
function titleize(input) {
|
||||
return input.replaceAll('-', ' ').replace(/\b\w/g, (m) => m.toUpperCase());
|
||||
}
|
||||
|
||||
function markdownToHtml(markdown, currentRel) {
|
||||
const lines = markdown.replace(/\r\n/g, '\n').split('\n');
|
||||
const html = [];
|
||||
let paragraph = [];
|
||||
let list = null;
|
||||
let fence = null;
|
||||
let blockquote = [];
|
||||
|
||||
const flushParagraph = () => {
|
||||
if (!paragraph.length) return;
|
||||
html.push(`<p>${inline(paragraph.join(' '), currentRel)}</p>`);
|
||||
paragraph = [];
|
||||
};
|
||||
const closeList = () => {
|
||||
if (!list) return;
|
||||
html.push(`</${list}>`);
|
||||
list = null;
|
||||
};
|
||||
const flushBlockquote = () => {
|
||||
if (!blockquote.length) return;
|
||||
const inner = markdownToHtml(blockquote.join('\n'), currentRel);
|
||||
html.push(`<blockquote>${inner}</blockquote>`);
|
||||
blockquote = [];
|
||||
};
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
const fenceMatch = line.match(/^```([\w+-]+)?\s*$/);
|
||||
if (fenceMatch) {
|
||||
flushParagraph();
|
||||
closeList();
|
||||
flushBlockquote();
|
||||
if (fence) {
|
||||
html.push(
|
||||
`<pre><code class="language-${escapeAttr(fence.lang)}">${escapeHtml(fence.lines.join('\n'))}</code></pre>`
|
||||
);
|
||||
fence = null;
|
||||
} else {
|
||||
fence = { lang: fenceMatch[1] || 'text', lines: [] };
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (fence) {
|
||||
fence.lines.push(line);
|
||||
continue;
|
||||
}
|
||||
if (/^>\s?/.test(line)) {
|
||||
flushParagraph();
|
||||
closeList();
|
||||
blockquote.push(line.replace(/^>\s?/, ''));
|
||||
continue;
|
||||
}
|
||||
flushBlockquote();
|
||||
if (!line.trim()) {
|
||||
flushParagraph();
|
||||
closeList();
|
||||
continue;
|
||||
}
|
||||
if (/^\s*---+\s*$/.test(line)) {
|
||||
flushParagraph();
|
||||
closeList();
|
||||
html.push('<hr>');
|
||||
continue;
|
||||
}
|
||||
const heading = line.match(/^(#{1,4})\s+(.+)$/);
|
||||
if (heading) {
|
||||
flushParagraph();
|
||||
closeList();
|
||||
const level = heading[1].length;
|
||||
const text = heading[2].trim();
|
||||
const id = slug(text);
|
||||
const inner = inline(text, currentRel);
|
||||
if (level === 1) {
|
||||
html.push(`<h1 id="${id}">${inner}</h1>`);
|
||||
} else {
|
||||
html.push(
|
||||
`<h${level} id="${id}"><a class="anchor" href="#${id}" aria-label="Anchor link">#</a>${inner}</h${level}>`
|
||||
);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (
|
||||
line.trimStart().startsWith('|') &&
|
||||
line.includes('|', line.indexOf('|') + 1) &&
|
||||
isDivider(lines[i + 1] || '')
|
||||
) {
|
||||
flushParagraph();
|
||||
closeList();
|
||||
const header = splitRow(line);
|
||||
const aligns = splitRow(lines[i + 1]).map((cell) => {
|
||||
const left = cell.startsWith(':');
|
||||
const right = cell.endsWith(':');
|
||||
return right && left ? 'center' : right ? 'right' : left ? 'left' : '';
|
||||
});
|
||||
i += 1;
|
||||
const rows = [];
|
||||
while (i + 1 < lines.length && lines[i + 1].trimStart().startsWith('|')) {
|
||||
i += 1;
|
||||
rows.push(splitRow(lines[i]));
|
||||
}
|
||||
const th = header
|
||||
.map((c, idx) => `<th${aligns[idx] ? ` style="text-align:${aligns[idx]}"` : ''}>${inline(c, currentRel)}</th>`)
|
||||
.join('');
|
||||
const tb = rows
|
||||
.map(
|
||||
(r) =>
|
||||
`<tr>${r.map((c, idx) => `<td${aligns[idx] ? ` style="text-align:${aligns[idx]}"` : ''}>${inline(c, currentRel)}</td>`).join('')}</tr>`
|
||||
)
|
||||
.join('');
|
||||
html.push(`<table><thead><tr>${th}</tr></thead><tbody>${tb}</tbody></table>`);
|
||||
continue;
|
||||
}
|
||||
const bullet = line.match(/^\s*-\s+(.+)$/);
|
||||
const numbered = line.match(/^\s*\d+\.\s+(.+)$/);
|
||||
if (bullet || numbered) {
|
||||
flushParagraph();
|
||||
const tag = bullet ? 'ul' : 'ol';
|
||||
if (list && list !== tag) closeList();
|
||||
if (!list) {
|
||||
list = tag;
|
||||
html.push(`<${tag}>`);
|
||||
}
|
||||
html.push(`<li>${inline((bullet || numbered)[1], currentRel)}</li>`);
|
||||
continue;
|
||||
}
|
||||
paragraph.push(line.trim());
|
||||
}
|
||||
flushParagraph();
|
||||
closeList();
|
||||
flushBlockquote();
|
||||
return html.join('\n');
|
||||
}
|
||||
|
||||
function inline(text, currentRel) {
|
||||
const stash = [];
|
||||
let out = text.replace(/`([^`]+)`/g, (_, code) => {
|
||||
stash.push(`<code>${escapeHtml(code)}</code>`);
|
||||
return `\uE000${stash.length - 1}\uE000`;
|
||||
});
|
||||
out = escapeHtml(out)
|
||||
.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
|
||||
.replace(/(^|[^*])\*([^*\s][^*]*?)\*(?!\*)/g, '$1<em>$2</em>')
|
||||
.replace(/(^|[^_])_([^_\s][^_]*?)_(?!_)/g, '$1<em>$2</em>')
|
||||
.replace(
|
||||
/\[([^\]]+)\]\(([^)]+)\)/g,
|
||||
(_, label, href) => `<a href="${escapeAttr(rewriteHref(href, currentRel))}">${label}</a>`
|
||||
)
|
||||
.replace(/<(https?:\/\/[^\s<>]+)>/g, '<a href="$1">$1</a>');
|
||||
out = out.replace(/\\\|/g, '|');
|
||||
out = out.replace(/<br>/g, '<br>');
|
||||
return out.replace(/\uE000(\d+)\uE000/g, (_, i) => stash[Number(i)]);
|
||||
}
|
||||
|
||||
function splitRow(line) {
|
||||
let trimmed = line.trim();
|
||||
if (trimmed.startsWith('|')) trimmed = trimmed.slice(1);
|
||||
if (trimmed.endsWith('|') && !trimmed.endsWith('\\|')) trimmed = trimmed.slice(0, -1);
|
||||
const cells = [];
|
||||
let current = '';
|
||||
for (let idx = 0; idx < trimmed.length; idx++) {
|
||||
const char = trimmed[idx];
|
||||
if (char === '\\' && trimmed[idx + 1] === '|') {
|
||||
current += '\\|';
|
||||
idx += 1;
|
||||
continue;
|
||||
}
|
||||
if (char === '|') {
|
||||
cells.push(current.trim().replace(/\\\|/g, '|'));
|
||||
current = '';
|
||||
continue;
|
||||
}
|
||||
current += char;
|
||||
}
|
||||
cells.push(current.trim().replace(/\\\|/g, '|'));
|
||||
return cells;
|
||||
}
|
||||
|
||||
function isDivider(line) {
|
||||
return /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(line);
|
||||
}
|
||||
|
||||
function rewriteHref(href, currentRel) {
|
||||
if (/^(https?:|mailto:|tel:|#)/.test(href)) return href;
|
||||
const [raw, hash = ''] = href.split('#');
|
||||
if (!raw) return hash ? `#${hash}` : '';
|
||||
if (raw.startsWith('/')) {
|
||||
const target = permalinkMap.get(normalizePermalink(raw));
|
||||
if (target) {
|
||||
const currentOut = pageMap.get(currentRel)?.outRel || outPath(currentRel);
|
||||
const out = hrefToOutRel(target.outRel, currentOut);
|
||||
return hash ? `${out}#${hash}` : out;
|
||||
}
|
||||
return href;
|
||||
}
|
||||
if (!raw.endsWith('.md')) return href;
|
||||
const from = path.posix.dirname(currentRel);
|
||||
const target = path.posix.normalize(path.posix.join(from, raw));
|
||||
let rewritten = pageMap.get(target)?.outRel || outPath(target);
|
||||
const currentOut = pageMap.get(currentRel)?.outRel || outPath(currentRel);
|
||||
rewritten = hrefToOutRel(rewritten, currentOut);
|
||||
return `${rewritten}${hash ? `#${hash}` : ''}`;
|
||||
}
|
||||
|
||||
function tocFromHtml(html) {
|
||||
const items = [];
|
||||
const re = /<h([23]) id="([^"]+)">([\s\S]*?)<\/h[23]>/g;
|
||||
let m;
|
||||
while ((m = re.exec(html))) {
|
||||
const text = m[3]
|
||||
.replace(/<a class="anchor"[^>]*>.*?<\/a>/, '')
|
||||
.replace(/<[^>]+>/g, '')
|
||||
.trim();
|
||||
items.push({ level: Number(m[1]), id: m[2], text });
|
||||
}
|
||||
if (items.length < 2) return '';
|
||||
return `<nav class="toc" aria-label="On this page"><h2>On this page</h2>${items
|
||||
.map((i) => `<a class="toc-l${i.level}" href="#${i.id}">${escapeHtml(i.text)}</a>`)
|
||||
.join('')}</nav>`;
|
||||
}
|
||||
|
||||
function isHomePage(page) {
|
||||
if (page.frontmatter.permalink && normalizePermalink(page.frontmatter.permalink) === '/') return true;
|
||||
return page.rel === 'index.md' || page.rel === 'README.md';
|
||||
}
|
||||
|
||||
function homeHero(page) {
|
||||
const description = page.frontmatter.description || productDescription;
|
||||
const installRel = pageMap.get('install.md')?.outRel
|
||||
? hrefToOutRel(pageMap.get('install.md').outRel, page.outRel)
|
||||
: 'install.html';
|
||||
const quickstartRel = pageMap.get('quickstart.md')?.outRel
|
||||
? hrefToOutRel(pageMap.get('quickstart.md').outRel, page.outRel)
|
||||
: 'quickstart.html';
|
||||
const features = ['TypeScript runtime', 'CLI', 'Generated CLIs', 'Typed clients', 'OAuth', 'stdio + HTTP + SSE'];
|
||||
return `<header class="home-hero">
|
||||
<p class="eyebrow">Model Context Protocol · Toolkit</p>
|
||||
<h1>${escapeHtml(productTagline)}</h1>
|
||||
<p class="lede">${escapeHtml(description)}</p>
|
||||
<div class="home-cta">
|
||||
<a class="btn btn-primary" href="${quickstartRel}">Quickstart</a>
|
||||
<a class="btn btn-ghost" href="${repoBase}" rel="noopener">GitHub</a>
|
||||
<div class="home-install" aria-label="Try with npx">
|
||||
<span class="prompt" aria-hidden="true">$</span>
|
||||
<code>${escapeHtml(brewInstall)}</code>
|
||||
</div>
|
||||
</div>
|
||||
<div class="home-services" aria-label="Capabilities">
|
||||
${features.map((s) => `<span>${escapeHtml(s)}</span>`).join('')}
|
||||
</div>
|
||||
<p class="muted"><a href="${installRel}">Install options →</a></p>
|
||||
</header>`;
|
||||
}
|
||||
|
||||
function standardHero(page, sectionName, editUrl) {
|
||||
return `<header class="hero">
|
||||
<div class="hero-text">
|
||||
<p class="eyebrow">${escapeHtml(sectionName)}</p>
|
||||
<h1>${escapeHtml(page.title)}</h1>
|
||||
</div>
|
||||
<div class="hero-meta">
|
||||
<a class="repo" href="${repoBase}" rel="noopener">GitHub</a>
|
||||
<a class="edit" href="${escapeAttr(editUrl)}" rel="noopener">Edit page</a>
|
||||
</div>
|
||||
</header>`;
|
||||
}
|
||||
|
||||
function layout({ page, html, toc, prev, next, sectionName }) {
|
||||
const depth = page.outRel.split('/').length - 1;
|
||||
const rootPrefix = depth ? '../'.repeat(depth) : '';
|
||||
const editUrl = `${repoEditBase}/${page.rel}`;
|
||||
const home = isHomePage(page);
|
||||
const prevNext = !home && (prev || next) ? pageNavHtml(prev, next, page.outRel) : '';
|
||||
const heroBlock = home ? homeHero(page) : standardHero(page, sectionName, editUrl);
|
||||
const articleClass = home ? 'doc doc-home' : 'doc';
|
||||
const tocBlock = home ? '' : toc;
|
||||
const titleSuffix = home ? `${productName} — ${productTagline}` : `${page.title} — ${productName}`;
|
||||
const description =
|
||||
page.frontmatter.description || (home ? productDescription : `${page.title} — ${productName} documentation.`);
|
||||
const canonicalUrl = pageCanonicalUrl(page);
|
||||
const socialImage = siteBase ? `${siteBase}/social-card.png` : `${rootPrefix}social-card.png`;
|
||||
const socialMeta = [
|
||||
['link', 'rel', 'canonical', 'href', canonicalUrl],
|
||||
['meta', 'property', 'og:type', 'content', 'website'],
|
||||
['meta', 'property', 'og:site_name', 'content', productName],
|
||||
['meta', 'property', 'og:title', 'content', titleSuffix],
|
||||
['meta', 'property', 'og:description', 'content', description],
|
||||
['meta', 'property', 'og:url', 'content', canonicalUrl],
|
||||
['meta', 'property', 'og:image', 'content', socialImage],
|
||||
['meta', 'property', 'og:image:width', 'content', '1200'],
|
||||
['meta', 'property', 'og:image:height', 'content', '630'],
|
||||
['meta', 'name', 'twitter:card', 'content', 'summary_large_image'],
|
||||
['meta', 'name', 'twitter:title', 'content', titleSuffix],
|
||||
['meta', 'name', 'twitter:description', 'content', description],
|
||||
['meta', 'name', 'twitter:image', 'content', socialImage],
|
||||
]
|
||||
.map(tagHtml)
|
||||
.join('\n ');
|
||||
return `<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>${escapeHtml(titleSuffix)}</title>
|
||||
<meta name="description" content="${escapeAttr(description)}">
|
||||
${socialMeta}
|
||||
<link rel="icon" href="${rootPrefix}favicon.svg" type="image/svg+xml">
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
|
||||
<script>${preThemeScript()}</script>
|
||||
<style>${css()}</style>
|
||||
</head>
|
||||
<body${home ? ' class="home"' : ''}>
|
||||
<button class="nav-toggle" type="button" aria-label="Toggle navigation" aria-expanded="false">
|
||||
<span aria-hidden="true"></span><span aria-hidden="true"></span><span aria-hidden="true"></span>
|
||||
</button>
|
||||
<div class="shell">
|
||||
<aside class="sidebar">
|
||||
<div class="sidebar-head">
|
||||
<a class="brand" href="${hrefToOutRel('index.html', page.outRel)}" aria-label="${productName} docs home">
|
||||
<span class="mark" aria-hidden="true"></span>
|
||||
<span><strong>${escapeHtml(productName)}</strong><small>MCP toolkit docs</small></span>
|
||||
</a>
|
||||
${themeToggleHtml()}
|
||||
</div>
|
||||
<label class="search"><span>Search</span><input id="doc-search" type="search" placeholder="call, generate-cli, oauth"></label>
|
||||
<nav>${navHtml(page)}</nav>
|
||||
</aside>
|
||||
<main>
|
||||
${heroBlock}
|
||||
<div class="doc-grid${home ? ' doc-grid-home' : ''}">
|
||||
<article class="${articleClass}">${html}${prevNext}</article>
|
||||
${tocBlock}
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
<script>${js()}</script>
|
||||
</body>
|
||||
</html>`;
|
||||
}
|
||||
|
||||
function pageCanonicalUrl(page) {
|
||||
if (!siteBase) return page.outRel;
|
||||
if (page.outRel === 'index.html') return `${siteBase}/`;
|
||||
const rel = page.outRel.endsWith('/index.html') ? page.outRel.slice(0, -'index.html'.length) : page.outRel;
|
||||
return `${siteBase}/${rel}`;
|
||||
}
|
||||
|
||||
function tagHtml([tag, k1, v1, k2, v2]) {
|
||||
return tag === 'link'
|
||||
? `<link ${k1}="${v1}" ${k2}="${escapeAttr(v2)}">`
|
||||
: `<meta ${k1}="${v1}" ${k2}="${escapeAttr(v2)}">`;
|
||||
}
|
||||
|
||||
function pageNavHtml(prev, next, currentOutRel) {
|
||||
const cell = (page, dir) => {
|
||||
if (!page) return '';
|
||||
return `<a class="page-nav-${dir}" href="${hrefToOutRel(page.outRel, currentOutRel)}"><small>${dir === 'prev' ? 'Previous' : 'Next'}</small><span>${escapeHtml(page.title)}</span></a>`;
|
||||
};
|
||||
return `<nav class="page-nav" aria-label="Pager">${cell(prev, 'prev')}${cell(next, 'next')}</nav>`;
|
||||
}
|
||||
|
||||
function navHtml(currentPage) {
|
||||
return nav
|
||||
.map(
|
||||
(section) =>
|
||||
`<section><h2>${escapeHtml(section.name)}</h2>${section.pages
|
||||
.map((page) => {
|
||||
const href = hrefToOutRel(page.outRel, currentPage.outRel);
|
||||
const active = page.rel === currentPage.rel ? ' active' : '';
|
||||
return `<a class="nav-link${active}" href="${href}">${escapeHtml(navTitle(page))}</a>`;
|
||||
})
|
||||
.join('')}</section>`
|
||||
)
|
||||
.join('');
|
||||
}
|
||||
|
||||
function navTitle(page) {
|
||||
if (page.rel === 'index.md') return 'Overview';
|
||||
return page.title.replace(/^`mcporter\s*/, '').replace(/`$/, '');
|
||||
}
|
||||
|
||||
function hrefToOutRel(targetOutRel, currentOutRel) {
|
||||
const currentDir = path.posix.dirname(currentOutRel);
|
||||
if (targetOutRel.endsWith('/index.html')) {
|
||||
const targetDir = targetOutRel.slice(0, -'index.html'.length);
|
||||
const rel = path.posix.relative(currentDir, targetDir || '.') || '.';
|
||||
return rel.endsWith('/') ? rel : `${rel}/`;
|
||||
}
|
||||
if (targetOutRel === 'index.html') {
|
||||
const rel = path.posix.relative(currentDir, '.') || '.';
|
||||
return rel.endsWith('/') ? rel : `${rel}/`;
|
||||
}
|
||||
return path.posix.relative(currentDir, targetOutRel) || path.posix.basename(targetOutRel);
|
||||
}
|
||||
|
||||
function slug(text) {
|
||||
return text
|
||||
.toLowerCase()
|
||||
.replace(/`/g, '')
|
||||
.replace(/[^a-z0-9]+/g, '-')
|
||||
.replace(/^-|-$/g, '');
|
||||
}
|
||||
|
||||
function escapeHtml(value) {
|
||||
return String(value ?? '').replace(
|
||||
/[&<>"']/g,
|
||||
(char) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[char]
|
||||
);
|
||||
}
|
||||
|
||||
function escapeAttr(value) {
|
||||
return escapeHtml(value);
|
||||
}
|
||||
|
||||
function validateLinks(outputDir) {
|
||||
const failures = [];
|
||||
const placeholderHrefs = /^(url|path|file|dir|name)$/i;
|
||||
for (const file of allHtml(outputDir)) {
|
||||
const html = fs.readFileSync(file, 'utf8');
|
||||
for (const match of html.matchAll(/href="([^"]+)"/g)) {
|
||||
const href = match[1];
|
||||
if (/^(#|https?:|mailto:|tel:|javascript:)/.test(href)) continue;
|
||||
if (placeholderHrefs.test(href)) continue;
|
||||
const [rawPath, anchor = ''] = href.split('#');
|
||||
const targetPath = rawPath ? path.resolve(path.dirname(file), rawPath) : file;
|
||||
const target =
|
||||
fs.existsSync(targetPath) && fs.statSync(targetPath).isDirectory()
|
||||
? path.join(targetPath, 'index.html')
|
||||
: targetPath;
|
||||
if (!fs.existsSync(target)) {
|
||||
failures.push(`${path.relative(outputDir, file)}: ${href} -> missing ${path.relative(outputDir, target)}`);
|
||||
continue;
|
||||
}
|
||||
if (anchor) {
|
||||
const targetHtml = fs.readFileSync(target, 'utf8');
|
||||
if (!targetHtml.includes(`id="${anchor}"`) && !targetHtml.includes(`name="${anchor}"`)) {
|
||||
failures.push(`${path.relative(outputDir, file)}: ${href} -> missing anchor`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if (failures.length) {
|
||||
throw new Error(`broken docs links:\n${failures.join('\n')}`);
|
||||
}
|
||||
}
|
||||
|
||||
function allHtml(dir) {
|
||||
return fs
|
||||
.readdirSync(dir, { withFileTypes: true })
|
||||
.flatMap((entry) => {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) return allHtml(full);
|
||||
return entry.name.endsWith('.html') ? [full] : [];
|
||||
})
|
||||
.toSorted((a, b) => a.localeCompare(b));
|
||||
}
|
||||
@ -28,7 +28,7 @@ function walkMarkdownFiles(dir: string, base: string = dir): string[] {
|
||||
files.push(relative(base, fullPath));
|
||||
}
|
||||
}
|
||||
return files.toSorted((a, b) => a.localeCompare(b));
|
||||
return files.sort((a, b) => a.localeCompare(b));
|
||||
}
|
||||
|
||||
function extractMetadata(fullPath: string): {
|
||||
|
||||
@ -1,286 +0,0 @@
|
||||
export function css() {
|
||||
return `
|
||||
:root{
|
||||
--ink:#0d1116;
|
||||
--text:#1f2530;
|
||||
--muted:#5f6b7a;
|
||||
--subtle:#94a0b1;
|
||||
--bg:#f7f9fc;
|
||||
--paper:#ffffff;
|
||||
--accent:#7c3aed;
|
||||
--accent-soft:rgba(124,58,237,.10);
|
||||
--accent-strong:#5b21b6;
|
||||
--brand-cyan:#06b6d4;
|
||||
--brand-pink:#ec4899;
|
||||
--brand-amber:#f59e0b;
|
||||
--brand-emerald:#10b981;
|
||||
--line:#e3e7ef;
|
||||
--line-soft:#eef1f6;
|
||||
--code-bg:#0b0d12;
|
||||
--code-fg:#e6edf3;
|
||||
--code-inline-fg:#1c2128;
|
||||
--pill-border:#dbe2eb;
|
||||
--shadow-card:0 4px 14px rgba(15,17,21,.08);
|
||||
--scrollbar:#cbd5e1;
|
||||
}
|
||||
:root[data-theme="dark"]{
|
||||
--ink:#f3f5f9;
|
||||
--text:#cbd2dc;
|
||||
--muted:#8d96a4;
|
||||
--subtle:#5d6371;
|
||||
--bg:#0a0c12;
|
||||
--paper:#13161f;
|
||||
--accent:#a78bfa;
|
||||
--accent-soft:rgba(167,139,250,.16);
|
||||
--accent-strong:#c4b5fd;
|
||||
--line:#262a36;
|
||||
--line-soft:#1d2029;
|
||||
--code-bg:#06080d;
|
||||
--code-fg:#e6edf3;
|
||||
--code-inline-fg:#e6edf3;
|
||||
--pill-border:#2a2f3c;
|
||||
--shadow-card:0 4px 18px rgba(0,0,0,.45);
|
||||
--scrollbar:#3a4154;
|
||||
}
|
||||
:root{color-scheme:light}
|
||||
:root[data-theme="dark"]{color-scheme:dark}
|
||||
*{box-sizing:border-box}
|
||||
html{scroll-behavior:smooth;scroll-padding-top:24px}
|
||||
body{margin:0;background:var(--bg);color:var(--text);font-family:"Inter",ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif;line-height:1.65;overflow-x:hidden;-webkit-font-smoothing:antialiased;font-feature-settings:"cv02","cv03","cv04","cv11";transition:background-color .18s,color .18s}
|
||||
::selection{background:var(--accent);color:#fff}
|
||||
a{color:var(--accent);text-decoration:none;transition:color .12s}
|
||||
a:hover{text-decoration:underline;text-underline-offset:.2em}
|
||||
.shell{display:grid;grid-template-columns:268px minmax(0,1fr);min-height:100vh}
|
||||
.sidebar{position:sticky;top:0;height:100vh;overflow:auto;padding:24px 22px;background:var(--paper);border-right:1px solid var(--line);scrollbar-width:thin;scrollbar-color:var(--line) transparent;transition:background-color .18s,border-color .18s}
|
||||
.sidebar::-webkit-scrollbar{width:6px}
|
||||
.sidebar::-webkit-scrollbar-thumb{background:var(--line);border-radius:6px}
|
||||
.sidebar-head{display:flex;align-items:center;gap:10px;margin-bottom:24px}
|
||||
.brand{display:flex;align-items:center;gap:11px;color:var(--ink);text-decoration:none;flex:1;min-width:0}
|
||||
.brand:hover{text-decoration:none}
|
||||
.brand .mark{position:relative;flex:0 0 32px;width:32px;height:32px;border-radius:8px;background:linear-gradient(135deg,var(--accent) 0%,var(--brand-cyan) 100%);box-shadow:0 1px 2px rgba(15,17,21,.18),inset 0 1px 0 rgba(255,255,255,.18)}
|
||||
.brand .mark::before,.brand .mark::after{content:"";position:absolute;background:#fff;border-radius:2px}
|
||||
.brand .mark::before{left:7px;right:7px;top:9px;height:3px;opacity:.95}
|
||||
.brand .mark::after{left:13px;right:13px;top:14px;bottom:7px;border-radius:1px;opacity:.85}
|
||||
.brand strong{display:block;font-size:1.05rem;line-height:1.1;font-weight:600;letter-spacing:0;color:var(--ink)}
|
||||
.brand small{display:block;color:var(--muted);font-size:.74rem;margin-top:3px;font-weight:400}
|
||||
.theme-toggle{display:inline-flex;align-items:center;justify-content:center;flex:0 0 auto;width:34px;height:34px;border-radius:8px;border:1px solid var(--line);background:var(--paper);color:var(--muted);cursor:pointer;padding:0;transition:border-color .15s,color .15s,background-color .15s,transform .12s}
|
||||
.theme-toggle:hover{border-color:var(--ink);color:var(--ink)}
|
||||
.theme-toggle:active{transform:scale(.94)}
|
||||
.theme-toggle svg{width:16px;height:16px;display:block}
|
||||
.theme-icon-sun{display:none}
|
||||
:root[data-theme="dark"] .theme-icon-sun{display:block}
|
||||
:root[data-theme="dark"] .theme-icon-moon{display:none}
|
||||
.search{display:block;margin:0 0 22px}
|
||||
.search span{display:block;color:var(--muted);font-size:.7rem;font-weight:600;text-transform:uppercase;letter-spacing:0;margin-bottom:7px}
|
||||
.search input{width:100%;border:1px solid var(--line);background:var(--paper);border-radius:8px;padding:9px 12px;font:inherit;font-size:.9rem;color:var(--text);outline:none;transition:border-color .15s,box-shadow .15s,background-color .18s}
|
||||
.search input:focus{border-color:var(--accent);box-shadow:0 0 0 3px var(--accent-soft)}
|
||||
nav section{margin:0 0 18px}
|
||||
nav h2{font-size:.68rem;color:var(--muted);text-transform:uppercase;letter-spacing:0;margin:0 0 6px;font-weight:600}
|
||||
.nav-link{display:block;color:var(--text);text-decoration:none;border-radius:6px;padding:5px 10px;margin:1px 0;font-size:.9rem;line-height:1.4;transition:background .12s,color .12s}
|
||||
.nav-link:hover{background:var(--line-soft);color:var(--ink);text-decoration:none}
|
||||
.nav-link.active{background:var(--accent-soft);color:var(--accent);font-weight:600}
|
||||
main{min-width:0;padding:32px clamp(20px,4.5vw,56px) 80px;max-width:1180px;margin:0 auto;width:100%}
|
||||
.hero{display:flex;align-items:flex-end;justify-content:space-between;gap:22px;border-bottom:1px solid var(--line);padding:8px 0 22px;margin-bottom:8px;flex-wrap:wrap}
|
||||
.hero-text{min-width:0;flex:1 1 320px}
|
||||
.eyebrow{margin:0 0 8px;color:var(--muted);font-weight:600;text-transform:uppercase;letter-spacing:0;font-size:.7rem}
|
||||
.hero h1{font-size:2.25rem;line-height:1.1;letter-spacing:0;margin:0;font-weight:700;color:var(--ink)}
|
||||
.hero-meta{display:flex;gap:8px;flex:0 0 auto;flex-wrap:wrap}
|
||||
.repo,.edit,.btn-ghost{border:1px solid var(--line);color:var(--text);text-decoration:none;border-radius:7px;padding:6px 11px;font-weight:500;font-size:.83rem;background:var(--paper);transition:border-color .15s,color .15s,background .15s}
|
||||
.repo:hover,.edit:hover,.btn-ghost:hover{border-color:var(--ink);color:var(--ink);text-decoration:none}
|
||||
.edit{color:var(--muted)}
|
||||
.home-hero{padding:14px 0 28px;margin-bottom:8px;border-bottom:1px solid var(--line)}
|
||||
.home-hero h1{font-size:3.25rem;line-height:1.04;letter-spacing:0;margin:0 0 .35em;font-weight:700;color:var(--ink);background:linear-gradient(120deg,var(--accent) 0%,var(--brand-cyan) 60%,var(--brand-pink) 100%);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent}
|
||||
.home-hero .lede{font-size:1.18rem;line-height:1.55;color:var(--text);margin:0 0 1.2em;max-width:60ch}
|
||||
.home-cta{display:flex;flex-wrap:wrap;gap:10px;align-items:center;margin:0 0 18px}
|
||||
.home-cta .btn{display:inline-flex;align-items:center;gap:7px;border-radius:8px;padding:10px 16px;font-weight:600;font-size:.92rem;text-decoration:none;transition:background .15s,border-color .15s,color .15s,transform .12s}
|
||||
.home-cta .btn-primary{background:var(--accent);color:#fff;border:1px solid var(--accent)}
|
||||
.home-cta .btn-primary:hover{background:var(--accent-strong);border-color:var(--accent-strong);text-decoration:none;color:#fff}
|
||||
.home-cta .btn-ghost{padding:10px 16px}
|
||||
.home-install{display:flex;align-items:center;gap:12px;background:var(--code-bg);color:var(--code-fg);border-radius:8px;padding:10px 10px 10px 16px;font:500 .9rem/1.2 "JetBrains Mono","SF Mono",ui-monospace,monospace;max-width:32em;border:1px solid #1f2937}
|
||||
.home-install .prompt{color:#64748b;user-select:none;flex:0 0 auto}
|
||||
.home-install code{flex:1;background:transparent;border:0;color:var(--code-fg);font:inherit;padding:0;white-space:pre;overflow:hidden;text-overflow:ellipsis}
|
||||
.home-install .copy{flex:0 0 auto;background:rgba(255,255,255,.08);color:var(--code-fg);border:1px solid rgba(255,255,255,.16);border-radius:6px;padding:5px 11px;font:500 .72rem/1 "Inter",sans-serif;cursor:pointer;transition:background .15s,border-color .15s}
|
||||
.home-install .copy:hover{background:rgba(255,255,255,.16)}
|
||||
.home-install .copy.copied{background:var(--accent);border-color:var(--accent)}
|
||||
.home-services{display:flex;flex-wrap:wrap;gap:6px;margin:6px 0 18px}
|
||||
.home-services span{display:inline-block;padding:3px 9px;border:1px solid var(--line);border-radius:999px;font-size:.78rem;color:var(--muted);background:var(--paper)}
|
||||
.doc-grid{display:grid;grid-template-columns:minmax(0,1fr);gap:48px;margin-top:24px}
|
||||
.doc-grid-home{margin-top:8px}
|
||||
@media(min-width:1180px){.doc-grid{grid-template-columns:minmax(0,72ch) 200px;justify-content:start}.doc-grid-home{grid-template-columns:minmax(0,76ch);justify-content:start}}
|
||||
.doc{min-width:0;max-width:72ch;overflow-wrap:break-word}
|
||||
.doc-home{max-width:76ch}
|
||||
.doc h1{font-size:2.6rem;line-height:1.08;letter-spacing:0;margin:0 0 .4em;font-weight:700;color:var(--ink)}
|
||||
body:not(.home) .doc>h1:first-child{display:none}
|
||||
.doc h2{font-size:1.45rem;line-height:1.2;margin:2em 0 .5em;font-weight:600;letter-spacing:0;color:var(--ink);position:relative}
|
||||
.doc h3{font-size:1.1rem;margin:1.7em 0 .35em;position:relative;font-weight:600;color:var(--ink);letter-spacing:0}
|
||||
.doc h4{font-size:.98rem;margin:1.4em 0 .25em;color:var(--ink);position:relative;font-weight:600}
|
||||
.doc h2:first-child,.doc h3:first-child,.doc h4:first-child{margin-top:.2em}
|
||||
.doc :is(h2,h3,h4) .anchor{position:absolute;left:-1.05em;top:0;color:var(--subtle);opacity:0;text-decoration:none;font-weight:400;padding-right:.3em;transition:opacity .12s,color .12s}
|
||||
.doc :is(h2,h3,h4):hover .anchor{opacity:.7}
|
||||
.doc :is(h2,h3,h4) .anchor:hover{opacity:1;color:var(--accent);text-decoration:none}
|
||||
.doc p{margin:0 0 1.05em}
|
||||
.doc ul,.doc ol{padding-left:1.3rem;margin:0 0 1.15em}
|
||||
.doc li{margin:.25em 0}
|
||||
.doc li>p{margin:0 0 .4em}
|
||||
.doc strong{font-weight:600;color:var(--ink)}
|
||||
.doc em{font-style:italic}
|
||||
.doc code{font-family:"JetBrains Mono","SF Mono",ui-monospace,monospace;font-size:.84em;background:var(--line-soft);border:1px solid var(--line);border-radius:5px;padding:.08em .35em;color:var(--code-inline-fg)}
|
||||
.doc pre{position:relative;overflow:auto;background:var(--code-bg);color:var(--code-fg);border-radius:8px;padding:14px 18px;margin:1.3em 0;font-size:.85em;line-height:1.6;scrollbar-width:thin;scrollbar-color:#334155 transparent;border:1px solid #1f2937}
|
||||
.doc pre::-webkit-scrollbar{height:8px;width:8px}
|
||||
.doc pre::-webkit-scrollbar-thumb{background:#334155;border-radius:8px}
|
||||
.doc pre code{display:block;background:transparent;border:0;color:inherit;padding:0;font-size:1em;white-space:pre}
|
||||
.doc pre code .tok-comment{color:#6b7280;font-style:italic}
|
||||
.doc pre code .tok-cmd{color:#67e8f9;font-weight:600}
|
||||
.doc pre code .tok-flag{color:#c4b5fd}
|
||||
.doc pre code .tok-string{color:#fde68a}
|
||||
.doc pre code .tok-key{color:#93c5fd}
|
||||
.doc pre code .tok-value{color:#86efac}
|
||||
.doc pre .copy{position:absolute;top:8px;right:8px;background:rgba(255,255,255,.06);color:var(--code-fg);border:1px solid rgba(255,255,255,.16);border-radius:6px;padding:3px 9px;font:500 .7rem/1 "Inter",sans-serif;cursor:pointer;opacity:0;transition:opacity .15s,background .15s,border-color .15s}
|
||||
.doc pre:hover .copy,.doc pre .copy:focus{opacity:1}
|
||||
.doc pre .copy:hover{background:rgba(255,255,255,.12)}
|
||||
.doc pre .copy.copied{background:var(--accent);border-color:var(--accent);opacity:1}
|
||||
.doc blockquote{margin:1.4em 0;padding:10px 16px;border-left:3px solid var(--accent);background:var(--accent-soft);border-radius:0 8px 8px 0;color:var(--text)}
|
||||
.doc blockquote p:last-child{margin-bottom:0}
|
||||
.doc table{width:100%;border-collapse:collapse;margin:1.2em 0;font-size:.92em}
|
||||
.doc th,.doc td{border-bottom:1px solid var(--line);padding:9px 10px;text-align:left;vertical-align:top}
|
||||
.doc th{font-weight:600;color:var(--ink);background:var(--line-soft);border-bottom:1px solid var(--line)}
|
||||
.doc hr{border:0;border-top:1px solid var(--line);margin:2.2em 0}
|
||||
.toc{position:sticky;top:24px;align-self:start;font-size:.84rem;padding-left:14px;border-left:1px solid var(--line);max-height:calc(100vh - 48px);overflow:auto;scrollbar-width:thin;scrollbar-color:var(--line) transparent}
|
||||
.toc::-webkit-scrollbar{width:5px}
|
||||
.toc::-webkit-scrollbar-thumb{background:var(--line);border-radius:5px}
|
||||
.toc h2{font-size:.66rem;color:var(--muted);text-transform:uppercase;letter-spacing:0;margin:0 0 10px;font-weight:600}
|
||||
.toc a{display:block;color:var(--muted);text-decoration:none;padding:4px 0 4px 10px;line-height:1.35;border-left:2px solid transparent;margin-left:-12px;transition:color .12s,border-color .12s}
|
||||
.toc a:hover{color:var(--ink);text-decoration:none}
|
||||
.toc a.active{color:var(--accent);border-left-color:var(--accent);font-weight:500}
|
||||
.toc-l3{padding-left:22px!important;font-size:.94em}
|
||||
@media(max-width:1179px){.toc{display:none}}
|
||||
.page-nav{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:48px;border-top:1px solid var(--line);padding-top:20px}
|
||||
.page-nav>a{display:block;border:1px solid var(--line);background:var(--paper);border-radius:9px;padding:13px 16px;text-decoration:none;color:var(--text);transition:border-color .15s,transform .15s,box-shadow .15s,background-color .18s}
|
||||
.page-nav>a:hover{border-color:var(--accent);text-decoration:none;color:var(--ink)}
|
||||
.page-nav small{display:block;color:var(--muted);font-size:.7rem;text-transform:uppercase;letter-spacing:0;margin-bottom:5px;font-weight:600}
|
||||
.page-nav span{display:block;font-weight:600;line-height:1.3;color:var(--ink)}
|
||||
.page-nav-prev{text-align:left}
|
||||
.page-nav-next{text-align:right;grid-column:2}
|
||||
.page-nav-prev:only-child{grid-column:1}
|
||||
.nav-toggle{display:none;position:fixed;top:14px;right:14px;top:calc(14px + env(safe-area-inset-top, 0px));right:calc(14px + env(safe-area-inset-right, 0px));z-index:20;width:40px;height:40px;border-radius:9px;background:var(--paper);border:1px solid var(--line);color:var(--ink);cursor:pointer;padding:10px 9px;flex-direction:column;align-items:stretch;justify-content:space-between;box-shadow:var(--shadow-card)}
|
||||
.nav-toggle span{display:block;width:100%;height:2px;flex:0 0 2px;background:currentColor;border-radius:2px;transition:transform .2s,opacity .2s}
|
||||
.nav-toggle[aria-expanded="true"] span:nth-child(1){transform:translateY(8px) rotate(45deg)}
|
||||
.nav-toggle[aria-expanded="true"] span:nth-child(2){opacity:0}
|
||||
.nav-toggle[aria-expanded="true"] span:nth-child(3){transform:translateY(-8px) rotate(-45deg)}
|
||||
@media(max-width:900px){
|
||||
.shell{display:block}
|
||||
.sidebar{position:fixed;inset:0 30% 0 0;max-width:320px;height:100vh;z-index:15;transform:translateX(-100%);transition:transform .25s ease,background-color .18s,border-color .18s;box-shadow:0 18px 40px rgba(0,0,0,.18);background:var(--paper);pointer-events:none}
|
||||
.sidebar.open{transform:translateX(0);pointer-events:auto}
|
||||
.nav-toggle{display:flex}
|
||||
main{padding:64px 18px 56px}
|
||||
.hero{padding-top:6px}
|
||||
.hero h1{font-size:1.8rem}
|
||||
.home-hero h1{font-size:2.45rem}
|
||||
.doc h1{font-size:2.1rem}
|
||||
.hero-meta{width:100%;justify-content:flex-start}
|
||||
.home-hero{padding-top:8px}
|
||||
.doc{padding:0}
|
||||
.doc-grid{margin-top:18px;gap:24px}
|
||||
.doc :is(h2,h3,h4) .anchor{display:none}
|
||||
}
|
||||
@media(max-width:520px){
|
||||
main{padding:60px 14px 48px}
|
||||
.doc pre{margin-left:-14px;margin-right:-14px;border-radius:0;border-left:0;border-right:0}
|
||||
.home-install{flex-wrap:wrap}
|
||||
}
|
||||
`;
|
||||
}
|
||||
|
||||
export function js() {
|
||||
return `
|
||||
const themeRoot=document.documentElement;
|
||||
function applyTheme(mode){themeRoot.dataset.theme=mode;document.querySelectorAll('[data-theme-toggle]').forEach(b=>b.setAttribute('aria-pressed',mode==='dark'?'true':'false'))}
|
||||
function storedTheme(){try{return localStorage.getItem('theme')}catch(e){return null}}
|
||||
function persistTheme(mode){try{localStorage.setItem('theme',mode)}catch(e){}}
|
||||
applyTheme(themeRoot.dataset.theme==='dark'?'dark':'light');
|
||||
document.querySelectorAll('[data-theme-toggle]').forEach(btn=>{btn.addEventListener('click',()=>{const next=themeRoot.dataset.theme==='dark'?'light':'dark';applyTheme(next);persistTheme(next)})});
|
||||
const systemDark=window.matchMedia&&matchMedia('(prefers-color-scheme: dark)');
|
||||
function onSystemChange(e){if(storedTheme())return;applyTheme(e.matches?'dark':'light')}
|
||||
if(systemDark){if(systemDark.addEventListener)systemDark.addEventListener('change',onSystemChange);else if(systemDark.addListener)systemDark.addListener(onSystemChange)}
|
||||
const sidebar=document.querySelector('.sidebar');
|
||||
const toggle=document.querySelector('.nav-toggle');
|
||||
const mobileNav=window.matchMedia('(max-width: 900px)');
|
||||
const sidebarFocusable='a[href],button,input,select,textarea,[tabindex]';
|
||||
function setSidebarFocusable(enabled){
|
||||
sidebar?.querySelectorAll(sidebarFocusable).forEach((el)=>{
|
||||
if(enabled){
|
||||
if(el.dataset.sidebarTabindex!==undefined){
|
||||
if(el.dataset.sidebarTabindex)el.setAttribute('tabindex',el.dataset.sidebarTabindex);
|
||||
else el.removeAttribute('tabindex');
|
||||
delete el.dataset.sidebarTabindex;
|
||||
}
|
||||
}else if(el.dataset.sidebarTabindex===undefined){
|
||||
el.dataset.sidebarTabindex=el.getAttribute('tabindex')??'';
|
||||
el.setAttribute('tabindex','-1');
|
||||
}
|
||||
});
|
||||
}
|
||||
function setSidebarOpen(open){
|
||||
if(!sidebar||!toggle)return;
|
||||
sidebar.classList.toggle('open',open);
|
||||
toggle.setAttribute('aria-expanded',open?'true':'false');
|
||||
if(mobileNav.matches){
|
||||
sidebar.inert=!open;
|
||||
if(open)sidebar.removeAttribute('aria-hidden');
|
||||
else sidebar.setAttribute('aria-hidden','true');
|
||||
setSidebarFocusable(open);
|
||||
}else{
|
||||
sidebar.inert=false;
|
||||
sidebar.removeAttribute('aria-hidden');
|
||||
setSidebarFocusable(true);
|
||||
}
|
||||
}
|
||||
setSidebarOpen(false);
|
||||
toggle?.addEventListener('click',()=>setSidebarOpen(!sidebar?.classList.contains('open')));
|
||||
document.addEventListener('click',(e)=>{if(!sidebar?.classList.contains('open'))return;if(sidebar.contains(e.target)||toggle?.contains(e.target))return;setSidebarOpen(false)});
|
||||
document.addEventListener('keydown',(e)=>{if(e.key==='Escape')setSidebarOpen(false)});
|
||||
const syncSidebarForViewport=()=>setSidebarOpen(sidebar?.classList.contains('open')??false);
|
||||
if(mobileNav.addEventListener)mobileNav.addEventListener('change',syncSidebarForViewport);
|
||||
else mobileNav.addListener?.(syncSidebarForViewport);
|
||||
const input=document.getElementById('doc-search');
|
||||
input?.addEventListener('input',()=>{const q=input.value.trim().toLowerCase();document.querySelectorAll('nav section').forEach(sec=>{let any=false;sec.querySelectorAll('.nav-link').forEach(a=>{const m=!q||a.textContent.toLowerCase().includes(q);a.style.display=m?'block':'none';if(m)any=true});sec.style.display=any?'block':'none'})});
|
||||
function escapeHtmlText(value){return value.replace(/[&<>"']/g,ch=>({'&':'&','<':'<','>':'>','"':'"',"'":'''}[ch]))}
|
||||
const shellCommands=new Set(['bun','mcporter','node','npm','npx','pnpm','list','call','resource','generate-cli','emit-ts','auth','config','daemon','inspect-cli']);
|
||||
function span(cls,text){return '<span class="'+cls+'">'+escapeHtmlText(text)+'</span>'}
|
||||
function highlightShellLine(line){if(/^\\s*#/.test(line))return span('tok-comment',line);let html='';let i=0;while(i<line.length){const ch=line[i];if(/\\s/.test(ch)){html+=ch;i++;continue}if(ch==='#'){html+=span('tok-comment',line.slice(i));break}if(ch==="'"||ch==='"'){const quote=ch;let j=i+1;while(j<line.length){if(line[j]==='\\\\'){j+=2;continue}if(line[j]===quote){j++;break}j++}html+=span('tok-string',line.slice(i,j));i=j;continue}let j=i;while(j<line.length&&!/\\s/.test(line[j])&&line[j]!=="'"&&line[j]!=='"'&&line[j]!=='#')j++;const token=line.slice(i,j);if(token.startsWith('--')||/^-[A-Za-z]/.test(token))html+=span('tok-flag',token);else if(shellCommands.has(token))html+=span('tok-cmd',token);else if(/^[A-Za-z][A-Za-z0-9_-]*:/.test(token)){const idx=token.indexOf(':')+1;html+=span('tok-key',token.slice(0,idx))+span('tok-value',token.slice(idx))}else html+=escapeHtmlText(token);i=j}return html}
|
||||
function highlightCodeBlocks(){document.querySelectorAll('.doc pre code.language-bash,.doc pre code.language-sh,.doc pre code.language-shell').forEach(code=>{if(code.dataset.highlighted)return;code.dataset.highlighted='true';code.innerHTML=code.textContent.split('\\n').map(highlightShellLine).join('\\n')})}
|
||||
function attachCopy(target,getText){const btn=document.createElement('button');btn.type='button';btn.className='copy';btn.textContent='Copy';btn.addEventListener('click',async()=>{try{await navigator.clipboard.writeText(getText());btn.textContent='Copied';btn.classList.add('copied');setTimeout(()=>{btn.textContent='Copy';btn.classList.remove('copied')},1400)}catch{btn.textContent='Failed';setTimeout(()=>{btn.textContent='Copy'},1400)}});target.appendChild(btn)}
|
||||
highlightCodeBlocks();
|
||||
document.querySelectorAll('.doc pre').forEach(pre=>attachCopy(pre,()=>pre.querySelector('code')?.textContent??''));
|
||||
document.querySelectorAll('.home-install').forEach(el=>attachCopy(el,()=>el.querySelector('code')?.textContent??''));
|
||||
const tocLinks=document.querySelectorAll('.toc a');
|
||||
if(tocLinks.length){const map=new Map();tocLinks.forEach(a=>{const id=a.getAttribute('href').slice(1);const el=document.getElementById(id);if(el)map.set(el,a)});const setActive=l=>{tocLinks.forEach(x=>x.classList.remove('active'));l.classList.add('active')};const obs=new IntersectionObserver(entries=>{const visible=entries.filter(e=>e.isIntersecting).sort((a,b)=>a.boundingClientRect.top-b.boundingClientRect.top);if(visible.length){const link=map.get(visible[0].target);if(link)setActive(link)}},{rootMargin:'-15% 0px -65% 0px',threshold:0});map.forEach((_,el)=>obs.observe(el))}
|
||||
`;
|
||||
}
|
||||
|
||||
export function preThemeScript() {
|
||||
return `(function(){var s;try{s=localStorage.getItem('theme')}catch(e){}var d=window.matchMedia&&matchMedia('(prefers-color-scheme: dark)').matches;document.documentElement.dataset.theme=s||(d?'dark':'light')})();`;
|
||||
}
|
||||
|
||||
export function themeToggleHtml() {
|
||||
return `<button class="theme-toggle" type="button" aria-label="Toggle dark mode" aria-pressed="false" data-theme-toggle>
|
||||
<svg class="theme-icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
|
||||
<svg class="theme-icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
|
||||
</button>`;
|
||||
}
|
||||
|
||||
export function faviconSvg() {
|
||||
return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="mcporter">
|
||||
<defs>
|
||||
<linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0" stop-color="#7c3aed"/>
|
||||
<stop offset="1" stop-color="#06b6d4"/>
|
||||
</linearGradient>
|
||||
</defs>
|
||||
<rect width="64" height="64" rx="14" fill="url(#g)"/>
|
||||
<rect x="14" y="22" width="36" height="22" rx="4" fill="#0b0d12"/>
|
||||
<rect x="22" y="16" width="20" height="8" rx="2" fill="#0b0d12"/>
|
||||
<rect x="14" y="29" width="36" height="2" fill="rgba(255,255,255,.18)"/>
|
||||
<circle cx="32" cy="38" r="3" fill="#7c3aed"/>
|
||||
</svg>`;
|
||||
}
|
||||
@ -1,50 +0,0 @@
|
||||
#!/usr/bin/env tsx
|
||||
|
||||
/**
|
||||
* Generate JSON Schema from Zod schemas using Zod v4's native toJSONSchema() method.
|
||||
* Run with: pnpm generate:schema
|
||||
*/
|
||||
|
||||
import { writeFileSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { RawConfigSchema } from '../src/config-schema.js';
|
||||
|
||||
export const CONFIG_SCHEMA_ID = 'https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json';
|
||||
export const CONFIG_SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema';
|
||||
|
||||
export function buildConfigJsonSchema(): Record<string, unknown> {
|
||||
const jsonSchema = RawConfigSchema.toJSONSchema({
|
||||
override(ctx) {
|
||||
const schema = ctx.jsonSchema;
|
||||
// Disallow additional properties on objects for stricter validation
|
||||
if (schema?.type === 'object' && schema.additionalProperties === undefined) {
|
||||
schema.additionalProperties = false;
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
// Allow $schema property in config files for IDE support
|
||||
if (jsonSchema.properties && typeof jsonSchema.properties === 'object') {
|
||||
(jsonSchema.properties as Record<string, unknown>).$schema = {
|
||||
type: 'string',
|
||||
description: 'JSON Schema URL for IDE validation and autocomplete',
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
...jsonSchema,
|
||||
$id: CONFIG_SCHEMA_ID,
|
||||
$schema: CONFIG_SCHEMA_DRAFT,
|
||||
};
|
||||
}
|
||||
|
||||
export function writeConfigJsonSchema(outputPath = 'mcporter.schema.json'): void {
|
||||
const schema = buildConfigJsonSchema();
|
||||
writeFileSync(outputPath, `${JSON.stringify(schema, null, 2)}\n`);
|
||||
console.log(`Generated: ${outputPath}`);
|
||||
}
|
||||
|
||||
const entryPath = process.argv[1];
|
||||
if (entryPath && fileURLToPath(import.meta.url) === entryPath) {
|
||||
writeConfigJsonSchema();
|
||||
}
|
||||
@ -10,7 +10,7 @@ RUNNER="${MCP_RUNNER:-./runner}"
|
||||
VERSION="${VERSION:-$(node -p "require('./package.json').version")}"
|
||||
|
||||
banner() { printf "\n==== %s ====" "$1"; printf "\n"; }
|
||||
run() { echo ">> $*" >&2; "$@"; }
|
||||
run() { echo ">> $*"; "$@"; }
|
||||
|
||||
phase_gates() {
|
||||
banner "Gates (lint/type/test/build)"
|
||||
@ -26,7 +26,7 @@ phase_artifacts() {
|
||||
run tar -C dist-bun -czf "$bun_tar" mcporter
|
||||
run shasum -a 256 "$bun_tar" | tee "${bun_tar}.sha256"
|
||||
|
||||
run "$RUNNER" pnpm pack --pack-destination /tmp
|
||||
run "$RUNNER" npm pack --pack-destination /tmp
|
||||
mv "/tmp/mcporter-${VERSION}.tgz" .
|
||||
run shasum "mcporter-${VERSION}.tgz" > "mcporter-${VERSION}.tgz.sha1"
|
||||
run shasum -a 256 "mcporter-${VERSION}.tgz" > "mcporter-${VERSION}.tgz.sha256"
|
||||
|
||||
@ -40,7 +40,7 @@ const WRAPPER_COMMANDS = new Set([
|
||||
type SummaryStyle = 'compact' | 'minimal' | 'verbose';
|
||||
const SUMMARY_STYLE = resolveSummaryStyle(process.env.RUNNER_SUMMARY_STYLE);
|
||||
|
||||
// Keep each keyword on its own line for grep-friendly diffs.
|
||||
// biome-ignore format: keep each keyword on its own line for grep-friendly diffs.
|
||||
const LONG_SCRIPT_KEYWORDS = [
|
||||
'build',
|
||||
'test:all',
|
||||
@ -54,7 +54,7 @@ const EXTENDED_SCRIPT_KEYWORDS = ['lint', 'test', 'playwright', 'check', 'docker
|
||||
const SINGLE_TEST_SCRIPTS = new Set(['test:file']);
|
||||
const SINGLE_TEST_FLAGS = new Set(['--run', '--filter']);
|
||||
const TEST_BINARIES = new Set(['vitest', 'playwright', 'jest']);
|
||||
const LINT_BINARIES = new Set(['eslint', 'oxfmt', 'oxlint', 'knip']);
|
||||
const LINT_BINARIES = new Set(['eslint', 'biome', 'oxlint', 'knip']);
|
||||
|
||||
type RunnerExecutionContext = {
|
||||
commandArgs: string[];
|
||||
@ -568,7 +568,7 @@ async function runCommand(context: RunnerExecutionContext): Promise<void> {
|
||||
|
||||
let killTimer: NodeJS.Timeout | null = null;
|
||||
try {
|
||||
const result = await new Promise<{ exitCode: number; timedOut: boolean }>((fulfill, reject) => {
|
||||
const result = await new Promise<{ exitCode: number; timedOut: boolean }>((resolve, reject) => {
|
||||
let timedOut = false;
|
||||
const timeout = setTimeout(() => {
|
||||
timedOut = true;
|
||||
@ -600,7 +600,7 @@ async function runCommand(context: RunnerExecutionContext): Promise<void> {
|
||||
clearTimeout(killTimer);
|
||||
}
|
||||
removeSignalHandlers();
|
||||
fulfill({ exitCode: code ?? exitCodeFromSignal(signal), timedOut });
|
||||
resolve({ exitCode: code ?? exitCodeFromSignal(signal), timedOut });
|
||||
});
|
||||
});
|
||||
const { exitCode, timedOut } = result;
|
||||
@ -645,14 +645,14 @@ async function runCommandWithoutTimeout(context: RunnerExecutionContext): Promis
|
||||
const removeSignalHandlers = registerSignalForwarding(child);
|
||||
|
||||
try {
|
||||
const exitCode = await new Promise<number>((fulfill, reject) => {
|
||||
const exitCode = await new Promise<number>((resolve, reject) => {
|
||||
child.once('error', (error) => {
|
||||
removeSignalHandlers();
|
||||
reject(error);
|
||||
});
|
||||
child.once('exit', (code, signal) => {
|
||||
removeSignalHandlers();
|
||||
fulfill(code ?? exitCodeFromSignal(signal));
|
||||
resolve(code ?? exitCodeFromSignal(signal));
|
||||
});
|
||||
});
|
||||
const elapsedMs = Date.now() - startTime;
|
||||
|
||||
@ -1,72 +0,0 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
const MARKER = 'MCPORTER_DEVTOOLS_TIMEOUT_PATCH';
|
||||
const HELPER = `// ${MARKER}
|
||||
const MCPORTER_DEVTOOLS_DETECTION_TIMEOUT = 1_000;
|
||||
async function mcporterWithTimeout(promise, fallback) {
|
||||
let timer;
|
||||
try {
|
||||
return await Promise.race([
|
||||
promise,
|
||||
new Promise(resolve => {
|
||||
timer = setTimeout(resolve, MCPORTER_DEVTOOLS_DETECTION_TIMEOUT, fallback);
|
||||
timer.unref?.();
|
||||
}),
|
||||
]);
|
||||
}
|
||||
finally {
|
||||
if (timer) {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
}
|
||||
`;
|
||||
|
||||
const DETECTION_BLOCK = `if (await page.hasDevTools()) {
|
||||
mcpPage.devToolsPage = await page.openDevTools();
|
||||
}`;
|
||||
|
||||
const PATCHED_DETECTION_BLOCK = `if (await mcporterWithTimeout(page.hasDevTools(), false)) {
|
||||
mcpPage.devToolsPage = await mcporterWithTimeout(page.openDevTools(), undefined);
|
||||
}`;
|
||||
|
||||
patchChromeDevtoolsMcp();
|
||||
|
||||
export function patchChromeDevtoolsMcp(mainPath = process.argv[1]): void {
|
||||
if (!mainPath || !mainPath.includes('chrome-devtools-mcp')) {
|
||||
return;
|
||||
}
|
||||
let resolvedMainPath: string;
|
||||
try {
|
||||
resolvedMainPath = fs.realpathSync(mainPath);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
if (!resolvedMainPath.endsWith(path.join('bin', 'chrome-devtools-mcp.js'))) {
|
||||
return;
|
||||
}
|
||||
const contextPath = path.resolve(path.dirname(resolvedMainPath), '..', 'McpContext.js');
|
||||
let source: string;
|
||||
try {
|
||||
source = fs.readFileSync(contextPath, 'utf8');
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
if (source.includes(MARKER)) {
|
||||
return;
|
||||
}
|
||||
if (!source.includes(DETECTION_BLOCK)) {
|
||||
return;
|
||||
}
|
||||
const withHelper = source.replace(
|
||||
'const NAVIGATION_TIMEOUT = 10_000;\n',
|
||||
`const NAVIGATION_TIMEOUT = 10_000;\n${HELPER}`
|
||||
);
|
||||
const patched = withHelper.replace(DETECTION_BLOCK, PATCHED_DETECTION_BLOCK);
|
||||
try {
|
||||
fs.writeFileSync(contextPath, patched);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
}
|
||||
@ -1,162 +0,0 @@
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||||
|
||||
const AUTO_CONNECT_FLAGS = new Set(['--autoConnect', '--auto-connect']);
|
||||
const FALLBACK_PATCH_FILENAME = 'mcporter-chrome-devtools-auto-connect-patch.js';
|
||||
const FALLBACK_PATCH_SOURCE = `import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
const MARKER = 'MCPORTER_DEVTOOLS_TIMEOUT_PATCH';
|
||||
const HELPER = \`// \${MARKER}
|
||||
const MCPORTER_DEVTOOLS_DETECTION_TIMEOUT = 1_000;
|
||||
async function mcporterWithTimeout(promise, fallback) {
|
||||
let timer;
|
||||
try {
|
||||
return await Promise.race([
|
||||
promise,
|
||||
new Promise(resolve => {
|
||||
timer = setTimeout(resolve, MCPORTER_DEVTOOLS_DETECTION_TIMEOUT, fallback);
|
||||
timer.unref?.();
|
||||
}),
|
||||
]);
|
||||
}
|
||||
finally {
|
||||
if (timer) {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
}
|
||||
\`;
|
||||
|
||||
const DETECTION_BLOCK = \`if (await page.hasDevTools()) {
|
||||
mcpPage.devToolsPage = await page.openDevTools();
|
||||
}\`;
|
||||
|
||||
const PATCHED_DETECTION_BLOCK = \`if (await mcporterWithTimeout(page.hasDevTools(), false)) {
|
||||
mcpPage.devToolsPage = await mcporterWithTimeout(page.openDevTools(), undefined);
|
||||
}\`;
|
||||
|
||||
patchChromeDevtoolsMcp();
|
||||
|
||||
function patchChromeDevtoolsMcp(mainPath = process.argv[1]) {
|
||||
if (!mainPath || !mainPath.includes('chrome-devtools-mcp')) {
|
||||
return;
|
||||
}
|
||||
let resolvedMainPath;
|
||||
try {
|
||||
resolvedMainPath = fs.realpathSync(mainPath);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
if (!resolvedMainPath.endsWith(path.join('bin', 'chrome-devtools-mcp.js'))) {
|
||||
return;
|
||||
}
|
||||
const contextPath = path.resolve(path.dirname(resolvedMainPath), '..', 'McpContext.js');
|
||||
let source;
|
||||
try {
|
||||
source = fs.readFileSync(contextPath, 'utf8');
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
if (source.includes(MARKER)) {
|
||||
return;
|
||||
}
|
||||
if (!source.includes(DETECTION_BLOCK)) {
|
||||
return;
|
||||
}
|
||||
const withHelper = source.replace(
|
||||
'const NAVIGATION_TIMEOUT = 10_000;\\n',
|
||||
\`const NAVIGATION_TIMEOUT = 10_000;\\n\${HELPER}\`
|
||||
);
|
||||
const patched = withHelper.replace(DETECTION_BLOCK, PATCHED_DETECTION_BLOCK);
|
||||
try {
|
||||
fs.writeFileSync(contextPath, patched);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
}
|
||||
`;
|
||||
|
||||
export interface ChromeDevtoolsCompatResult {
|
||||
readonly env: Record<string, string>;
|
||||
readonly applied: boolean;
|
||||
readonly patchPath?: string;
|
||||
}
|
||||
|
||||
export function applyChromeDevtoolsCompat(
|
||||
env: Record<string, string>,
|
||||
command: string,
|
||||
args: readonly string[]
|
||||
): ChromeDevtoolsCompatResult {
|
||||
if (!shouldApplyChromeDevtoolsCompat(command, args, env)) {
|
||||
return { env, applied: false };
|
||||
}
|
||||
const patchPath = resolveChromeDevtoolsCompatPatchPath();
|
||||
if (!patchPath) {
|
||||
return { env, applied: false };
|
||||
}
|
||||
const importFlag = `--import=${pathToFileURL(patchPath).href}`;
|
||||
const existingOptions = env.NODE_OPTIONS?.trim();
|
||||
if (existingOptions?.includes(importFlag)) {
|
||||
return { env, applied: true, patchPath };
|
||||
}
|
||||
return {
|
||||
env: {
|
||||
...env,
|
||||
NODE_OPTIONS: existingOptions ? `${existingOptions} ${importFlag}` : importFlag,
|
||||
},
|
||||
applied: true,
|
||||
patchPath,
|
||||
};
|
||||
}
|
||||
|
||||
export function shouldApplyChromeDevtoolsCompat(
|
||||
command: string,
|
||||
args: readonly string[],
|
||||
env: NodeJS.ProcessEnv | Record<string, string> = process.env
|
||||
): boolean {
|
||||
if (env.MCPORTER_DISABLE_CHROME_DEVTOOLS_COMPAT === '1') {
|
||||
return false;
|
||||
}
|
||||
const tokens = [command, ...args];
|
||||
return tokens.some(isChromeDevtoolsToken) && args.some((arg) => AUTO_CONNECT_FLAGS.has(arg));
|
||||
}
|
||||
|
||||
function isChromeDevtoolsToken(token: string): boolean {
|
||||
return (
|
||||
token === 'chrome-devtools-mcp' ||
|
||||
token.startsWith('chrome-devtools-mcp@') ||
|
||||
token.includes('/chrome-devtools-mcp')
|
||||
);
|
||||
}
|
||||
|
||||
export function resolveChromeDevtoolsCompatPatchPath(
|
||||
candidates = defaultChromeDevtoolsPatchCandidates(),
|
||||
fallbackDir = os.tmpdir()
|
||||
): string | undefined {
|
||||
const existing = candidates.find((candidate) => fs.existsSync(candidate));
|
||||
if (existing) {
|
||||
return existing;
|
||||
}
|
||||
return writeFallbackPatch(fallbackDir);
|
||||
}
|
||||
|
||||
function defaultChromeDevtoolsPatchCandidates(): string[] {
|
||||
const here = path.dirname(fileURLToPath(import.meta.url));
|
||||
return [
|
||||
path.join(here, 'chrome-devtools-auto-connect-patch.js'),
|
||||
path.resolve(here, '..', 'dist', 'chrome-devtools-auto-connect-patch.js'),
|
||||
];
|
||||
}
|
||||
|
||||
function writeFallbackPatch(fallbackDir: string): string | undefined {
|
||||
const patchPath = path.join(fallbackDir, FALLBACK_PATCH_FILENAME);
|
||||
try {
|
||||
fs.writeFileSync(patchPath, FALLBACK_PATCH_SOURCE, { mode: 0o600 });
|
||||
return patchPath;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
@ -23,15 +23,7 @@ export interface SerializedServerDefinition {
|
||||
readonly auth?: string;
|
||||
readonly tokenCacheDir?: string;
|
||||
readonly clientName?: string;
|
||||
readonly oauthClientId?: string;
|
||||
readonly oauthClientSecretEnv?: string;
|
||||
readonly oauthTokenEndpointAuthMethod?: string;
|
||||
readonly oauthRedirectUrl?: string;
|
||||
readonly oauthScope?: string;
|
||||
readonly refresh?: ServerDefinition['refresh'];
|
||||
readonly httpFetch?: ServerDefinition['httpFetch'];
|
||||
readonly allowedTools?: readonly string[];
|
||||
readonly blockedTools?: readonly string[];
|
||||
}
|
||||
|
||||
export interface CliArtifactMetadata {
|
||||
@ -61,8 +53,6 @@ export interface CliArtifactMetadata {
|
||||
compile?: boolean | string;
|
||||
timeoutMs: number;
|
||||
minify: boolean;
|
||||
includeTools?: string[];
|
||||
excludeTools?: string[];
|
||||
};
|
||||
}
|
||||
|
||||
@ -74,26 +64,16 @@ export function metadataPathForArtifact(artifactPath: string): string {
|
||||
// readCliMetadata loads metadata for a generated CLI artifact, preferring the embedded
|
||||
// inspect command and falling back to legacy sidecar files.
|
||||
export async function readCliMetadata(artifactPath: string): Promise<CliArtifactMetadata> {
|
||||
let embeddedError: unknown;
|
||||
try {
|
||||
return await readMetadataFromCli(artifactPath);
|
||||
} catch (error) {
|
||||
embeddedError = error;
|
||||
}
|
||||
|
||||
const legacyPath = metadataPathForArtifact(artifactPath);
|
||||
try {
|
||||
const buffer = await fs.readFile(legacyPath, 'utf8');
|
||||
return JSON.parse(buffer) as CliArtifactMetadata;
|
||||
} catch (error) {
|
||||
if (isErrno(error, 'ENOENT') && embeddedError) {
|
||||
throw embeddedError;
|
||||
}
|
||||
if (!isErrno(error, 'ENOENT')) {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
throw embeddedError;
|
||||
return await readMetadataFromCli(artifactPath);
|
||||
}
|
||||
|
||||
async function readMetadataFromCli(artifactPath: string): Promise<CliArtifactMetadata> {
|
||||
@ -158,15 +138,7 @@ export function serializeDefinition(definition: ServerDefinition): SerializedSer
|
||||
auth: definition.auth,
|
||||
tokenCacheDir: definition.tokenCacheDir,
|
||||
clientName: definition.clientName,
|
||||
oauthClientId: definition.oauthClientId,
|
||||
oauthClientSecretEnv: definition.oauthClientSecretEnv,
|
||||
oauthTokenEndpointAuthMethod: definition.oauthTokenEndpointAuthMethod,
|
||||
oauthRedirectUrl: definition.oauthRedirectUrl,
|
||||
oauthScope: definition.oauthScope,
|
||||
refresh: definition.refresh,
|
||||
httpFetch: definition.httpFetch,
|
||||
allowedTools: definition.allowedTools,
|
||||
blockedTools: definition.blockedTools,
|
||||
};
|
||||
}
|
||||
return {
|
||||
@ -182,14 +154,6 @@ export function serializeDefinition(definition: ServerDefinition): SerializedSer
|
||||
auth: definition.auth,
|
||||
tokenCacheDir: definition.tokenCacheDir,
|
||||
clientName: definition.clientName,
|
||||
oauthClientId: definition.oauthClientId,
|
||||
oauthClientSecretEnv: definition.oauthClientSecretEnv,
|
||||
oauthTokenEndpointAuthMethod: definition.oauthTokenEndpointAuthMethod,
|
||||
oauthRedirectUrl: definition.oauthRedirectUrl,
|
||||
oauthScope: definition.oauthScope,
|
||||
refresh: definition.refresh,
|
||||
httpFetch: definition.httpFetch,
|
||||
allowedTools: definition.allowedTools,
|
||||
blockedTools: definition.blockedTools,
|
||||
};
|
||||
}
|
||||
|
||||
886
src/cli.ts
886
src/cli.ts
@ -1,68 +1,41 @@
|
||||
#!/usr/bin/env node
|
||||
import { spawn } from 'node:child_process';
|
||||
import fsPromises from 'node:fs/promises';
|
||||
import type { EphemeralServerSpec } from './cli/adhoc-server.js';
|
||||
import { printCallHelp, handleCall as runHandleCall } from './cli/call-command.js';
|
||||
import { buildGlobalContext } from './cli/cli-factory.js';
|
||||
import { inferCommandRouting } from './cli/command-inference.js';
|
||||
import { handleConfigCli } from './cli/config-command.js';
|
||||
import { handleDaemonCli } from './cli/daemon-command.js';
|
||||
import { handleEmitTs } from './cli/emit-ts-command.js';
|
||||
import { extractEphemeralServerFlags } from './cli/ephemeral-flags.js';
|
||||
import { prepareEphemeralServerTarget } from './cli/ephemeral-target.js';
|
||||
import { CliUsageError } from './cli/errors.js';
|
||||
import { consumeHelpTokens, isHelpToken, isVersionToken, printHelp, printVersion } from './cli/help-output.js';
|
||||
import { logError, logInfo } from './cli/logger-context.js';
|
||||
import { isRecordReplayModeActive, isReplayModeActive } from './cli/record-replay-env.js';
|
||||
import { handleGenerateCli } from './cli/generate-cli-runner.js';
|
||||
import { looksLikeHttpUrl } from './cli/http-utils.js';
|
||||
import { handleInspectCli } from './cli/inspect-cli-command.js';
|
||||
import { buildConnectionIssueEnvelope } from './cli/json-output.js';
|
||||
import { handleList, printListHelp } from './cli/list-command.js';
|
||||
import { logError, logInfo, logWarn } from './cli/logger-context.js';
|
||||
import { consumeOutputFormat } from './cli/output-format.js';
|
||||
import { DEBUG_HANG, dumpActiveHandles, terminateChildProcesses } from './cli/runtime-debug.js';
|
||||
import { resolveConfigPath } from './config/path-discovery.js';
|
||||
import type { Runtime, RuntimeOptions } from './runtime.js';
|
||||
import { boldText, dimText, extraDimText, supportsAnsiColor } from './cli/terminal.js';
|
||||
import { resolveConfigPath } from './config.js';
|
||||
import type { ServerDefinition } from './config-schema.js';
|
||||
import { DaemonClient } from './daemon/client.js';
|
||||
import { createKeepAliveRuntime } from './daemon/runtime-wrapper.js';
|
||||
import { analyzeConnectionError } from './error-classifier.js';
|
||||
import { isKeepAliveServer } from './lifecycle.js';
|
||||
import { clearOAuthCaches } from './oauth-persistence.js';
|
||||
import { createRuntime, MCPORTER_VERSION } from './runtime.js';
|
||||
|
||||
export { parseCallArguments } from './cli/call-arguments.js';
|
||||
export { extractListFlags } from './cli/list-flags.js';
|
||||
export { handleCall } from './cli/call-command.js';
|
||||
export { handleGenerateCli } from './cli/generate-cli-runner.js';
|
||||
export { handleInspectCli } from './cli/inspect-cli-command.js';
|
||||
export { extractListFlags, handleList } from './cli/list-command.js';
|
||||
export { resolveCallTimeout } from './cli/timeouts.js';
|
||||
|
||||
const FORCE_EXIT_GRACE_MS = 50;
|
||||
const DAEMON_FAST_PATH_SERVERS = new Set(['chrome-devtools', 'mobile-mcp', 'playwright']);
|
||||
|
||||
export async function handleAuth(
|
||||
...args: Parameters<typeof import('./cli/auth-command.js').handleAuth>
|
||||
): ReturnType<typeof import('./cli/auth-command.js').handleAuth> {
|
||||
const { handleAuth: imported } = await import('./cli/auth-command.js');
|
||||
return imported(...args);
|
||||
}
|
||||
|
||||
export async function printAuthHelp(): Promise<void> {
|
||||
const { printAuthHelp: imported } = await import('./cli/auth-command.js');
|
||||
imported();
|
||||
}
|
||||
|
||||
export async function handleCall(
|
||||
...args: Parameters<typeof import('./cli/call-command.js').handleCall>
|
||||
): ReturnType<typeof import('./cli/call-command.js').handleCall> {
|
||||
const { handleCall: imported } = await import('./cli/call-command.js');
|
||||
return imported(...args);
|
||||
}
|
||||
|
||||
export async function handleGenerateCli(
|
||||
...args: Parameters<typeof import('./cli/generate-cli-runner.js').handleGenerateCli>
|
||||
): ReturnType<typeof import('./cli/generate-cli-runner.js').handleGenerateCli> {
|
||||
const { handleGenerateCli: imported } = await import('./cli/generate-cli-runner.js');
|
||||
return imported(...args);
|
||||
}
|
||||
|
||||
export async function handleInspectCli(
|
||||
...args: Parameters<typeof import('./cli/inspect-cli-command.js').handleInspectCli>
|
||||
): ReturnType<typeof import('./cli/inspect-cli-command.js').handleInspectCli> {
|
||||
const { handleInspectCli: imported } = await import('./cli/inspect-cli-command.js');
|
||||
return imported(...args);
|
||||
}
|
||||
|
||||
export async function handleList(
|
||||
...args: Parameters<typeof import('./cli/list-command.js').handleList>
|
||||
): ReturnType<typeof import('./cli/list-command.js').handleList> {
|
||||
const { handleList: imported } = await import('./cli/list-command.js');
|
||||
return imported(...args);
|
||||
}
|
||||
|
||||
export async function handleResource(
|
||||
...args: Parameters<typeof import('./cli/resource-command.js').handleResource>
|
||||
): ReturnType<typeof import('./cli/resource-command.js').handleResource> {
|
||||
const { handleResource: imported } = await import('./cli/resource-command.js');
|
||||
return imported(...args);
|
||||
}
|
||||
|
||||
export async function runCli(argv: string[]): Promise<void> {
|
||||
const args = [...argv];
|
||||
if (args.length === 0) {
|
||||
@ -98,25 +71,11 @@ export async function runCli(argv: string[]): Promise<void> {
|
||||
|
||||
// Early-exit command handlers that don't require runtime inference.
|
||||
if (command === 'generate-cli') {
|
||||
if (consumeHelpTokens(args)) {
|
||||
const { printGenerateCliHelp } = await import('./cli/generate-cli-runner.js');
|
||||
printGenerateCliHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
const { handleGenerateCli: importedHandleGenerateCli } = await import('./cli/generate-cli-runner.js');
|
||||
await importedHandleGenerateCli(args, globalFlags);
|
||||
await handleGenerateCli(args, globalFlags);
|
||||
return;
|
||||
}
|
||||
if (command === 'inspect-cli') {
|
||||
if (consumeHelpTokens(args)) {
|
||||
const { printInspectCliHelp } = await import('./cli/inspect-cli-command.js');
|
||||
printInspectCliHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
const { handleInspectCli: importedHandleInspectCli } = await import('./cli/inspect-cli-command.js');
|
||||
await importedHandleInspectCli(args);
|
||||
await handleInspectCli(args);
|
||||
return;
|
||||
}
|
||||
const rootOverride = globalFlags['--root'];
|
||||
@ -131,7 +90,6 @@ export async function runCli(argv: string[]): Promise<void> {
|
||||
};
|
||||
|
||||
if (command === 'daemon') {
|
||||
const { handleDaemonCli } = await import('./cli/daemon-command.js');
|
||||
await handleDaemonCli(args, {
|
||||
configPath: configPathResolved,
|
||||
configExplicit: configResolution.explicit,
|
||||
@ -140,45 +98,7 @@ export async function runCli(argv: string[]): Promise<void> {
|
||||
return;
|
||||
}
|
||||
|
||||
if (command === 'serve') {
|
||||
const { handleServeCli, printServeHelp } = await import('./cli/serve-command.js');
|
||||
if (consumeHelpTokens(args)) {
|
||||
printServeHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
await handleServeCli(args, {
|
||||
configPath: configPathResolved,
|
||||
configExplicit: configResolution.explicit,
|
||||
rootDir: rootOverride,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
if (command === 'record') {
|
||||
const { handleRecordCli, printRecordHelp } = await import('./cli/record-command.js');
|
||||
if (consumeHelpTokens(wrapperArgsBeforeSeparator(args))) {
|
||||
printRecordHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
await handleRecordCli(args);
|
||||
return;
|
||||
}
|
||||
|
||||
if (command === 'replay') {
|
||||
const { handleReplayCli, printReplayHelp } = await import('./cli/replay-command.js');
|
||||
if (consumeHelpTokens(wrapperArgsBeforeSeparator(args))) {
|
||||
printReplayHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
await handleReplayCli(args);
|
||||
return;
|
||||
}
|
||||
|
||||
if (command === 'config') {
|
||||
const { handleConfigCli } = await import('./cli/config-command.js');
|
||||
await handleConfigCli(
|
||||
{
|
||||
loadOptions: { configPath, rootDir: rootOverride },
|
||||
@ -190,16 +110,6 @@ export async function runCli(argv: string[]): Promise<void> {
|
||||
}
|
||||
|
||||
if (command === 'emit-ts') {
|
||||
if (consumeHelpTokens(args)) {
|
||||
const { printEmitTsHelp } = await import('./cli/emit-ts-command.js');
|
||||
printEmitTsHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
const [{ createRuntime }, { handleEmitTs }] = await Promise.all([
|
||||
import('./runtime.js'),
|
||||
import('./cli/emit-ts-command.js'),
|
||||
]);
|
||||
const runtime = await createRuntime(runtimeOptionsWithPath);
|
||||
try {
|
||||
await handleEmitTs(runtime, args);
|
||||
@ -209,28 +119,15 @@ export async function runCli(argv: string[]): Promise<void> {
|
||||
return;
|
||||
}
|
||||
|
||||
if (await maybeHandleDaemonFastCall(command, args, configResolution, rootOverride)) {
|
||||
return;
|
||||
}
|
||||
|
||||
const [{ createRuntime }, { DaemonClient }, { createKeepAliveRuntime }, { isKeepAliveServer }] = await Promise.all([
|
||||
import('./runtime.js'),
|
||||
import('./daemon/client.js'),
|
||||
import('./daemon/runtime-wrapper.js'),
|
||||
import('./lifecycle.js'),
|
||||
]);
|
||||
const baseRuntime = await createRuntime(runtimeOptionsWithPath);
|
||||
const recordReplayModeActive = isRecordReplayModeActive();
|
||||
const keepAliveServers = recordReplayModeActive
|
||||
? new Set<string>()
|
||||
: new Set(
|
||||
baseRuntime
|
||||
.getDefinitions()
|
||||
.filter(isKeepAliveServer)
|
||||
.map((entry) => entry.name)
|
||||
);
|
||||
const keepAliveServers = new Set(
|
||||
baseRuntime
|
||||
.getDefinitions()
|
||||
.filter(isKeepAliveServer)
|
||||
.map((entry) => entry.name)
|
||||
);
|
||||
const daemonClient =
|
||||
!recordReplayModeActive && keepAliveServers.size > 0
|
||||
keepAliveServers.size > 0
|
||||
? new DaemonClient({
|
||||
configPath: configResolution.path,
|
||||
configExplicit: configResolution.explicit,
|
||||
@ -239,138 +136,83 @@ export async function runCli(argv: string[]): Promise<void> {
|
||||
: null;
|
||||
const runtime = createKeepAliveRuntime(baseRuntime, { daemonClient, keepAliveServers });
|
||||
|
||||
let primaryError: unknown;
|
||||
try {
|
||||
const inference = inferCommandRouting(command, args, runtime.getDefinitions());
|
||||
if (inference.kind === 'abort') {
|
||||
process.exitCode = inference.exitCode;
|
||||
return;
|
||||
}
|
||||
const resolvedCommand = inference.command;
|
||||
const resolvedArgs = inference.args;
|
||||
const inference = inferCommandRouting(command, args, runtime.getDefinitions());
|
||||
if (inference.kind === 'abort') {
|
||||
process.exitCode = inference.exitCode;
|
||||
return;
|
||||
}
|
||||
const resolvedCommand = inference.command;
|
||||
const resolvedArgs = inference.args;
|
||||
|
||||
try {
|
||||
if (resolvedCommand === 'list') {
|
||||
if (consumeHelpTokens(resolvedArgs)) {
|
||||
const { printListHelp } = await import('./cli/list-command.js');
|
||||
printListHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
const { handleList: importedHandleList } = await import('./cli/list-command.js');
|
||||
await importedHandleList(runtime, resolvedArgs);
|
||||
await handleList(runtime, resolvedArgs);
|
||||
return;
|
||||
}
|
||||
|
||||
if (resolvedCommand === 'call') {
|
||||
if (consumeHelpTokens(resolvedArgs)) {
|
||||
const { printCallHelp } = await import('./cli/call-command.js');
|
||||
printCallHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
const { handleCall: runHandleCall } = await import('./cli/call-command.js');
|
||||
await runHandleCall(runtime, resolvedArgs);
|
||||
return;
|
||||
}
|
||||
|
||||
if (resolvedCommand === 'auth') {
|
||||
if (consumeHelpTokens(resolvedArgs)) {
|
||||
const { printAuthHelp: importedPrintAuthHelp } = await import('./cli/auth-command.js');
|
||||
importedPrintAuthHelp();
|
||||
printAuthHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
const { handleAuth: importedHandleAuth } = await import('./cli/auth-command.js');
|
||||
await importedHandleAuth(runtime, resolvedArgs);
|
||||
await handleAuth(runtime, resolvedArgs);
|
||||
return;
|
||||
}
|
||||
|
||||
if (resolvedCommand === 'vault') {
|
||||
if (consumeHelpTokens(resolvedArgs)) {
|
||||
const { printVaultHelp } = await import('./cli/vault-command.js');
|
||||
printVaultHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
const { handleVault } = await import('./cli/vault-command.js');
|
||||
await handleVault(runtime, resolvedArgs);
|
||||
return;
|
||||
}
|
||||
|
||||
if (resolvedCommand === 'resource' || resolvedCommand === 'resources') {
|
||||
if (consumeHelpTokens(resolvedArgs)) {
|
||||
const { printResourceHelp } = await import('./cli/resource-command.js');
|
||||
printResourceHelp();
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
const { handleResource: importedHandleResource } = await import('./cli/resource-command.js');
|
||||
await importedHandleResource(runtime, resolvedArgs);
|
||||
return;
|
||||
}
|
||||
|
||||
printHelp(`Unknown command '${resolvedCommand}'.`);
|
||||
process.exit(1);
|
||||
} catch (error) {
|
||||
primaryError = error;
|
||||
throw error;
|
||||
} finally {
|
||||
await closeRuntimeAfterCommand(runtime, { suppressReplayCloseError: primaryError !== undefined });
|
||||
}
|
||||
}
|
||||
|
||||
async function closeRuntimeAfterCommand(
|
||||
runtime: Runtime,
|
||||
options: { readonly suppressReplayCloseError?: boolean } = {}
|
||||
): Promise<void> {
|
||||
const closeStart = Date.now();
|
||||
let closeError: unknown;
|
||||
if (DEBUG_HANG) {
|
||||
logInfo('[debug] beginning runtime.close()');
|
||||
dumpActiveHandles('before runtime.close');
|
||||
}
|
||||
try {
|
||||
await runtime.close();
|
||||
if (DEBUG_HANG) {
|
||||
const duration = Date.now() - closeStart;
|
||||
logInfo(`[debug] runtime.close() completed in ${duration}ms`);
|
||||
dumpActiveHandles('after runtime.close');
|
||||
}
|
||||
} catch (error) {
|
||||
if (DEBUG_HANG) {
|
||||
logError('[debug] runtime.close() failed', error);
|
||||
}
|
||||
if (isReplayModeActive() && !options.suppressReplayCloseError) {
|
||||
closeError = error;
|
||||
}
|
||||
} finally {
|
||||
terminateChildProcesses('runtime.finally');
|
||||
// By default we force an exit after cleanup so Node doesn't hang on lingering stdio handles
|
||||
// (see typescript-sdk#579/#780/#1049). Opt out by exporting MCPORTER_NO_FORCE_EXIT=1.
|
||||
const disableForceExit = process.env.MCPORTER_NO_FORCE_EXIT === '1';
|
||||
const shouldForceExit = !disableForceExit || process.env.MCPORTER_FORCE_EXIT === '1';
|
||||
const scheduleForcedExit = () => {
|
||||
if (shouldForceExit) {
|
||||
setTimeout(() => {
|
||||
process.exit(process.exitCode ?? 0);
|
||||
}, FORCE_EXIT_GRACE_MS);
|
||||
}
|
||||
};
|
||||
const closeStart = Date.now();
|
||||
if (DEBUG_HANG) {
|
||||
dumpActiveHandles('after terminateChildProcesses');
|
||||
scheduleForcedExit();
|
||||
} else {
|
||||
setImmediate(scheduleForcedExit);
|
||||
logInfo('[debug] beginning runtime.close()');
|
||||
dumpActiveHandles('before runtime.close');
|
||||
}
|
||||
try {
|
||||
await runtime.close();
|
||||
if (DEBUG_HANG) {
|
||||
const duration = Date.now() - closeStart;
|
||||
logInfo(`[debug] runtime.close() completed in ${duration}ms`);
|
||||
dumpActiveHandles('after runtime.close');
|
||||
}
|
||||
} catch (error) {
|
||||
if (DEBUG_HANG) {
|
||||
logError('[debug] runtime.close() failed', error);
|
||||
}
|
||||
} finally {
|
||||
terminateChildProcesses('runtime.finally');
|
||||
// By default we force an exit after cleanup so Node doesn't hang on lingering stdio handles
|
||||
// (see typescript-sdk#579/#780/#1049). Opt out by exporting MCPORTER_NO_FORCE_EXIT=1.
|
||||
const disableForceExit = process.env.MCPORTER_NO_FORCE_EXIT === '1';
|
||||
if (DEBUG_HANG) {
|
||||
dumpActiveHandles('after terminateChildProcesses');
|
||||
if (!disableForceExit || process.env.MCPORTER_FORCE_EXIT === '1') {
|
||||
process.exit(0);
|
||||
}
|
||||
} else {
|
||||
const scheduleExit = () => {
|
||||
if (!disableForceExit || process.env.MCPORTER_FORCE_EXIT === '1') {
|
||||
process.exit(0);
|
||||
}
|
||||
};
|
||||
setImmediate(scheduleExit);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (closeError) {
|
||||
throw closeError;
|
||||
}
|
||||
}
|
||||
|
||||
function wrapperArgsBeforeSeparator(args: readonly string[]): string[] {
|
||||
const separatorIndex = args.indexOf('--');
|
||||
return separatorIndex === -1 ? [...args] : args.slice(0, separatorIndex);
|
||||
printHelp(`Unknown command '${resolvedCommand}'.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// main parses CLI flags and dispatches to list/call commands.
|
||||
@ -378,6 +220,211 @@ async function main(): Promise<void> {
|
||||
await runCli(process.argv.slice(2));
|
||||
}
|
||||
|
||||
// printHelp explains available commands and global flags.
|
||||
function printHelp(message?: string): void {
|
||||
if (message) {
|
||||
console.error(message);
|
||||
console.error('');
|
||||
}
|
||||
const colorize = supportsAnsiColor;
|
||||
const sections = buildCommandSections(colorize);
|
||||
const globalFlags = formatGlobalFlags(colorize);
|
||||
const quickStart = formatQuickStart(colorize);
|
||||
const footer = formatHelpFooter(colorize);
|
||||
const title = colorize
|
||||
? `${boldText('mcporter')} ${dimText('— Model Context Protocol CLI & generator')}`
|
||||
: 'mcporter — Model Context Protocol CLI & generator';
|
||||
const lines = [
|
||||
title,
|
||||
'',
|
||||
'Usage: mcporter <command> [options]',
|
||||
'',
|
||||
...sections,
|
||||
'',
|
||||
globalFlags,
|
||||
'',
|
||||
quickStart,
|
||||
'',
|
||||
footer,
|
||||
];
|
||||
console.error(lines.join('\n'));
|
||||
}
|
||||
|
||||
type HelpEntry = {
|
||||
name: string;
|
||||
summary: string;
|
||||
usage: string;
|
||||
};
|
||||
|
||||
type HelpSection = {
|
||||
title: string;
|
||||
entries: HelpEntry[];
|
||||
};
|
||||
|
||||
function buildCommandSections(colorize: boolean): string[] {
|
||||
const sections: HelpSection[] = [
|
||||
{
|
||||
title: 'Core commands',
|
||||
entries: [
|
||||
{
|
||||
name: 'list',
|
||||
summary: 'List configured servers (add --schema for tool docs)',
|
||||
usage: 'mcporter list [name] [--schema] [--json]',
|
||||
},
|
||||
{
|
||||
name: 'call',
|
||||
summary: 'Call a tool by selector (server.tool) or HTTP URL; key=value flags supported',
|
||||
usage: 'mcporter call <selector> [key=value ...]',
|
||||
},
|
||||
{
|
||||
name: 'auth',
|
||||
summary: 'Complete OAuth for a server without listing tools',
|
||||
usage: 'mcporter auth <server | url> [--reset]',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Generator & tooling',
|
||||
entries: [
|
||||
{
|
||||
name: 'generate-cli',
|
||||
summary: 'Emit a standalone CLI (supports HTTP, stdio, and inline commands)',
|
||||
usage: 'mcporter generate-cli --server <name> | --command <ref> [options]',
|
||||
},
|
||||
{
|
||||
name: 'inspect-cli',
|
||||
summary: 'Show metadata and regen instructions for a generated CLI',
|
||||
usage: 'mcporter inspect-cli <path> [--json]',
|
||||
},
|
||||
{
|
||||
name: 'emit-ts',
|
||||
summary: 'Generate TypeScript client/types for a server',
|
||||
usage: 'mcporter emit-ts <server> --mode client|types [options]',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Configuration',
|
||||
entries: [
|
||||
{
|
||||
name: 'config',
|
||||
summary: 'Inspect or edit config files (list, get, add, remove, import, login, logout)',
|
||||
usage: 'mcporter config <command> [options]',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Daemon',
|
||||
entries: [
|
||||
{
|
||||
name: 'daemon',
|
||||
summary: 'Manage the keep-alive daemon (start | status | stop | restart)',
|
||||
usage: 'mcporter daemon <subcommand>',
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
return sections.flatMap((section) => formatCommandSection(section, colorize));
|
||||
}
|
||||
|
||||
function formatCommandSection(section: HelpSection, colorize: boolean): string[] {
|
||||
const maxNameLength = Math.max(...section.entries.map((entry) => entry.name.length));
|
||||
const header = colorize ? boldText(section.title) : section.title;
|
||||
const lines = [header];
|
||||
section.entries.forEach((entry) => {
|
||||
const paddedName = entry.name.padEnd(maxNameLength);
|
||||
const renderedName = colorize ? boldText(paddedName) : paddedName;
|
||||
const summary = colorize ? dimText(entry.summary) : entry.summary;
|
||||
lines.push(` ${renderedName} ${summary}`);
|
||||
lines.push(` ${extraDimText('usage:')} ${entry.usage}`);
|
||||
});
|
||||
return [...lines, ''];
|
||||
}
|
||||
|
||||
function formatGlobalFlags(colorize: boolean): string {
|
||||
const title = colorize ? boldText('Global flags') : 'Global flags';
|
||||
const entries = [
|
||||
{
|
||||
flag: '--config <path>',
|
||||
summary: 'Path to mcporter.json (defaults to ./config/mcporter.json)',
|
||||
},
|
||||
{
|
||||
flag: '--root <path>',
|
||||
summary: 'Working directory for stdio servers',
|
||||
},
|
||||
{
|
||||
flag: '--log-level <debug|info|warn|error>',
|
||||
summary: 'Adjust CLI logging (defaults to warn)',
|
||||
},
|
||||
{
|
||||
flag: '--oauth-timeout <ms>',
|
||||
summary: 'Time to wait for browser-based OAuth before giving up (default 60000)',
|
||||
},
|
||||
];
|
||||
const formatted = entries.map((entry) => ` ${entry.flag.padEnd(34)}${entry.summary}`);
|
||||
return [title, ...formatted].join('\n');
|
||||
}
|
||||
|
||||
function formatQuickStart(colorize: boolean): string {
|
||||
const title = colorize ? boldText('Quick start') : 'Quick start';
|
||||
const entries = [
|
||||
['mcporter list', 'show configured servers'],
|
||||
['mcporter list linear --schema', 'view Linear tool docs'],
|
||||
['mcporter call linear.list_issues limit:5', 'invoke a tool with key=value arguments'],
|
||||
['mcporter generate-cli --command https://host/mcp --compile ./my-cli', 'build a standalone CLI/binary'],
|
||||
];
|
||||
const formatted = entries.map(([cmd, note]) => {
|
||||
const comment = colorize ? dimText(`# ${note}`) : `# ${note}`;
|
||||
return ` ${cmd}\n ${comment}`;
|
||||
});
|
||||
return [title, ...formatted].join('\n');
|
||||
}
|
||||
|
||||
function formatHelpFooter(colorize: boolean): string {
|
||||
const pointer = 'Run `mcporter <command> --help` for detailed flags.';
|
||||
const autoLoad =
|
||||
'mcporter auto-loads servers from ./config/mcporter.json and editor imports (Cursor, Claude, Codex, etc.).';
|
||||
if (!colorize) {
|
||||
return `${pointer}\n${autoLoad}`;
|
||||
}
|
||||
return `${dimText(pointer)}\n${extraDimText(autoLoad)}`;
|
||||
}
|
||||
|
||||
async function printVersion(): Promise<void> {
|
||||
console.log(await resolveCliVersion());
|
||||
}
|
||||
|
||||
function isHelpToken(token: string): boolean {
|
||||
return token === '--help' || token === '-h' || token === 'help';
|
||||
}
|
||||
|
||||
function consumeHelpTokens(args: string[]): boolean {
|
||||
let found = false;
|
||||
for (let index = args.length - 1; index >= 0; index -= 1) {
|
||||
const token = args[index];
|
||||
if (token && isHelpToken(token)) {
|
||||
args.splice(index, 1);
|
||||
found = true;
|
||||
}
|
||||
}
|
||||
return found;
|
||||
}
|
||||
|
||||
function isVersionToken(token: string): boolean {
|
||||
return token === '--version' || token === '-v' || token === '-V';
|
||||
}
|
||||
|
||||
async function resolveCliVersion(): Promise<string> {
|
||||
try {
|
||||
const packageJsonPath = new URL('../package.json', import.meta.url);
|
||||
const buffer = await fsPromises.readFile(packageJsonPath, 'utf8');
|
||||
const pkg = JSON.parse(buffer) as { version?: string };
|
||||
return pkg.version ?? MCPORTER_VERSION;
|
||||
} catch {
|
||||
return MCPORTER_VERSION;
|
||||
}
|
||||
}
|
||||
|
||||
if (process.env.MCPORTER_DISABLE_AUTORUN !== '1') {
|
||||
main().catch((error) => {
|
||||
if (error instanceof CliUsageError) {
|
||||
@ -390,238 +437,145 @@ if (process.env.MCPORTER_DISABLE_AUTORUN !== '1') {
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
// handleAuth clears cached tokens and executes standalone OAuth flows.
|
||||
export async function handleAuth(runtime: Awaited<ReturnType<typeof createRuntime>>, args: string[]): Promise<void> {
|
||||
// Peel off optional flags before we consume positional args.
|
||||
const resetIndex = args.indexOf('--reset');
|
||||
const shouldReset = resetIndex !== -1;
|
||||
if (shouldReset) {
|
||||
args.splice(resetIndex, 1);
|
||||
}
|
||||
const format = consumeOutputFormat(args, {
|
||||
defaultFormat: 'text',
|
||||
allowed: ['text', 'json'],
|
||||
enableRawShortcut: false,
|
||||
jsonShortcutFlag: '--json',
|
||||
}) as 'text' | 'json';
|
||||
const ephemeralSpec: EphemeralServerSpec | undefined = extractEphemeralServerFlags(args);
|
||||
let target = args.shift();
|
||||
const nameHints: string[] = [];
|
||||
if (ephemeralSpec && target && !looksLikeHttpUrl(target)) {
|
||||
nameHints.push(target);
|
||||
}
|
||||
|
||||
async function invokeAuthCommand(runtimeOptions: RuntimeOptions, args: string[]): Promise<void> {
|
||||
const [{ createRuntime }, { handleAuth: importedHandleAuth }] = await Promise.all([
|
||||
import('./runtime.js'),
|
||||
import('./cli/auth-command.js'),
|
||||
]);
|
||||
const prepared = await prepareEphemeralServerTarget({
|
||||
runtime,
|
||||
target,
|
||||
ephemeral: ephemeralSpec,
|
||||
nameHints,
|
||||
reuseFromSpec: true,
|
||||
});
|
||||
target = prepared.target;
|
||||
|
||||
if (!target) {
|
||||
throw new Error('Usage: mcporter auth <server | url> [--http-url <url> | --stdio <command>]');
|
||||
}
|
||||
|
||||
const definition = runtime.getDefinition(target);
|
||||
if (shouldReset) {
|
||||
await clearOAuthCaches(definition);
|
||||
logInfo(`Cleared cached credentials for '${target}'.`);
|
||||
}
|
||||
|
||||
if (definition.command.kind === 'stdio' && definition.oauthCommand) {
|
||||
logInfo(`Starting auth helper for '${target}' (stdio). Leave this running until the browser flow completes.`);
|
||||
await runStdioAuth(definition);
|
||||
logInfo(`Auth helper for '${target}' finished. You can now call tools.`);
|
||||
return;
|
||||
}
|
||||
|
||||
// Kick off the interactive OAuth flow without blocking list output. We retry once if the
|
||||
// server gets auto-promoted to OAuth mid-flight.
|
||||
for (let attempt = 0; attempt < 2; attempt += 1) {
|
||||
try {
|
||||
logInfo(`Initiating OAuth flow for '${target}'...`);
|
||||
const tools = await runtime.listTools(target, { autoAuthorize: true });
|
||||
logInfo(`Authorization complete. ${tools.length} tool${tools.length === 1 ? '' : 's'} available.`);
|
||||
return;
|
||||
} catch (error) {
|
||||
if (attempt === 0 && shouldRetryAuthError(error)) {
|
||||
logWarn('Server signaled OAuth after the initial attempt. Retrying with browser flow...');
|
||||
continue;
|
||||
}
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
if (format === 'json') {
|
||||
const payload = buildConnectionIssueEnvelope({
|
||||
server: target,
|
||||
error,
|
||||
issue: analyzeConnectionError(error),
|
||||
});
|
||||
console.log(JSON.stringify(payload, null, 2));
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
throw new Error(`Failed to authorize '${target}': ${message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async function invokeAuthCommand(runtimeOptions: Parameters<typeof createRuntime>[0], args: string[]): Promise<void> {
|
||||
const runtime = await createRuntime(runtimeOptions);
|
||||
try {
|
||||
await importedHandleAuth(runtime, args);
|
||||
await handleAuth(runtime, args);
|
||||
} finally {
|
||||
await runtime.close().catch(() => {});
|
||||
}
|
||||
}
|
||||
|
||||
async function maybeHandleDaemonFastCall(
|
||||
command: string,
|
||||
args: string[],
|
||||
configResolution: { path: string; explicit: boolean },
|
||||
rootDir: string | undefined
|
||||
): Promise<boolean> {
|
||||
if (isRecordReplayModeActive()) {
|
||||
return false;
|
||||
async function runStdioAuth(definition: ServerDefinition): Promise<void> {
|
||||
const authArgs = [...(definition.command.kind === 'stdio' ? (definition.command.args ?? []) : [])];
|
||||
if (definition.oauthCommand) {
|
||||
authArgs.push(...definition.oauthCommand.args);
|
||||
}
|
||||
const callArgs = resolveDaemonFastCallArgs(command, args);
|
||||
if (!callArgs) {
|
||||
return false;
|
||||
}
|
||||
const server = resolveExplicitCallServer(callArgs);
|
||||
if (!server || !DAEMON_FAST_PATH_SERVERS.has(server) || isFastPathKeepAliveDisabled(server)) {
|
||||
return false;
|
||||
}
|
||||
if (await maybeHandleSimpleDaemonFastCall(callArgs, configResolution, rootDir)) {
|
||||
return true;
|
||||
}
|
||||
const [{ DaemonClient }, { handleCall: importedHandleCall }] = await Promise.all([
|
||||
import('./daemon/client.js'),
|
||||
import('./cli/call-command.js'),
|
||||
]);
|
||||
const daemonClient = new DaemonClient({
|
||||
configPath: configResolution.path,
|
||||
configExplicit: configResolution.explicit,
|
||||
rootDir,
|
||||
});
|
||||
await importedHandleCall(createDaemonOnlyRuntime(daemonClient), callArgs);
|
||||
return true;
|
||||
}
|
||||
|
||||
async function maybeHandleSimpleDaemonFastCall(
|
||||
callArgs: string[],
|
||||
configResolution: { path: string; explicit: boolean },
|
||||
rootDir: string | undefined
|
||||
): Promise<boolean> {
|
||||
const [{ parseCallArguments }, { resolveCallTimeout }] = await Promise.all([
|
||||
import('./cli/call-arguments.js'),
|
||||
import('./cli/timeouts.js'),
|
||||
]);
|
||||
let parsed: ReturnType<typeof parseCallArguments>;
|
||||
try {
|
||||
parsed = parseCallArguments([...callArgs]);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
if (
|
||||
!parsed.server ||
|
||||
!parsed.tool ||
|
||||
parsed.ephemeral ||
|
||||
parsed.tailLog ||
|
||||
parsed.saveImagesDir ||
|
||||
(parsed.positionalArgs?.length ?? 0) > 0 ||
|
||||
parsed.schemaStringCoercionCandidates ||
|
||||
parsed.schemaArrayCoercionCandidates
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
|
||||
const [{ DaemonClient }, { wrapCallResult }, { printCallOutput }] = await Promise.all([
|
||||
import('./daemon/client.js'),
|
||||
import('./result-utils.js'),
|
||||
import('./cli/output-utils.js'),
|
||||
]);
|
||||
const daemonClient = new DaemonClient({
|
||||
configPath: configResolution.path,
|
||||
configExplicit: configResolution.explicit,
|
||||
rootDir,
|
||||
});
|
||||
const result = await daemonClient.callTool({
|
||||
server: parsed.server,
|
||||
tool: parsed.tool,
|
||||
args: Object.keys(parsed.args).length > 0 ? parsed.args : undefined,
|
||||
timeoutMs: resolveCallTimeout(parsed.timeoutMs),
|
||||
disableOAuth: parsed.disableOAuth,
|
||||
});
|
||||
const { callResult } = wrapCallResult(result);
|
||||
printCallOutput(callResult, result, parsed.output);
|
||||
return true;
|
||||
}
|
||||
|
||||
function resolveDaemonFastCallArgs(command: string, args: string[]): string[] | undefined {
|
||||
if (command === 'call') {
|
||||
return args;
|
||||
}
|
||||
if (isExplicitNonCallCommand(command) || command.includes('://')) {
|
||||
return undefined;
|
||||
}
|
||||
if (!/[.(]/.test(command)) {
|
||||
return undefined;
|
||||
}
|
||||
return [command, ...args];
|
||||
}
|
||||
|
||||
function isExplicitNonCallCommand(command: string): boolean {
|
||||
return (
|
||||
command === 'list' ||
|
||||
command === 'auth' ||
|
||||
command === 'resource' ||
|
||||
command === 'resources' ||
|
||||
command === 'daemon' ||
|
||||
command === 'serve' ||
|
||||
command === 'record' ||
|
||||
command === 'replay' ||
|
||||
command === 'config' ||
|
||||
command === 'emit-ts' ||
|
||||
command === 'generate-cli' ||
|
||||
command === 'inspect-cli' ||
|
||||
command === 'describe'
|
||||
);
|
||||
}
|
||||
|
||||
function resolveExplicitCallServer(args: readonly string[]): string | undefined {
|
||||
let serverFlag: string | undefined;
|
||||
for (let index = 0; index < args.length; index += 1) {
|
||||
const token = args[index];
|
||||
if (!token) {
|
||||
continue;
|
||||
}
|
||||
if (isHelpToken(token)) {
|
||||
return undefined;
|
||||
}
|
||||
if (token === '--http-url' || token === '--stdio') {
|
||||
return undefined;
|
||||
}
|
||||
if (token === '--server') {
|
||||
serverFlag = args[index + 1];
|
||||
index += 1;
|
||||
continue;
|
||||
}
|
||||
if (token.startsWith('--server=')) {
|
||||
serverFlag = token.slice('--server='.length);
|
||||
continue;
|
||||
}
|
||||
if (token.startsWith('-')) {
|
||||
continue;
|
||||
}
|
||||
if (token.includes('://')) {
|
||||
return undefined;
|
||||
}
|
||||
const separator = token.indexOf('.');
|
||||
if (separator > 0) {
|
||||
return token.slice(0, separator);
|
||||
}
|
||||
return serverFlag;
|
||||
}
|
||||
return serverFlag;
|
||||
}
|
||||
|
||||
function isFastPathKeepAliveDisabled(server: string): boolean {
|
||||
const raw = process.env.MCPORTER_DISABLE_KEEPALIVE ?? process.env.MCPORTER_NO_KEEPALIVE;
|
||||
if (!raw) {
|
||||
return false;
|
||||
}
|
||||
const disabled = new Set(
|
||||
raw
|
||||
.split(',')
|
||||
.map((entry) => entry.trim().toLowerCase())
|
||||
.filter(Boolean)
|
||||
);
|
||||
return disabled.has('*') || disabled.has(server.toLowerCase());
|
||||
}
|
||||
|
||||
function createDaemonOnlyRuntime(daemonClient: import('./daemon/client.js').DaemonClient): Runtime {
|
||||
return {
|
||||
listServers: () => [],
|
||||
getDefinitions: () => [],
|
||||
getDefinition: (server: string) => {
|
||||
throw new Error(`Server '${server}' is only available through the keep-alive daemon fast path.`);
|
||||
},
|
||||
registerDefinition: () => {
|
||||
throw new Error('Ad-hoc servers are not supported by the keep-alive daemon fast path.');
|
||||
},
|
||||
getInstructions: async () => undefined,
|
||||
listTools: async (server, options) =>
|
||||
(await daemonClient.listTools({
|
||||
server,
|
||||
includeSchema: options?.includeSchema,
|
||||
autoAuthorize: options?.autoAuthorize,
|
||||
allowCachedAuth: options?.allowCachedAuth,
|
||||
disableOAuth: options?.disableOAuth,
|
||||
})) as Awaited<ReturnType<Runtime['listTools']>>,
|
||||
callTool: (server, toolName, options) =>
|
||||
daemonClient.callTool({
|
||||
server,
|
||||
tool: toolName,
|
||||
args: options?.args,
|
||||
timeoutMs: options?.timeoutMs,
|
||||
disableOAuth: options?.disableOAuth,
|
||||
}),
|
||||
listResources: (server, options) => {
|
||||
const params: Record<string, unknown> = { ...options };
|
||||
delete params.allowCachedAuth;
|
||||
delete params.disableOAuth;
|
||||
delete params.oauthSessionOptions;
|
||||
return daemonClient.listResources({
|
||||
server,
|
||||
params,
|
||||
allowCachedAuth: options?.allowCachedAuth,
|
||||
disableOAuth: options?.disableOAuth,
|
||||
});
|
||||
},
|
||||
readResource: (server, uri, options) =>
|
||||
daemonClient.readResource({
|
||||
server,
|
||||
uri,
|
||||
allowCachedAuth: options?.allowCachedAuth,
|
||||
disableOAuth: options?.disableOAuth,
|
||||
}),
|
||||
connect: async (server) => {
|
||||
throw new Error(`Server '${server}' is only available through daemon request methods.`);
|
||||
},
|
||||
close: async (server?: string) => {
|
||||
if (server) {
|
||||
await daemonClient.closeServer({ server }).catch(() => {});
|
||||
return new Promise((resolve, reject) => {
|
||||
const child = spawn(definition.command.kind === 'stdio' ? definition.command.command : '', authArgs, {
|
||||
stdio: 'inherit',
|
||||
cwd: definition.command.kind === 'stdio' ? definition.command.cwd : process.cwd(),
|
||||
env: process.env,
|
||||
});
|
||||
child.on('error', reject);
|
||||
child.on('exit', (code) => {
|
||||
if (code === 0) {
|
||||
resolve();
|
||||
} else {
|
||||
reject(new Error(`Auth helper exited with code ${code ?? 'null'}`));
|
||||
}
|
||||
},
|
||||
};
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function shouldRetryAuthError(error: unknown): boolean {
|
||||
return analyzeConnectionError(error).kind === 'auth';
|
||||
}
|
||||
|
||||
export function printAuthHelp(): void {
|
||||
const lines = [
|
||||
'Usage: mcporter auth <server | url> [flags]',
|
||||
'',
|
||||
'Purpose:',
|
||||
' Run the authentication flow for a server without listing tools.',
|
||||
'',
|
||||
'Common flags:',
|
||||
' --reset Clear cached credentials before re-authorizing.',
|
||||
' --json Emit a JSON envelope on failure.',
|
||||
'',
|
||||
'Ad-hoc targets:',
|
||||
' --http-url <url> Register an HTTP server for this run.',
|
||||
' --allow-http Permit plain http:// URLs with --http-url.',
|
||||
' --stdio <command> Run a stdio MCP server (repeat --stdio-arg for args).',
|
||||
' --stdio-arg <value> Append args to the stdio command (repeatable).',
|
||||
' --env KEY=value Inject env vars for stdio servers (repeatable).',
|
||||
' --cwd <path> Working directory for stdio servers.',
|
||||
' --name <value> Override the display name for ad-hoc servers.',
|
||||
' --description <text> Override the description for ad-hoc servers.',
|
||||
' --persist <path> Write the ad-hoc definition to config/mcporter.json.',
|
||||
' --yes Skip confirmation prompts when persisting.',
|
||||
'',
|
||||
'Examples:',
|
||||
' mcporter auth linear',
|
||||
' mcporter auth https://mcp.example.com/mcp',
|
||||
' mcporter auth --stdio "npx -y chrome-devtools-mcp@latest"',
|
||||
' mcporter auth --http-url http://localhost:3000/mcp --allow-http',
|
||||
];
|
||||
console.error(lines.join('\n'));
|
||||
}
|
||||
|
||||
@ -3,7 +3,6 @@ import path from 'node:path';
|
||||
import type { CommandSpec, ServerDefinition } from '../config.js';
|
||||
import { __configInternals } from '../config.js';
|
||||
import { expandHome } from '../env.js';
|
||||
import { withFileLock, writeTextFileAtomic } from '../fs-json.js';
|
||||
import { canonicalKeepAliveName, resolveLifecycle } from '../lifecycle.js';
|
||||
|
||||
export interface EphemeralServerSpec {
|
||||
@ -14,7 +13,6 @@ export interface EphemeralServerSpec {
|
||||
stdioArgs?: string[];
|
||||
cwd?: string;
|
||||
env?: Record<string, string>;
|
||||
headers?: Record<string, string>;
|
||||
description?: string;
|
||||
persistPath?: string;
|
||||
}
|
||||
@ -46,10 +44,10 @@ export function resolveEphemeralServer(spec: EphemeralServerSpec): EphemeralServ
|
||||
const command: CommandSpec = {
|
||||
kind: 'http',
|
||||
url,
|
||||
headers: __configInternals.ensureHttpAcceptHeader(spec.headers),
|
||||
headers: __configInternals.ensureHttpAcceptHeader(undefined),
|
||||
};
|
||||
const canonical = spec.name ? undefined : canonicalKeepAliveName(command);
|
||||
const name = normalizeEphemeralName(spec.name ?? canonical ?? inferNameFromUrl(url));
|
||||
const name = slugify(spec.name ?? canonical ?? inferNameFromUrl(url));
|
||||
const lifecycle = resolveLifecycle(name, undefined, command);
|
||||
const definition: ServerDefinition = {
|
||||
name,
|
||||
@ -63,7 +61,6 @@ export function resolveEphemeralServer(spec: EphemeralServerSpec): EphemeralServ
|
||||
baseUrl: url.href,
|
||||
...(spec.description ? { description: spec.description } : {}),
|
||||
...(spec.env && Object.keys(spec.env).length > 0 ? { env: spec.env } : {}),
|
||||
...(spec.headers && Object.keys(spec.headers).length > 0 ? { headers: spec.headers } : {}),
|
||||
...(lifecycle ? { lifecycle: serializeLifecycle(lifecycle) } : {}),
|
||||
};
|
||||
return { definition, name, persistedEntry };
|
||||
@ -84,7 +81,7 @@ export function resolveEphemeralServer(spec: EphemeralServerSpec): EphemeralServ
|
||||
cwd,
|
||||
};
|
||||
const canonical = spec.name ? undefined : canonicalKeepAliveName(command);
|
||||
const name = normalizeEphemeralName(spec.name ?? canonical ?? inferNameFromCommand(parts));
|
||||
const name = slugify(spec.name ?? canonical ?? inferNameFromCommand(parts));
|
||||
const lifecycle = resolveLifecycle(name, undefined, command);
|
||||
const definition: ServerDefinition = {
|
||||
name,
|
||||
@ -109,27 +106,26 @@ export function resolveEphemeralServer(spec: EphemeralServerSpec): EphemeralServ
|
||||
|
||||
export async function persistEphemeralServer(resolution: EphemeralServerResolution, rawPath: string): Promise<void> {
|
||||
const resolvedPath = path.resolve(expandHome(rawPath));
|
||||
await withFileLock(resolvedPath, async () => {
|
||||
let existing: Record<string, unknown>;
|
||||
try {
|
||||
const buffer = await fs.readFile(resolvedPath, 'utf8');
|
||||
existing = JSON.parse(buffer) as Record<string, unknown>;
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
|
||||
throw error;
|
||||
}
|
||||
existing = { mcpServers: {} };
|
||||
let existing: Record<string, unknown>;
|
||||
try {
|
||||
const buffer = await fs.readFile(resolvedPath, 'utf8');
|
||||
existing = JSON.parse(buffer) as Record<string, unknown>;
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
|
||||
throw error;
|
||||
}
|
||||
existing = { mcpServers: {} };
|
||||
}
|
||||
|
||||
if (typeof existing.mcpServers !== 'object' || existing.mcpServers === null) {
|
||||
existing.mcpServers = {};
|
||||
}
|
||||
const servers = existing.mcpServers as Record<string, unknown>;
|
||||
servers[resolution.name] = resolution.persistedEntry;
|
||||
if (typeof existing.mcpServers !== 'object' || existing.mcpServers === null) {
|
||||
existing.mcpServers = {};
|
||||
}
|
||||
const servers = existing.mcpServers as Record<string, unknown>;
|
||||
servers[resolution.name] = resolution.persistedEntry;
|
||||
|
||||
const serialized = `${JSON.stringify(existing, null, 2)}\n`;
|
||||
await writeTextFileAtomic(resolvedPath, serialized);
|
||||
});
|
||||
await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
|
||||
const serialized = `${JSON.stringify(existing, null, 2)}\n`;
|
||||
await fs.writeFile(resolvedPath, serialized, 'utf8');
|
||||
}
|
||||
|
||||
function inferNameFromUrl(url: URL): string {
|
||||
@ -206,14 +202,6 @@ function slugify(value: string): string {
|
||||
.replace(/-{2,}/g, '-');
|
||||
}
|
||||
|
||||
function normalizeEphemeralName(value: string): string {
|
||||
const name = slugify(value);
|
||||
if (!name) {
|
||||
throw new Error('Ad-hoc server name must contain at least one letter or digit.');
|
||||
}
|
||||
return name;
|
||||
}
|
||||
|
||||
export function splitCommandLine(input: string): string[] {
|
||||
const result: string[] = [];
|
||||
let current = '';
|
||||
|
||||
@ -1,267 +0,0 @@
|
||||
import { spawn } from 'node:child_process';
|
||||
import type { ServerDefinition } from '../config-schema.js';
|
||||
import type { OAuthAuthorizationRequest, OAuthSessionOptions } from '../oauth.js';
|
||||
import { analyzeConnectionError } from '../error-classifier.js';
|
||||
import { clearOAuthCaches } from '../oauth-persistence.js';
|
||||
import type { createRuntime } from '../runtime.js';
|
||||
import { isOAuthFlowError } from '../runtime/oauth.js';
|
||||
import type { EphemeralServerSpec } from './adhoc-server.js';
|
||||
import { extractEphemeralServerFlags } from './ephemeral-flags.js';
|
||||
import { persistPreparedEphemeralServer, prepareEphemeralServerTarget } from './ephemeral-target.js';
|
||||
import { looksLikeHttpUrl } from './http-utils.js';
|
||||
import { buildConnectionIssueEnvelope } from './json-output.js';
|
||||
import { getActiveLogger, logInfo, logWarn } from './logger-context.js';
|
||||
import { consumeOutputFormat } from './output-format.js';
|
||||
|
||||
type Runtime = Awaited<ReturnType<typeof createRuntime>>;
|
||||
|
||||
type BrowserSuppression = 'default' | 'no-browser';
|
||||
|
||||
const TRUE_VALUES = new Set(['1', 'true', 'yes']);
|
||||
const FALSE_VALUES = new Set(['0', 'false', 'no']);
|
||||
|
||||
export async function handleAuth(runtime: Runtime, args: string[]): Promise<void> {
|
||||
const browserSuppression = consumeBrowserSuppression(args, process.env);
|
||||
const noBrowser = browserSuppression === 'no-browser';
|
||||
let authorizationOutputEmitted = false;
|
||||
const markAuthorizationOutputEmitted = () => {
|
||||
authorizationOutputEmitted = true;
|
||||
};
|
||||
const resetIndex = args.indexOf('--reset');
|
||||
const shouldReset = resetIndex !== -1;
|
||||
if (shouldReset) {
|
||||
args.splice(resetIndex, 1);
|
||||
}
|
||||
const format = consumeOutputFormat(args, {
|
||||
defaultFormat: 'text',
|
||||
allowed: ['text', 'json'],
|
||||
enableRawShortcut: false,
|
||||
jsonShortcutFlag: '--json',
|
||||
}) as 'text' | 'json';
|
||||
const ephemeralSpec: EphemeralServerSpec | undefined = extractEphemeralServerFlags(args);
|
||||
let target = args.shift();
|
||||
const nameHints: string[] = [];
|
||||
if (ephemeralSpec && target && !looksLikeHttpUrl(target)) {
|
||||
nameHints.push(target);
|
||||
}
|
||||
|
||||
const prepared = await prepareEphemeralServerTarget({
|
||||
runtime,
|
||||
target,
|
||||
ephemeral: ephemeralSpec,
|
||||
nameHints,
|
||||
reuseFromSpec: true,
|
||||
});
|
||||
target = prepared.target;
|
||||
|
||||
if (!target) {
|
||||
throw new Error('Usage: mcporter auth <server | url> [--http-url <url> | --stdio <command>]');
|
||||
}
|
||||
|
||||
const definition = runtime.getDefinition(target);
|
||||
if (shouldReset) {
|
||||
await clearOAuthCaches(definition);
|
||||
if (!noBrowser) {
|
||||
logInfo(`Cleared cached credentials for '${target}'.`);
|
||||
}
|
||||
}
|
||||
|
||||
if (definition.command.kind === 'stdio' && definition.oauthCommand) {
|
||||
logInfo(`Starting auth helper for '${target}' (stdio). Leave this running until the browser flow completes.`);
|
||||
try {
|
||||
await runStdioAuth(definition, { noBrowser });
|
||||
logInfo(`Auth helper for '${target}' finished. You can now call tools.`);
|
||||
} finally {
|
||||
await persistPreparedEphemeralServer(runtime, prepared);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
for (let attempt = 0; attempt < 2; attempt += 1) {
|
||||
try {
|
||||
if (!noBrowser) {
|
||||
logInfo(`Initiating OAuth flow for '${target}'...`);
|
||||
}
|
||||
const tools = await withInfoLogsSuppressed(noBrowser, () =>
|
||||
runtime.listTools(target, {
|
||||
autoAuthorize: true,
|
||||
...(noBrowser
|
||||
? {
|
||||
oauthSessionOptions: buildNoBrowserOAuthOptions(format, markAuthorizationOutputEmitted),
|
||||
}
|
||||
: {}),
|
||||
})
|
||||
);
|
||||
await persistPreparedEphemeralServer(runtime, prepared);
|
||||
if (!noBrowser) {
|
||||
logInfo(`Authorization complete. ${tools.length} tool${tools.length === 1 ? '' : 's'} available.`);
|
||||
}
|
||||
return;
|
||||
} catch (error) {
|
||||
await persistPreparedEphemeralServer(runtime, prepared);
|
||||
if (attempt === 0 && shouldRetryAuthError(error)) {
|
||||
logWarn('Server signaled OAuth after the initial attempt. Retrying with browser flow...');
|
||||
continue;
|
||||
}
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
if (format === 'json') {
|
||||
if (authorizationOutputEmitted) {
|
||||
console.error(`Failed to authorize '${target}': ${message}`);
|
||||
} else {
|
||||
const payload = buildConnectionIssueEnvelope({
|
||||
server: target,
|
||||
error,
|
||||
issue: analyzeConnectionError(error),
|
||||
});
|
||||
console.log(JSON.stringify(payload, null, 2));
|
||||
}
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
throw new Error(`Failed to authorize '${target}': ${message}`, { cause: error });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async function withInfoLogsSuppressed<T>(enabled: boolean, task: () => Promise<T>): Promise<T> {
|
||||
if (!enabled) {
|
||||
return task();
|
||||
}
|
||||
const logger = getActiveLogger();
|
||||
const originalInfo = logger.info.bind(logger);
|
||||
logger.info = () => {};
|
||||
try {
|
||||
return await task();
|
||||
} finally {
|
||||
logger.info = originalInfo;
|
||||
}
|
||||
}
|
||||
|
||||
async function runStdioAuth(definition: ServerDefinition, options: { noBrowser?: boolean } = {}): Promise<void> {
|
||||
const authArgs = [...(definition.command.kind === 'stdio' ? (definition.command.args ?? []) : [])];
|
||||
if (definition.oauthCommand) {
|
||||
authArgs.push(...definition.oauthCommand.args);
|
||||
}
|
||||
const env = options.noBrowser ? { ...process.env, MCPORTER_OAUTH_NO_BROWSER: '1' } : process.env;
|
||||
return new Promise((resolve, reject) => {
|
||||
const child = spawn(definition.command.kind === 'stdio' ? definition.command.command : '', authArgs, {
|
||||
stdio: 'inherit',
|
||||
cwd: definition.command.kind === 'stdio' ? definition.command.cwd : process.cwd(),
|
||||
env,
|
||||
});
|
||||
child.on('error', reject);
|
||||
child.on('exit', (code) => {
|
||||
if (code === 0) {
|
||||
resolve();
|
||||
} else {
|
||||
reject(new Error(`Auth helper exited with code ${code ?? 'null'}`));
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function buildNoBrowserOAuthOptions(
|
||||
format: 'text' | 'json',
|
||||
markAuthorizationOutputEmitted: () => void
|
||||
): OAuthSessionOptions {
|
||||
return {
|
||||
suppressBrowserLaunch: true,
|
||||
onAuthorizationUrl(request: OAuthAuthorizationRequest) {
|
||||
markAuthorizationOutputEmitted();
|
||||
if (format === 'json') {
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
authorizationUrl: request.authorizationUrl,
|
||||
redirectUrl: request.redirectUrl,
|
||||
},
|
||||
null,
|
||||
2
|
||||
)
|
||||
);
|
||||
return;
|
||||
}
|
||||
console.log(request.authorizationUrl);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function consumeBrowserSuppression(args: string[], env: NodeJS.ProcessEnv): BrowserSuppression {
|
||||
let mode = resolveBrowserSuppressionFromEnv(env.MCPORTER_OAUTH_NO_BROWSER);
|
||||
const noBrowserIndex = args.indexOf('--no-browser');
|
||||
if (noBrowserIndex !== -1) {
|
||||
args.splice(noBrowserIndex, 1);
|
||||
mode = 'no-browser';
|
||||
}
|
||||
const browserIndex = args.indexOf('--browser');
|
||||
if (browserIndex !== -1) {
|
||||
const value = args[browserIndex + 1];
|
||||
if (!value) {
|
||||
throw new Error("Flag '--browser' requires a value.");
|
||||
}
|
||||
if (value !== 'none') {
|
||||
throw new Error("--browser must be 'none' when provided to mcporter auth.");
|
||||
}
|
||||
args.splice(browserIndex, 2);
|
||||
mode = 'no-browser';
|
||||
}
|
||||
return mode;
|
||||
}
|
||||
|
||||
function resolveBrowserSuppressionFromEnv(raw: string | undefined): BrowserSuppression {
|
||||
if (raw === undefined) {
|
||||
return 'default';
|
||||
}
|
||||
const normalized = raw.trim().toLowerCase();
|
||||
if (!normalized || FALSE_VALUES.has(normalized)) {
|
||||
return 'default';
|
||||
}
|
||||
if (TRUE_VALUES.has(normalized)) {
|
||||
return 'no-browser';
|
||||
}
|
||||
return 'default';
|
||||
}
|
||||
|
||||
function shouldRetryAuthError(error: unknown): boolean {
|
||||
if (isOAuthFlowError(error)) {
|
||||
return false;
|
||||
}
|
||||
return analyzeConnectionError(error).kind === 'auth';
|
||||
}
|
||||
|
||||
export function printAuthHelp(): void {
|
||||
const lines = [
|
||||
'Usage: mcporter auth <server | url> [flags]',
|
||||
'',
|
||||
'Purpose:',
|
||||
' Run the authentication flow for a server without listing tools.',
|
||||
'',
|
||||
'Common flags:',
|
||||
' --reset Clear cached credentials before re-authorizing.',
|
||||
' --json Emit a JSON envelope on failure (and auth-start JSON with --no-browser).',
|
||||
' --no-browser Print the OAuth authorization URL without launching a browser.',
|
||||
' --browser none Alias for --no-browser (also supported by config login).',
|
||||
' MCPORTER_OAUTH_NO_BROWSER=1|true|yes also enables --no-browser behavior.',
|
||||
'',
|
||||
'Ad-hoc targets:',
|
||||
' --http-url <url> Register an HTTP server for this run.',
|
||||
' --allow-http Permit plain http:// URLs with --http-url.',
|
||||
' --header KEY=value Attach HTTP headers (repeatable).',
|
||||
' --stdio <command> Run a stdio MCP server (repeat --stdio-arg for args).',
|
||||
' --stdio-arg <value> Append args to the stdio command (repeatable).',
|
||||
' --env KEY=value Inject env vars for stdio servers (repeatable).',
|
||||
' --cwd <path> Working directory for stdio servers.',
|
||||
' --name <value> Override the display name for ad-hoc servers.',
|
||||
' --description <text> Override the description for ad-hoc servers.',
|
||||
' --persist <path> Write the ad-hoc definition to config/mcporter.json.',
|
||||
' --yes Skip confirmation prompts when persisting.',
|
||||
'',
|
||||
'Examples:',
|
||||
' mcporter auth linear',
|
||||
' mcporter auth linear --no-browser',
|
||||
' mcporter auth https://mcp.example.com/mcp',
|
||||
' mcporter auth --stdio "npx -y chrome-devtools-mcp@latest"',
|
||||
' mcporter auth --http-url http://localhost:3000/mcp --allow-http',
|
||||
];
|
||||
console.error(lines.join('\n'));
|
||||
}
|
||||
@ -1,61 +0,0 @@
|
||||
import { parseCallExpressionFragment } from './call-expression-parser.js';
|
||||
import { CliUsageError } from './errors.js';
|
||||
import { splitHttpToolSelector } from './http-utils.js';
|
||||
|
||||
type ParsedCallExpression = NonNullable<ReturnType<typeof parseCallExpressionFragment>>;
|
||||
|
||||
export function parseLeadingCallExpression(rawToken: string): ParsedCallExpression | null {
|
||||
try {
|
||||
return extractHttpCallExpression(rawToken) ?? parseCallExpressionFragment(rawToken);
|
||||
} catch (error) {
|
||||
throw buildCallExpressionUsageError(error);
|
||||
}
|
||||
}
|
||||
|
||||
function extractHttpCallExpression(raw: string): ParsedCallExpression | null {
|
||||
const trimmed = raw.trim();
|
||||
const openParen = trimmed.indexOf('(');
|
||||
const prefix = openParen === -1 ? trimmed : trimmed.slice(0, openParen);
|
||||
const split = splitHttpToolSelector(prefix);
|
||||
if (!split) {
|
||||
return null;
|
||||
}
|
||||
if (openParen === -1) {
|
||||
return { server: split.baseUrl, tool: split.tool, args: {} };
|
||||
}
|
||||
if (!trimmed.endsWith(')')) {
|
||||
throw new Error('Function-call syntax requires a closing ) character.');
|
||||
}
|
||||
const argsPortion = trimmed.slice(openParen);
|
||||
const parsed = parseCallExpressionFragment(`${split.tool}${argsPortion}`);
|
||||
if (!parsed) {
|
||||
return { server: split.baseUrl, tool: split.tool, args: {} };
|
||||
}
|
||||
return {
|
||||
server: split.baseUrl,
|
||||
tool: split.tool,
|
||||
args: parsed.args,
|
||||
positionalArgs: parsed.positionalArgs ?? [],
|
||||
};
|
||||
}
|
||||
|
||||
function buildCallExpressionUsageError(error: unknown): CliUsageError {
|
||||
const reason =
|
||||
error instanceof Error
|
||||
? error.message
|
||||
: typeof error === 'string'
|
||||
? error
|
||||
: JSON.stringify(error ?? 'Unknown error');
|
||||
const lines = [
|
||||
'Unable to parse function-style call.',
|
||||
`Reason: ${reason}`,
|
||||
'',
|
||||
'Examples:',
|
||||
' mcporter \'context7.resolve-library-id(query: "React hooks docs", libraryName: "react")\'',
|
||||
' mcporter \'context7.resolve-library-id("React hooks docs", "react")\'',
|
||||
' mcporter context7.resolve-library-id query="React hooks docs" libraryName=react',
|
||||
'',
|
||||
'Tip: wrap the entire expression in single quotes so the shell preserves parentheses and commas.',
|
||||
];
|
||||
return new CliUsageError(lines.join('\n'));
|
||||
}
|
||||
@ -1,96 +0,0 @@
|
||||
export type CoercionMode = 'default' | 'raw-strings' | 'none';
|
||||
|
||||
export interface ParsedKeyValueToken {
|
||||
key: string;
|
||||
rawValue: string;
|
||||
consumed: number;
|
||||
}
|
||||
|
||||
export function parseKeyValueToken(token: string, nextToken: string | undefined): ParsedKeyValueToken | undefined {
|
||||
const eqIndex = token.indexOf('=');
|
||||
if (eqIndex !== -1) {
|
||||
const keyEnd = eqIndex > 0 && token[eqIndex - 1] === ':' ? eqIndex - 1 : eqIndex;
|
||||
const key = token.slice(0, keyEnd);
|
||||
const rawValue = token.slice(eqIndex + 1);
|
||||
if (!key) {
|
||||
return undefined;
|
||||
}
|
||||
return { key, rawValue, consumed: 1 };
|
||||
}
|
||||
|
||||
const colonIndex = token.indexOf(':');
|
||||
if (colonIndex !== -1) {
|
||||
const key = token.slice(0, colonIndex);
|
||||
const remainder = token.slice(colonIndex + 1);
|
||||
if (!key) {
|
||||
return undefined;
|
||||
}
|
||||
if (remainder.length > 0) {
|
||||
return { key, rawValue: remainder, consumed: 1 };
|
||||
}
|
||||
if (nextToken !== undefined) {
|
||||
return { key, rawValue: nextToken, consumed: 2 };
|
||||
}
|
||||
warnMissingNamedArgumentValue(key);
|
||||
return { key, rawValue: '', consumed: 1 };
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
export function coerceValue(value: string, coercionMode: CoercionMode = 'default'): unknown {
|
||||
const trimmed = value.trim();
|
||||
if (trimmed === '') {
|
||||
return '';
|
||||
}
|
||||
if (coercionMode === 'none') {
|
||||
return trimmed;
|
||||
}
|
||||
if (trimmed === 'true' || trimmed === 'false') {
|
||||
return trimmed === 'true';
|
||||
}
|
||||
if (trimmed === 'null' || trimmed === 'none') {
|
||||
return null;
|
||||
}
|
||||
if (coercionMode === 'default' && !Number.isNaN(Number(trimmed)) && trimmed === `${Number(trimmed)}`) {
|
||||
return Number(trimmed);
|
||||
}
|
||||
if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
|
||||
try {
|
||||
return JSON.parse(trimmed);
|
||||
} catch {
|
||||
return trimmed;
|
||||
}
|
||||
}
|
||||
return trimmed;
|
||||
}
|
||||
|
||||
export function shouldPromoteSelectorToCommand(selector: string): boolean {
|
||||
const trimmed = selector.trim();
|
||||
if (!trimmed) {
|
||||
return false;
|
||||
}
|
||||
if (/\s/.test(trimmed)) {
|
||||
return true;
|
||||
}
|
||||
if (/^(?:\.{1,2}\/|~\/|\/)/.test(trimmed)) {
|
||||
return true;
|
||||
}
|
||||
if (/^[A-Za-z]:\\/.test(trimmed) || trimmed.startsWith('\\\\')) {
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function warnMissingNamedArgumentValue(key: string): void {
|
||||
const hint =
|
||||
key === 'command' ? `Example: mcporter call iterm-mcp.write_to_terminal --args '{"command":"echo hi"}'` : undefined;
|
||||
const lines = [
|
||||
`[mcporter] Argument '${key}' was provided without a value.`,
|
||||
`Wrap the entire key/value pair in quotes (e.g., 'command: "echo hi"') or use --args with JSON.`,
|
||||
];
|
||||
if (hint) {
|
||||
lines.push(hint);
|
||||
}
|
||||
console.warn(lines.join(' '));
|
||||
}
|
||||
@ -1,15 +1,8 @@
|
||||
import fs from 'node:fs';
|
||||
import type { EphemeralServerSpec } from './adhoc-server.js';
|
||||
import { parseLeadingCallExpression } from './call-argument-expression.js';
|
||||
import {
|
||||
type CoercionMode,
|
||||
coerceValue,
|
||||
parseKeyValueToken,
|
||||
shouldPromoteSelectorToCommand,
|
||||
} from './call-argument-values.js';
|
||||
import { buildUnknownCallFlagMessage } from './call-help.js';
|
||||
import { parseCallExpressionFragment } from './call-expression-parser.js';
|
||||
import { extractEphemeralServerFlags } from './ephemeral-flags.js';
|
||||
import { CliUsageError } from './errors.js';
|
||||
import { splitHttpToolSelector } from './http-utils.js';
|
||||
import { consumeOutputFormat } from './output-format.js';
|
||||
import type { OutputFormat } from './output-utils.js';
|
||||
import { consumeTimeoutFlag } from './timeouts.js';
|
||||
@ -19,75 +12,21 @@ export interface CallArgsParseResult {
|
||||
server?: string;
|
||||
tool?: string;
|
||||
args: Record<string, unknown>;
|
||||
schemaStringCoercionCandidates?: Record<string, string>;
|
||||
schemaArrayCoercionCandidates?: Record<string, string>;
|
||||
positionalArgs?: unknown[];
|
||||
tailLog: boolean;
|
||||
output: OutputFormat;
|
||||
timeoutMs?: number;
|
||||
disableOAuth?: boolean;
|
||||
ephemeral?: EphemeralServerSpec;
|
||||
rawStrings?: boolean;
|
||||
saveImagesDir?: string;
|
||||
}
|
||||
|
||||
interface FlagParseState {
|
||||
coercionMode: CoercionMode;
|
||||
}
|
||||
|
||||
interface FlagHandlerContext {
|
||||
args: string[];
|
||||
index: number;
|
||||
result: CallArgsParseResult;
|
||||
state: FlagParseState;
|
||||
}
|
||||
|
||||
type FlagHandler = (context: FlagHandlerContext) => number;
|
||||
|
||||
interface ScannedCallTokens {
|
||||
positional: string[];
|
||||
literalPositional: string[];
|
||||
}
|
||||
|
||||
interface CallExpressionResolution {
|
||||
callExpressionProvidedServer: boolean;
|
||||
callExpressionProvidedTool: boolean;
|
||||
}
|
||||
|
||||
const FLAG_HANDLERS: Record<string, FlagHandler> = {
|
||||
'--server': handleServerFlag,
|
||||
'--mcp': handleServerFlag,
|
||||
'--tool': handleToolFlag,
|
||||
'--timeout': handleTimeoutFlag,
|
||||
'--tail-log': handleTailLogFlag,
|
||||
'--no-oauth': handleDisableOAuthFlag,
|
||||
'--save-images': handleSaveImagesFlag,
|
||||
'--yes': handleNoopFlag,
|
||||
'--raw-strings': handleRawStringsFlag,
|
||||
'--no-coerce': handleNoCoerceFlag,
|
||||
'--args': handleArgsFlag,
|
||||
'--json': handleJsonArgsFlag,
|
||||
};
|
||||
|
||||
export function parseCallArguments(args: string[]): CallArgsParseResult {
|
||||
const result: CallArgsParseResult = { args: {}, tailLog: false, output: 'auto' };
|
||||
const flagState: FlagParseState = { coercionMode: 'default' };
|
||||
const ephemeral = extractEphemeralServerFlags(args);
|
||||
result.ephemeral = ephemeral;
|
||||
result.output = consumeOutputFormat(args, {
|
||||
defaultFormat: 'auto',
|
||||
});
|
||||
const { positional, literalPositional } = scanCallTokens(args, result, flagState);
|
||||
const { callExpressionProvidedServer, callExpressionProvidedTool } = applyLeadingCallExpression(positional, result);
|
||||
resolveSelectorAndTool(positional, result, callExpressionProvidedServer, callExpressionProvidedTool);
|
||||
applyTrailingArguments(positional, result, flagState);
|
||||
appendLiteralPositionalArguments(literalPositional, result, flagState);
|
||||
return result;
|
||||
}
|
||||
|
||||
function scanCallTokens(args: string[], result: CallArgsParseResult, state: FlagParseState): ScannedCallTokens {
|
||||
const positional: string[] = [];
|
||||
const literalPositional: string[] = [];
|
||||
let index = 0;
|
||||
while (index < args.length) {
|
||||
const token = args[index];
|
||||
@ -95,77 +34,120 @@ function scanCallTokens(args: string[], result: CallArgsParseResult, state: Flag
|
||||
index += 1;
|
||||
continue;
|
||||
}
|
||||
if (token === '--') {
|
||||
literalPositional.push(...args.slice(index + 1).filter(Boolean));
|
||||
break;
|
||||
}
|
||||
const flagHandler = FLAG_HANDLERS[token];
|
||||
if (flagHandler) {
|
||||
index = flagHandler({ args, index, result, state });
|
||||
if (token === '--server' || token === '--mcp') {
|
||||
const value = args[index + 1];
|
||||
if (!value) {
|
||||
throw new Error(`Flag '${token}' requires a value.`);
|
||||
}
|
||||
result.server = value;
|
||||
index += 2;
|
||||
continue;
|
||||
}
|
||||
if (token.startsWith('--')) {
|
||||
index = handleNamedArgumentFlag({ args, index, result, state });
|
||||
if (token === '--tool') {
|
||||
const value = args[index + 1];
|
||||
if (!value) {
|
||||
throw new Error(`Flag '${token}' requires a value.`);
|
||||
}
|
||||
result.tool = value;
|
||||
index += 2;
|
||||
continue;
|
||||
}
|
||||
if (token === '--timeout') {
|
||||
result.timeoutMs = consumeTimeoutFlag(args, index, {
|
||||
flagName: '--timeout',
|
||||
missingValueMessage: '--timeout requires a value (milliseconds).',
|
||||
});
|
||||
continue;
|
||||
}
|
||||
if (token === '--tail-log') {
|
||||
result.tailLog = true;
|
||||
index += 1;
|
||||
continue;
|
||||
}
|
||||
if (token === '--yes') {
|
||||
index += 1;
|
||||
continue;
|
||||
}
|
||||
if (token === '--args') {
|
||||
const value = args[index + 1];
|
||||
if (!value) {
|
||||
throw new Error('--args requires a JSON value.');
|
||||
}
|
||||
try {
|
||||
const decoded = JSON.parse(value);
|
||||
if (decoded === null || typeof decoded !== 'object' || Array.isArray(decoded)) {
|
||||
throw new Error('--args must be a JSON object.');
|
||||
}
|
||||
Object.assign(result.args, decoded);
|
||||
} catch (error) {
|
||||
throw new Error(`Unable to parse --args: ${(error as Error).message}`);
|
||||
}
|
||||
index += 2;
|
||||
continue;
|
||||
}
|
||||
positional.push(token);
|
||||
index += 1;
|
||||
}
|
||||
return { positional, literalPositional };
|
||||
}
|
||||
|
||||
function applyLeadingCallExpression(positional: string[], result: CallArgsParseResult): CallExpressionResolution {
|
||||
if (positional.length === 0) {
|
||||
return { callExpressionProvidedServer: false, callExpressionProvidedTool: false };
|
||||
}
|
||||
const rawToken = positional[0] ?? '';
|
||||
const callExpression = parseLeadingCallExpression(rawToken);
|
||||
if (!callExpression) {
|
||||
return { callExpressionProvidedServer: false, callExpressionProvidedTool: false };
|
||||
}
|
||||
positional.shift();
|
||||
if (callExpression.server) {
|
||||
if (result.server && result.server !== callExpression.server) {
|
||||
throw new Error(
|
||||
`Conflicting server names: '${result.server}' from flags and '${callExpression.server}' from call expression.`
|
||||
);
|
||||
let callExpressionProvidedServer = false;
|
||||
let callExpressionProvidedTool = false;
|
||||
|
||||
if (positional.length > 0) {
|
||||
const rawToken = positional[0] ?? '';
|
||||
let callExpression: ReturnType<typeof parseCallExpressionFragment> | null = null;
|
||||
try {
|
||||
callExpression = extractHttpCallExpression(rawToken);
|
||||
} catch (error) {
|
||||
throw buildCallExpressionUsageError(error);
|
||||
}
|
||||
if (!callExpression) {
|
||||
try {
|
||||
callExpression = parseCallExpressionFragment(rawToken);
|
||||
} catch (error) {
|
||||
throw buildCallExpressionUsageError(error);
|
||||
}
|
||||
}
|
||||
if (callExpression) {
|
||||
positional.shift();
|
||||
callExpressionProvidedServer = Boolean(callExpression.server);
|
||||
callExpressionProvidedTool = Boolean(callExpression.tool);
|
||||
if (callExpression.server) {
|
||||
if (result.server && result.server !== callExpression.server) {
|
||||
throw new Error(
|
||||
`Conflicting server names: '${result.server}' from flags and '${callExpression.server}' from call expression.`
|
||||
);
|
||||
}
|
||||
result.server = result.server ?? callExpression.server;
|
||||
}
|
||||
if (result.tool && result.tool !== callExpression.tool) {
|
||||
throw new Error(
|
||||
`Conflicting tool names: '${result.tool}' from flags and '${callExpression.tool}' from call expression.`
|
||||
);
|
||||
}
|
||||
result.tool = callExpression.tool;
|
||||
Object.assign(result.args, callExpression.args);
|
||||
if (callExpression.positionalArgs && callExpression.positionalArgs.length > 0) {
|
||||
result.positionalArgs = [...(result.positionalArgs ?? []), ...callExpression.positionalArgs];
|
||||
}
|
||||
}
|
||||
result.server = result.server ?? callExpression.server;
|
||||
}
|
||||
if (result.tool && result.tool !== callExpression.tool) {
|
||||
throw new Error(
|
||||
`Conflicting tool names: '${result.tool}' from flags and '${callExpression.tool}' from call expression.`
|
||||
);
|
||||
}
|
||||
result.tool = callExpression.tool;
|
||||
Object.assign(result.args, callExpression.args);
|
||||
if (callExpression.positionalArgs && callExpression.positionalArgs.length > 0) {
|
||||
result.positionalArgs = [...(result.positionalArgs ?? []), ...callExpression.positionalArgs];
|
||||
}
|
||||
return {
|
||||
callExpressionProvidedServer: Boolean(callExpression.server),
|
||||
callExpressionProvidedTool: Boolean(callExpression.tool),
|
||||
};
|
||||
}
|
||||
|
||||
function resolveSelectorAndTool(
|
||||
positional: string[],
|
||||
result: CallArgsParseResult,
|
||||
callExpressionProvidedServer: boolean,
|
||||
callExpressionProvidedTool: boolean
|
||||
): void {
|
||||
if (!result.selector && positional.length > 0 && !callExpressionProvidedServer && !result.server) {
|
||||
result.selector = positional.shift();
|
||||
}
|
||||
|
||||
if (
|
||||
!result.server &&
|
||||
result.selector &&
|
||||
shouldPromoteSelectorToCommand(result.selector) &&
|
||||
!result.ephemeral?.stdioCommand
|
||||
) {
|
||||
// Treat the first positional token as an ad-hoc stdio command when it looks like
|
||||
// `npx ...`/`./script`/etc., so users can skip `--stdio` entirely.
|
||||
result.ephemeral = { ...result.ephemeral, stdioCommand: result.selector };
|
||||
result.selector = undefined;
|
||||
}
|
||||
|
||||
const nextPositional = positional[0];
|
||||
if (
|
||||
!result.tool &&
|
||||
@ -176,9 +158,7 @@ function resolveSelectorAndTool(
|
||||
) {
|
||||
result.tool = positional.shift();
|
||||
}
|
||||
}
|
||||
|
||||
function applyTrailingArguments(positional: string[], result: CallArgsParseResult, state: FlagParseState): void {
|
||||
const trailingPositional: unknown[] = [];
|
||||
for (let index = 0; index < positional.length; ) {
|
||||
const token = positional[index];
|
||||
@ -188,12 +168,12 @@ function applyTrailingArguments(positional: string[], result: CallArgsParseResul
|
||||
}
|
||||
const parsed = parseKeyValueToken(token, positional[index + 1]);
|
||||
if (!parsed) {
|
||||
trailingPositional.push(coerceValue(token, state.coercionMode));
|
||||
trailingPositional.push(coerceValue(token));
|
||||
index += 1;
|
||||
continue;
|
||||
}
|
||||
index += parsed.consumed;
|
||||
const { value, schemaValue } = resolveNamedArgumentValue(parsed.rawValue, state.coercionMode);
|
||||
const value = coerceValue(parsed.rawValue);
|
||||
if (parsed.key === 'tool' && !result.tool) {
|
||||
if (typeof value !== 'string') {
|
||||
throw new Error("Argument 'tool' must be a string value.");
|
||||
@ -208,183 +188,149 @@ function applyTrailingArguments(positional: string[], result: CallArgsParseResul
|
||||
result.server = value as string;
|
||||
continue;
|
||||
}
|
||||
if (state.coercionMode === 'default' && typeof value === 'number') {
|
||||
result.schemaStringCoercionCandidates ??= {};
|
||||
result.schemaStringCoercionCandidates[parsed.key] = schemaValue;
|
||||
}
|
||||
result.args[parsed.key] = value;
|
||||
}
|
||||
if (trailingPositional.length > 0) {
|
||||
result.positionalArgs = [...(result.positionalArgs ?? []), ...trailingPositional];
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
function appendLiteralPositionalArguments(
|
||||
literalPositional: string[],
|
||||
result: CallArgsParseResult,
|
||||
state: FlagParseState
|
||||
): void {
|
||||
if (literalPositional.length === 0) {
|
||||
return;
|
||||
interface ParsedKeyValueToken {
|
||||
key: string;
|
||||
rawValue: string;
|
||||
consumed: number;
|
||||
}
|
||||
|
||||
function parseKeyValueToken(token: string, nextToken: string | undefined): ParsedKeyValueToken | undefined {
|
||||
const eqIndex = token.indexOf('=');
|
||||
if (eqIndex !== -1) {
|
||||
const key = token.slice(0, eqIndex);
|
||||
const rawValue = token.slice(eqIndex + 1);
|
||||
if (!key) {
|
||||
return undefined;
|
||||
}
|
||||
return { key, rawValue, consumed: 1 };
|
||||
}
|
||||
result.positionalArgs = [
|
||||
...(result.positionalArgs ?? []),
|
||||
...literalPositional.map((token) => coerceValue(token, state.coercionMode)),
|
||||
|
||||
const colonIndex = token.indexOf(':');
|
||||
if (colonIndex !== -1) {
|
||||
const key = token.slice(0, colonIndex);
|
||||
const remainder = token.slice(colonIndex + 1);
|
||||
if (!key) {
|
||||
return undefined;
|
||||
}
|
||||
if (remainder.length > 0) {
|
||||
return { key, rawValue: remainder, consumed: 1 };
|
||||
}
|
||||
if (nextToken !== undefined) {
|
||||
return { key, rawValue: nextToken, consumed: 2 };
|
||||
}
|
||||
warnMissingNamedArgumentValue(key);
|
||||
return { key, rawValue: '', consumed: 1 };
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function warnMissingNamedArgumentValue(key: string): void {
|
||||
const hint =
|
||||
key === 'command' ? `Example: mcporter call iterm-mcp.write_to_terminal --args '{"command":"echo hi"}'` : undefined;
|
||||
const lines = [
|
||||
`[mcporter] Argument '${key}' was provided without a value.`,
|
||||
`Wrap the entire key/value pair in quotes (e.g., 'command: "echo hi"') or use --args with JSON.`,
|
||||
];
|
||||
}
|
||||
|
||||
function handleServerFlag(context: FlagHandlerContext): number {
|
||||
const token = context.args[context.index] ?? '--server';
|
||||
context.result.server = consumeFlagValue(context.args, context.index, token);
|
||||
return context.index + 2;
|
||||
}
|
||||
|
||||
function handleToolFlag(context: FlagHandlerContext): number {
|
||||
context.result.tool = consumeFlagValue(context.args, context.index, '--tool');
|
||||
return context.index + 2;
|
||||
}
|
||||
|
||||
function handleTimeoutFlag(context: FlagHandlerContext): number {
|
||||
context.result.timeoutMs = consumeTimeoutFlag(context.args, context.index, {
|
||||
flagName: '--timeout',
|
||||
missingValueMessage: '--timeout requires a value (milliseconds).',
|
||||
});
|
||||
// consumeTimeoutFlag removes the flag/value pair in-place; stay on the same index.
|
||||
return context.index;
|
||||
}
|
||||
|
||||
function handleTailLogFlag(context: FlagHandlerContext): number {
|
||||
context.result.tailLog = true;
|
||||
return context.index + 1;
|
||||
}
|
||||
|
||||
function handleDisableOAuthFlag(context: FlagHandlerContext): number {
|
||||
context.result.disableOAuth = true;
|
||||
return context.index + 1;
|
||||
}
|
||||
|
||||
function handleSaveImagesFlag(context: FlagHandlerContext): number {
|
||||
context.result.saveImagesDir = consumeFlagValue(
|
||||
context.args,
|
||||
context.index,
|
||||
'--save-images',
|
||||
'--save-images requires a directory path.'
|
||||
);
|
||||
return context.index + 2;
|
||||
}
|
||||
|
||||
function handleNoopFlag(context: FlagHandlerContext): number {
|
||||
return context.index + 1;
|
||||
}
|
||||
|
||||
function handleRawStringsFlag(context: FlagHandlerContext): number {
|
||||
context.state.coercionMode = 'raw-strings';
|
||||
context.result.rawStrings = true;
|
||||
return context.index + 1;
|
||||
}
|
||||
|
||||
function handleNoCoerceFlag(context: FlagHandlerContext): number {
|
||||
context.state.coercionMode = 'none';
|
||||
context.result.rawStrings = true;
|
||||
return context.index + 1;
|
||||
}
|
||||
|
||||
function handleArgsFlag(context: FlagHandlerContext): number {
|
||||
return consumeJsonArgsFlag(context, '--args', '--args requires a JSON value.');
|
||||
}
|
||||
|
||||
function handleJsonArgsFlag(context: FlagHandlerContext): number {
|
||||
return consumeJsonArgsFlag(context, '--json', '--json requires a JSON object value.');
|
||||
}
|
||||
|
||||
function consumeJsonArgsFlag(context: FlagHandlerContext, flagName: string, missingValueMessage: string): number {
|
||||
const rawFlagValue = consumeFlagValue(context.args, context.index, flagName, missingValueMessage);
|
||||
const raw = rawFlagValue === '-' ? fs.readFileSync(0, 'utf8') : rawFlagValue;
|
||||
let decoded: unknown;
|
||||
try {
|
||||
decoded = JSON.parse(raw);
|
||||
} catch (error) {
|
||||
throw new Error(`Unable to parse ${flagName}: ${(error as Error).message}`, { cause: error });
|
||||
if (hint) {
|
||||
lines.push(hint);
|
||||
}
|
||||
if (decoded === null || typeof decoded !== 'object' || Array.isArray(decoded)) {
|
||||
throw new Error(`Unable to parse ${flagName}: ${flagName} must be a JSON object.`);
|
||||
}
|
||||
Object.assign(context.result.args, decoded);
|
||||
return context.index + 2;
|
||||
console.warn(lines.join(' '));
|
||||
}
|
||||
|
||||
function handleNamedArgumentFlag(context: FlagHandlerContext): number {
|
||||
const token = context.args[context.index] ?? '';
|
||||
const body = token.slice(2);
|
||||
const eqIndex = body.indexOf('=');
|
||||
const rawKey = eqIndex === -1 ? body : body.slice(0, eqIndex);
|
||||
const key = normalizeLongFlagArgumentKey(rawKey);
|
||||
if (!key) {
|
||||
throw new CliUsageError(buildUnknownCallFlagMessage(token));
|
||||
function extractHttpCallExpression(raw: string): ReturnType<typeof parseCallExpressionFragment> | null {
|
||||
const trimmed = raw.trim();
|
||||
const openParen = trimmed.indexOf('(');
|
||||
const prefix = openParen === -1 ? trimmed : trimmed.slice(0, openParen);
|
||||
const split = splitHttpToolSelector(prefix);
|
||||
if (!split) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const rawValue =
|
||||
eqIndex === -1
|
||||
? consumeFlagValue(context.args, context.index, token, `Flag '${token}' requires a value.`)
|
||||
: body.slice(eqIndex + 1);
|
||||
const { value, schemaValue } = resolveNamedArgumentValue(rawValue, context.state.coercionMode);
|
||||
if (context.state.coercionMode === 'default' && typeof value === 'number') {
|
||||
context.result.schemaStringCoercionCandidates ??= {};
|
||||
context.result.schemaStringCoercionCandidates[key] = schemaValue;
|
||||
} else if (context.state.coercionMode === 'default' && typeof value === 'string') {
|
||||
context.result.schemaArrayCoercionCandidates ??= {};
|
||||
context.result.schemaArrayCoercionCandidates[key] = schemaValue;
|
||||
if (openParen === -1) {
|
||||
return { server: split.baseUrl, tool: split.tool, args: {} };
|
||||
}
|
||||
context.result.args[key] = value;
|
||||
return context.index + (eqIndex === -1 ? 2 : 1);
|
||||
if (!trimmed.endsWith(')')) {
|
||||
throw new Error('Function-call syntax requires a closing ) character.');
|
||||
}
|
||||
const argsPortion = trimmed.slice(openParen);
|
||||
const parsed = parseCallExpressionFragment(`${split.tool}${argsPortion}`);
|
||||
if (!parsed) {
|
||||
return { server: split.baseUrl, tool: split.tool, args: {} };
|
||||
}
|
||||
return {
|
||||
server: split.baseUrl,
|
||||
tool: split.tool,
|
||||
args: parsed.args,
|
||||
positionalArgs: parsed.positionalArgs ?? [],
|
||||
};
|
||||
}
|
||||
|
||||
function resolveNamedArgumentValue(
|
||||
rawValue: string,
|
||||
coercionMode: CoercionMode
|
||||
): { value: unknown; schemaValue: string } {
|
||||
if (rawValue.startsWith('@@')) {
|
||||
const literal = rawValue.slice(1);
|
||||
return { value: literal, schemaValue: literal };
|
||||
}
|
||||
if (rawValue.length > 0 && rawValue.trim() === '') {
|
||||
return { value: rawValue, schemaValue: rawValue };
|
||||
}
|
||||
if (!rawValue.startsWith('@')) {
|
||||
return { value: coerceValue(rawValue, coercionMode), schemaValue: rawValue };
|
||||
}
|
||||
|
||||
const filePath = rawValue.slice(1);
|
||||
if (!filePath) {
|
||||
throw new CliUsageError("Argument file reference '@' requires a path. Use '@@' for a literal leading '@'.");
|
||||
}
|
||||
|
||||
let contents: Buffer;
|
||||
try {
|
||||
contents = fs.readFileSync(filePath);
|
||||
} catch (error) {
|
||||
const detail = error instanceof Error ? error.message : String(error);
|
||||
throw new CliUsageError(`Unable to read argument file '${filePath}': ${detail}`);
|
||||
}
|
||||
try {
|
||||
const text = new TextDecoder('utf-8', { fatal: true }).decode(contents);
|
||||
return { value: text, schemaValue: text };
|
||||
} catch {
|
||||
throw new CliUsageError(`Argument file '${filePath}' is not valid UTF-8 text.`);
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeLongFlagArgumentKey(rawKey: string): string {
|
||||
if (!rawKey || rawKey.startsWith('-')) {
|
||||
function coerceValue(value: string): unknown {
|
||||
const trimmed = value.trim();
|
||||
if (trimmed === '') {
|
||||
return '';
|
||||
}
|
||||
return rawKey.replace(/-([a-zA-Z0-9])/g, (_match, char: string) => char.toUpperCase());
|
||||
if (trimmed === 'true' || trimmed === 'false') {
|
||||
return trimmed === 'true';
|
||||
}
|
||||
if (trimmed === 'null' || trimmed === 'none') {
|
||||
return null;
|
||||
}
|
||||
if (!Number.isNaN(Number(trimmed)) && trimmed === `${Number(trimmed)}`) {
|
||||
return Number(trimmed);
|
||||
}
|
||||
if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
|
||||
try {
|
||||
return JSON.parse(trimmed);
|
||||
} catch {
|
||||
return trimmed;
|
||||
}
|
||||
}
|
||||
return trimmed;
|
||||
}
|
||||
|
||||
function consumeFlagValue(args: string[], index: number, token: string, missingValueMessage?: string): string {
|
||||
const value = args[index + 1];
|
||||
if (value) {
|
||||
return value;
|
||||
}
|
||||
throw new Error(missingValueMessage ?? `Flag '${token}' requires a value.`);
|
||||
function buildCallExpressionUsageError(error: unknown): CliUsageError {
|
||||
const reason =
|
||||
error instanceof Error
|
||||
? error.message
|
||||
: typeof error === 'string'
|
||||
? error
|
||||
: JSON.stringify(error ?? 'Unknown error');
|
||||
const lines = [
|
||||
'Unable to parse function-style call.',
|
||||
`Reason: ${reason}`,
|
||||
'',
|
||||
'Examples:',
|
||||
' mcporter \'context7.resolve-library-id(libraryName: "react")\'',
|
||||
' mcporter \'context7.resolve-library-id("react")\'',
|
||||
' mcporter context7.resolve-library-id libraryName=react',
|
||||
'',
|
||||
'Tip: wrap the entire expression in single quotes so the shell preserves parentheses and commas.',
|
||||
];
|
||||
return new CliUsageError(lines.join('\n'));
|
||||
}
|
||||
|
||||
function shouldPromoteSelectorToCommand(selector: string): boolean {
|
||||
const trimmed = selector.trim();
|
||||
if (!trimmed) {
|
||||
return false;
|
||||
}
|
||||
if (/\s/.test(trimmed)) {
|
||||
return true;
|
||||
}
|
||||
if (/^(?:\.{1,2}\/|~\/|\/)/.test(trimmed)) {
|
||||
return true;
|
||||
}
|
||||
if (/^[A-Za-z]:\\/.test(trimmed) || trimmed.startsWith('\\\\')) {
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
@ -1,17 +1,7 @@
|
||||
import { analyzeConnectionError, type ConnectionIssue } from '../error-classifier.js';
|
||||
import { wrapCallResult } from '../result-utils.js';
|
||||
import { type CallArgsParseResult, parseCallArguments } from './call-arguments.js';
|
||||
import {
|
||||
CALL_HELP_ADHOC_SERVER_LINES,
|
||||
CALL_HELP_ARGUMENT_LINES,
|
||||
CALL_HELP_EXAMPLE_LINES,
|
||||
CALL_HELP_RUNTIME_FLAG_LINES,
|
||||
} from './call-help.js';
|
||||
import {
|
||||
persistPreparedEphemeralServer,
|
||||
prepareEphemeralServerTarget,
|
||||
type PrepareEphemeralServerTargetResult,
|
||||
} from './ephemeral-target.js';
|
||||
import { prepareEphemeralServerTarget } from './ephemeral-target.js';
|
||||
import { looksLikeHttpUrl, normalizeHttpUrlCandidate } from './http-utils.js';
|
||||
import type { IdentifierResolution } from './identifier-helpers.js';
|
||||
import {
|
||||
@ -19,8 +9,8 @@ import {
|
||||
normalizeIdentifier,
|
||||
renderIdentifierResolutionMessages,
|
||||
} from './identifier-helpers.js';
|
||||
import { saveCallImagesIfRequested } from './image-output.js';
|
||||
import { buildConnectionIssueEnvelope } from './json-output.js';
|
||||
import { handleList } from './list-command.js';
|
||||
import type { OutputFormat } from './output-utils.js';
|
||||
import { printCallOutput, tailLogIfRequested } from './output-utils.js';
|
||||
import { dumpActiveHandles } from './runtime-debug.js';
|
||||
@ -28,84 +18,13 @@ import { dimText, redText, yellowText } from './terminal.js';
|
||||
import { resolveCallTimeout, withTimeout } from './timeouts.js';
|
||||
import { loadToolMetadata } from './tool-cache.js';
|
||||
|
||||
type Runtime = Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>;
|
||||
|
||||
interface ResolvedCallTarget {
|
||||
server: string;
|
||||
tool: string;
|
||||
}
|
||||
|
||||
interface PreparedCallRequest extends ResolvedCallTarget {
|
||||
parsed: CallArgsParseResult;
|
||||
hydratedArgs: Record<string, unknown>;
|
||||
timeoutMs: number;
|
||||
disableOAuth?: boolean;
|
||||
ephemeralTarget?: PrepareEphemeralServerTargetResult;
|
||||
}
|
||||
|
||||
export async function handleCall(runtime: Runtime, args: string[]): Promise<void> {
|
||||
let prepared: PreparedCallRequest | undefined;
|
||||
try {
|
||||
prepared = await prepareCallRequest(runtime, args);
|
||||
if (!prepared) {
|
||||
return;
|
||||
}
|
||||
|
||||
const invocation = await invokePreparedCall(runtime, prepared);
|
||||
if (!invocation) {
|
||||
return;
|
||||
}
|
||||
|
||||
renderCallResult(invocation.result, prepared.parsed);
|
||||
} finally {
|
||||
await persistPreparedEphemeralServer(runtime, prepared?.ephemeralTarget);
|
||||
}
|
||||
}
|
||||
|
||||
async function prepareCallRequest(runtime: Runtime, args: string[]): Promise<PreparedCallRequest | undefined> {
|
||||
export async function handleCall(
|
||||
runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
|
||||
args: string[]
|
||||
): Promise<void> {
|
||||
const parsed = parseCallArguments(args);
|
||||
const ephemeralTarget = await normalizeParsedCallArguments(runtime, parsed);
|
||||
const { server, tool } = await resolveServerAndTool(runtime, parsed);
|
||||
|
||||
if (await maybeDescribeServer(runtime, server, tool, parsed.output, parsed.disableOAuth)) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const timeoutMs = resolveCallTimeout(parsed.timeoutMs);
|
||||
const hydratedArgs = await hydratePositionalArguments(
|
||||
runtime,
|
||||
server,
|
||||
tool,
|
||||
parsed.args,
|
||||
parsed.positionalArgs,
|
||||
parsed.disableOAuth
|
||||
);
|
||||
const schemaAwareArgs = await enforceSchemaAwareArgumentTypes(
|
||||
runtime,
|
||||
server,
|
||||
tool,
|
||||
hydratedArgs,
|
||||
parsed.schemaStringCoercionCandidates,
|
||||
parsed.schemaArrayCoercionCandidates,
|
||||
timeoutMs,
|
||||
parsed.disableOAuth
|
||||
);
|
||||
return {
|
||||
parsed,
|
||||
server,
|
||||
tool,
|
||||
hydratedArgs: schemaAwareArgs,
|
||||
timeoutMs,
|
||||
disableOAuth: parsed.disableOAuth,
|
||||
ephemeralTarget,
|
||||
};
|
||||
}
|
||||
|
||||
async function normalizeParsedCallArguments(
|
||||
runtime: Runtime,
|
||||
parsed: CallArgsParseResult
|
||||
): Promise<PrepareEphemeralServerTargetResult> {
|
||||
let ephemeralSpec = parsed.ephemeral ? { ...parsed.ephemeral } : undefined;
|
||||
|
||||
const nameHints: string[] = [];
|
||||
const absorbUrlCandidate = (value: string | undefined): string | undefined => {
|
||||
if (!value) {
|
||||
@ -151,10 +70,7 @@ async function normalizeParsedCallArguments(
|
||||
if (!parsed.selector) {
|
||||
parsed.selector = prepared.target;
|
||||
}
|
||||
return prepared;
|
||||
}
|
||||
|
||||
async function resolveServerAndTool(runtime: Runtime, parsed: CallArgsParseResult): Promise<ResolvedCallTarget> {
|
||||
const target = resolveCallTarget(parsed, { allowMissingTool: true });
|
||||
const server = target.server;
|
||||
let tool = target.tool;
|
||||
@ -162,57 +78,39 @@ async function resolveServerAndTool(runtime: Runtime, parsed: CallArgsParseResul
|
||||
throw new Error('Missing server name. Provide it via <server>.<tool> or --server.');
|
||||
}
|
||||
if (!tool) {
|
||||
tool = await inferSingleToolName(runtime, server, parsed.disableOAuth);
|
||||
tool = await inferSingleToolName(runtime, server);
|
||||
if (!tool) {
|
||||
throw new Error('Missing tool name. Provide it via <server>.<tool> or --tool.');
|
||||
}
|
||||
}
|
||||
return { server, tool };
|
||||
}
|
||||
|
||||
async function invokePreparedCall(
|
||||
runtime: Runtime,
|
||||
prepared: PreparedCallRequest
|
||||
): Promise<{ result: unknown; resolvedTool: string } | undefined> {
|
||||
if (await maybeDescribeServer(runtime, server, tool, parsed.output)) {
|
||||
return;
|
||||
}
|
||||
|
||||
const timeoutMs = resolveCallTimeout(parsed.timeoutMs);
|
||||
const hydratedArgs = await hydratePositionalArguments(runtime, server, tool, parsed.args, parsed.positionalArgs);
|
||||
let invocation: { result: unknown; resolvedTool: string };
|
||||
try {
|
||||
invocation = await invokeWithAutoCorrection(
|
||||
runtime,
|
||||
prepared.server,
|
||||
prepared.tool,
|
||||
prepared.hydratedArgs,
|
||||
prepared.timeoutMs,
|
||||
prepared.parsed.output,
|
||||
prepared.disableOAuth
|
||||
);
|
||||
invocation = await invokeWithAutoCorrection(runtime, server, tool, hydratedArgs, timeoutMs);
|
||||
} catch (error) {
|
||||
const issue = maybeReportConnectionIssue(prepared.server, prepared.tool, error);
|
||||
if (prepared.parsed.output === 'json' || prepared.parsed.output === 'raw') {
|
||||
const payload = buildConnectionIssueEnvelope({ server: prepared.server, tool: prepared.tool, error, issue });
|
||||
const issue = maybeReportConnectionIssue(server, tool, error);
|
||||
if (parsed.output === 'json' || parsed.output === 'raw') {
|
||||
const payload = buildConnectionIssueEnvelope({ server, tool, error, issue });
|
||||
console.log(JSON.stringify(payload, null, 2));
|
||||
process.exitCode = 1;
|
||||
return undefined;
|
||||
return;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
return invocation;
|
||||
}
|
||||
const { result } = invocation;
|
||||
|
||||
function renderCallResult(result: unknown, parsed: CallArgsParseResult): void {
|
||||
const { callResult: wrapped } = wrapCallResult(result);
|
||||
if (isErrorCallResult(result)) {
|
||||
process.exitCode = 1;
|
||||
}
|
||||
printCallOutput(wrapped, result, parsed.output);
|
||||
saveCallImagesIfRequested(wrapped, parsed.saveImagesDir);
|
||||
tailLogIfRequested(result, parsed.tailLog);
|
||||
dumpActiveHandles('after call (formatted result)');
|
||||
}
|
||||
|
||||
function isErrorCallResult(result: unknown): boolean {
|
||||
return !!result && typeof result === 'object' && (result as { isError?: unknown }).isError === true;
|
||||
}
|
||||
|
||||
export function printCallHelp(): void {
|
||||
const lines = [
|
||||
'Usage: mcporter call <server.tool | url> [arguments] [flags]',
|
||||
@ -224,46 +122,56 @@ export function printCallHelp(): void {
|
||||
' --tool <name> Override the tool name.',
|
||||
'',
|
||||
'Arguments:',
|
||||
...CALL_HELP_ARGUMENT_LINES,
|
||||
' key=value / key:value Flag-style named arguments.',
|
||||
' function-call syntax \'server.tool(arg: "value", other: 1)\'.',
|
||||
' --args <json> Provide a JSON object payload.',
|
||||
' positional values Accepted when schema order is known.',
|
||||
'',
|
||||
'Runtime flags:',
|
||||
...CALL_HELP_RUNTIME_FLAG_LINES,
|
||||
' --timeout <ms> Override the call timeout.',
|
||||
' --output text|markdown|json|raw Control formatting.',
|
||||
' --tail-log Stream returned log handles.',
|
||||
'',
|
||||
'Ad-hoc servers:',
|
||||
...CALL_HELP_ADHOC_SERVER_LINES,
|
||||
' --http-url <url> Register an HTTP server for this run.',
|
||||
' --allow-http Permit plain http:// URLs with --http-url.',
|
||||
' --stdio <command> Run a stdio MCP server (repeat --stdio-arg for args).',
|
||||
' --stdio-arg <value> Append args to the stdio command (repeatable).',
|
||||
' --env KEY=value Inject env vars for stdio servers (repeatable).',
|
||||
' --cwd <path> Working directory for stdio servers.',
|
||||
' --name <value> Override the display name for ad-hoc servers.',
|
||||
' --description <text> Override the description for ad-hoc servers.',
|
||||
' --persist <path> Write the ad-hoc definition to config/mcporter.json.',
|
||||
' --yes Skip confirmation prompts when persisting.',
|
||||
'',
|
||||
'Examples:',
|
||||
...CALL_HELP_EXAMPLE_LINES,
|
||||
' mcporter call linear.list_issues team=ENG limit:5',
|
||||
' mcporter call "linear.create_issue(title: \\"Bug\\", team: \\"ENG\\")"',
|
||||
' mcporter call https://api.example.com/mcp.fetch url:https://example.com',
|
||||
' mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com',
|
||||
];
|
||||
console.error(lines.join('\n'));
|
||||
}
|
||||
|
||||
async function maybeDescribeServer(
|
||||
runtime: Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>,
|
||||
runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
|
||||
server: string,
|
||||
tool: string,
|
||||
outputFormat: OutputFormat,
|
||||
disableOAuth: boolean | undefined
|
||||
outputFormat: OutputFormat
|
||||
): Promise<boolean> {
|
||||
if (tool === 'list_tools') {
|
||||
console.log(dimText(`[mcporter] ${server}.list_tools is a shortcut for 'mcporter list ${server}'.`));
|
||||
const listArgs = [server];
|
||||
if (disableOAuth) {
|
||||
listArgs.push('--no-oauth');
|
||||
}
|
||||
if (outputFormat === 'json') {
|
||||
listArgs.push('--json');
|
||||
}
|
||||
const { handleList } = await import('./list-command.js');
|
||||
await handleList(runtime, listArgs);
|
||||
return true;
|
||||
}
|
||||
if (tool !== 'help') {
|
||||
return false;
|
||||
}
|
||||
const tools = await runtime
|
||||
.listTools(server, { includeSchema: false, autoAuthorize: false, disableOAuth })
|
||||
.catch(() => undefined);
|
||||
const tools = await runtime.listTools(server, { includeSchema: false, autoAuthorize: false }).catch(() => undefined);
|
||||
if (!tools) {
|
||||
return false;
|
||||
}
|
||||
@ -273,13 +181,9 @@ async function maybeDescribeServer(
|
||||
}
|
||||
console.log(dimText(`[mcporter] ${server} does not expose a 'help' tool; showing mcporter list output instead.`));
|
||||
const listArgs = [server];
|
||||
if (disableOAuth) {
|
||||
listArgs.push('--no-oauth');
|
||||
}
|
||||
if (outputFormat === 'json') {
|
||||
listArgs.push('--json');
|
||||
}
|
||||
const { handleList } = await import('./list-command.js');
|
||||
await handleList(runtime, listArgs);
|
||||
return true;
|
||||
}
|
||||
@ -316,117 +220,19 @@ function resolveCallTarget(
|
||||
return { server, tool };
|
||||
}
|
||||
|
||||
async function enforceSchemaAwareArgumentTypes(
|
||||
runtime: Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>,
|
||||
server: string,
|
||||
tool: string,
|
||||
args: Record<string, unknown>,
|
||||
stringCandidates: Record<string, string> | undefined,
|
||||
arrayCandidates: Record<string, string> | undefined,
|
||||
timeoutMs: number,
|
||||
disableOAuth: boolean | undefined
|
||||
): Promise<Record<string, unknown>> {
|
||||
if (
|
||||
(!stringCandidates || Object.keys(stringCandidates).length === 0) &&
|
||||
(!arrayCandidates || Object.keys(arrayCandidates).length === 0)
|
||||
) {
|
||||
return args;
|
||||
}
|
||||
|
||||
const tools = await withTimeout(
|
||||
loadToolMetadata(runtime, server, { includeSchema: true, disableOAuth }),
|
||||
timeoutMs
|
||||
).catch(() => undefined);
|
||||
if (!tools) {
|
||||
return args;
|
||||
}
|
||||
const toolInfo = tools.find((entry) => entry.tool.name === tool);
|
||||
const schema = toolInfo?.tool.inputSchema as { properties?: Record<string, unknown> } | undefined;
|
||||
if (!schema?.properties) {
|
||||
return args;
|
||||
}
|
||||
|
||||
let corrected: Record<string, unknown> | undefined;
|
||||
for (const [key, rawValue] of Object.entries(stringCandidates ?? {})) {
|
||||
if (typeof args[key] !== 'number') {
|
||||
continue;
|
||||
}
|
||||
if (!schemaAllowsString(schema.properties[key])) {
|
||||
continue;
|
||||
}
|
||||
corrected ??= { ...args };
|
||||
corrected[key] = rawValue;
|
||||
}
|
||||
for (const [key, rawValue] of Object.entries(arrayCandidates ?? {})) {
|
||||
if (typeof args[key] !== 'string') {
|
||||
continue;
|
||||
}
|
||||
const descriptor = schema.properties[key];
|
||||
if (!schemaAllowsArray(descriptor) || schemaAllowsString(descriptor)) {
|
||||
continue;
|
||||
}
|
||||
corrected ??= { ...args };
|
||||
corrected[key] = [rawValue];
|
||||
}
|
||||
return corrected ?? args;
|
||||
}
|
||||
|
||||
function schemaAllowsString(descriptor: unknown): boolean {
|
||||
if (!descriptor || typeof descriptor !== 'object') {
|
||||
return false;
|
||||
}
|
||||
const record = descriptor as Record<string, unknown>;
|
||||
const type = record.type;
|
||||
if (type === 'string') {
|
||||
return true;
|
||||
}
|
||||
if (Array.isArray(type) && type.includes('string')) {
|
||||
return true;
|
||||
}
|
||||
for (const key of ['anyOf', 'oneOf', 'allOf'] as const) {
|
||||
const variants = record[key];
|
||||
if (Array.isArray(variants) && variants.some(schemaAllowsString)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function schemaAllowsArray(descriptor: unknown): boolean {
|
||||
if (!descriptor || typeof descriptor !== 'object') {
|
||||
return false;
|
||||
}
|
||||
const record = descriptor as Record<string, unknown>;
|
||||
const type = record.type;
|
||||
if (type === 'array') {
|
||||
return true;
|
||||
}
|
||||
if (Array.isArray(type) && type.includes('array')) {
|
||||
return true;
|
||||
}
|
||||
for (const key of ['anyOf', 'oneOf', 'allOf'] as const) {
|
||||
const variants = record[key];
|
||||
if (Array.isArray(variants) && variants.some(schemaAllowsArray)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
async function hydratePositionalArguments(
|
||||
runtime: Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>,
|
||||
runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
|
||||
server: string,
|
||||
tool: string,
|
||||
namedArgs: Record<string, unknown>,
|
||||
positionalArgs: unknown[] | undefined,
|
||||
disableOAuth: boolean | undefined
|
||||
positionalArgs: unknown[] | undefined
|
||||
): Promise<Record<string, unknown>> {
|
||||
if (!positionalArgs || positionalArgs.length === 0) {
|
||||
return namedArgs;
|
||||
}
|
||||
// We need the schema order to know which field each positional argument maps to; pull the
|
||||
// tool list with schemas instead of guessing locally so optional/required order stays correct.
|
||||
const tools = await loadToolMetadata(runtime, server, { includeSchema: true, disableOAuth }).catch(() => undefined);
|
||||
const tools = await loadToolMetadata(runtime, server, { includeSchema: true }).catch(() => undefined);
|
||||
if (!tools) {
|
||||
throw new Error('Unable to load tool metadata; name positional arguments explicitly.');
|
||||
}
|
||||
@ -465,11 +271,10 @@ async function hydratePositionalArguments(
|
||||
type ToolResolution = IdentifierResolution;
|
||||
|
||||
async function inferSingleToolName(
|
||||
runtime: Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>,
|
||||
server: string,
|
||||
disableOAuth: boolean | undefined
|
||||
runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
|
||||
server: string
|
||||
): Promise<string | undefined> {
|
||||
const tools = await loadToolMetadata(runtime, server, { includeSchema: false, disableOAuth });
|
||||
const tools = await loadToolMetadata(runtime, server, { includeSchema: false });
|
||||
if (tools.length !== 1) {
|
||||
return undefined;
|
||||
}
|
||||
@ -482,56 +287,33 @@ async function inferSingleToolName(
|
||||
}
|
||||
|
||||
async function invokeWithAutoCorrection(
|
||||
runtime: Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>,
|
||||
runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
|
||||
server: string,
|
||||
tool: string,
|
||||
args: Record<string, unknown>,
|
||||
timeoutMs: number,
|
||||
outputFormat: OutputFormat,
|
||||
disableOAuth: boolean | undefined
|
||||
timeoutMs: number
|
||||
): Promise<{ result: unknown; resolvedTool: string }> {
|
||||
// Attempt the original request first; if it fails with a "tool not found" we opportunistically retry once with a better match.
|
||||
return attemptCall(runtime, server, tool, args, timeoutMs, outputFormat, true, disableOAuth);
|
||||
return attemptCall(runtime, server, tool, args, timeoutMs, true);
|
||||
}
|
||||
|
||||
async function attemptCall(
|
||||
runtime: Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>,
|
||||
runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
|
||||
server: string,
|
||||
tool: string,
|
||||
args: Record<string, unknown>,
|
||||
timeoutMs: number,
|
||||
outputFormat: OutputFormat,
|
||||
allowCorrection: boolean,
|
||||
disableOAuth: boolean | undefined
|
||||
allowCorrection: boolean
|
||||
): Promise<{ result: unknown; resolvedTool: string }> {
|
||||
try {
|
||||
const result = await withTimeout(runtime.callTool(server, tool, { args, timeoutMs, disableOAuth }), timeoutMs);
|
||||
if (allowCorrection && isErrorCallResult(result)) {
|
||||
const resolution = await maybeResolveToolName(runtime, server, tool, result, disableOAuth);
|
||||
if (resolution) {
|
||||
const retry = await maybeRetryResolvedTool(
|
||||
runtime,
|
||||
server,
|
||||
tool,
|
||||
args,
|
||||
timeoutMs,
|
||||
outputFormat,
|
||||
resolution,
|
||||
disableOAuth
|
||||
);
|
||||
if (retry) {
|
||||
return retry;
|
||||
}
|
||||
}
|
||||
}
|
||||
const result = await withTimeout(runtime.callTool(server, tool, { args, timeoutMs }), timeoutMs);
|
||||
return { result, resolvedTool: tool };
|
||||
} catch (error) {
|
||||
if (error instanceof Error && error.message === 'Timeout') {
|
||||
const timeoutDisplay = `${timeoutMs}ms`;
|
||||
await runtime.close(server).catch(() => {});
|
||||
throw new Error(
|
||||
`Call to ${server}.${tool} timed out after ${timeoutDisplay}. Override MCPORTER_CALL_TIMEOUT or pass --timeout to adjust.`,
|
||||
{ cause: error }
|
||||
`Call to ${server}.${tool} timed out after ${timeoutDisplay}. Override MCPORTER_CALL_TIMEOUT or pass --timeout to adjust.`
|
||||
);
|
||||
}
|
||||
|
||||
@ -539,64 +321,36 @@ async function attemptCall(
|
||||
throw error;
|
||||
}
|
||||
|
||||
const resolution = await maybeResolveToolName(runtime, server, tool, error, disableOAuth);
|
||||
const resolution = await maybeResolveToolName(runtime, server, tool, error);
|
||||
if (!resolution) {
|
||||
maybeReportConnectionIssue(server, tool, error);
|
||||
throw error;
|
||||
}
|
||||
|
||||
const retry = await maybeRetryResolvedTool(
|
||||
runtime,
|
||||
server,
|
||||
tool,
|
||||
args,
|
||||
timeoutMs,
|
||||
outputFormat,
|
||||
const messages = renderIdentifierResolutionMessages({
|
||||
entity: 'tool',
|
||||
attempted: tool,
|
||||
resolution,
|
||||
disableOAuth
|
||||
);
|
||||
if (!retry) {
|
||||
scope: server,
|
||||
});
|
||||
if (resolution.kind === 'suggest') {
|
||||
if (messages.suggest) {
|
||||
console.error(dimText(messages.suggest));
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
return retry;
|
||||
}
|
||||
}
|
||||
|
||||
async function maybeRetryResolvedTool(
|
||||
runtime: Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>,
|
||||
server: string,
|
||||
tool: string,
|
||||
args: Record<string, unknown>,
|
||||
timeoutMs: number,
|
||||
outputFormat: OutputFormat,
|
||||
resolution: ToolResolution,
|
||||
disableOAuth: boolean | undefined
|
||||
): Promise<{ result: unknown; resolvedTool: string } | undefined> {
|
||||
const messages = renderIdentifierResolutionMessages({
|
||||
entity: 'tool',
|
||||
attempted: tool,
|
||||
resolution,
|
||||
scope: server,
|
||||
});
|
||||
if (resolution.kind === 'suggest') {
|
||||
if (messages.suggest) {
|
||||
console.error(dimText(messages.suggest));
|
||||
if (messages.auto) {
|
||||
console.log(dimText(messages.auto));
|
||||
}
|
||||
return undefined;
|
||||
return attemptCall(runtime, server, resolution.value, args, timeoutMs, false);
|
||||
}
|
||||
if (messages.auto) {
|
||||
const emitAutoMessage = outputFormat === 'json' || outputFormat === 'raw' ? console.error : console.log;
|
||||
emitAutoMessage(dimText(messages.auto));
|
||||
}
|
||||
return attemptCall(runtime, server, resolution.value, args, timeoutMs, outputFormat, false, disableOAuth);
|
||||
}
|
||||
|
||||
async function maybeResolveToolName(
|
||||
runtime: Awaited<ReturnType<(typeof import('../runtime.js'))['createRuntime']>>,
|
||||
runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
|
||||
server: string,
|
||||
attemptedTool: string,
|
||||
error: unknown,
|
||||
disableOAuth: boolean | undefined
|
||||
error: unknown
|
||||
): Promise<ToolResolution | undefined> {
|
||||
const missingName = extractMissingToolFromError(error);
|
||||
if (!missingName) {
|
||||
@ -608,7 +362,7 @@ async function maybeResolveToolName(
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const tools = await loadToolMetadata(runtime, server, { includeSchema: false, disableOAuth }).catch(() => undefined);
|
||||
const tools = await loadToolMetadata(runtime, server, { includeSchema: false }).catch(() => undefined);
|
||||
if (!tools) {
|
||||
return undefined;
|
||||
}
|
||||
@ -624,39 +378,14 @@ async function maybeResolveToolName(
|
||||
}
|
||||
|
||||
function extractMissingToolFromError(error: unknown): string | undefined {
|
||||
const message = extractErrorMessageText(error);
|
||||
const message = error instanceof Error ? error.message : typeof error === 'string' ? error : undefined;
|
||||
if (!message) {
|
||||
return undefined;
|
||||
}
|
||||
const match =
|
||||
message.match(/Tool\s+([A-Za-z0-9._-]+)\s+not found/i) ?? message.match(/Unknown tool:?\s+([A-Za-z0-9._-]+)/i);
|
||||
const match = message.match(/Tool\s+([A-Za-z0-9._-]+)\s+not found/i);
|
||||
return match?.[1];
|
||||
}
|
||||
|
||||
function extractErrorMessageText(value: unknown): string | undefined {
|
||||
if (value instanceof Error) {
|
||||
return value.message;
|
||||
}
|
||||
if (typeof value === 'string') {
|
||||
return value;
|
||||
}
|
||||
if (!value || typeof value !== 'object') {
|
||||
return undefined;
|
||||
}
|
||||
const content = (value as { content?: unknown }).content;
|
||||
if (!Array.isArray(content)) {
|
||||
return undefined;
|
||||
}
|
||||
return content
|
||||
.map((entry) =>
|
||||
entry && typeof entry === 'object' && typeof (entry as { text?: unknown }).text === 'string'
|
||||
? (entry as { text: string }).text
|
||||
: ''
|
||||
)
|
||||
.filter(Boolean)
|
||||
.join('\n');
|
||||
}
|
||||
|
||||
function maybeReportConnectionIssue(server: string, tool: string, error: unknown): ConnectionIssue | undefined {
|
||||
const issue = analyzeConnectionError(error);
|
||||
const detail = summarizeIssueMessage(issue.rawMessage);
|
||||
|
||||
@ -1,50 +0,0 @@
|
||||
export const CALL_HELP_ARGUMENT_LINES = [
|
||||
' key=value / key:value Flag-style named arguments.',
|
||||
' key=@path Read a UTF-8 string value from a file; use @@ for a literal @.',
|
||||
' function-call syntax \'server.tool(arg: "value", other: 1)\'.',
|
||||
' --args <json> Provide a JSON object payload.',
|
||||
' positional values Accepted when schema order is known.',
|
||||
' -- Treat remaining tokens as literal positional values.',
|
||||
] as const;
|
||||
|
||||
export const CALL_HELP_RUNTIME_FLAG_LINES = [
|
||||
' --timeout <ms> Override the call timeout.',
|
||||
' --output text|markdown|json|raw Control formatting.',
|
||||
' --save-images <dir> Save image content blocks to a directory.',
|
||||
' --no-oauth Never start OAuth; use cached tokens only.',
|
||||
' --raw-strings Keep numeric-looking argument values as strings.',
|
||||
' --no-coerce Keep all key/value and positional arguments as raw strings.',
|
||||
' --tail-log Stream returned log handles.',
|
||||
] as const;
|
||||
|
||||
export const CALL_HELP_ADHOC_SERVER_LINES = [
|
||||
' --http-url <url> Register an HTTP server for this run.',
|
||||
' --allow-http Permit plain http:// URLs with --http-url.',
|
||||
' --header KEY=value Attach HTTP headers (repeatable).',
|
||||
' --stdio <command> Run a stdio MCP server (repeat --stdio-arg for args).',
|
||||
' --stdio-arg <value> Append args to the stdio command (repeatable).',
|
||||
' --env KEY=value Inject env vars for stdio servers (repeatable).',
|
||||
' --cwd <path> Working directory for stdio servers.',
|
||||
' --name <value> Override the display name for ad-hoc servers.',
|
||||
' --description <text> Override the description for ad-hoc servers.',
|
||||
' --persist <path> Write the ad-hoc definition to config/mcporter.json.',
|
||||
' --yes Skip confirmation prompts when persisting.',
|
||||
] as const;
|
||||
|
||||
export const CALL_HELP_EXAMPLE_LINES = [
|
||||
' mcporter call linear.list_issues team=ENG limit:5',
|
||||
' mcporter call linear.create_comment body=@comment.md',
|
||||
' mcporter call "linear.create_issue(title: \\"Bug\\", team: \\"ENG\\")"',
|
||||
' mcporter call https://api.example.com/mcp.fetch url:https://example.com',
|
||||
' mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com',
|
||||
] as const;
|
||||
|
||||
export function buildUnknownCallFlagMessage(token: string): string {
|
||||
const argumentName = token.startsWith('--') ? token.slice(2) : token;
|
||||
return [
|
||||
`Unknown flag '${token}' passed to call command.`,
|
||||
`If you intended to pass a tool argument, use '${argumentName}=<value>' or --args '{"${argumentName}": ...}'.`,
|
||||
"If you intended to pass a literal positional value, insert '--' before it.",
|
||||
"Run 'mcporter call --help' to see available flags.",
|
||||
].join('\n');
|
||||
}
|
||||
@ -1,8 +1,7 @@
|
||||
import { resolveConfigPath } from '../config/path-discovery.js';
|
||||
import { resolveConfigPath } from '../config.js';
|
||||
import { parseLogLevel } from '../logging.js';
|
||||
import { extractFlags } from './flag-utils.js';
|
||||
import { getActiveLogger, getActiveLogLevel, logError, setLogLevel } from './logger-context.js';
|
||||
import { parsePositiveInteger } from './timeouts.js';
|
||||
|
||||
export interface GlobalCliContext {
|
||||
readonly globalFlags: Record<string, string | undefined>;
|
||||
@ -30,8 +29,8 @@ export function buildGlobalContext(argv: string[]): GlobalCliContext | { exit: t
|
||||
|
||||
let oauthTimeoutOverride: number | undefined;
|
||||
if (globalFlags['--oauth-timeout']) {
|
||||
const parsed = parsePositiveInteger(globalFlags['--oauth-timeout']);
|
||||
if (parsed === undefined) {
|
||||
const parsed = Number.parseInt(globalFlags['--oauth-timeout'], 10);
|
||||
if (!Number.isFinite(parsed) || parsed <= 0) {
|
||||
logError("Flag '--oauth-timeout' must be a positive integer (milliseconds).");
|
||||
return { exit: true, code: 1 };
|
||||
}
|
||||
|
||||
@ -84,14 +84,7 @@ function isCallLikeToken(token: string): boolean {
|
||||
}
|
||||
|
||||
function isExplicitCommand(token: string): boolean {
|
||||
return (
|
||||
token === 'list' ||
|
||||
token === 'call' ||
|
||||
token === 'auth' ||
|
||||
token === 'vault' ||
|
||||
token === 'resource' ||
|
||||
token === 'resources'
|
||||
);
|
||||
return token === 'list' || token === 'call' || token === 'auth';
|
||||
}
|
||||
|
||||
function isUrlToken(token: string): boolean {
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { writeRawConfig, type LoadConfigOptions, type RawEntry } from '../../config.js';
|
||||
import type { LoadConfigOptions, RawEntry } from '../../config.js';
|
||||
import { writeRawConfig } from '../../config.js';
|
||||
import { pathsForImport, readExternalEntries } from '../../config-imports.js';
|
||||
import { expandHome } from '../../env.js';
|
||||
import { withFileLock } from '../../fs-json.js';
|
||||
import { mcporterDir } from '../../paths.js';
|
||||
import { CliUsageError } from '../errors.js';
|
||||
import { cloneConfig, loadOrCreateConfig } from './shared.js';
|
||||
import type { ConfigCliOptions } from './types.js';
|
||||
@ -19,9 +19,6 @@ export type AddFlags = {
|
||||
headers: Record<string, string>;
|
||||
tokenCacheDir?: string;
|
||||
clientName?: string;
|
||||
oauthClientId?: string;
|
||||
oauthClientSecretEnv?: string;
|
||||
oauthTokenEndpointAuthMethod?: string;
|
||||
oauthRedirectUrl?: string;
|
||||
auth?: string;
|
||||
copyFrom?: string;
|
||||
@ -44,6 +41,9 @@ export async function handleAddCommand(options: ConfigCliOptions, args: string[]
|
||||
const targetPath = resolveWriteTarget(flags, options.loadOptions, options.loadOptions.rootDir ?? process.cwd());
|
||||
const effectiveLoadOptions: LoadConfigOptions = { ...options.loadOptions, configPath: targetPath };
|
||||
|
||||
const { config, path: configPath } = await loadOrCreateConfig(effectiveLoadOptions);
|
||||
const nextConfig = cloneConfig(config);
|
||||
|
||||
const baseEntry = await resolveBaseEntry(flags.copyFrom, options.loadOptions);
|
||||
const entry: RawEntry = baseEntry ? { ...baseEntry } : {};
|
||||
|
||||
@ -60,32 +60,25 @@ export async function handleAddCommand(options: ConfigCliOptions, args: string[]
|
||||
const hasCommandTarget = Boolean(entry.command ?? entry.executable);
|
||||
|
||||
if (flags.args.length > 0 && !hasCommandTarget) {
|
||||
throw new CliUsageError(
|
||||
'--arg/--args requires a stdio command (use --command, --stdio, or provide a positional target).'
|
||||
);
|
||||
throw new CliUsageError('--arg requires a stdio command (use --command, --stdio, or provide a positional target).');
|
||||
}
|
||||
|
||||
if (!hasHttpTarget && !hasCommandTarget) {
|
||||
throw new CliUsageError('Server definitions require either a --url/target or a stdio command.');
|
||||
}
|
||||
|
||||
if (!nextConfig.mcpServers) {
|
||||
nextConfig.mcpServers = {};
|
||||
}
|
||||
nextConfig.mcpServers[name] = entry;
|
||||
|
||||
if (flags.dryRun) {
|
||||
console.log(JSON.stringify({ [name]: entry }, null, 2));
|
||||
console.log('(dry-run) No changes were written.');
|
||||
return;
|
||||
}
|
||||
|
||||
let configPath = targetPath;
|
||||
await withFileLock(targetPath, async () => {
|
||||
const loaded = await loadOrCreateConfig(effectiveLoadOptions);
|
||||
configPath = loaded.path;
|
||||
const nextConfig = cloneConfig(loaded.config);
|
||||
if (!nextConfig.mcpServers) {
|
||||
nextConfig.mcpServers = {};
|
||||
}
|
||||
nextConfig.mcpServers[name] = entry;
|
||||
await writeRawConfig(configPath, nextConfig);
|
||||
});
|
||||
await writeRawConfig(configPath, nextConfig);
|
||||
console.log(`Added '${name}' to ${configPath}`);
|
||||
}
|
||||
|
||||
@ -94,7 +87,7 @@ export function resolveWriteTarget(flags: AddFlags, loadOptions: LoadConfigOptio
|
||||
return path.resolve(expandHome(flags.persistPath));
|
||||
}
|
||||
if (flags.scope === 'home') {
|
||||
return path.join(mcporterDir('config'), 'mcporter.json');
|
||||
return path.join(os.homedir(), '.mcporter', 'mcporter.json');
|
||||
}
|
||||
if (flags.scope === 'project') {
|
||||
return path.resolve(rootDir, 'config', 'mcporter.json');
|
||||
@ -128,7 +121,6 @@ function extractAddFlags(args: string[]): AddFlags {
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
case '--arg':
|
||||
case '--args':
|
||||
flags.args.push(requireValue(args, index, token));
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
@ -152,18 +144,6 @@ function extractAddFlags(args: string[]): AddFlags {
|
||||
flags.clientName = requireValue(args, index, token);
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
case '--oauth-client-id':
|
||||
flags.oauthClientId = requireValue(args, index, token);
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
case '--oauth-client-secret-env':
|
||||
flags.oauthClientSecretEnv = requireValue(args, index, token);
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
case '--oauth-token-endpoint-auth-method':
|
||||
flags.oauthTokenEndpointAuthMethod = requireValue(args, index, token);
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
case '--oauth-redirect-url':
|
||||
flags.oauthRedirectUrl = requireValue(args, index, token);
|
||||
args.splice(index, 2);
|
||||
@ -219,7 +199,7 @@ function parseTransport(value: string | undefined): 'http' | 'sse' | 'stdio' {
|
||||
}
|
||||
|
||||
function parseKeyValue(input: string | undefined, target: Record<string, string>, flagName: string): void {
|
||||
if (!input?.includes('=')) {
|
||||
if (!input || !input.includes('=')) {
|
||||
throw new CliUsageError(`${flagName} requires KEY=value.`);
|
||||
}
|
||||
const [key, ...rest] = input.split('=');
|
||||
@ -301,15 +281,6 @@ function applyFlagsToEntry(entry: RawEntry, flags: AddFlags): void {
|
||||
if (flags.clientName) {
|
||||
entry.clientName = flags.clientName;
|
||||
}
|
||||
if (flags.oauthClientId) {
|
||||
entry.oauthClientId = flags.oauthClientId;
|
||||
}
|
||||
if (flags.oauthClientSecretEnv) {
|
||||
entry.oauthClientSecretEnv = flags.oauthClientSecretEnv;
|
||||
}
|
||||
if (flags.oauthTokenEndpointAuthMethod) {
|
||||
entry.oauthTokenEndpointAuthMethod = flags.oauthTokenEndpointAuthMethod;
|
||||
}
|
||||
if (flags.oauthRedirectUrl) {
|
||||
entry.oauthRedirectUrl = flags.oauthRedirectUrl;
|
||||
}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
import path from 'node:path';
|
||||
import { loadServerDefinitions } from '../../config.js';
|
||||
import { MCPORTER_VERSION } from '../../version.js';
|
||||
import { MCPORTER_VERSION } from '../../runtime.js';
|
||||
import { logConfigLocations, resolveConfigLocations } from './shared.js';
|
||||
import type { ConfigCliOptions } from './types.js';
|
||||
|
||||
|
||||
@ -51,12 +51,6 @@ export const CONFIG_HELP_ENTRIES: Record<ConfigSubcommand, ConfigHelpEntry> = {
|
||||
{ flag: '--header KEY=value', description: 'Attach HTTP headers (repeatable).' },
|
||||
{ flag: '--token-cache-dir <path>', description: 'Override where OAuth tokens are persisted.' },
|
||||
{ flag: '--client-name <name>', description: 'Customize the OAuth client identifier.' },
|
||||
{ flag: '--oauth-client-id <id>', description: 'Use a pre-registered OAuth client id.' },
|
||||
{ flag: '--oauth-client-secret-env <env>', description: 'Read the OAuth client secret from an env var.' },
|
||||
{
|
||||
flag: '--oauth-token-endpoint-auth-method <method>',
|
||||
description: 'Set token auth, e.g. client_secret_post.',
|
||||
},
|
||||
{ flag: '--oauth-redirect-url <url>', description: 'Set a custom OAuth redirect URL.' },
|
||||
{ flag: '--auth <strategy>', description: 'Force the auth type (e.g., oauth).' },
|
||||
{ flag: '--copy-from <import:name>', description: 'Start with an imported definition by name.' },
|
||||
@ -98,21 +92,8 @@ export const CONFIG_HELP_ENTRIES: Record<ConfigSubcommand, ConfigHelpEntry> = {
|
||||
name: 'login <name|url> [options]',
|
||||
summary: 'Run the OAuth/auth flow',
|
||||
usage: 'mcporter config login <name|url> [options]',
|
||||
description:
|
||||
'Delegates to `mcporter auth`, so you can pass ephemeral flags like --http-url/--stdio/--reset and browser-suppression flags for headless OAuth.',
|
||||
flags: [
|
||||
{ flag: '--no-browser', description: 'Print the OAuth authorization URL without launching a browser.' },
|
||||
{ flag: '--browser none', description: 'Alias for --no-browser.' },
|
||||
{
|
||||
flag: 'MCPORTER_OAUTH_NO_BROWSER=1|true|yes',
|
||||
description: 'Environment default for browser-suppressed OAuth.',
|
||||
},
|
||||
],
|
||||
examples: [
|
||||
'pnpm mcporter config login linear',
|
||||
'pnpm mcporter config login linear --no-browser',
|
||||
'pnpm mcporter config login https://example.com/mcp --reset',
|
||||
],
|
||||
description: 'Delegates to `mcporter auth`, so you can pass ephemeral flags like --http-url/--stdio/--reset.',
|
||||
examples: ['pnpm mcporter config login linear', 'pnpm mcporter config login https://example.com/mcp --reset'],
|
||||
},
|
||||
logout: {
|
||||
name: 'logout <name>',
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
import path from 'node:path';
|
||||
import { resolveConfigPath, writeRawConfig, type RawEntry } from '../../config.js';
|
||||
import type { RawEntry } from '../../config.js';
|
||||
import { writeRawConfig } from '../../config.js';
|
||||
import { pathsForImport, readExternalEntries } from '../../config-imports.js';
|
||||
import { expandHome } from '../../env.js';
|
||||
import { withFileLock } from '../../fs-json.js';
|
||||
import { CliUsageError } from '../errors.js';
|
||||
import { cloneConfig, loadOrCreateConfig } from './shared.js';
|
||||
import type { ConfigCliOptions } from './types.js';
|
||||
@ -53,31 +53,19 @@ export async function handleImportCommand(options: ConfigCliOptions, args: strin
|
||||
}
|
||||
}
|
||||
if (flags.copy) {
|
||||
const lockPath = resolveImportCopyTarget(options.loadOptions.configPath, rootDir);
|
||||
let configPath = lockPath;
|
||||
await withFileLock(lockPath, async () => {
|
||||
const loaded = await loadOrCreateConfig({ ...options.loadOptions, configPath: lockPath });
|
||||
configPath = loaded.path;
|
||||
const nextConfig = cloneConfig(loaded.config);
|
||||
if (!nextConfig.mcpServers) {
|
||||
nextConfig.mcpServers = {};
|
||||
}
|
||||
for (const item of entries) {
|
||||
nextConfig.mcpServers[item.name] = structuredClone(item.entry);
|
||||
}
|
||||
await writeRawConfig(configPath, nextConfig);
|
||||
});
|
||||
const { config, path: configPath } = await loadOrCreateConfig(options.loadOptions);
|
||||
const nextConfig = cloneConfig(config);
|
||||
if (!nextConfig.mcpServers) {
|
||||
nextConfig.mcpServers = {};
|
||||
}
|
||||
for (const item of entries) {
|
||||
nextConfig.mcpServers[item.name] = structuredClone(item.entry);
|
||||
}
|
||||
await writeRawConfig(configPath, nextConfig);
|
||||
console.log(`Copied ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} to ${configPath}`);
|
||||
}
|
||||
}
|
||||
|
||||
function resolveImportCopyTarget(configPath: string | undefined, rootDir: string): string {
|
||||
if (configPath || process.env.MCPORTER_CONFIG) {
|
||||
return resolveConfigPath(configPath, rootDir).path;
|
||||
}
|
||||
return path.resolve(rootDir, 'config', 'mcporter.json');
|
||||
}
|
||||
|
||||
function extractImportFlags(args: string[]): ImportFlags {
|
||||
const flags: ImportFlags = { format: 'text' };
|
||||
let index = 0;
|
||||
|
||||
@ -1,5 +1,4 @@
|
||||
import { resolveConfigPath, writeRawConfig } from '../../config.js';
|
||||
import { withFileLock } from '../../fs-json.js';
|
||||
import { writeRawConfig } from '../../config.js';
|
||||
import { CliUsageError } from '../errors.js';
|
||||
import { cloneConfig, findServerNameWithFuzzyMatch, loadOrCreateConfig } from './shared.js';
|
||||
import type { ConfigCliOptions } from './types.js';
|
||||
@ -9,21 +8,13 @@ export async function handleRemoveCommand(options: ConfigCliOptions, args: strin
|
||||
if (!name) {
|
||||
throw new CliUsageError('Usage: mcporter config remove <name>');
|
||||
}
|
||||
const rootDir = options.loadOptions.rootDir ?? process.cwd();
|
||||
const lockPath = resolveConfigPath(options.loadOptions.configPath, rootDir).path;
|
||||
let configPath = lockPath;
|
||||
let targetName = name;
|
||||
await withFileLock(lockPath, async () => {
|
||||
const loaded = await loadOrCreateConfig({ ...options.loadOptions, configPath: lockPath });
|
||||
configPath = loaded.path;
|
||||
const matched = findServerNameWithFuzzyMatch(name, Object.keys(loaded.config.mcpServers ?? {}));
|
||||
if (!matched) {
|
||||
throw new CliUsageError(`Server '${name}' does not exist in ${configPath}.`);
|
||||
}
|
||||
targetName = matched;
|
||||
const nextConfig = cloneConfig(loaded.config);
|
||||
delete nextConfig.mcpServers[targetName];
|
||||
await writeRawConfig(configPath, nextConfig);
|
||||
});
|
||||
const { config, path: configPath } = await loadOrCreateConfig(options.loadOptions);
|
||||
const targetName = findServerNameWithFuzzyMatch(name, Object.keys(config.mcpServers ?? {}));
|
||||
if (!targetName) {
|
||||
throw new CliUsageError(`Server '${name}' does not exist in ${configPath}.`);
|
||||
}
|
||||
const nextConfig = cloneConfig(config);
|
||||
delete nextConfig.mcpServers[targetName];
|
||||
await writeRawConfig(configPath, nextConfig);
|
||||
console.log(`Removed '${targetName}' from ${configPath}`);
|
||||
}
|
||||
|
||||
@ -9,15 +9,7 @@ export type SerializedServerDefinition = {
|
||||
auth?: ServerDefinition['auth'];
|
||||
tokenCacheDir?: string;
|
||||
clientName?: string;
|
||||
oauthClientId?: string;
|
||||
oauthClientSecretEnv?: string;
|
||||
oauthTokenEndpointAuthMethod?: string;
|
||||
oauthRedirectUrl?: string;
|
||||
oauthScope?: string;
|
||||
refresh?: ServerDefinition['refresh'];
|
||||
httpFetch?: ServerDefinition['httpFetch'];
|
||||
allowedTools?: readonly string[];
|
||||
blockedTools?: readonly string[];
|
||||
env?: Record<string, string>;
|
||||
transport: 'http' | 'stdio';
|
||||
baseUrl?: string;
|
||||
@ -37,15 +29,7 @@ export function serializeDefinition(definition: ServerDefinition): SerializedSer
|
||||
auth: definition.auth,
|
||||
tokenCacheDir: definition.tokenCacheDir,
|
||||
clientName: definition.clientName,
|
||||
oauthClientId: definition.oauthClientId,
|
||||
oauthClientSecretEnv: definition.oauthClientSecretEnv,
|
||||
oauthTokenEndpointAuthMethod: definition.oauthTokenEndpointAuthMethod,
|
||||
oauthRedirectUrl: definition.oauthRedirectUrl,
|
||||
oauthScope: definition.oauthScope,
|
||||
refresh: definition.refresh,
|
||||
httpFetch: definition.httpFetch,
|
||||
allowedTools: definition.allowedTools,
|
||||
blockedTools: definition.blockedTools,
|
||||
env: definition.env,
|
||||
transport: 'http',
|
||||
baseUrl: definition.command.url.href,
|
||||
@ -59,15 +43,7 @@ export function serializeDefinition(definition: ServerDefinition): SerializedSer
|
||||
auth: definition.auth,
|
||||
tokenCacheDir: definition.tokenCacheDir,
|
||||
clientName: definition.clientName,
|
||||
oauthClientId: definition.oauthClientId,
|
||||
oauthClientSecretEnv: definition.oauthClientSecretEnv,
|
||||
oauthTokenEndpointAuthMethod: definition.oauthTokenEndpointAuthMethod,
|
||||
oauthRedirectUrl: definition.oauthRedirectUrl,
|
||||
oauthScope: definition.oauthScope,
|
||||
refresh: definition.refresh,
|
||||
httpFetch: definition.httpFetch,
|
||||
allowedTools: definition.allowedTools,
|
||||
blockedTools: definition.blockedTools,
|
||||
env: definition.env,
|
||||
transport: 'stdio',
|
||||
command: definition.command.command,
|
||||
@ -97,16 +73,8 @@ export function printServerSummary(definition: ServerDefinition): void {
|
||||
if (definition.description) {
|
||||
console.log(` ${label('Description')}: ${definition.description}`);
|
||||
}
|
||||
if (definition.auth) {
|
||||
console.log(` ${label('Auth')}: ${definition.auth}`);
|
||||
}
|
||||
if (definition.allowedTools !== undefined) {
|
||||
const rendered = definition.allowedTools.length > 0 ? definition.allowedTools.join(', ') : '<none>';
|
||||
console.log(` ${label('Allowed tools')}: ${rendered}`);
|
||||
}
|
||||
if (definition.blockedTools !== undefined) {
|
||||
const rendered = definition.blockedTools.length > 0 ? definition.blockedTools.join(', ') : '<none>';
|
||||
console.log(` ${label('Blocked tools')}: ${rendered}`);
|
||||
if (definition.auth === 'oauth') {
|
||||
console.log(` ${label('Auth')}: oauth`);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
import fs from 'node:fs/promises';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import type { LoadConfigOptions, RawConfig } from '../../config.js';
|
||||
import { loadRawConfig, resolveConfigPath } from '../../config.js';
|
||||
import type { ServerDefinition } from '../../config-schema.js';
|
||||
import { mcporterConfigCandidates } from '../../paths.js';
|
||||
import { CliUsageError } from '../errors.js';
|
||||
import { chooseClosestIdentifier, renderIdentifierResolutionMessages } from '../identifier-helpers.js';
|
||||
import { dimText, supportsAnsiColor } from '../terminal.js';
|
||||
@ -20,19 +20,19 @@ export type ConfigLocationSummary = {
|
||||
export function cloneConfig(config: RawConfig): RawConfig {
|
||||
return {
|
||||
mcpServers: config.mcpServers ? { ...config.mcpServers } : {},
|
||||
imports: config.imports ? [...config.imports] : undefined,
|
||||
imports: config.imports ? [...config.imports] : [],
|
||||
};
|
||||
}
|
||||
|
||||
export async function loadOrCreateConfig(loadOptions: LoadConfigOptions): Promise<{ config: RawConfig; path: string }> {
|
||||
try {
|
||||
const { config, path: configPath } = await loadRawConfig(loadOptions);
|
||||
return { config, path: configPath };
|
||||
const { config, path } = await loadRawConfig(loadOptions);
|
||||
return { config, path };
|
||||
} catch (error) {
|
||||
if (isErrno(error, 'ENOENT')) {
|
||||
const rootDir = loadOptions.rootDir ?? process.cwd();
|
||||
const resolved = resolveConfigPath(loadOptions.configPath, rootDir);
|
||||
return { config: { mcpServers: {} }, path: resolved.path };
|
||||
return { config: { mcpServers: {}, imports: [] }, path: resolved.path };
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
@ -127,7 +127,9 @@ export function resolveServerDefinition(
|
||||
}
|
||||
|
||||
function buildSystemConfigCandidates(): string[] {
|
||||
return mcporterConfigCandidates();
|
||||
const homeDir = os.homedir();
|
||||
const base = path.join(homeDir, '.mcporter');
|
||||
return [path.join(base, 'mcporter.json'), path.join(base, 'mcporter.jsonc')];
|
||||
}
|
||||
|
||||
async function resolveFirstExisting(pathsToCheck: string[]): Promise<{ path: string; exists: boolean }> {
|
||||
|
||||
@ -68,8 +68,7 @@ Commands:
|
||||
|
||||
Flags:
|
||||
--foreground Run the daemon in the current process (debug only).
|
||||
--log Enable daemon logging (defaults to ~/.mcporter/daemon/daemon-<hash>.log,
|
||||
or $XDG_STATE_HOME/mcporter/daemon/... when set).
|
||||
--log Enable daemon logging (defaults to ~/.mcporter/daemon/daemon-<hash>.log).
|
||||
--log-file <path> Write daemon stdout/stderr to a specific log file.
|
||||
--log-servers <csv> Only log call activity for the listed servers (implies --log).`);
|
||||
}
|
||||
|
||||
@ -93,21 +93,6 @@ export async function handleEmitTs(runtime: Runtime, args: string[]): Promise<vo
|
||||
}
|
||||
}
|
||||
|
||||
export function printEmitTsHelp(): void {
|
||||
console.error(
|
||||
[
|
||||
'Usage: mcporter emit-ts <server> --out <file> [flags]',
|
||||
'',
|
||||
'Flags:',
|
||||
' --mode types|client Emit declarations only or client + declarations.',
|
||||
' --out <path> Output .ts/.d.ts file.',
|
||||
' --types-out <path> Declaration output path for --mode client.',
|
||||
' --include-optional Include optional schema fields in signatures.',
|
||||
' --json Print a JSON summary.',
|
||||
].join('\n')
|
||||
);
|
||||
}
|
||||
|
||||
function parseEmitTsArgs(args: string[]): ParsedEmitTsOptions {
|
||||
const flags: EmitTsFlags = {
|
||||
mode: 'types',
|
||||
@ -197,7 +182,7 @@ function getServerDefinition(runtime: Runtime, selector: string): ServerDefiniti
|
||||
return runtime.getDefinition(resolved);
|
||||
}
|
||||
if (error instanceof Error) {
|
||||
throw new Error(error.message, { cause: error });
|
||||
throw new Error(error.message);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
@ -259,7 +244,7 @@ async function writeFile(targetPath: string, contents: string): Promise<void> {
|
||||
function computeImportPath(fromPath: string, typesPath: string): string {
|
||||
const fromDir = path.dirname(fromPath);
|
||||
const relative = path.relative(fromDir, typesPath).replace(/\\/g, '/');
|
||||
const withoutExt = relative.endsWith('.d.ts') ? relative.slice(0, -5) : relative.replace(/\.[^.]+$/, '');
|
||||
const withoutExt = relative.replace(/\.[^.]+$/, '');
|
||||
if (withoutExt.startsWith('.')) {
|
||||
return withoutExt;
|
||||
}
|
||||
|
||||
@ -32,7 +32,7 @@ export function renderTypesModule(input: EmitTypesTemplateInput): string {
|
||||
lines.push(`export interface ${input.interfaceName} {`);
|
||||
input.docs.forEach((entry, index) => {
|
||||
lines.push(...renderDocComment(entry.doc.docLines, ' '));
|
||||
const methodSignature = toInterfaceSignature(entry.doc.tsSignature, entry.toolName, { wrapInPromise: true });
|
||||
const methodSignature = toInterfaceSignature(entry.doc.tsSignature, { wrapInPromise: true });
|
||||
lines.push(` ${methodSignature}`);
|
||||
if (entry.doc.optionalSummary) {
|
||||
lines.push(` // ${entry.doc.optionalSummary.replace(/^\/\//, '').trim()}`);
|
||||
@ -76,11 +76,10 @@ export function renderClientModule(input: EmitClientTemplateInput): string {
|
||||
lines.push(` const proxy = createServerProxy(runtime, ${JSON.stringify(serverName)});`);
|
||||
lines.push(` const client: ${clientType} = {`);
|
||||
input.docs.forEach((entry, _index) => {
|
||||
const memberName = toMemberName(entry.toolName);
|
||||
const indexKey = toIndexKey(entry.toolName);
|
||||
lines.push(` async ${memberName}(params: Parameters<${input.interfaceName}[${indexKey}]>[0]) {`);
|
||||
const methodName = entry.doc.tsSignature.match(/^function\s+([^()]+)/)?.[1] ?? entry.toolName;
|
||||
lines.push(` async ${methodName}(params: Parameters<${input.interfaceName}['${methodName}']>[0]) {`);
|
||||
lines.push(
|
||||
` const tool = proxy.${entry.methodName} as (args: Parameters<${input.interfaceName}[${indexKey}]>[0]) => Promise<unknown>;`
|
||||
` const tool = proxy.${entry.methodName} as (args: Parameters<${input.interfaceName}['${methodName}']>[0]) => Promise<unknown>;`
|
||||
);
|
||||
lines.push(' const raw = await tool(params);');
|
||||
lines.push(' return wrapCallResult(raw).callResult;');
|
||||
@ -127,26 +126,16 @@ function renderDocComment(docLines: string[] | undefined, indent: string): strin
|
||||
return docLines.map((line) => `${indent}${line}`);
|
||||
}
|
||||
|
||||
function toInterfaceSignature(signature: string, toolName: string, options?: { wrapInPromise?: boolean }): string {
|
||||
function toInterfaceSignature(signature: string, options?: { wrapInPromise?: boolean }): string {
|
||||
const trimmed = signature.trim();
|
||||
const match = trimmed.match(/^function\s+([^(]+)\((.*)\)\s*(?::\s*([^;]+))?;?$/);
|
||||
if (!match) {
|
||||
return trimmed.replace(/^function\s+/, '');
|
||||
}
|
||||
const [, , params, returnTypeRaw] = match;
|
||||
const [, name, params, returnTypeRaw] = match;
|
||||
const returnType = (returnTypeRaw ?? 'void').trim();
|
||||
const finalReturn = options?.wrapInPromise ? `Promise<${returnType}>` : returnType;
|
||||
return `${toMemberName(toolName)}(${params}): ${finalReturn};`;
|
||||
}
|
||||
|
||||
const SAFE_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
|
||||
|
||||
function toMemberName(name: string): string {
|
||||
return SAFE_IDENTIFIER.test(name) ? name : JSON.stringify(name);
|
||||
}
|
||||
|
||||
function toIndexKey(name: string): string {
|
||||
return JSON.stringify(name);
|
||||
return `${name}(${params}): ${finalReturn};`;
|
||||
}
|
||||
|
||||
function describeTransport(definition: ServerDefinition): string | undefined {
|
||||
|
||||
@ -66,24 +66,21 @@ export function extractEphemeralServerFlags(
|
||||
|
||||
if (token === '--env') {
|
||||
const value = args[index + 1];
|
||||
if (!value || !value.includes('=')) {
|
||||
throw new Error("Flag '--env' requires KEY=value.");
|
||||
}
|
||||
const [key, ...rest] = value.split('=');
|
||||
if (!key) {
|
||||
throw new Error("Flag '--env' requires KEY=value.");
|
||||
}
|
||||
const current = ensureSpec();
|
||||
const envMap = current.env ? { ...current.env } : {};
|
||||
parseKeyValue(value, envMap, '--env');
|
||||
envMap[key] = rest.join('=');
|
||||
current.env = envMap;
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (token === '--header') {
|
||||
const value = args[index + 1];
|
||||
const current = ensureSpec();
|
||||
const headerMap = current.headers ? { ...current.headers } : {};
|
||||
parseKeyValue(value, headerMap, '--header');
|
||||
current.headers = headerMap;
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (token === '--cwd') {
|
||||
const value = args[index + 1];
|
||||
if (!value) {
|
||||
@ -129,14 +126,3 @@ export function extractEphemeralServerFlags(
|
||||
|
||||
return spec;
|
||||
}
|
||||
|
||||
function parseKeyValue(value: string | undefined, target: Record<string, string>, flagName: string): void {
|
||||
if (!value?.includes('=')) {
|
||||
throw new Error(`Flag '${flagName}' requires KEY=value.`);
|
||||
}
|
||||
const [key, ...rest] = value.split('=');
|
||||
if (!key) {
|
||||
throw new Error(`Flag '${flagName}' requires KEY=value.`);
|
||||
}
|
||||
target[key] = rest.join('=');
|
||||
}
|
||||
|
||||
@ -17,10 +17,9 @@ interface PrepareEphemeralServerTargetOptions {
|
||||
reuseFromSpec?: boolean;
|
||||
}
|
||||
|
||||
export interface PrepareEphemeralServerTargetResult {
|
||||
interface PrepareEphemeralServerTargetResult {
|
||||
target?: string;
|
||||
resolution?: EphemeralServerResolution;
|
||||
persistPath?: string;
|
||||
}
|
||||
|
||||
export async function prepareEphemeralServerTarget(
|
||||
@ -86,33 +85,7 @@ export async function prepareEphemeralServerTarget(
|
||||
await persistEphemeralServer(resolution, spec.persistPath);
|
||||
}
|
||||
const resolvedTarget = target ?? resolution.name;
|
||||
return { target: resolvedTarget, resolution, persistPath: spec.persistPath };
|
||||
}
|
||||
|
||||
export async function persistPreparedEphemeralServer(
|
||||
runtime: Runtime,
|
||||
prepared: PrepareEphemeralServerTargetResult | undefined
|
||||
): Promise<void> {
|
||||
if (!prepared?.resolution || !prepared.persistPath) {
|
||||
return;
|
||||
}
|
||||
let currentDefinition;
|
||||
try {
|
||||
currentDefinition = runtime.getDefinition(prepared.resolution.name);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
const persistedEntry = { ...prepared.resolution.persistedEntry };
|
||||
if (currentDefinition.auth === 'oauth') {
|
||||
persistedEntry.auth = 'oauth';
|
||||
}
|
||||
await persistEphemeralServer(
|
||||
{
|
||||
...prepared.resolution,
|
||||
persistedEntry,
|
||||
},
|
||||
prepared.persistPath
|
||||
);
|
||||
return { target: resolvedTarget, resolution };
|
||||
}
|
||||
|
||||
function applyNameHints(spec: EphemeralServerSpec | undefined, hints: string[] | undefined): void {
|
||||
|
||||
@ -6,9 +6,6 @@ export function extractFlags(args: string[], keys: readonly string[]): FlagMap {
|
||||
let index = 0;
|
||||
while (index < args.length) {
|
||||
const token = args[index];
|
||||
if (token === '--') {
|
||||
break;
|
||||
}
|
||||
if (token === undefined || !keys.includes(token)) {
|
||||
index += 1;
|
||||
continue;
|
||||
|
||||
@ -9,15 +9,6 @@ import { buildGenerateCliCommand, resolveGenerateRequestFromArtifact } from './g
|
||||
// handleGenerateCli parses flags and generates the requested standalone CLI.
|
||||
export async function handleGenerateCli(args: string[], globalFlags: FlagMap): Promise<void> {
|
||||
const parsed = parseGenerateFlags(args);
|
||||
if (parsed.includeTools && parsed.excludeTools) {
|
||||
throw new Error('--include-tools and --exclude-tools cannot be used together.');
|
||||
}
|
||||
if (parsed.includeTools && parsed.includeTools.length === 0) {
|
||||
throw new Error('--include-tools requires at least one tool name.');
|
||||
}
|
||||
if (parsed.excludeTools && parsed.excludeTools.length === 0) {
|
||||
throw new Error('--exclude-tools requires at least one tool name.');
|
||||
}
|
||||
if (parsed.from && (parsed.command || parsed.description || parsed.name)) {
|
||||
throw new Error('--from cannot be combined with --command/--description/--name.');
|
||||
}
|
||||
@ -40,8 +31,6 @@ export async function handleGenerateCli(args: string[], globalFlags: FlagMap): P
|
||||
runtime: request.runtime ?? 'node',
|
||||
timeoutMs: request.timeoutMs ?? 30_000,
|
||||
minify: request.minify ?? false,
|
||||
includeTools: request.includeTools,
|
||||
excludeTools: request.excludeTools,
|
||||
},
|
||||
metadata.server.definition,
|
||||
globalFlags
|
||||
@ -76,34 +65,5 @@ export async function handleGenerateCli(args: string[], globalFlags: FlagMap): P
|
||||
timeoutMs: parsed.timeout,
|
||||
compile: parsed.compile,
|
||||
minify: parsed.minify ?? false,
|
||||
includeTools: parsed.includeTools,
|
||||
excludeTools: parsed.excludeTools,
|
||||
});
|
||||
}
|
||||
|
||||
export function printGenerateCliHelp(): void {
|
||||
console.error(
|
||||
[
|
||||
'Usage: mcporter generate-cli [server | command | url] [flags]',
|
||||
'',
|
||||
'Targets:',
|
||||
' <server> Use a configured server.',
|
||||
' <command|url> Infer an inline stdio or HTTP server.',
|
||||
' --server <name|json> Server name, HTTP URL, or JSON definition.',
|
||||
' --command <value> Inline stdio command or HTTP URL.',
|
||||
' --from <artifact> Regenerate from an existing generated CLI.',
|
||||
'',
|
||||
'Flags:',
|
||||
' --output <path> Write the TypeScript template to a path.',
|
||||
' --bundle [path] Emit a bundled JavaScript artifact.',
|
||||
' --compile [path] Emit a Bun-compiled binary.',
|
||||
' --runtime node|bun Runtime for generated code.',
|
||||
' --bundler rolldown|bun Bundler for JavaScript output.',
|
||||
' --timeout <ms> Discovery/call timeout in milliseconds.',
|
||||
' --minify / --no-minify Toggle bundle minification.',
|
||||
' --include-tools a,b Generate only these tools.',
|
||||
' --exclude-tools a,b Omit these tools.',
|
||||
' --dry-run Print regeneration command for --from.',
|
||||
].join('\n')
|
||||
);
|
||||
}
|
||||
|
||||
@ -1,11 +1,10 @@
|
||||
import { execFile } from 'node:child_process';
|
||||
import fsSync from 'node:fs';
|
||||
import fs from 'node:fs/promises';
|
||||
import { builtinModules, createRequire } from 'node:module';
|
||||
import { createRequire } from 'node:module';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import type { RolldownPlugin } from 'rolldown';
|
||||
import { MCPORTER_VERSION } from '../../version.js';
|
||||
import { markExecutable, safeCopyFile } from './fs-helpers.js';
|
||||
import { verifyBunAvailable } from './runtime.js';
|
||||
|
||||
@ -16,7 +15,6 @@ const packageRoot = fileURLToPath(new URL('../../..', import.meta.url));
|
||||
// even in empty temp dirs (fixes #1).
|
||||
const BUNDLED_DEPENDENCIES = ['commander', 'mcporter', 'jsonc-parser'] as const;
|
||||
const dependencyAliasPlugin = createLocalDependencyAliasPlugin([...BUNDLED_DEPENDENCIES]);
|
||||
const NODE_BUILTIN_SPECIFIERS = new Set(builtinModules.flatMap((specifier) => [specifier, `node:${specifier}`]));
|
||||
|
||||
export async function bundleOutput({
|
||||
sourcePath,
|
||||
@ -48,7 +46,7 @@ async function bundleWithRolldown({
|
||||
runtimeKind: 'node' | 'bun';
|
||||
minify: boolean;
|
||||
}): Promise<string> {
|
||||
let rolldownImpl: (typeof import('rolldown'))['rolldown'];
|
||||
let rolldownImpl: typeof import('rolldown')['rolldown'];
|
||||
try {
|
||||
({ rolldown: rolldownImpl } = await import('rolldown'));
|
||||
} catch (error) {
|
||||
@ -58,7 +56,7 @@ async function bundleWithRolldown({
|
||||
error.message = `${message}\n\n${error.message}`;
|
||||
throw error;
|
||||
}
|
||||
throw new Error(message, { cause: error });
|
||||
throw new Error(message);
|
||||
}
|
||||
const absTarget = path.resolve(targetPath);
|
||||
await fs.mkdir(path.dirname(absTarget), { recursive: true });
|
||||
@ -71,52 +69,19 @@ async function bundleWithRolldown({
|
||||
if (typeof (log as { code?: string }).code === 'string' && (log as { code?: string }).code === 'EVAL') {
|
||||
return;
|
||||
}
|
||||
if (isExpectedNodeBuiltinWarning(log)) {
|
||||
return;
|
||||
}
|
||||
handler(level, log);
|
||||
},
|
||||
});
|
||||
const format = outputFormatForTarget(absTarget, runtimeKind);
|
||||
await bundle.write({
|
||||
file: absTarget,
|
||||
format,
|
||||
codeSplitting: false,
|
||||
format: runtimeKind === 'bun' ? 'esm' : 'cjs',
|
||||
sourcemap: false,
|
||||
minify,
|
||||
...(format === 'esm' ? { banner: buildEsmRequireBanner() } : {}),
|
||||
});
|
||||
await markExecutable(absTarget);
|
||||
return absTarget;
|
||||
}
|
||||
|
||||
function isExpectedNodeBuiltinWarning(log: unknown): boolean {
|
||||
const record = log as { code?: string; message?: string };
|
||||
if (record.code !== 'UNRESOLVED_IMPORT' || typeof record.message !== 'string') {
|
||||
return false;
|
||||
}
|
||||
const match = record.message.match(/Could not resolve ['"]([^'"]+)['"]/);
|
||||
return Boolean(match?.[1] && NODE_BUILTIN_SPECIFIERS.has(match[1]));
|
||||
}
|
||||
|
||||
function buildEsmRequireBanner(): string {
|
||||
return [
|
||||
'import { createRequire as __mcporterCreateRequire } from "node:module";',
|
||||
'const require = __mcporterCreateRequire(import.meta.url);',
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
function outputFormatForTarget(targetPath: string, runtimeKind: 'node' | 'bun'): 'cjs' | 'esm' {
|
||||
const extension = path.extname(targetPath).toLowerCase();
|
||||
if (extension === '.mjs') {
|
||||
return 'esm';
|
||||
}
|
||||
if (extension === '.cjs') {
|
||||
return 'cjs';
|
||||
}
|
||||
return runtimeKind === 'bun' ? 'esm' : 'cjs';
|
||||
}
|
||||
|
||||
async function bundleWithBun({
|
||||
sourcePath,
|
||||
targetPath,
|
||||
@ -145,7 +110,7 @@ async function bundleWithBun({
|
||||
args.push('--minify');
|
||||
}
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
execFile(bunBin, args, { cwd: stagingDir, env: process.env }, (error) => {
|
||||
execFile(bunBin, args, { cwd: packageRoot, env: process.env }, (error) => {
|
||||
if (error) {
|
||||
reject(error);
|
||||
return;
|
||||
@ -290,62 +255,6 @@ async function ensureBundlerDeps(stagingDir: string): Promise<void> {
|
||||
await linkOrCopyDependency(sourceDir, target);
|
||||
})
|
||||
);
|
||||
const missing = await findMissingBundlerDeps(stagingDir);
|
||||
if (missing.length > 0) {
|
||||
await installPublishedBundlerDeps(stagingDir);
|
||||
}
|
||||
}
|
||||
|
||||
async function findMissingBundlerDeps(stagingDir: string): Promise<string[]> {
|
||||
const missing: string[] = [];
|
||||
for (const specifier of BUNDLED_DEPENDENCIES) {
|
||||
const pkgPath = path.join(stagingDir, 'node_modules', specifier, 'package.json');
|
||||
try {
|
||||
await fs.access(pkgPath);
|
||||
} catch {
|
||||
missing.push(specifier);
|
||||
}
|
||||
}
|
||||
return missing;
|
||||
}
|
||||
|
||||
async function installPublishedBundlerDeps(stagingDir: string): Promise<void> {
|
||||
const installSpec = process.env.MCPORTER_BUNDLER_DEP_PACKAGE ?? MCPORTER_VERSION;
|
||||
if (installSpec === '0.0.0-dev') {
|
||||
throw new Error(
|
||||
'Unable to resolve generated-CLI bundler dependencies from this standalone mcporter binary. Install mcporter via npm/Homebrew or publish the matching mcporter package before using --compile.'
|
||||
);
|
||||
}
|
||||
await fs.writeFile(
|
||||
path.join(stagingDir, 'package.json'),
|
||||
JSON.stringify({ private: true, type: 'module', dependencies: { mcporter: installSpec } }, null, 2),
|
||||
'utf8'
|
||||
);
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
execFile(
|
||||
'npm',
|
||||
['install', '--ignore-scripts', '--no-audit', '--no-fund', '--min-release-age=0'],
|
||||
{ cwd: stagingDir, env: process.env },
|
||||
(error) => {
|
||||
if (error) {
|
||||
reject(
|
||||
new Error(
|
||||
`Unable to install ${formatMcporterInstallSpec(installSpec)} dependencies needed for Bun compilation from this standalone binary. Install mcporter via npm/Homebrew, or ensure npm can reach the registry.\n\n${error.message}`
|
||||
)
|
||||
);
|
||||
return;
|
||||
}
|
||||
resolve();
|
||||
}
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
function formatMcporterInstallSpec(installSpec: string): string {
|
||||
if (installSpec === MCPORTER_VERSION) {
|
||||
return `mcporter@${MCPORTER_VERSION}`;
|
||||
}
|
||||
return `mcporter from ${installSpec}`;
|
||||
}
|
||||
|
||||
function resolveDependencyDirectory(specifier: (typeof BUNDLED_DEPENDENCIES)[number]): string | undefined {
|
||||
|
||||
@ -1,16 +1,7 @@
|
||||
import fs from 'node:fs/promises';
|
||||
import path from 'node:path';
|
||||
import type { CliArtifactMetadata } from '../../cli-metadata.js';
|
||||
import {
|
||||
type HttpCommand,
|
||||
loadServerDefinitions,
|
||||
type RawLifecycle,
|
||||
type RefreshableBearerOptions,
|
||||
type ServerDefinition,
|
||||
type ServerLoggingOptions,
|
||||
type StdioCommand,
|
||||
} from '../../config.js';
|
||||
import { resolveLifecycle } from '../../lifecycle.js';
|
||||
import { type HttpCommand, loadServerDefinitions, type ServerDefinition, type StdioCommand } from '../../config.js';
|
||||
import type { Runtime, ServerToolInfo } from '../../runtime.js';
|
||||
import { createRuntime } from '../../runtime.js';
|
||||
import { extractHttpServerTarget, normalizeHttpUrl } from '../http-utils.js';
|
||||
@ -185,6 +176,10 @@ function pickDescription(
|
||||
}
|
||||
|
||||
export function normalizeDefinition(def: DefinitionInput): ServerDefinition {
|
||||
if (isServerDefinition(def)) {
|
||||
return def;
|
||||
}
|
||||
|
||||
const name = def.name;
|
||||
if (typeof name !== 'string' || name.trim().length === 0) {
|
||||
throw new Error('Server definition must include a name.');
|
||||
@ -195,67 +190,29 @@ export function normalizeDefinition(def: DefinitionInput): ServerDefinition {
|
||||
const auth = typeof def.auth === 'string' ? def.auth : undefined;
|
||||
const tokenCacheDir = typeof def.tokenCacheDir === 'string' ? def.tokenCacheDir : undefined;
|
||||
const clientName = typeof def.clientName === 'string' ? def.clientName : undefined;
|
||||
const record = def as Record<string, unknown>;
|
||||
const oauthClientId = stringFromAliases(record, 'oauthClientId', 'oauth_client_id');
|
||||
const oauthClientSecret = stringFromAliases(record, 'oauthClientSecret', 'oauth_client_secret');
|
||||
const oauthClientSecretEnv = stringFromAliases(record, 'oauthClientSecretEnv', 'oauth_client_secret_env');
|
||||
const oauthTokenEndpointAuthMethod = stringFromAliases(
|
||||
record,
|
||||
'oauthTokenEndpointAuthMethod',
|
||||
'oauth_token_endpoint_auth_method'
|
||||
);
|
||||
const oauthRedirectUrl = typeof def.oauthRedirectUrl === 'string' ? def.oauthRedirectUrl : undefined;
|
||||
const oauthScope = typeof def.oauthScope === 'string' ? def.oauthScope : undefined;
|
||||
const refresh = getRefresh(record.refresh);
|
||||
const httpFetch = normalizeHttpFetch(stringFromAliases(record, 'httpFetch', 'http_fetch'));
|
||||
const headers = toStringRecord((def as Record<string, unknown>).headers);
|
||||
const oauthCommand = getOauthCommand(record.oauthCommand ?? record.oauth_command);
|
||||
const rawLifecycle = getRawLifecycle(record.lifecycle);
|
||||
const logging = getLogging(record.logging);
|
||||
const allowedTools = getOptionalStringArray(record.allowedTools ?? record.allowed_tools, 'allowedTools');
|
||||
const blockedTools = getOptionalStringArray(record.blockedTools ?? record.blocked_tools, 'blockedTools');
|
||||
if (allowedTools !== undefined && blockedTools !== undefined) {
|
||||
throw new Error(`Server definition '${name}' cannot specify both allowedTools and blockedTools.`);
|
||||
}
|
||||
const shared = (
|
||||
command: ServerDefinition['command']
|
||||
): Omit<ServerDefinition, 'name' | 'description' | 'command'> => ({
|
||||
env,
|
||||
auth,
|
||||
tokenCacheDir,
|
||||
clientName,
|
||||
oauthClientId,
|
||||
oauthClientSecret,
|
||||
oauthClientSecretEnv,
|
||||
oauthTokenEndpointAuthMethod,
|
||||
oauthRedirectUrl,
|
||||
oauthScope,
|
||||
oauthCommand,
|
||||
refresh,
|
||||
httpFetch,
|
||||
lifecycle: resolveLifecycle(name, rawLifecycle, command),
|
||||
logging,
|
||||
...(allowedTools !== undefined ? { allowedTools } : {}),
|
||||
...(blockedTools !== undefined ? { blockedTools } : {}),
|
||||
});
|
||||
|
||||
const commandValue = def.command;
|
||||
if (isCommandSpec(commandValue)) {
|
||||
const command = normalizeCommand(commandValue, headers);
|
||||
return {
|
||||
name,
|
||||
description,
|
||||
command,
|
||||
...shared(command),
|
||||
command: normalizeCommand(commandValue, headers),
|
||||
env,
|
||||
auth,
|
||||
tokenCacheDir,
|
||||
clientName,
|
||||
};
|
||||
}
|
||||
if (typeof commandValue === 'string' && commandValue.trim().length > 0) {
|
||||
const command = toCommandSpec(commandValue, getStringArray(record.args), headers ? { headers } : undefined);
|
||||
return {
|
||||
name,
|
||||
description,
|
||||
command,
|
||||
...shared(command),
|
||||
command: toCommandSpec(commandValue, getStringArray(def.args), headers ? { headers } : undefined),
|
||||
env,
|
||||
auth,
|
||||
tokenCacheDir,
|
||||
clientName,
|
||||
};
|
||||
}
|
||||
if (Array.isArray(commandValue) && commandValue.length > 0) {
|
||||
@ -263,17 +220,30 @@ export function normalizeDefinition(def: DefinitionInput): ServerDefinition {
|
||||
if (typeof first !== 'string' || !rest.every((entry) => typeof entry === 'string')) {
|
||||
throw new Error('Command array must contain only strings.');
|
||||
}
|
||||
const command = toCommandSpec(first, rest as string[], headers ? { headers } : undefined);
|
||||
return {
|
||||
name,
|
||||
description,
|
||||
command,
|
||||
...shared(command),
|
||||
command: toCommandSpec(first, rest as string[], headers ? { headers } : undefined),
|
||||
env,
|
||||
auth,
|
||||
tokenCacheDir,
|
||||
clientName,
|
||||
};
|
||||
}
|
||||
throw new Error('Server definition must include command information.');
|
||||
}
|
||||
|
||||
function isServerDefinition(value: unknown): value is ServerDefinition {
|
||||
if (typeof value !== 'object' || value === null) {
|
||||
return false;
|
||||
}
|
||||
const record = value as Record<string, unknown>;
|
||||
if (typeof record.name !== 'string') {
|
||||
return false;
|
||||
}
|
||||
return isCommandSpec(record.command);
|
||||
}
|
||||
|
||||
function isCommandSpec(value: unknown): value is ServerDefinition['command'] {
|
||||
if (typeof value !== 'object' || value === null) {
|
||||
return false;
|
||||
@ -341,88 +311,6 @@ function getStringArray(value: unknown): string[] | undefined {
|
||||
return entries.length > 0 ? entries : undefined;
|
||||
}
|
||||
|
||||
function getOptionalStringArray(value: unknown, fieldName: string): string[] | undefined {
|
||||
if (value === undefined) {
|
||||
return undefined;
|
||||
}
|
||||
if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
|
||||
throw new Error(`${fieldName} must be an array of strings.`);
|
||||
}
|
||||
return [...value];
|
||||
}
|
||||
|
||||
function getRawLifecycle(value: unknown): RawLifecycle | undefined {
|
||||
if (value === 'keep-alive' || value === 'ephemeral') {
|
||||
return value;
|
||||
}
|
||||
if (typeof value === 'object' && value !== null) {
|
||||
const record = value as { mode?: unknown; idleTimeoutMs?: unknown };
|
||||
if (record.mode === 'keep-alive' || record.mode === 'ephemeral') {
|
||||
return {
|
||||
mode: record.mode,
|
||||
...(typeof record.idleTimeoutMs === 'number' ? { idleTimeoutMs: record.idleTimeoutMs } : {}),
|
||||
};
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function getLogging(value: unknown): ServerLoggingOptions | undefined {
|
||||
if (typeof value !== 'object' || value === null) {
|
||||
return undefined;
|
||||
}
|
||||
const daemon = (value as { daemon?: unknown }).daemon;
|
||||
if (typeof daemon !== 'object' || daemon === null) {
|
||||
return undefined;
|
||||
}
|
||||
const enabled = (daemon as { enabled?: unknown }).enabled;
|
||||
return typeof enabled === 'boolean' ? { daemon: { enabled } } : { daemon: {} };
|
||||
}
|
||||
|
||||
function getOauthCommand(value: unknown): ServerDefinition['oauthCommand'] | undefined {
|
||||
if (typeof value !== 'object' || value === null) {
|
||||
return undefined;
|
||||
}
|
||||
const args = getStringArray((value as { args?: unknown }).args);
|
||||
return args ? { args } : undefined;
|
||||
}
|
||||
|
||||
function getRefresh(value: unknown): RefreshableBearerOptions | undefined {
|
||||
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
||||
return undefined;
|
||||
}
|
||||
const record = value as Record<string, unknown>;
|
||||
const tokenEndpoint = stringFromAliases(record, 'tokenEndpoint', 'token_endpoint');
|
||||
if (!tokenEndpoint) {
|
||||
return undefined;
|
||||
}
|
||||
const refreshSkewSeconds = record.refreshSkewSeconds ?? record.refresh_skew_seconds;
|
||||
return {
|
||||
tokenEndpoint,
|
||||
clientIdEnv: stringFromAliases(record, 'clientIdEnv', 'client_id_env'),
|
||||
clientSecretEnv: stringFromAliases(record, 'clientSecretEnv', 'client_secret_env'),
|
||||
clientAuthMethod: stringFromAliases(record, 'clientAuthMethod', 'client_auth_method'),
|
||||
...(typeof refreshSkewSeconds === 'number' && Number.isInteger(refreshSkewSeconds) && refreshSkewSeconds >= 0
|
||||
? { refreshSkewSeconds }
|
||||
: {}),
|
||||
accessTokenEnv: stringFromAliases(record, 'accessTokenEnv', 'access_token_env'),
|
||||
};
|
||||
}
|
||||
|
||||
function normalizeHttpFetch(value: string | undefined): ServerDefinition['httpFetch'] | undefined {
|
||||
return value === 'default' || value === 'node-http1' ? value : undefined;
|
||||
}
|
||||
|
||||
function stringFromAliases(record: Record<string, unknown>, ...keys: string[]): string | undefined {
|
||||
for (const key of keys) {
|
||||
const value = record[key];
|
||||
if (typeof value === 'string') {
|
||||
return value;
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function toStringRecord(value: unknown): Record<string, string> | undefined {
|
||||
if (typeof value !== 'object' || value === null) {
|
||||
return undefined;
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
import { parsePositiveInteger } from '../timeouts.js';
|
||||
|
||||
export interface GeneratorCommonFlags {
|
||||
runtime?: 'node' | 'bun';
|
||||
timeout?: number;
|
||||
@ -33,8 +31,8 @@ export function extractGeneratorFlags(args: string[], options: ExtractOptions =
|
||||
if (!raw) {
|
||||
throw new Error("Flag '--timeout' requires a value.");
|
||||
}
|
||||
const parsed = parsePositiveInteger(raw);
|
||||
if (parsed === undefined) {
|
||||
const parsed = Number.parseInt(raw, 10);
|
||||
if (!Number.isFinite(parsed) || parsed <= 0) {
|
||||
throw new Error('--timeout must be a positive integer.');
|
||||
}
|
||||
result.timeout = parsed;
|
||||
|
||||
@ -23,8 +23,6 @@ export interface GenerateFlags {
|
||||
minify?: boolean;
|
||||
from?: string;
|
||||
dryRun: boolean;
|
||||
includeTools?: string[];
|
||||
excludeTools?: string[];
|
||||
}
|
||||
|
||||
export function parseGenerateFlags(args: string[]): GenerateFlags {
|
||||
@ -42,8 +40,6 @@ export function parseGenerateFlags(args: string[]): GenerateFlags {
|
||||
let minify: boolean | undefined;
|
||||
let from: string | undefined;
|
||||
let dryRun = false;
|
||||
let includeTools: string[] | undefined;
|
||||
let excludeTools: string[] | undefined;
|
||||
|
||||
let index = 0;
|
||||
while (index < args.length) {
|
||||
@ -62,18 +58,6 @@ export function parseGenerateFlags(args: string[]): GenerateFlags {
|
||||
args.splice(index, 1);
|
||||
continue;
|
||||
}
|
||||
if (token === '--include-tools') {
|
||||
const value = expectValue(token, args[index + 1]);
|
||||
includeTools = mergeCsvList(includeTools, value);
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
}
|
||||
if (token === '--exclude-tools') {
|
||||
const value = expectValue(token, args[index + 1]);
|
||||
excludeTools = mergeCsvList(excludeTools, value);
|
||||
args.splice(index, 2);
|
||||
continue;
|
||||
}
|
||||
if (token === '--server') {
|
||||
server = expectValue(token, args[index + 1]);
|
||||
args.splice(index, 2);
|
||||
@ -184,30 +168,9 @@ export function parseGenerateFlags(args: string[]): GenerateFlags {
|
||||
minify,
|
||||
from,
|
||||
dryRun,
|
||||
includeTools,
|
||||
excludeTools,
|
||||
};
|
||||
}
|
||||
|
||||
function mergeCsvList(existing: string[] | undefined, value: string): string[] {
|
||||
const parts = value
|
||||
.split(',')
|
||||
.map((entry) => entry.trim())
|
||||
.filter((entry) => entry.length > 0);
|
||||
|
||||
const base = existing ?? [];
|
||||
const merged = [...base, ...parts];
|
||||
const seen = new Set<string>();
|
||||
const result: string[] = [];
|
||||
for (const name of merged) {
|
||||
if (!seen.has(name)) {
|
||||
seen.add(name);
|
||||
result.push(name);
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
function normalizeCommandInput(value: string): CommandInput {
|
||||
const httpCandidate = normalizeHttpUrlCandidate(value);
|
||||
if (httpCandidate) {
|
||||
|
||||
@ -167,7 +167,8 @@ function deriveNameFromUrl(url: URL): string | undefined {
|
||||
return last;
|
||||
}
|
||||
}
|
||||
const firstSegment = url.pathname.split('/').find(Boolean);
|
||||
const segments = url.pathname.split('/').filter(Boolean);
|
||||
const firstSegment = segments[0];
|
||||
if (firstSegment) {
|
||||
return firstSegment.replace(/[^a-zA-Z0-9-_]/g, '-');
|
||||
}
|
||||
|
||||
@ -17,9 +17,7 @@ export async function performGenerateFromArtifact(
|
||||
|
||||
export async function performGenerateFromRequest(request: GenerateCliOptions): Promise<void> {
|
||||
const { outputPath, bundlePath, compilePath } = await generateCli(request);
|
||||
if (request.outputPath || (!bundlePath && !compilePath)) {
|
||||
console.log(`Generated CLI at ${outputPath}`);
|
||||
}
|
||||
console.log(`Generated CLI at ${outputPath}`);
|
||||
if (bundlePath) {
|
||||
console.log(`Bundled executable created at ${bundlePath}`);
|
||||
}
|
||||
|
||||
@ -1,32 +0,0 @@
|
||||
export function stableJsonStringify(value: unknown, space?: number): string {
|
||||
const json = JSON.stringify(sortJsonValue(value), undefined, space);
|
||||
if (json === undefined) {
|
||||
throw new TypeError('Cannot serialize unsupported JSON root value.');
|
||||
}
|
||||
return json;
|
||||
}
|
||||
|
||||
function sortJsonValue(value: unknown): unknown {
|
||||
if (Array.isArray(value)) {
|
||||
return value.map((entry) => sortJsonValue(entry));
|
||||
}
|
||||
if (!isPlainObject(value)) {
|
||||
return value;
|
||||
}
|
||||
const result: Record<string, unknown> = {};
|
||||
for (const key of Object.keys(value).toSorted()) {
|
||||
const entry = (value as Record<string, unknown>)[key];
|
||||
if (entry !== undefined) {
|
||||
result[key] = sortJsonValue(entry);
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
function isPlainObject(value: unknown): value is Record<string, unknown> {
|
||||
if (!value || typeof value !== 'object') {
|
||||
return false;
|
||||
}
|
||||
const prototype = Object.getPrototypeOf(value);
|
||||
return prototype === Object.prototype || prototype === null;
|
||||
}
|
||||
@ -54,12 +54,6 @@ export function buildGenerateCliCommand(
|
||||
if (invocation.minify) {
|
||||
tokens.push('--minify');
|
||||
}
|
||||
if (invocation.includeTools && invocation.includeTools.length > 0) {
|
||||
tokens.push('--include-tools', invocation.includeTools.join(','));
|
||||
}
|
||||
if (invocation.excludeTools && invocation.excludeTools.length > 0) {
|
||||
tokens.push('--exclude-tools', invocation.excludeTools.join(','));
|
||||
}
|
||||
return tokens.map(shellQuote).join(' ');
|
||||
}
|
||||
|
||||
@ -74,8 +68,6 @@ export function resolveGenerateRequestFromArtifact(
|
||||
timeout: number;
|
||||
compile?: GenerateCliOptions['compile'];
|
||||
minify?: boolean;
|
||||
includeTools?: string[];
|
||||
excludeTools?: string[];
|
||||
},
|
||||
metadata: CliArtifactMetadata,
|
||||
globalFlags: Record<string, string | undefined>
|
||||
@ -89,19 +81,6 @@ export function resolveGenerateRequestFromArtifact(
|
||||
if (!serverRef) {
|
||||
throw new Error('Unable to determine server definition from artifact; pass --server with a target name.');
|
||||
}
|
||||
|
||||
const includeTools = parsed.includeTools ?? invocation.includeTools;
|
||||
const excludeTools = parsed.excludeTools ?? invocation.excludeTools;
|
||||
if (includeTools && excludeTools) {
|
||||
throw new Error('Cannot combine --include-tools and --exclude-tools.');
|
||||
}
|
||||
if (includeTools && includeTools.length === 0) {
|
||||
throw new Error('--include-tools requires at least one tool name.');
|
||||
}
|
||||
if (excludeTools && excludeTools.length === 0) {
|
||||
throw new Error('--exclude-tools requires at least one tool name.');
|
||||
}
|
||||
|
||||
return {
|
||||
serverRef,
|
||||
configPath: globalFlags['--config'] ?? invocation.configPath,
|
||||
@ -113,8 +92,6 @@ export function resolveGenerateRequestFromArtifact(
|
||||
timeoutMs: parsed.timeout ?? invocation.timeoutMs,
|
||||
compile: parsed.compile ?? invocation.compile,
|
||||
minify: parsed.minify ?? invocation.minify ?? false,
|
||||
includeTools,
|
||||
excludeTools,
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user