p4plan-mcp

開発時や、ローカルクローンから実行する場合：

npm ci
npm run build

# For using npx locally
npm link

Node.js をローカルにインストールする代わりに、Docker 経由で MCP サーバーを実行します。MCP クライアント（VS Code、Claude Desktop）がコンテナを子プロセスとして起動します。npx と同じ動作ですが、コマンドに docker を使用します。

イメージは Docker Hub の perforce/p4plan-mcp で公開されています。リリースのたびに、SLSA の来歴情報と SBOM の証明書を付けて、マルチアーキテクチャ（linux/amd64 + linux/arm64）向けにビルドされます。

VS Code（.vscode/mcp.json）：

{
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-e", "P4PLAN_API_AUTH_TOKEN=YOUR_JWT_TOKEN",
                "-e", "P4PLAN_API_URL=http://host.docker.internal:4000",
                "perforce/p4plan-mcp:latest"
            ]
        }
    }
}

Claude Desktop：

{
  "mcpServers": {
    "p4-plan": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "P4PLAN_API_AUTH_TOKEN=YOUR_JWT_TOKEN",
        "-e", "P4PLAN_API_URL=http://host.docker.internal:4000",
        "perforce/p4plan-mcp:latest"
      ]
    }
  }
}

注： ホストマシン上で稼働している P4 Plan GraphQL API に接続するには、host.docker.internal（macOS/Windows）または 172.17.0.1（Linux）を使用します。

特定のバージョンを固定するには、 再現可能なデプロイのために :latest を :2026.3.2（または任意のタグ）に置き換えます。

ローカルでビルドする場合（未リリースの変更を使った開発用）：

docker build -t p4plan-mcp:dev .
# then swap "perforce/p4plan-mcp:latest" for "p4plan-mcp:dev" in the configs above

curl -s -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Login($loginUserInput: LoginUserInput!) { login(loginUserInput: $loginUserInput) { access_token } }",
    "variables": { "loginUserInput": { "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD" } }
  }'

PAT は、同じログインミューテーションでパスワードの代わりに使用できます。これにより、実際のパスワードを公開せずに済みます。

curl -s -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Login($loginUserInput: LoginUserInput!) { login(loginUserInput: $loginUserInput) { access_token } }",
    "variables": { "loginUserInput": { "username": "YOUR_USERNAME", "password": "YOUR_PERSONAL_ACCESS_TOKEN" } }
  }'

1. P4 Plan にログインします
2. ユーザー設定 → 個人用アクセストークンに移動します
3. 新しいトークンを生成をクリックします
4. 適切な有効期限を設定します
5. トークンをコピーします。上記のログインミューテーションで使用して JWT を取得します

• ユースケース：他のツールで必要なプロジェクト ID を確認します

• パラメーター：projectId
• ユースケース：他のツールで使用するセクション ID（バックログ、QA、計画）を取得します

• パラメーター：name、任意の methodTemplate、defaultMode、members（ユーザー名またはグループ全体の名前／ID）、managers（通常のユーザー名／ID）、addMeAsManager（デフォルトは true）、または既存のプロジェクトを基にする場合は copyUsers／copyColumns とともに copyFromProjectId
• ユースケース：UI を使わずにチームの新しいプロジェクトを立ち上げます。P4 Plan の管理者権限が必要です。プロジェクトの作成後に失敗した手順は failed に一覧表示されます

• パラメーター：showCompleted、showOnlyNextFourWeeks、showHidden、showPipelineTasksThatCannotStart
• ユースケース：すべてのプロジェクトを対象に、自分の作業キューを確認します

• パラメーター：taskIds（文字列の配列、最大 20 件）-- データベース項目 ID。つまり、他のツールが返す id です
• 各項目のレスポンスには、すべてのツールが受け取るデータベース ID の id と、P4 Plan UI の「ID」列に表示される番号の localID の両方が含まれます。
• ユースケース：項目の詳細情報の取得、リンクの確認、複数項目の一括取得

• パラメーター：findQuery、projectId
• すべての検索で P4 Plan の検索クエリ構文を使用します。正確な列名、演算子、値の形式を確認するには、最初に skillName="search-queries" を指定して read_skill を呼び出してください。名前の単純検索には Itemname:Text("text") を使用します。ステータス、担当者、重大度、項目の種類、日付、ブール条件、および AND／OR／NOT を使った組み合わせで絞り込めます。
• 各プロジェクトには、異なる ID を持つ 3 つのセクション（バックログ、QA、計画）があります。
• ID を特定するには、直接クエリを実行します。ID=<n> は UI の「ID」列（セクション内でのみ一意のローカル ID）に一致し、Databaseid=<n> はデータベース ID に一致します。
• ユースケース：項目の検索、絞り込み、レポート作成

