MCP Tool Documentation

MCP ツールのドキュメント

概要

MCP ツールは、Model Context Protocol（MCP）サーバーを管理するためのコマンドラインユーティリティです。Claude や Cursor などのツールと、さまざまな MCP サーバーの実行、設定、統合を行うための統一インターフェースを提供します。

主な機能

コア機能

• 利用可能な MCP サーバーとサーバーグループを一覧表示
• MCP サーバーを個別またはグループ単位で実行
• サーバーの詳細情報を表示
• すべてのサーバーの包括的なドキュメントを生成
• サーバー定義を JSON 形式で出力

高度な機能

• Claude との統合：サーバー定義を Claude MCP に簡単に追加
• Cursor との統合：サーバー定義を Cursor の MCP 設定に追加
• .zshrc 用オートローダー：オートコンプリート機能を備えたシェル環境への統合
• インタラクティブモード：使いやすいメニューからサーバーを選択、管理
• 設定ウィザード：サーバーが必要とする環境変数を設定
• エラーハンドリングの改善：問題発生時のフィードバックを向上
• ヘルプシステムの強化：各コマンドの詳細な使用方法を表示

インストール

1. スクリプトファイルを任意の場所にクローンまたはダウンロードします：

   git clone https://github.com/your-username/mcptool.git
   cd mcptool
   

2. メインスクリプトを実行可能にします：

   chmod +x mcptool.sh
   

3. 必要な依存関係がインストールされていることを確認します：

   • jq：JSON プロセッサ（サーバー設定の解析に必要）
   • dialog：オプション。インタラクティブモードで使用

4. （任意）アクセスしやすいようにエイリアスを作成します：

   alias mcpt='/path/to/mcptool.sh'
   

使用方法

メインスクリプト（mcptool.sh）は、すべての機能を利用するための統一されたコマンドセンターとして機能します。

基本コマンド

MCP Tool v1.2.0 - Manage MCP Servers

Usage: ./bin/mcptool.sh <command> [target] [options]

Commands:
  list                   List servers and groups
  run <target> [--bg]    Run a server or group. Groups run in separate terminals.
                         Use --background or --bg to run in detached background mode.
  add <server> <opts>    Add server definition to a required backend/file.
                         Target Options (required): --claude | --cursor [--global] | --json <file> | <file>
  info <target> [-v]     Show info for a server or group (use -v for group details)
  json <target>          Output server/group JSON definition
  docs                   Show documentation for all servers
  interactive            Launch interactive TUI menu (requires 'dialog')
  autoloader             Generate shell autocompletion script
  help <cmd>             Show detailed help for a command

Common Options:
  --servers-file=<path>  Specify servers file (default: /Users/estiens/code/mcptool/config/servers.json)
  --groups-file=<path>   Specify groups file (default: /Users/estiens/code/mcptool/config/groups.json)
  -v, --verbose          Show detailed output (used with 'info group')
  --background, --bg     Run server/group in background (used with 'run')

Note: The tool supports both JSON and YAML formats for configuration files

Run './bin/mcptool.sh help <command>' for more details on a specific command.

共通オプション

• -v, --verbose：詳細な出力を表示します（特に info コマンドで便利です）
• --project：Claude／Cursor との統合にプロジェクトレベルのスコープを使用します（デフォルト）
• --global：Claude／Cursor との統合にグローバル／ユーザーレベルのスコープを使用します
• --json-file=<path>：カスタム JSON ファイルの場所を指定します

環境変数

• MCP_CONFIG_FILE：JSON 設定ファイルの代替パス

オートローダーによるシェル統合

オートローダー機能は、.zshrc ファイルから読み込めるスクリプトを作成し、MCP サーバーコマンド用の便利なシェル関数とタブ補完を提供します。

1. オートローダーファイルを生成します：

   ./mcptool.sh autoloader
   

2. .zshrc ファイルに次の行を追加します：

   source ~/.mcp_autoloader.zsh
   

3. シェルを再読み込みすると、タブ補完を使って次のコマンドを実行できます：

   • mcpt list：利用可能なすべてのサーバーとグループを一覧表示
   • mcpt run <server|group>：指定したサーバーまたはグループを実行
   • mcpt info <server|group>：サーバーまたはグループの情報を取得
   • mcpt json <server|group>：サーバーまたはグループの JSON 定義を取得
   • mcpt add <server> --claude|--cursor [--global]|--json <file>|<file>：サーバー定義を追加
   • mcpt docs：包括的なドキュメントを生成
   • mcpt interactive：インタラクティブモードを起動

