p4mcp-server

uv がインストールされている場合は、手動でインストールせずに P4 MCP Server を直接実行できます。

# Run the server
uvx p4mcp-server

# Check version
uvx p4mcp-server --version

# Run with arguments
uvx p4mcp-server --readonly --allow-usage

PyPI から最新バージョンを自動的に取得して実行します。Python 仮想環境のセットアップや依存関係の管理は不要です。

要件：

• システムに uv がインストールされていること
• Python 3.11 以降（uv が自動的に処理します）

お使いのオペレーティングシステムに適したバイナリをダウンロードします。

• macOS： p4-mcp-server-mac.zip
• Windows： p4-mcp-server-win.zip
• Linux： p4-mcp-server-linux.zip

展開して、実行ファイルを直接使用します。Python のインストールは不要です。

# macOS / Linux
unzip p4-mcp-server-mac.zip   # or p4-mcp-server-linux.zip
./p4-mcp-server --help

# Windows
Expand-Archive p4-mcp-server-win.zip -DestinationPath .
.\p4-mcp-server.exe --help

要件：

• Python 3.11 以降（Tkinter を含む）

ビルド：

• macOS： chmod +x build.sh && ./build.sh package
• Linux： chmod +x build.sh && ./build.sh package
• Windows： build.bat package

出力：

• macOS および Linux： p4-mcp-server-<version>.tgz
• Windows： p4-mcp-server-<version>.zip

デフォルトの STDIO トランスポートを使用して、P4 MCP Server をマシン上で直接実行します。

次の内容を mcp.json に追加します。

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

注： この例では env の値を明示的に指定しています。P4CONFIG が設定されている場合は、これらを省略して、代わりに「MCP クライアントの設定」セクションにある汎用設定例を使用できます。

STDIO トランスポートを使用して、Docker コンテナから P4 MCP Server を実行します。これにより、MCP クライアントがコンテナのライフサイクルを管理できます。

注： Docker を使用した実行は、現在 macOS と Linux のみでサポートされています。

前提条件

• Docker がインストールされ、実行中であること
• 有効な P4 認証情報と P4 サーバーへのアクセス権があること

Docker イメージをプルする

docker pull ghcr.io/perforce/p4mcp-server:latest

cd /path/to/p4mcp-server
docker build -t ghcr.io/perforce/p4mcp-server .

MCP クライアントの設定

次の内容を mcp.json に追加します。

{
    "servers": {
        "perforce-p4mcp-docker": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "--hostname", "your-hostname",
                "-e", "P4PORT=ssl:perforce.example.com:1666",
                "-e", "P4USER=your_username",
                "-e", "P4CLIENT=your_workspace",
                "-e", "P4DAM_API_KEY=your_api_key",
                "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro",
                "ghcr.io/perforce/p4mcp-server:latest"
            ]
        }
    }
}

設定オプション

認証

P4 チケットを使用する場合：

# macOS/Linux
-v /Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro

注： チケットファイルにはフルパスを使用してください（~ は使用しないでください）。p4 login の実行後、新しいチケットを読み込ませるために MCP サーバーを再起動してください。

注： デフォルトでは、コンテナは root として起動し、バインドマウントされたチケットファイルを非 root ユーザーの mcpuser が読み取り可能な場所にコピーした後、権限を落として（gosu 経由）、サーバーを mcpuser として実行します。この自動コピーにより、ホストの所有権を保持するランタイム（ネイティブ Linux Docker／podman）では、別の uid が所有する所有者のみ読み取り可能な（0600）チケットファイルを使用できます。チケットの :ro バインドマウントもサポートされています。ファイルはコピーされ、元の場所では変更されません（これは読み取り専用のコンテナルートファイルシステムとは異なります。後述を参照してください）。この自動コピーは、コンテナが root として起動した場合（デフォルト）のみ実行される点に注意してください。非 root uid の強制や読み取り専用ルートファイルシステムの使用により、この動作は以下で説明するように変わります。 **Kubernetes／制限付き（非 root 強制）プロファイル：**イメージは意図的に root として起動し、gosu を介して mcpuser（uid 1000）に切り替えるため、サーバーは常に非 root で実行されます。どちらの方法にも対応しています。runAsNonRoot／制限付き PodSecurity／OpenShift の制限付き SCC を使用する場合は、securityContext.runAsUser: 1000（チケットをマウントする場合は fsGroup: 1000 も）を設定してください。このモードでは、エントリーポイントによる root 専用のチケットコピーがスキップされるため、マウントしたチケットは uid 1000 で読み取り可能である必要があります（所有者が一致するマウント、-e P4PASSWD="your_ticket_content"、または podman -v <host>:/home/mcpuser/.p4tickets:U）。

