Migration Guide

This guide walks through replacing the Python-based pnpm mcp:* helpers with the new TypeScript runtime and CLI.

#1. Install

pnpm add mcporter
# or
yarn add mcporter
# or
npm install mcporter

#2. Update Scripts

• Replace pnpm mcporter:list with npx mcporter list.
• Replace pnpm mcporter:call <server>.<tool> key=value with npx mcporter call <server>.<tool> key=value.
• Add --config <path> if your configuration is not under ./config/mcporter.json.
• Optional: set "imports" inside mcporter.json (for example [] to disable auto-imports or ["cursor", "codex"] to customize the order).
• Append --tail-log to stream the last 20 lines of any log file returned by the tool.

#3. OAuth Tokens

• Tokens are saved in the shared vault under ~/.mcporter/credentials.json by default, or $XDG_DATA_HOME/mcporter/credentials.json when XDG_DATA_HOME is set.
• 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

import { createRuntime } from 'mcporter';

const runtime = await createRuntime({ configPath: './config/mcporter.json' });
const tools = await runtime.listTools('chrome-devtools');
await runtime.callTool('chrome-devtools', 'take_screenshot', { args: { url: 'https://x.com' } });
await runtime.close();

Prefer createRuntime for long-lived agents so connections and OAuth tokens can be reused.

#5. Single Call Helper

import { callOnce } from 'mcporter';

await callOnce({
  server: 'firecrawl',
  toolName: 'crawl',
  args: { url: 'https://anthropic.com' },
});

Use callOnce for fire-and-forget invocations.

#6. Environment Variables

• LINEAR_API_KEY, FIRECRAWL_API_KEY, and similar tokens are read exactly as before via ${VAR} syntax.
• ${VAR:-default} continues to work; empty values are ignored.
• $env:VAR placeholders resolve to raw OS environment variables.

#7. Troubleshooting

For deeper architectural notes and future work, see docs/spec.md.