MCP Perforce Server

MCP Perforce Server

Claude Desktop で Perforce（P4）操作を行うための、使いやすいインターフェースを提供する Model Context Protocol（MCP）サーバーです。このサーバーは P4 コマンドをラップし、対話型プロンプトや複雑な状態管理に関する問題を解消して、Claude がより確実かつ簡単に利用できるようにします。

特長

• 非対話型の操作：対話型プロンプトを回避できるよう、すべてのコマンドをラップします
• 構造化された応答：生の P4 出力ではなく、整理されて解析可能な出力を返します
• 複数プロジェクトのサポート：プロジェクトごとの設定に .p4config ファイルを自動的に使用します
• 一般的な操作：追加、編集、削除、サブミット、取り消し、同期など
• チェンジリスト管理：明示的なパラメーターを指定してチェンジリストを作成、サブミットします
• エラー処理：明確なエラーメッセージを表示し、適切にエラーを処理します

インストール

前提条件

• Node.js 18 以降がインストールされていること
• Perforce コマンドラインクライアント（p4）がインストールされ、PATH に設定されていること
• プロジェクトディレクトリに .p4config ファイルがあること（推奨）

Claude Code でのクイックインストール

# Install the package globally
npm install -g @cocoon-ai/mcp-perforce

# Add to Claude Code
claude mcp add perforce @cocoon-ai/mcp-perforce

これで完了です！Claude Code がサーバーを自動的に設定します。

手動インストール

NPM 経由（公開後）

npm install -g @cocoon-ai/mcp-perforce

ソースからインストール

git clone https://github.com/Cocoon-AI/mcp-perforce.git
cd mcp-perforce
npm install
npm run build
npm link  # Makes 'mcp-perforce' available globally

設定

基本設定

Claude Desktop の設定ファイルにサーバーを追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "perforce": {
      "command": "npx",
      "args": ["-y", "@cocoon-ai/mcp-perforce"],
      "env": {
        "P4CONFIG": ".p4config"
      }
    }
  }
}

.p4config ファイルの設定

このサーバーは Perforce に組み込まれている P4CONFIG の仕組みを使用して、現在のディレクトリに応じて異なる Perforce サーバーを自動的に切り替えます。各プロジェクトのルートに .p4config ファイルを作成します。

# ~/projects/gamedev/.p4config
P4PORT=perforce-game.company.com:1666
P4CLIENT=gamedev-workspace
P4USER=your-username

# ~/projects/web/.p4config
P4PORT=perforce-web.company.com:1666
P4CLIENT=web-workspace
P4USER=your-username

これで、作業中のプロジェクトディレクトリに応じて、MCP サーバーが適切な Perforce 設定を自動的に使用します！

使用可能なコマンド

設定が完了すると、Claude にこれらの P4 操作を依頼できます。すべてのコマンドは、現在のプロジェクトディレクトリにある .p4config の設定を自動的に使用します。

基本的なファイル操作

• p4_status：ワークスペースの状態と保留中の変更を確認します

  "Show me my pending P4 changes"
  "Check P4 status in the gamedev directory"
  

• p4_add：ファイルを Perforce に追加します

  "Add all .js files in the src directory to Perforce"
  

• p4_edit：ファイルを編集用に開きます

  "Open config.json for editing in Perforce"
  

• p4_delete：ファイルを削除対象としてマークします

  "Delete the old_module.py file from Perforce"
  

• p4_sync：デポからファイルを同期します

  "Sync all files in the project"
  "Force sync the src directory"
  

• p4_revert：ファイルまたはチェンジリスト全体を取り消します

  "Revert all files in changelist 12345"
  "Revert changes to config.json"
  

• p4_diff：ファイルの差分を表示します

  "Show me the diff for all my open files"
  

チェンジリスト操作

• p4_changelist_create：新しいチェンジリストを作成します

  "Create a new changelist with description 'Fix login bug'"
  

• p4_changelist_submit：チェンジリストをサブミットします

  "Submit changelist 12345"
  

• p4_move_to_changelist：ファイルを別のチェンジリストに移動します

  "Move all my open files to changelist 12345"
  

ストリーム操作

• p4_stream_list：デポ内のストリームを一覧表示します

  "List all streams in //depot"
  "Show me development streams matching 'feature'"
  

• p4_stream_info：ストリームの詳細情報を取得します

  "Show me details about //depot/main stream"
  

• p4_stream_switch：ワークスペースを別のストリームに切り替えます

  "Switch to the //depot/dev stream"
  "Force switch to //depot/release-2.0"
  