**ルートファイルシステムが読み取り専用（--read-only／readOnlyRootFilesystem）の場合：**チケットのコピー先として書き込み可能な /home/mcpuser を用意してください（例：--tmpfs /home/mcpuser）。用意しない場合、チケットのコピーに失敗し、P4 は通常の認証エラーを報告します。

パスワードを使用する場合：

-e P4PASSWD="your_password"

ワークスペースのホスト制限

⚠️ **重要：**Docker コンテナーには、ローカルマシンとは異なる独自のホスト名があります。P4 ワークスペースが特定のホストに制限されている場合、sync などの操作は失敗します。

これを解決するには、コンテナーのホスト名をワークスペースのホスト制限に一致させます。

--hostname your-hostname

ワークスペースのホスト名を確認するには：

# macOS/Linux
p4 client -o your_workspace | grep "^Host:"

書き込み操作のためのクライアントルートのマウント

⚠️ 重要：デフォルトでは、Docker コンテナーからローカルのワークスペースファイルにアクセスできません。sync、submit、reconcile などの書き込み操作を行うには、クライアントルートディレクトリを同じパスでコンテナーにマウントする必要があります。

クライアントルートのボリュームマウントを追加します。

-v /path/to/your/client/root:/path/to/your/client/root

クライアントルートをマウントした設定例：

{
    "servers": {
        "perforce-p4mcp-docker": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "--hostname", "your-hostname",
                "-e", "P4PORT=ssl:perforce.example.com:1666",
                "-e", "P4USER=your_username",
                "-e", "P4CLIENT=your_workspace",
                "-e", "P4DAM_API_KEY=your_api_key",
                "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets",
                "-v", "/path/to/client/root:/path/to/client/root",
                "ghcr.io/perforce/p4mcp-server:latest"
            ]
        }
    }
}

クライアントルートを確認するには：

p4 client -o your_workspace | grep "^Root:"

**注：**コンテナー内のマウントパスは、クライアントルートのパスと完全に一致している必要があります。P4 は絶対パスでファイルを追跡するためです。

HTTP トランスポートを使用して VM 上で MCP サーバーを実行すると、クライアントはネットワーク経由で接続できます。

VM 上でサーバーを起動します：

P4PORT=ssl:perforce.example.com:1666 P4USER=your_username P4PASSWD=YOUR_TICKET ./p4-mcp-server --readonly --transport http --port 8000

MCP クライアントを設定します：

以下を mcp.json に追加します。

{
    "servers": {
        "perforce-p4-mcp": {
            "type": "http",
            "url": "http://<ip-or-hostname>:8000/mcp"
        }
    }
}

**注：**選択したポートでの受信接続を VM のファイアウォールが許可していることを確認してください。本番環境で使用する場合は、TLS 対応のリバースプロキシの背後にサーバーを配置することを検討してください。

HTTP トランスポートを使用して Docker コンテナー内で MCP サーバーを実行し、ホストポート経由で MCP エンドポイントを公開します。

コンテナーを起動します：

docker run --rm -p 8000:8000 \
  -e P4PORT=ssl:perforce.example.com:1666 \
  -e P4USER=your_username \
  -e P4PASSWD=YOUR_TICKET \
  -e P4DAM_API_KEY=your_api_key \
  ghcr.io/perforce/p4mcp-server:latest \
  python3 -m p4mcp.main --readonly --transport http --port 8000

MCP クライアントを設定します：

以下を mcp.json に追加します。

{
  "servers": {
    "perforce-p4-mcp": {
      "type": "http",
      "url": "http://<ip-or-hostname>:8000/mcp"
    }
  }
}

**注：**Docker も HTTP ベースのデプロイに対応しています。コンテナーイメージのデフォルトは STDIO トランスポートのため、HTTP の起動コマンドでデフォルトのコマンドを明示的に上書きする必要があります。書き込み操作が必要な場合は、クライアントルートとチケットファイルのパスもコンテナーにマウントしてください。

詳しい設定手順については、JetBrains AI Assistant VCS Integration のドキュメントをご覧ください。

詳しくは、Claude Code MCP のドキュメントをご覧ください。