インタラクティブモード

インタラクティブモードでは、使いやすいメニューインターフェースから MCP サーバーを管理できます。次のコマンドで起動します：

./mcptool.sh interactive

メニューから次の操作を行えます：

• サーバーを実行
• サーバー情報を取得
• サーバーグループを実行
• グループ情報を取得
• ドキュメントを表示
• 「add」コマンドを使ってサーバー定義を追加（インタラクティブモード外）
• アプリケーションを終了

Claude と Cursor の統合

MCP ツールを使うと、Claude と Cursor の両方にサーバー定義を簡単に追加できます：

Claude との統合

# Add a server definition to Claude MCP (project scope)
./mcptool.sh add server_name --claude

# Add a server definition to Claude MCP (global/user scope)
./mcptool.sh add server_name --claude --global

# Add a server definition, overwriting existing Claude config
./mcptool.sh add server_name --claude --overwrite

# Note: Adding entire groups directly is not supported via 'add'. Add servers individually.

Cursor との統合

# Add a server definition to Cursor MCP (project scope - ./.cursor/mcp.json)
./mcptool.sh add server_name --cursor

# Add a server definition to Cursor MCP (global scope - ~/.cursor/mcp.json)
./mcptool.sh add server_name --cursor --global

# Add a server definition, overwriting existing Cursor config
./mcptool.sh add server_name --cursor --overwrite

# Note: Adding entire groups directly is not supported via 'add'. Add servers individually.

JSON／YAML ファイルへの追加

# Add a server definition to a specific JSON file
./mcptool.sh add server_name --json path/to/your/config.json

# Add a server definition, overwriting the target JSON file
./mcptool.sh add server_name --json path/to/your/config.json --overwrite

# Add a server definition to a specific YAML file (or any text file)
./mcptool.sh add server_name path/to/your/config.yaml

# Add a server definition, overwriting the target YAML file
./mcptool.sh add server_name path/to/your/config.yaml --overwrite

設定ファイル

MCP サーバーは、次の構造の JSON 設定ファイルで定義します：

{
  "servers": {
    "server_name": {
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "required_env": ["ENV_VAR1", "ENV_VAR2"],
      "description": "Server description"
    }
  },
  "groups": {
    "group_name": ["server1", "server2"]
  }
}

トラブルシューティング

よくある問題

1. JSON ファイルが見つからない

   • --json-file=path/to/file で正しいパスを指定していることを確認してください
   • MCP_CONFIG_FILE 環境変数が正しく設定されているか確認してください
   • デフォルトの場所はスクリプトと同じディレクトリです：mcp_servers.json

2. 依存関係が不足している

   • jq をインストールしてください：brew install jq（macOS）または sudo apt-get install -y jq（Ubuntu/Debian）
   • dialog をインストールしてください（対話モード用）：brew install dialog（macOS）または sudo apt-get install -y dialog（Ubuntu/Debian）

3. 環境変数が不足している

   • 一部のサーバーでは環境変数が必要です。必要な変数については、サーバーのドキュメント（mcptool docs または mcptool info <server>）を確認してください。
   • 環境または .env ファイル（例：.env.mcp）に設定し、読み込んでください（source .env.mcp）。

4. 「add」コマンドが失敗する

   • 有効な対象を指定していることを確認してください：--claude、--cursor [--global]、--json <file>、またはファイル名 <file>。
   • --claude の場合：Claude CLI がインストールされ、PATH に含まれていることを確認してください。
   • --cursor またはファイルを対象にする場合：対象のディレクトリ／ファイルに書き込み可能か確認してください。

5. 無効な JSON エラー

   • jq empty your_file.json を使用して JSON ファイルを検証してください
   • よくある問題には、カンマの不足、余分なカンマ、文字列の引用符の誤りなどがあります

プラットフォーム固有の問題

• macOS：sed -i コマンドの動作は macOS では異なります。スクリプトが自動的に対応します。
• Linux：既知のプラットフォーム固有の問題はありません。
• Windows：直接サポートされていません。WSL（Windows Subsystem for Linux）の使用を検討してください。

コントリビュート

ライブラリに新しい MCP サーバーを追加するには：

1. JSON 設定ファイルを編集して、新しいサーバー定義を追加します
2. MCP Tool でサーバーをテストします
3. サーバーの目的、要件、使い方を記述します
4. メインリポジトリに貢献する場合は、プルリクエストを送信します

ライセンス

このツールは、DWTFYouWant の unlicense の下で提供されています