p4plan-mcp

用于开发，或在本地克隆后运行：

npm ci
npm run build

# For using npx locally
npm link

通过 Docker 运行 MCP 服务，无需在本地安装 Node.js。MCP 客户端（VS Code、Claude Desktop）会将容器作为子进程启动——与 npx 相同，只是将命令换成了 docker。

镜像发布在 Docker Hub 上，地址为 perforce/p4plan-mcp，每次发布都会构建多架构镜像（linux/amd64 + linux/arm64），并提供 SLSA 来源证明和 SBOM 证明。

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"
      ]
    }
  }
}

注意： 使用 host.docker.internal（macOS/Windows）或 172.17.0.1（Linux）访问主机上运行的 P4 Plan GraphQL API。

固定特定版本： 将 :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 可在同一个登录 mutation 中代替密码使用。这样可以避免泄露你的实际密码：

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. 复制令牌 — 在上方的登录 mutation 中使用它，以获取 JWT

• 用途：查找其他工具所需的项目 ID

• 参数：projectId
• 用途：获取其他工具所需的分区 ID（backlog、QA、规划）

• 参数：name、可选的 methodTemplate、defaultMode、members（用户或全局群组的名称/ID）、managers（普通用户的名称/ID）、addMeAsManager（默认为 true），或通过 copyFromProjectId 复制现有项目，并设置 copyUsers/copyColumns
• 用途：无需使用界面即可为团队创建新项目。需要 P4 Plan 管理员权限；项目创建后失败的步骤会列在 failed 中

• 参数：showCompleted、showOnlyNextFourWeeks、showHidden、showPipelineTasksThatCannotStart
• 用途：查看所有项目中的个人待办队列

• 参数：taskIds（字符串数组，最多 20 个）——数据库条目 ID，即其他工具返回的 id
• 每条响应都包含 id（所有工具使用的数据库 ID）和 localID（P4 Plan 界面“ID”列中显示的编号）。
• 用途：获取条目完整详情、检查链接、批量检索多个条目

• 参数：findQuery、projectId
• 所有搜索均使用 P4 Plan Find 查询语法。请先调用 read_skill 并设置 skillName="search-queries"，以获取准确的列名、运算符和取值格式。简单名称搜索可使用 Itemname:Text("text")。支持按状态、负责人、严重程度、条目类型、日期、布尔条件以及 AND/OR/NOT 组合进行筛选。
• 每个项目包含三个分区（Backlog、QA、Planning），各自的 ID 不同。
• 若要解析 ID，请直接查询：ID=<n> 匹配界面中的“ID”列（本地 ID，仅在一个分区内唯一），Databaseid=<n> 匹配数据库 ID。
• 用途：查找条目、筛选、生成报告

• 类型：backlog_task、bug、scheduled_task、sprint、release、sprint_task
• 参数：type、name、projectId、parentItemId、previousItemId，以及特定类型的字段
• 用途：创建任务、创建 sprint、提交 bug

• 类型：BacklogTask、Bug、ScheduledTask、Sprint、Release
• 参数：itemId，以及所有可更新字段（name、status、assignedTo、points 等）
• 用途：更新状态、分配任务、估算、配置 sprint

• 参数：taskId、sprintId
• 使用场景：Sprint 规划、待办事项承诺

• 参数：taskId
• 使用场景：调整 sprint 范围

• 参数：projectId
• 使用场景：读取或写入值之前，查找自定义字段

• 参数：projectId（planning、backlog 或 QA ID）、name、columnType、activated、readOnly，以及类型专属的 unitName、updateOn*/updateOnlyFirstTime、useForTimeReporting/updateWorkRemaining、dropListItems（标签，或包含 icon、autoAssignToUsers、autoAssignToUserGroups 的对象）
• 使用场景：无需使用 UI 即可设置项目的列。需要拥有主项目经理权限

• 参数：taskId、onlySet
• 使用场景：读取项目专属元数据

• 参数：taskId、customFieldId、value
• 使用场景：更新项目专属元数据

• 参数：projectId
• 使用场景：查找状态转换所需的工作流状态

• 参数：taskId
• 使用场景：便捷地快速更新状态

• 参数：taskId
• 使用场景：便捷地快速更新状态

• 参数：taskId
• 用例：查看讨论历史

• 参数：taskId、text
• 用例：添加讨论内容、验收标准和备注

• 参数：taskId、commentId、text
• 用例：更正或更新现有评论

• 参数：taskId、commentId
• 用例：移除过时或错误的评论

• 参数：taskId
• 用例：列出附件文件，查找下载路径

• 参数：taskId、path
• 文本文件以内联形式返回，图片以 base64 格式返回
• 用例：阅读附件文档、查看屏幕截图

• 参数：taskId，以及 filePath（可选 fileName 用于重命名）或 content + fileName
• 本地文件必须位于允许的文件夹内，参见上传文件
• 返回新附件的 path；第一个附加的图片会成为封面图片
• 对于图片，还会返回 imageHtml，这是一个 <img> 标签，可在同一项的评论、描述、复现步骤或多行文本字段中显示图片
• 用例：在 Bug 报告和用户故事中附加屏幕截图、日志或复现文件

• 参数：taskId、path
• 用例：移除过时的附件

• 参数：taskId、imagePath
• 用例：为卡片/项目设置视觉标识

• 参数：fromItemId、toItemId 或 url、relation（blocks、duplicates、relatedTo）
• 用例：依赖关系跟踪、交叉引用、外部 URL

• 参数：fromItemId、toItemId 或 url
• 用例：清理过时的依赖关系

• 用例：身份验证、用户上下文

• 参数：projectId
• 用例：查找用于分配任务的用户 ID、管理冲刺成员

• 参数：skillName
• 返回所请求技能文档的完整 Markdown 内容。AI Agent 在为 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 替换为通过登录 mutation 获取的令牌（参见获取 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. 检查令牌是否有效： 如果令牌已过期或无效，服务会退出并显示“身份验证失败”。使用登录 mutation 生成新的 JWT。

3. 检查 GraphQL API 是否可访问： 必须能够通过已配置的 P4PLAN_API_URL 访问 P4 Plan GraphQL API（默认值：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 服务是否正在运行： 必须能够通过已配置的 URL 访问 P4 Plan GraphQL API。

2. 检查服务日志： 在 VS Code 中，打开“输出”面板 → 从下拉菜单中选择“p4-plan”，查看警告和错误。完整的调试日志请查看 logs/ 目录。

3. 确认 JWT 尚未过期： 如有需要，请生成新的 JWT 并更新 mcp.json 配置。