mcp-cli-scripts

MCP CLI スクリプトパターン

ステータス：本番環境対応 最終更新日：2026-01-09 依存関係：tsx（開発依存関係） 現在のバージョン：[email protected]

---

MCP サーバーと併せて CLI スクリプトを作成する理由

MCP サーバーを構築する際は、ターミナル環境で Claude Code と併用するために、同じ機能（多くの場合は拡張機能も）を提供する CLI スクリプトも作成してください。

項目	リモート MCP（Claude.ai）	CLI スクリプト（Claude Code）
コンテキスト	結果はモデルのコンテキストウィンドウを経由します	結果はローカルに保持され、関連部分のみが共有されます
ファイルシステム	アクセス不可	読み取り／書き込みに完全対応
バッチ処理	1 回につき 1 件	入力ファイルの複数項目を処理可能
キャッシュ	ステートレス	結果をローカルにキャッシュ可能
出力	モデルに JSON を出力	JSON、CSV、テーブル、ファイル、または stdout
連結	モデルが調整	スクリプトを直接パイプ／連結可能

---

ディレクトリ構成

mcp-{name}/
├── src/
│   └── index.ts              # MCP server (for Claude.ai, remote clients)
├── scripts/
│   ├── {tool-name}.ts        # One script per tool
│   ├── {another-tool}.ts
│   └── _shared.ts            # Shared auth/config helpers (optional)
├── SCRIPTS.md                # Documents available scripts for Claude Code
├── package.json
└── README.md

---

5 つの設計原則

1. ツールごとに 1 つのスクリプト

各スクリプトは 1 つの処理に特化し、拡張機能を備えながら MCP ツールに対応させます。

2. デフォルトで JSON を出力

スクリプトは解析しやすいよう、デフォルトで stdout に JSON を出力します。Claude Code はその結果を読み取って利用できます。

// Good - structured output
console.log(JSON.stringify({ success: true, data: result }, null, 2));

// Avoid - unstructured text (unless --format text requested)
console.log("Found 5 results:");

3. ローカル利用向けの拡張機能

CLI スクリプトでは、リモート MCP には適さない機能を提供できます。

// Input/Output files
--input data.csv          // Batch process from file
--output results.json     // Save results to file
--append                  // Append to existing file

// Caching
--cache                   // Use local cache
--cache-ttl 3600          // Cache for 1 hour
--no-cache                // Force fresh request

// Output formats
--format json|csv|table   // Different output formats
--quiet                   // Suppress non-essential output
--verbose                 // Extra debugging info

// Batch operations
--batch                   // Process multiple items
--concurrency 5           // Parallel processing limit

4. 一貫性のある引数パターン

すべてのスクリプトで一貫性のあるパターンを使用します。

# Standard patterns
--input <file>            # Read input from file
--output <file>           # Write output to file
--format <type>           # Output format
--profile <name>          # Auth profile (for multi-account)
--verbose                 # Debug output
--help                    # Show usage

5. シバンと直接実行

スクリプトは直接実行できるようにします。

#!/usr/bin/env npx tsx
/**
 * Brief description of what this script does
 *
 * Usage:
 *   npx tsx scripts/tool-name.ts <required-arg>
 *   npx tsx scripts/tool-name.ts --option value
 *
 * Examples:
 *   npx tsx scripts/tool-name.ts 12345
 *   npx tsx scripts/tool-name.ts --input batch.csv --output results.json
 */

---

重要なルール

必ず行うこと

✅ #!/usr/bin/env npx tsx のシバンを使用します（node や ts-node ではありません） ✅ デフォルトで stdout に JSON を出力します ✅ すべてのスクリプトで一貫性のある引数パターンを使用します ✅ スクリプトを SCRIPTS.md に記載します ✅ エラーは構造化 JSON { success: false, error: "..." } で処理します

絶対に行わないこと

❌ 説明文の出力に console.log() を使用しません（構造化 JSON を使用します） ❌ スクリプトごとに異なる引数パターンを使用しません ❌ スクリプトを SCRIPTS.md に記載し忘れません ❌ シバンに node や ts-node を使用しません（tsx が ESM と TypeScript を処理します）

---

スクリプトと MCP の使い分け

CLI スクリプトを使用する場合：

• ターミナル／Claude Code 環境で作業するとき
• 結果をファイルに保存する必要があるとき
• ファイルからの入力をまとめて処理するとき
• 複数の操作を連結するとき
• 繰り返し行う検索でキャッシュが必要なとき
• より多様な出力形式を使いたいとき

MCP ツールを使用する場合：

• Claude.ai のウェブインターフェースを使うとき
• 単発の簡単な検索を行うとき
• ファイル I/O が不要なとき
• 会話型のフローを構築するとき

---

MCP とスクリプトで共有するコード

MCP とスクリプトでロジックを共有する場合は、コアモジュールに切り出します。

src/
├── core/
│   ├── lookup.ts         # Pure function, no I/O assumptions
│   └── index.ts          # Export all core functions
├── mcp/
│   └── index.ts          # MCP handlers, import from core
└── cli/
    └── lookup.ts         # CLI wrapper, import from core

ただし、別々に管理しても問題ありません。スクリプトは MCP では対応できない機能を備えるように進化する場合がありますが、それで構いません。

---

バンドルされたリソースの使用

テンプレート（templates/）

script-template.ts：引数の解析、JSON 出力、ファイル I/O のパターンを含む、TypeScript スクリプトの完全なテンプレートです。

# Copy to your project
cp ~/.claude/skills/mcp-cli-scripts/templates/script-template.ts scripts/new-tool.ts

SCRIPTS-TEMPLATE.md：MCP サーバーのリポジトリで利用可能なスクリプトを説明するためのテンプレートです。

# Copy to your project
cp ~/.claude/skills/mcp-cli-scripts/templates/SCRIPTS-TEMPLATE.md SCRIPTS.md

ルール（rules/）

mcp-cli-scripts.md：スクリプトファイルの修正ルールです。プロジェクトの .claude/rules/ にコピーします。

cp ~/.claude/skills/mcp-cli-scripts/rules/mcp-cli-scripts.md .claude/rules/

---

依存関係

必須：

• [email protected] - コンパイルせずに TypeScript を実行

package.json に追加します：

{
  "devDependencies": {
    "tsx": "^4.21.0"
  }
}

---

公式ドキュメント

• tsx：https://github.com/privatenumber/tsx
• Node.js CLI：https://nodejs.org/api/cli.html

---

パッケージバージョン（2026-01-09 確認済み）

{
  "devDependencies": {
    "tsx": "^4.21.0"
  }
}

---

セットアップ完了チェックリスト

• MCP サーバープロジェクトに scripts/ ディレクトリを作成する
• tsx を devDependencies に追加する
• テンプレートから最初のスクリプトを作成する
• テンプレートから SCRIPTS.md を作成する
• スクリプトをテストする：npx tsx scripts/tool-name.ts --help
• JSON 出力形式を確認する
• すべてのスクリプトを SCRIPTS.md に記載する