MCPorter 🧳

TypeScript runtime & CLI toolkit for the Model Context Protocol · v0.8.1

1 — 概要
MCPorter とは

MCPorter は、Cursor・Claude・Codex・VS Code などで設定済みの MCP（Model Context Protocol）サーバーを、TypeScript コードや CLI からゼロ設定で呼び出すためのランタイムおよびツールキット。サーバー探索・型付きクライアント生成・スタンドアロン CLI 生成・OAuth 管理を一手に担う。

Zero Configエディタ設定を自動取得
Typed ProxycamelCase メソッドで呼び出し
CLI Gen任意 MCP をCLIに変換
OAuthブラウザ認証を自動化
ディスカバリ

createRuntime() は ~/.mcporter/mcporter.json・プロジェクト設定・Cursor/Claude/Codex/Windsurf/VS Code のインポートをマージし、${ENV} 変数展開・接続プールを透過的に行う。

対応プラットフォーム
  • macOS · Linux · Windows（Node ≥ 20.11）
  • HTTP / SSE / stdio トランスポート統一 API
  • npx mcporter でインストール不要即時実行
  • Homebrew tap 経由のバイナリ配布にも対応
2 — Quick Start & CLI
呼び出しスタイルの比較
スタイル例特徴
colon-flag linear.create_comment issueId:ENG-123 body:'Hi' シェルスクリプト向け。key=value / key:value 両対応。
function-call 'linear.create_comment(issueId: "ENG-123", body: "Hi")' mcporter list のシグネチャをそのままコピペ可能。
HTTP selector https://mcp.linear.app/mcp.list_issues URL + ツール名を直接指定。config 不要。
shorthand mcporter linear.list_issues 動詞を省略。dotted token は call に自動解釈。
list — サーバー確認
bash
# 全サーバー一覧
npx mcporter list

# TypeScript 形式のシグネチャ表示
npx mcporter list context7 --schema

# 全パラメータを展開
npx mcporter list linear --all-parameters

# JSON 出力（スクリプト連携）
npx mcporter list --json
call — ツール実行
bash
# Context7 でドキュメント取得
npx mcporter call context7.resolve-library-id \
  libraryName=react

# Linear にコメント投稿
npx mcporter call \
  'linear.create_comment(issueId: "LNR-123", body: "Hello")'

# Chrome DevTools スナップショット
npx mcporter call chrome-devtools.take_snapshot

# 未設定サーバーにアドホック接続
npx mcporter call \
  --stdio "bun run ./local-server.ts" --name local
list が返す TypeScript 形式シグネチャ
typescript — mcporter list linear の出力例
linear - Hosted Linear MCP
  23 tools · 1654ms · HTTP https://mcp.linear.app/mcp

  /**
   * Create a comment on a specific Linear issue
   * @param issueId The issue ID
   * @param body    The content of the comment as Markdown
   * @param parentId? A parent comment ID to reply to
   */
  function create_comment(issueId: string, body: string, parentId?: string): Comment;
  // optional (3): notifySubscribers, labelIds, mentionIds
オートコレクト: ツール名をタイポすると MCPorter がカタログを検索し、編集距離が小さければ自動補正、大きければ Did you mean …? ヒントを表示する。
主な CLI フラグ
フラグ対象コマンド説明
--config <path>全般config ファイルを明示指定
--http-url <url>list / call / authアドホック HTTP MCP サーバー指定
--stdio "cmd"list / call / authアドホック stdio サーバー指定
--persist <path>list / callアドホック定義を config に保存
--all-parameterslist省略された任意パラメータを全展開
--output json|rawcallJSON / 生テキスト出力
--tail-logcallレスポンスのログファイルを末尾表示
--raw-stringscall数値的引数を文字列として保持
--oauth-timeout <ms>call / authOAuth ブラウザ待機時間を変更
3 — Runtime API
callOnce — ワンショット呼び出し

最もシンプルな API。サーバー探索・OAuth・トランスポートの開閉を自動処理する。単発スクリプトやエージェントのツールフックに適している。

typescript
import { callOnce } from "mcporter";

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

console.log(result); // 生 MCP エンベロープ
createRuntime — 接続プール

複数回呼び出す場合やストリーミングが必要な場合は createRuntime() を使う。OAuth トークンのリフレッシュ・トランスポート再利用を内包する。

typescript
import { createRuntime } from "mcporter";

const runtime = await createRuntime();

const tools  = await runtime.listTools("context7");
const result = await runtime.callTool("context7", "resolve-library-id", {
  args: { libraryName: "react" },
});

console.log(result);
await runtime.close(); // トランスポートとセッションを終了
createServerProxy — 型付きプロキシ

ツール名を camelCase メソッドとして呼び出せる人間向け API。引数マッピング・JSON スキーマデフォルト適用・CallResult でラップが自動で行われる。

