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