• p4_stream_create：新しいストリームを作成します

  "Create a development stream //depot/feature-xyz from //depot/main"
  

• p4_stream_edit：ストリームの仕様を編集します

  "Edit the //depot/feature-xyz stream spec"
  

• p4_stream_graph：ストリームの階層を表示します

  "Show the stream hierarchy for //depot"
  

クライアント／ワークスペース操作

• p4_client_list：すべてのクライアント／ワークスペースを一覧表示します

  "List all my Perforce workspaces"
  "Show clients for user jsmith"
  

• p4_client_info：クライアント／ワークスペースの詳細を取得します

  "Show me details about my current workspace"
  "Show info for client gamedev-workspace"
  

• p4_client_create：新しいクライアント／ワークスペースを作成します

  "Create a new workspace called dev-feature in /home/user/p4/feature"
  "Create a stream client for //depot/main-stream"
  

• p4_client_edit：クライアントの仕様を編集します

  "Edit the view mappings for client dev-workspace"
  

• p4_client_delete：クライアント／ワークスペースを削除します

  "Delete the old-feature workspace"
  "Force delete the broken-client workspace"
  

• p4_client_switch：別のクライアントに切り替えます

  "Switch to the production-client workspace"
  

情報の取得

• p4_info：現在の Perforce 設定を表示します

  "Show me which P4 server and workspace I'm using"
  

• mcp_perforce_version：MCP Perforce サーバーのバージョンを表示します

  "What version of mcp-perforce is running?"
  

Claude での使用例

Claude との会話例をいくつか紹介します。

例 1：変更の作成とサブミット

You: "I've modified server.js and config.json. Create a changelist for these fixes"
Claude: I'll help you create a changelist for your changes. Let me first check the status...
[Uses p4_status, p4_changelist_create, p4_submit]

例 2：変更の同期とレビュー

You: "Sync the latest changes and show me what files I have open"
Claude: I'll sync your workspace and check your open files...
[Uses p4_sync, p4_status]

トラブルシューティング

Claude にサーバーが表示されない

1. 設定を変更した後、Claude Desktop を再起動してください
2. 設定ファイルが有効な JSON であることを確認してください
3. MCP サーバーがインストールされていることを確認してください：npm list -g @cocoon-ai/mcp-perforce

Perforce の認証エラー

1. .p4config ファイルが存在し、正しい設定になっていることを確認してください
2. Claude の外部で接続をテストしてください：p4 info
3. ログインしていることを確認してください：p4 login
4. P4CONFIG が認識されていることを確認してください：p4 set P4CONFIG

使用されている Perforce サーバーが違う

1. 現在のディレクトリを確認してください。サーバーは、現在のディレクトリまたは親ディレクトリにある .p4config を使用します
2. p4 info を実行して、どの設定が使用されているか確認してください
3. Claude で p4_info コマンドを使用してデバッグしてください：「P4 の設定を表示して」

コマンドが期待どおりに動作しない

1. Claude の応答にエラーメッセージがないか確認してください
2. 同じディレクトリから、ターミナルで P4 コマンドが動作することを確認してください
3. デバッグログを有効にしてください（下記を参照）

デバッグログ

デバッグ出力を有効にするには、設定に次を追加してください：

{
  "mcpServers": {
    "perforce": {
      "command": "npx",
      "args": ["-y", "@cocoon-ai/mcp-perforce"],
      "env": {
        "P4CONFIG": ".p4config",
        "DEBUG": "mcp:*"
      }
    }
  }
}

開発

ソースからビルドする

git clone https://github.com/Cocoon-AI/mcp-perforce.git
cd mcp-perforce
npm install
npm run build

テストを実行する

npm test

新しいコマンドを追加する

1. src/tools/ の適切なファイルにツールの定義を追加します
2. src/handlers/ の対応するファイルにハンドラー関数を追加します
3. src/handlers/index.ts の switch 文を更新します
4. パラメーターの検証とエラー処理には、既存のパターンに従ってください

コントリビューション

コントリビューションを歓迎します！次の手順に従ってください：

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/new-command）
3. 変更をコミットします（git commit -am 'Add new P4 command'）
4. ブランチにプッシュします（git push origin feature/new-command）
5. Pull Request を作成します

ライセンス

MIT License — 詳細は LICENSE ファイルを参照してください

謝辞

• Model Context Protocol SDK を基盤として構築されています
• AI アシスタントでの Perforce 統合を改善する必要性に着想を得ています

サポート

• 問題：GitHub Issues
• ディスカッション：GitHub Discussions

---

P4 のコマンドライン操作に苦労する AI のために ❤️ を込めて作られました