typescript
import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const chrome  = createServerProxy(runtime, "chrome-devtools");
const linear  = createServerProxy(runtime, "linear");

// takeSnapshot → take_snapshot に自動マッピング
const snapshot = await chrome.takeSnapshot();
console.log(snapshot.text());

// CallResult ヘルパー: .text() .json() .images() .markdown() .content() .raw
const docs = await linear.searchDocumentation({ query: "automations" });
console.log(docs.json());

await runtime.close();
4 — コード生成
generate-cli — CLI 生成

任意の MCP サーバー定義をスタンドアロン CLI に変換する。生成物にはリジェネレーション用メタデータが埋め込まれる。

bash
# HTTP MCP を CLI に変換
npx mcporter generate-cli \
  --command https://mcp.context7.com/mcp
# → context7.ts / context7.js を出力

# stdio MCP を Bun コンパイル済みバイナリに
npx mcporter generate-cli \
  "npx -y chrome-devtools-mcp@latest" \
  --compile

# 特定ツールだけ含める
npx mcporter generate-cli linear \
  --include-tools list_issues,create_issue

# 既存 CLI を最新 mcporter でリジェネ
npx mcporter generate-cli \
  --from dist/context7.js
emit-ts — 型クライアント生成

mcporter list と同じシグネチャ・Doc ブロックから .d.ts インターフェースまたはクライアントラッパーを生成する。

bash
# 型定義のみ（.d.ts）
npx mcporter emit-ts linear \
  --out types/linear-tools.d.ts

# クライアントラッパー（.d.ts + .ts）
npx mcporter emit-ts linear \
  --mode client --out clients/linear.ts

# 任意パラメータも含む
npx mcporter emit-ts linear \
  --mode client --include-optional \
  --out clients/linear-full.ts

# JSON サマリ出力（スクリプト連携）
npx mcporter emit-ts linear --json
--mode client を指定すると createRuntime / createServerProxy をラップしたファクトリ関数も一緒に出力される。
5 — 設定管理
config ファイル形式（JSONC）
config/mcporter.json
{
  "$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
  "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"]
}
${VAR} / ${VAR:-fallback} / $env:VAR の変数展開に対応。インラインコメント（// / /* */）と末尾カンマも許可される JSONC 形式。
解決優先度
優先度ソース備考
1--http-url / --stdio / ベア URL最高優先。--persist がない限りキャッシュされない。
2config/mcporter.json（または --config 指定）プロジェクトルートのローカル設定。
3~/.mcporter/mcporter.jsonホームディレクトリのグローバル設定。プロジェクト設定とマージされる。
4imports リストのエディタ設定Cursor / Claude / Codex / Windsurf / VS Code など。読み取り専用スナップショット。
config サブコマンド
サブコマンド説明
config list [filter]ローカルエントリを表示。--source import でインポート元を表示。
config get <name>単一サーバーの解決済み定義とソースパスを表示。
config add <name> [target]サーバーを config に永続化（URL または stdio コマンド）。
config remove <name>ローカルエントリを削除。インポート由来のエントリはコピー後に削除可能。
config import <kind>cursor / claude-code / codex などの設定を表示・コピー。
config login <name|url>OAuth / auth フローを完了し ~/.mcporter/<name>/ にキャッシュ。
config logout <name>OAuth トークンキャッシュを削除。--all で全消去。
config doctorconfig ファイルの共通ミスを検証（開発中）。
6 — デーモン（keep-alive）
ステートフルサーバーの維持

chrome-devtools や mobile-mcp のようなステートフル stdio サーバーは、初回呼び出し時に per-login デーモンが自動起動し、Chrome タブやデバイスセッションを複数の呼び出し間で維持する。

bash
# デーモンの状態確認（接続中サーバー一覧）
mcporter daemon status

# デーモンを明示的に起動
mcporter daemon start

# 起動しつつログをファイルに出力
mcporter daemon start --log --log-file /tmp/daemon.log

# 設定変更後にバウンス
mcporter daemon restart

# デーモン停止
mcporter daemon stop
lifecycle 設定

サーバーエントリに "lifecycle": "keep-alive" を追加するか、MCPORTER_KEEPALIVE=name 環境変数で指定するとデーモン管理対象になる。逆に "lifecycle": "ephemeral" または MCPORTER_DISABLE_KEEPALIVE=name でオプトアウト可能。

アドホック接続（--stdio / --http-url）はデーモン管理外。--persist で config に書き込んでから lifecycle を設定する。
デバッグ手法
  • MCPORTER_DEBUG_HANG=1 — ハングしたトランスポートの詳細ログを出力
  • --log-level debug — 全コマンドで詳細ログを有効化
  • --log-servers <name> — 特定サーバーの呼び出しトレースのみ出力
  • tmux new-session -- pnpm mcporter:list — バックグラウンドで長時間セッションを維持しつつ調査
  • ハング調査の詳細は docs/hang-debug.md と docs/tmux.md を参照
関連リンク