uvx を使用する場合（インストール不要）：

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "uvx",
      "args": [
        "p4mcp-server",
        "--readonly", "--allow-usage"
      ],
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      }
    }
  }
}

ビルド済みバイナリを使用する場合：

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

詳しくは、Cursor MCP のドキュメントをご覧ください。

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

詳しくは、Eclipse MCP のドキュメントをご覧ください。

{
  "servers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

詳しくは、Kiro MCP のドキュメントをご覧ください。

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

詳しくは、VS Code のドキュメントをご覧ください。

{
  "servers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

詳しくは、Windsurf MCP のドキュメントをご覧ください。

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

特定のグループのすべてのメンバーがアクセスできないようにするには、次のようにします。

p4 property -a -n mcp.enabled -v false -g noaccessgroup

同じ方法で、複数のグループ制限を設定できます。

ユーザーが設定の競合する複数のグループに属している場合、どの値が優先されるかは P4 のプロパティ解決によって決まります。

シーケンス番号（-s）が最も大きいものが優先されます。シーケンス番号が同じ場合は、グループ名のアルファベット順で最初のものが優先されます。

例：

p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
p4 property -a -n mcp.enabled -v true  -s2 -g accessgroup

この例では、-s2 が -s1 より大きいため、accessgroup が優先されます。

グループへの所属状況にかかわらず、特定のユーザーをブロックするには、次のようにします。

p4 property -a -n mcp.enabled -v false -u noaccessuser

シーケンス番号が同じ場合、ユーザーレベルのプロパティはグループレベルおよびグローバルの設定より優先されます（P4 のスコープによる優先順位）。

例：noaccessuser が MCP を有効にしている accessgroup に属していても、同じシーケンス番号のユーザープロパティが優先され、MCP は無効になります。

注： -s の値が大きいグループプロパティは、シーケンス番号が小さいユーザープロパティより優先される場合があります。ユーザーレベルのプロパティを常に優先させるには、高い -s 値を設定するか、それより大きいシーケンス番号のグループプロパティが存在しないようにしてください。

mcp.toolsets.allowed を使用して、サーバー全体で利用可能なツールセットを制限します。リストに記載されたツールセットのみが有効になり、それ以外はすべてブロックされます。

利用可能なツールセット：server、changelists、files、jobs、reviews、shelves、workspaces、streams

changelists と files のみを許可します。

p4 property -a -n mcp.toolsets.allowed -v changelists,files

すべてのツールセットを再び利用可能にするには、許可リストを削除します。

p4 property -d -n mcp.toolsets.allowed

書き込みを再び有効にします：

p4 property -a -n mcp.toolsets.write -v true

write=false の場合、すべての modify_* ツールがブロックされますが、すべての query_* ツールは引き続き機能します。

特定のグループに対して、個々のツールセットを有効または無効にします。

特定のグループでツールセットを無効にします：

p4 property -a -n mcp.toolset.changelists.enabled -v false -g reviewers

reviewers のユーザーはチェンジリストを利用できなくなります。ほかのグループのユーザー（明示的な設定がない場合）は、デフォルトのアクセス権を維持します。

ツールセットを1つのグループだけに制限するには、アクセスを許可しないほかのすべてのグループで無効にします：

p4 property -a -n mcp.toolset.files.enabled -v false -g reviewers
p4 property -a -n mcp.toolset.files.enabled -v false -g interns
# Only groups without an explicit "false" retain default access to files

注： すべてのツールセットはデフォルトで有効です。グループに enabled=true を設定するのは、以前の false 設定を明示的に上書きする場合を除き、冗長です。同じシーケンス番号では、グループのプロパティがグローバルプロパティより優先されます（P4のスコープ優先順位）。そのため、グループの enabled=true はグローバルの enabled=false を上書きできます。グローバル設定が上書きされないようにするには、高い -s 値を指定してください。特定のグループだけにツールセットを限定するには、ブロックするグループで無効にします。

グループレベルで、各ツールセットの書き込みアクセスを制御します。

グループごとに特定のツールセットへの書き込みを無効にします：

p4 property -a -n mcp.toolset.workspaces.write -v false -g reviewers

これにより、そのグループでは modify_workspaces がブロックされますが、query_workspaces は引き続き利用できます。

mcp.toolset.<name>.tools を使用して、グループのアクセスをツールセット内の特定のツールに制限します。

開発者には query_files のみを許可し（modify_files はブロック）、次のように設定します：

p4 property -a -n mcp.toolset.files.tools -v query_files -g developers

リードにはクエリと変更の両方を許可します：

p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads

書き込みが有効な場合でも、ツール固有のオーバーライドによってアクセスを制限できます：

p4 property -a -n mcp.toolsets.write -v true
p4 property -a -n mcp.toolset.files.tools -v query_files -g developers
# Result: modify_files is BLOCKED — tool list restricts

注： ツール固有のオーバーライドで書き込み制限を回避することはできません。サーバーはツールリストを評価する前に、書き込み権限を確認します。いずれかのレベルで write=false が設定されている場合、ツールリストにかかわらず書き込みツールはブロックされます。

ユーザーが設定の競合する複数のグループに所属している場合、P4は各プロパティを単一の値に解決します。MCP サーバーは独自の複数グループ処理を行わず、P4が返す値を使用します。

指定されたプロパティ名に対するP4の解決ルール：

1. 最も高い -s（シーケンス番号）が優先されます。 これが第一のソートキーです。
2. シーケンス番号が同じ場合： ユーザースコープ > グループスコープ > グローバルスコープ。
3. 同じシーケンス番号のグループ間では： アルファベット順で最初のグループ名が優先されます。

P4は値を比較しません。内容ではなく、位置に基づいて優先されるエントリを選びます。

例 — シーケンス番号が同じグループ（デフォルト）：

p4 property -a -n mcp.toolset.files.enabled -v true -g developers
p4 property -a -n mcp.toolset.files.enabled -v false -g leads
# User in both groups → resolved value is "true"
# Reason: "developers" < "leads" alphabetically, so developers wins

値を入れ替えても結果は false になります。値にかかわらず、引き続き developers が優先されます。

例 — 設定があるグループが1つだけの場合：

p4 property -a -n mcp.toolset.files.enabled -v false -g leads
# developers has no setting
# User in developers + leads → resolved value is "false"
# Reason: leads is the only group with a value, so it wins

例 — 書き込みアクセス：

p4 property -a -n mcp.toolset.files.write -v false -g developers
p4 property -a -n mcp.toolset.files.write -v true -g leads
# User in both groups → resolved value is "false"
# Reason: "developers" < "leads" alphabetically, not because false is "more restrictive"

例 — ツールリスト（結合されません）：

p4 property -a -n mcp.toolset.reviews.tools -v query_reviews -g developers
p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads
# User in both groups → resolved value is "query_reviews"
# Reason: "developers" wins alphabetically. P4 returns one value, not a union.

例 — -s を使用して優先されるグループを制御する場合：

p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
p4 property -a -n mcp.enabled -v true  -s2 -g accessgroup
# accessgroup wins because -s2 > -s1 (highest sequence wins)

ヒント： 複数のグループがある場合に予測可能な結果を得るには、アルファベット順のグループ名に頼らず、常に明示的な -s 値を使用してください。

ほかのツールセットに影響を与えずに、すべてのユーザーに対して単一のツールセットを無効にします：

p4 property -a -n mcp.toolset.reviews.enabled -v false

これにより、すべてのユーザーに対して query_reviews と modify_reviews の両方がブロックされます。ほかのツールセットには影響しません。

ほかのグループに影響を与えずに、特定のグループを読み取り専用に制限します：

p4 property -a -n mcp.toolsets.write -v false -g problematic_group

ほかのグループのユーザーは、引き続き完全な書き込みアクセスを維持します。ユーザーが制限対象のグループと制限のないグループの両方に所属している場合は、P4のプロパティ解決によって結果が決まります。同じシーケンス番号では、通常、アルファベット順で最初のグループ名が優先されます。予測可能な結果を得るには、明示的な -s 値を使用してください。

• アクション:
  • server_info - P4 のバージョン、稼働時間、構成を取得します
  • current_user - 現在のユーザー情報と権限を取得します
• ユースケース - サーバーの診断、ユーザーの確認、接続テスト

• アクション:
  • list - すべてのワークスペースを一覧表示します（ユーザーでの絞り込みは任意）
  • get - ワークスペースの詳細な仕様を取得します
  • type - ワークスペースの種類と構成を確認します
  • status - ワークスペースの同期状態を確認します
• パラメーター: workspace_name、user、max_results
• ユースケース: ワークスペースの検索、構成の確認、状態の確認

• アクション:
  • get - チェンジリストの詳細情報（ファイル、説明、ジョブ）を取得します
  • list - フィルター（状態、ユーザー、ワークスペース）を指定してチェンジリストを一覧表示します
• パラメーター: changelist_id、status（pending/submitted）、workspace_name、max_results
• ユースケース: コードレビュー、履歴の追跡、チェンジリストの分析

• アクション：
  • list - ユーザー別または全体のシェルブされた変更を一覧表示します
  • diff - シェルブされたファイルの差分を表示します
  • files - 特定のシェルフ内のファイルを一覧表示します
• パラメーター：changelist_id、user、max_results
• ユースケース：コードレビュー、作業中の進捗追跡、コラボレーション

• アクション：
  • list_jobs - チェンジリストに関連付けられたジョブを一覧表示します
  • get_job - ジョブの詳細情報とステータスを取得します
• パラメーター：changelist_id、job_id、max_results
• ユースケース：不具合追跡、要件のトレーサビリティ、プロジェクト管理

• アクション：
  • list - 任意のフィルターを指定してすべてのレビューを一覧表示します
  • dashboard - 現在のユーザーのレビューダッシュボード（自分のレビュー、対応が必要なレビュー）を取得します
  • get - レビューの詳細情報を取得します
  • transitions - レビューで利用可能な状態遷移を取得します
  • files_readby - ユーザーごとのファイル閲覧状況を取得します
  • files - レビュー内のファイルを取得します（バージョン範囲の指定は任意）
  • activity - レビューのアクティビティ履歴を取得します
  • comments - レビューへのコメントを取得します
• パラメーター：
  • review_id - レビュー ID（get、transitions、files_readby、files、comments、activity で必須）
  • review_fields - 返すフィールドをカンマ区切りで指定します（例："id,description,author,state"）
  • comments_fields - コメントのフィールド（デフォルト："id,body,user,time"）
  • up_voters - 遷移時の賛成投票者のリスト
  • from_version、to_version - files アクションのバージョン範囲
  • max_results - 結果の最大数（デフォルト：10）
• ユースケース：コードレビューの検出、レビュー状況の追跡、コメントの取得、レビューアクティビティの監視

• パラメーター：search_term、project_ids、repository_ids、path、tag、file_extension、user、all_revisions、max_results、offset
• ユースケース：アセットの検索、プロジェクト／リポジトリ／タグ／拡張子によるフィルタリング、P4 DAMコンテンツの閲覧に使用します。まだデポパスがわからない場合に利用します。

• パラメーター：depot_path（必須）、identifier、project_id、repository_id、include
• ユースケース：既知のアセットについて、コミット情報、アセットバンドル、ウェブリンク、カスタム属性、プロジェクト／リポジトリとの一致情報を取得します。特定のファイルの詳細を取得するには、query_p4dam_assetsの後に使用します。

• パラメーター：search_term、limit、offset
• ユースケース：アセットバンドルまたはファイルレビューを作成する前に利用可能なプロジェクトを探したり、他の呼び出しで使うプロジェクトIDを特定したりします。

• パラメーター：project_id（必須）、search_term、limit、offset
• ユースケース：アセットバンドルまたはファイルレビューの作成時にstream_pathを指定したり、ブランチを見つけたりするために必要なリポジトリタイプ（helix_streamまたはhelix_classic）とlinked_streamsを確認します。

• パラメーター：project_id（必須）、repository_id（必須）、limit、offset
• ユースケース：Helix Classicリポジトリでアセットバンドルまたはファイルレビューを作成する際に必要なブランチIDを確認します。

• パラメーター：project_id（必須）、depot_path、include、limit、offset
• ユースケース：プロジェクト内の進行中のレビューの閲覧、depot パスによる絞り込み、詳細取得に使用するレビュー UUID の検索。

• パラメーター：project_id（必須）、review_id（必須）
• ユースケース：状態、view_paths、asset_bundle、作成者、バンドルレビューの download_url など、レビューの詳細をすべて取得します。

• パラメーター：include、limit、offset
• ユースケース：利用可能なワークフローとその状態を確認します。include=['states'] を渡すと、すべての状態を 1 回の呼び出しで取得できます。ファイルレビュー操作の state パラメーターには、状態の short_name を使用します。

• パラメーター：workflow_id（必須）、include
• ユースケース：ワークフローの状態（kind：open/review/done、color、position）と遷移ルールを確認します。

• パラメーター：workflow_id（必須）、limit、offset
• ユースケース：short_name、kind、color、position を含むすべての状態を一覧表示します。ファイルレビューの作成または更新時に state として渡す値は short_name です。

• パラメーター：project_id（必須）
• ユースケース：値を設定する前に利用可能なカスタム属性を確認します。各テンプレートの UUID、名前、タイプ（text、single-select、multi-select、checkbox）、選択式タイプの available_values を返します。UUID は update_p4dam_asset_custom_attributes に渡します。

• アクション - create、update、delete、switch
• パラメーター - name、specs（View、Root、Options などを含む WorkspaceSpec オブジェクト）
• 要件 - 読み取り専用モードが無効であること、適切な権限があること
• ユースケース - 環境のセットアップ、ワークスペースのメンテナンス、ブランチの切り替え

• アクション - create、update、submit、delete、move_files
• パラメーター - changelist_id、description、file_paths
• 安全性 - 所有権の確認、項目の詳細を示す、削除操作用の対話型 PROCEED/CANCEL 確認プロンプト
• ユースケース - コードの提出、作業の整理、ファイルのグループ化

• アクション - shelve、unshelve、update、delete、unshelve_to_changelist
• パラメーター - changelist_id、file_paths、target_changelist、force
• ユースケース - 一時保存、コードの共有、実験前のバックアップ

• アクション - link_job、unlink_job
• パラメーター - changelist_id、job_id
• ユースケース - 不具合追跡との連携、要件の紐付け

• アクション:
  • create - チェンジリストから新しいレビューを作成
  • refresh_projects - プロジェクトとの関連付けを更新
  • vote - レビューに投票（up、down、clear）
  • transition - レビューの状態を変更（needsRevision、needsReview、approved、committed、rejected、archived）
  • append_participants - レビューにレビュアー／グループを追加
  • replace_participants - すべての参加者を置き換え
  • delete_participants - レビューから参加者を削除
  • add_comment - レビューにコメントを追加
  • reply_comment - 既存のコメントに返信
  • edit_comment - 既存のコメントの本文やタスク状態を編集
  • append_change - 既存のレビューにチェンジリストを追加
  • replace_with_change - レビューの内容をチェンジリストで置き換え
  • join - 参加者としてレビューに参加
  • leave - レビューから退出
  • archive_inactive - 非アクティブなレビューをアーカイブ
  • mark_comment_read / mark_comment_unread - 個別のコメントの既読状態を設定
  • mark_all_comments_read / mark_all_comments_unread - すべてのコメントの既読状態を設定
  • update_author - レビューの作成者を変更
  • update_description - レビューの説明を更新
  • obliterate - レビューを完全に削除
• パラメーター:
  • review_id - レビュー ID（ほとんどのアクションで必須）
  • change_id - チェンジリスト ID（create、append_change、replace_with_change で必須）
  • description - レビューの説明
  • reviewers、required_reviewers - レビュアーのユーザー名リスト
  • reviewer_groups - 要件を指定したレビュアーグループ
  • vote_value - 投票値：up、down、clear
  • version - 投票対象のレビューのバージョン
  • transition - 遷移先の状態：needsRevision、needsReview、approved、committed、approved:commit、rejected、archived
  • jobs、fix_status、cleanup - 状態遷移時のジョブの紐付けおよびクリーンアップのオプション
  • users、groups - 追加／置換／削除する参加者の構造化データ
  • body - コメント本文
  • task_state - コメントのタスク状態：open、comment、addressed、verified。add_comment で指定できるのは open と comment のみです。addressed と verified は edit_comment で設定できます。
  • notify - 通知モード：immediate、delayed
  • comment_id - 返信、編集、既読／未読の設定に使うコメント ID
  • context - コメントのコンテキスト（ファイル、行番号、内容、バージョン）
  • not_updated_since、max_reviews - archive_inactive のフィルター
  • new_author、new_description - 更新アクションに指定する値
• ユースケース: コードレビューのワークフロー、レビュー状態の管理、共同でのコメント、参加者の管理、レビューのクリーンアップ

• パラメーター: depot_path（必須。.p4bundleで終わる必要があります）、project（必須）、repository（必須）、view_paths（必須）、stream_path、helix_classic_branch、description、hero_file_path
• ユースケース: レビュー用に、名前と範囲を指定したデポファイルのコレクションを作成します。Helix Streamリポジトリではstream_pathを、Helix Classicリポジトリではhelix_classic_branchを指定してください。

• パラメーター: bundle_id（必須）、description、view_paths、hero_file_path
• ユースケース: バンドルの説明の変更、ファイル範囲（view_paths）の調整、カバー画像の更新に使用します。作成後、depot_pathは変更できません。

• パラメーター：bundle_id（必須）
• ユースケース：不要になったアセットバンドルを削除します。元に戻せません。

• パラメーター：view_paths（必須）、workspace_root（必須）、client_name、bundle_id、stream_path
• ユースケース：アセットバンドルの対象ファイルを p4 sync でダウンロードします。名前付きの P4 クライアントを作成または再利用し、以降の同期は差分のみを取得します。Helix Stream リポジトリでは stream_path を使用します（LimitView を適用するには Perforce 2025.2 以降が必要です）。

• パラメーター：project_id（必須）、name（必須）、depot_path（必須）、view_paths（必須）、state（必須）、repository、helix_classic_branch、asset_bundle、hero_file_path、description、position、base_commit_id、head_commit_id
• ユースケース：単一アセットまたはアセットバンドル（.p4bundle）のレビューを開始します。バンドルのレビューでは、asset_bundle を省略すると depot_path から自動検出されます。

• パラメーター：project_id（必須）、review_id（必須）、state、name、view_paths、hero_file_path、description、position
• ユースケース：レビューを新しいワークフロー状態に移行したり、名前や説明を更新したり、表示範囲を調整したりします。状態の遷移は、現在のユーザーに対してプロジェクトのワークフローで許可されている必要があります。

• パラメーター：project_id（必須）、review_id（必須）
• ユースケース：不要になったレビューを削除します。元に戻せません。成功すると、API は削除されたレビューオブジェクトを返します。

• パラメーター：paths（必須 — {path, identifier?} のリスト）、create、delete、delete_auto、propagatable、identifier
• ユースケース：1 回の呼び出しで 1 つ以上のアセットにタグを付けます。個別のファイル、特定のリビジョン、再帰的なフォルダーパス（//depot/folder/...）に対応しています。create はユーザータグを追加し、delete はユーザータグを削除し、delete_auto は自動生成されたタグを削除します。propagatable=true を設定すると、最新のリビジョンと今後のすべてのリビジョンにタグが適用されます。

• パラメーター：type（必須）、content（必須）、project、repository、file_review、commit、path、stream_path、helix_classic_branch、comment
• ユースケース：アセットバンドルのファイルレビュー（file_review）、レビュー内の特定ファイル（file_review_file）、レビューなしのコミット済みファイルまたはアセットバンドル（commit_file）にコメントするか、既存のコメント（comment）に返信します。必須パラメーターはタイプによって異なります。type の説明を参照してください。

• パラメーター：paths（必須 — {path, identifier?} のリスト）、create（{uuid, value} のリスト）、delete（削除する属性 UUID のリスト）、propagatable
• ユースケース：1 つ以上のアセットのカスタムメタデータを設定またはクリアします。まず query_p4dam_custom_attribute_templates で利用可能な属性とその UUID を確認してください。text／single-select／checkbox タイプでは value は文字列、multi-select タイプでは文字列のリストです。

• パラメーター: depot_path（必須）、commit_id（必須）
• ユースケース: プレビューが存在しない場合や古くなっている場合に、プレビュー生成を再実行します。commit_id は query_p4dam_asset の結果に含まれるチェンジセット番号です。

症状: OS がバイナリを見つけられない、または実行できません。エラーには ENOENT または "No such file or directory" が含まれます。
解決策:

1. パスを確認する: command フィールドに、OS に応じた正しい絶対パスが指定されていることを確認します。
   • macOS/Linux: /absolute/path/to/p4-mcp-server
   • Windows: C:\absolute\path\to\p4-mcp-server.exe
2. バイナリが存在し、実行可能であることを確認する:
   • macOS/Linux:

     ls -l /absolute/path/to/p4-mcp-server && chmod +x /absolute/path/to/p4-mcp-server
     

   • Windows:

     dir C:\absolute\path\to\p4-mcp-server.exe
     

3. Windows では、バイナリがブロックされていないことを確認する:
   • .exe ファイルを右クリックし、プロパティを選択して、表示される場合はブロックの解除をクリックします。

症状：P4 Server に接続できません
解決策：

1. P4PORT 環境変数を確認します：echo $P4PORT（macOS）または echo $env:P4PORT（Windows）
2. 直接接続をテストします：p4 info
3. サーバーが利用可能か確認します：ping perforce.example.com
4. ポートとプロトコルを確認します（SSL 接続の場合は ssl: プレフィックスを付けます）。

症状：P4 サーバーへの接続時に SSL の信頼エラーが発生します
解決策：

1. サーバーを信頼します：p4 trust -f -y
2. 信頼ステータスを確認します：p4 trust -l
3. 問題が解決しない場合は、SSL の設定を確認します。

症状：レビュー ツールの使用時に CERTIFICATE_VERIFY_FAILED エラーが発生します
解決策：

1. システムの信頼ストア：デフォルトでは、サーバーは truststore を介して OS の信頼ストアを使用します。社内 CA が OS の証明書ストアにインストールされていることを確認してください。
2. カスタム CA バンドル：カスタム CA 証明書を使用するには、まず P4MCP_TLS_CA_MODE=certifi を設定して（truststore を無効にして）から、--ca-bundle /path/to/ca.pem または P4MCP_CA_BUNDLE で CA パスを指定する必要があります。デフォルトの system モードでは、truststore がカスタム CA バンドルを上書きするため、これらは通知なく無視されます。
3. 検証を無効にする：--ssl-no-verify を使用するか、P4MCP_SSL_VERIFY=false を設定します（本番環境では推奨されません）。これはどちらの TLS モードでも機能します。

注： これらの SSL 設定が適用されるのは、Swarm URL が HTTPS を使用している場合のみです。Swarm が http:// URL で設定されている場合、SSL 検証は行われず、これらの設定も効果がありません。

症状：認証に失敗します
解決策：

1. P4 にログインします：p4 login -a
2. ログイン状態を確認します：p4 login -s
3. ユーザーが存在することを確認します：p4 users -m 1 your_username
4. 問題が解決しない場合は、パスワードを確認するか、チケットベースの認証を使用します。

症状：ログインに失敗します
解決策：

1. P4 管理者を通じてパスワードをリセットします。
2. チケットベースの認証を使用します：p4 login -a
3. ユーザー名が正しいことを確認します：p4 info

症状：ワークスペースが見つからないというエラーが発生します
解決策：

1. 利用可能なワークスペースを一覧表示します：p4 clients
2. P4CLIENT 環境変数を確認します。
3. 必要に応じてワークスペースを作成します：p4 client workspace_name
4. ワークスペースの所有者を確認します：p4 client -o workspace_name

症状：ファイルがワークスペースのマッピング範囲外にあります
解決策：

1. クライアントビューを確認します：p4 client -o workspace_name
2. 必要なパスが含まれるようにワークスペースのマッピングを更新します。
3. p4 where file_path を使用してマッピングを確認します。

症状：操作に必要な権限が不足しています
解決策：

1. ファイルの所有権を確認します：p4 opened file_path
2. ユーザー権限を確認します：p4 protects file_path
3. 適切なグループに所属していることを確認します。
4. 管理者操作の場合は、管理者権限を確認します。

症状：排他ロックが競合しています
解決策：

1. ファイルを開いているユーザーを確認します：p4 opened file_path
2. 競合を解決するため、該当ユーザーに連絡します。
3. 必要に応じて、管理者が操作を強制できます。

症状：応答時間が長い
解決策：

1. max_results パラメーターを使用して、クエリのサイズを制限します。
2. ワイルドカードではなく、具体的なファイルパスを使用します。
3. P4 へのネットワーク接続を確認します。
4. サーバーのパフォーマンスを監視します。

症状：メモリ使用量が多い
解決策：

1. 大きなクエリでは max_results を減らします。
2. ファイルをバッチ処理します。
3. 長時間実行するセッションでは、MCP サーバーを定期的に再起動します。

症状：組み込みツールまたは他の MCP ツールとの競合
解決策：

1. 環境または設定で、組み込みツールや競合する MCP サーバーツールを無効にします。
2. P4 MCP サーバーのツールが適切に登録され、有効になっていることを確認します。
3. 設定変更を適用した後、正しいツールを読み込むために MCP サーバーを再起動します。

症状：コンテキストが無効、またはセッション履歴が古い
解決策：

1. プロンプトを作成する際に、P4 関連のコンテキストを指定します。
2. 既存のセッションが古い場合や、競合するプロンプト履歴が含まれている場合は、新しいセッションを開始します。