Perforce P4 MCP 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 客户端配置部分中的通用配置示例。

通过 Docker 容器以 STDIO 传输方式运行 P4 MCP Server，让 MCP 客户端管理容器生命周期。

**注意：**目前仅 macOS 和 Linux 支持基于 Docker 的运行方式。

前置条件

• 已安装并运行 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 身份运行。此自动复制功能可使归属外部 uid 的仅所有者可读（0600）票据文件，在保留主机所有权的运行时环境（原生 Linux Docker/podman）中正常使用。支持对票据文件进行 :ro 绑定挂载——文件会被复制，而不会原地修改（这与只读容器根文件系统不同；请参见下文）。请注意，自动复制仅在容器以 root 身份启动时运行（默认行为）；强制使用非 root uid 或只读根文件系统会改变此行为，具体说明见下文。

使用 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 集成文档，了解详细配置步骤。

请参阅 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

在此示例中，accessgroup 优先，因为 -s2 高于 -s1。

无论组成员身份如何，阻止特定用户访问：

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 组中的用户无法访问变更列表。其他组中的用户（未进行显式设置）保留默认访问权限。

若要将工具集限制为仅一个组可用，请为其他所有不应获得访问权限的组禁用该工具集：

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 都优先。

示例 — 仅一个组具有设置：

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 - transitions 操作的赞成票用户列表
  • 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 路径时使用。

• 参数：depot_path（必需）、identifier、project_id、repository_id、include
• 使用场景：获取已知资源的提交信息、资源包、网页链接、自定义属性以及项目／仓库匹配信息。在 query_p4dam_assets 之后使用，以获取特定文件的完整详情。

• 参数：search_term、limit、offset
• 使用场景：在创建资源包或文件审查之前发现可用项目，为其他调用查找项目 ID。

• 参数：project_id（必需）、search_term、limit、offset
• 使用场景：查找仓库类型（helix_stream 或 helix_classic）和 linked_streams；创建资源包或文件审查时需要提供 stream_path，或据此发现分支。

• 参数：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、创建者，以及 bundle 评审的 download_url。

• 参数：include、limit、offset
• 使用场景：查找可用工作流及其状态。传入 include=['states']，即可在一次调用中获取所有状态 — 在文件评审操作中，将状态的 short_name 用作 state 参数。

• 参数：workflow_id（必填）、include
• 使用场景：检查工作流的状态（kind：open/review/done、color、position）和转换规则。

• 参数：workflow_id（必填）、limit、offset
• 使用场景：列出所有状态及其 short_name、kind、color 和 position。创建或更新文件评审时，short_name 是要作为 state 传入的值。

• 参数：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 - 对评审投票（赞成、反对、清除）
  • 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
• 使用场景：创建用于审核的命名且范围明确的 depot 文件集合。对于 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
• 使用场景：通过一次调用为一个或多个资源添加标签。支持单个文件、指定修订版本和递归文件夹路径（//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
• 使用场景：为一个或多个资源设置或清除自定义元数据。请先使用 query_p4dam_custom_attribute_templates 查找可用属性及其 UUID。对于 text/single-select/checkbox 类型，value 是字符串；对于 multi-select 类型，value 是字符串列表。

• 参数：depot_path（必需）、commit_id（必需）
• 使用场景：预览缺失或过时时，重新触发预览生成。commit_id 是 query_p4dam_asset 结果中的变更集编号。

症状：操作系统无法找到或执行二进制文件；错误中包含 ENOENT 或 "No such file or directory"。
解决方案：

1. 检查路径： 确保 command 字段使用适用于你的操作系统的正确绝对路径：
   • 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 服务器
解决方案：

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 使用操作系统的信任存储。请确保企业 CA 已安装在操作系统证书存储中。
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. 如果现有会话时间较久或包含冲突的提示词历史，请开启新会话。