• 種類：backlog_task、bug、scheduled_task、sprint、release、sprint_task
• パラメーター：type、name、projectId、parentItemId、previousItemId、および種類固有のフィールド
• ユースケース：タスクやスプリントの作成、バグの登録

• 種類：BacklogTask、Bug、ScheduledTask、Sprint、Release
• パラメーター：itemId と、更新可能な任意のフィールド（name、status、assignedTo、points など）
• ユースケース：ステータスの更新、担当者の割り当て、見積もり、スプリントの設定

• Parameters: taskId, sprintId
• Use cases: スプリント計画、バックログへのコミット

• Parameters: taskId
• Use cases: スプリントのスコープ調整

• Parameters: projectId
• Use cases: 値を読み書きする前にカスタムフィールドを確認します

• Parameters: projectId（planning、backlog、または QA ID）、name、columnType、activated、readOnly、および型固有の unitName、updateOn*/updateOnlyFirstTime、useForTimeReporting/updateWorkRemaining、dropListItems（ラベル、または icon、autoAssignToUsers、autoAssignToUserGroups を含むオブジェクト）
• Use cases: UI を使わずにプロジェクトの列を設定します。メインプロジェクトマネージャーの権限が必要です

• Parameters: taskId、onlySet
• Use cases: プロジェクト固有のメタデータを読み取ります

• Parameters: taskId、customFieldId、value
• Use cases: プロジェクト固有のメタデータを更新します

• Parameters: projectId
• Use cases: ステータス遷移に必要なワークフローのステータスを確認します

• Parameters: taskId
• Use cases: ステータスを手早く更新するための便利なメソッドです

• Parameters: taskId
• Use cases: ステータスを手早く更新するための便利なメソッドです

• パラメーター: taskId
• 使用例: ディスカッションの履歴を読む

• パラメーター: taskId, text
• 使用例: ディスカッション、受け入れ条件、メモを追加する

• パラメーター: taskId, commentId, text
• 使用例: 既存のコメントを修正または更新する

• パラメーター: taskId, commentId
• 使用例: 古くなったコメントや誤ったコメントを削除する

• パラメーター: taskId
• 使用例: 添付ファイルを一覧表示し、ダウンロード用のパスを確認する

• パラメーター: taskId, path
• テキストファイルはインラインで返され、画像は base64 で返されます
• 使用例: 添付されたドキュメントを読んだり、スクリーンショットを表示したりする

• パラメーター: taskId と、filePath（名前を変更する場合は任意で fileName）または content + fileName
• ローカルファイルは許可されたフォルダー内にある必要があります。ファイルのアップロードを参照してください
• 新しい添付ファイルの path を返します。最初に添付された画像がカバー画像になります
• 画像の場合、imageHtml も返します。これは同じアイテムのコメント、説明、再現手順、または複数行テキストフィールド内に画像を表示する <img> タグです
• 使用例: バグレポートやユーザーストーリーにスクリーンショット、ログ、再現用ファイルを添付する

• パラメーター: taskId, path
• 使用例: 古くなった添付ファイルを削除する

• パラメーター: taskId, imagePath
• 使用例: カードやアイテムに視覚的なアイデンティティを設定する

• パラメーター: fromItemId, toItemId または url、relation（blocks、duplicates、relatedTo）
• 使用例: 依存関係の追跡、相互参照、外部 URL

• パラメーター: fromItemId, toItemId または url
• 使用例: 古くなった依存関係を整理する

• 使用例: 本人確認、ユーザーコンテキスト

• パラメーター: projectId
• 使用例: 割り当てやスプリントメンバーの管理に使うユーザー ID を確認する

• パラメーター：skillName
• 指定したスキルドキュメントの Markdown 全文を返します。AI エージェントは、search_tasks 用の findQuery を作成する前に、skillName="search-queries" を指定して必ずこのツールを呼び出す必要があります。
• 利用可能なスキル：project-navigation、search-queries、task-management、planning、backlog-refinement、bug-tracking、custom-fields、gantt-scheduling、workflows、pipeline、comment-html-format、mentions
• 使用例：正しいクエリ構文の習得、ツールの使用パターンの確認、ドメインの概念の理解

ワークスペースに .vscode/mcp.json を作成します。

{
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@perforce/p4plan-mcp"],
            "env": {
                "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
                "P4PLAN_API_URL": "http://localhost:4000"
            }
        }
    }
}

注： -y フラグを指定すると npm のインストール確認プロンプトに自動で同意し、ユーザーの操作なしでサーバーが起動します。

npm ではなくローカルクローンから実行する場合：

{
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "node",
            "args": ["/path/to/MCP/dist/main.js"],
            "env": {
                "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
                "P4PLAN_API_URL": "http://localhost:4000"
            }
        }
    }
}

セキュリティを強化するため、VS Code の入力プロンプトを使用して、トークンをファイルに保存しないようにできます。

{
    "inputs": [
        {
            "type": "promptString",
            "id": "p4-plan-jwt",
            "description": "P4 Plan JWT Token",
            "password": true
        }
    ],
    "servers": {
        "p4-plan": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@perforce/p4plan-mcp"],
            "env": {
                "P4PLAN_API_AUTH_TOKEN": "${input:p4-plan-jwt}",
                "P4PLAN_API_URL": "http://localhost:4000"
            }
        }
    }
}

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "p4-plan": {
      "command": "npx",
      "args": ["-y", "@perforce/p4plan-mcp"],
      "env": {
        "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
        "P4PLAN_API_URL": "http://localhost:4000"
      }
    }
  }
}

YOUR_JWT_TOKEN を、ログインミューテーションで取得したトークンに置き換えます（JWT トークンの取得を参照）。

プロジェクトのルートに .mcp.json を作成します。

{
  "mcpServers": {
    "p4-plan": {
      "command": "npx",
      "args": ["-y", "@perforce/p4plan-mcp"],
      "env": {
        "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
        "P4PLAN_API_URL": "http://localhost:4000"
      }
    }
  }
}

ローカルビルドの場合は、"command" と "args" を次のように置き換えます。

{
  "mcpServers": {
    "p4-plan": {
      "command": "node",
      "args": ["/path/to/MCP/dist/main.js"],
      "env": {
        "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN",
        "P4PLAN_API_URL": "http://localhost:4000"
      }
    }
  }
}

または、CLI から追加します。

claude mcp add p4-plan \
  -e P4PLAN_API_AUTH_TOKEN=YOUR_JWT_TOKEN \
  -e P4PLAN_API_URL=http://localhost:4000 \
  -- npx -y @perforce/p4plan-mcp

注： サーバー名は -e フラグより前に指定する必要があります。そうしないと、可変長引数を処理する -e パーサーがサーバー名を環境変数の値として解釈します。

実行を確認する： Claude Code 内で /mcp と入力して、サーバーの状態を確認します。

ヒント： .mcp.json をプロジェクトのルートに配置すると、トークンを含めずにチームで設定を共有できます。個人用の設定では、代わりに ~/.claude.json にサーバーを追加します。

npm に公開せずに、npx の動作をローカルでテストするには：

# Build and create a global symlink
npm run build
npm link

# Now test exactly as an end user would
P4PLAN_API_AUTH_TOKEN=your-jwt-token npx @perforce/p4plan-mcp

# Clean up when done
npm unlink -g @perforce/p4plan-mcp

シンボリックリンクは再ビルド後も維持されます。コードを変更した後は、npm run build を実行するだけです。

1. src/tools/ にツールファイルを作成または編集します

2. 次の内容を定義してツールを作成します：

   • name：ツールを一意に識別する名前
   • description：ツールの機能（AI に表示されます）
   • inputSchema：パラメーター用の JSON Schema
   • handler：ツールを実行する関数

3. ToolsModule に登録します

# Unit tests
npm run test

# E2E tests (MCP protocol compliance via @modelcontextprotocol/sdk)
npm run test:e2e

1. P4PLAN_API_AUTH_TOKEN が設定されているか確認します： サーバーを実行するには、P4PLAN_API_AUTH_TOKEN 環境変数に有効な JWT トークンが必要です。設定されていない場合、エラーが発生してすぐに終了します。

2. トークンが有効か確認します： トークンの有効期限が切れているか無効な場合、サーバーは「Authentication failed」というエラーを出して終了します。ログインミューテーションを使って新しい JWT を生成してください。

3. GraphQL API に接続できるか確認します： P4 Plan GraphQL API が、設定された P4PLAN_API_URL（デフォルト：http://localhost:4000）でアクセス可能である必要があります。

1. mcp.json の構文を確認します： .vscode/mcp.json が有効な JSON であることを確認してください。末尾のカンマがないか確認します。

2. コマンドが利用可能か確認します： npx を使う場合は、Node.js が VS Code の PATH に含まれていることを確認してください。npx が見つからない場合は、代わりに node の絶対パスを使ってください（ローカルビルドの設定を参照）。

3. VS Code ウィンドウを再読み込みします： Cmd+Shift+P を押し、「Developer: Reload Window」を選択します。

4. 新しいチャットを開始します： MCP サーバーは、新しいチャットセッションの開始時に接続されます。

1. GraphQL サーバーが実行中か確認します： P4 Plan GraphQL API が、設定された URL でアクセス可能である必要があります。

2. サーバーログを確認します： VS Code で出力パネルを開き、ドロップダウンから「p4-plan」を選択して、警告やエラーを確認します。詳細なデバッグログは logs/ ディレクトリで確認してください。

3. JWT の有効期限が切れていないか確認します： 必要に応じて新しい JWT を生成し、mcp.json の設定を更新してください。