MCP Perforce Server

MCP Perforce 服务

一个模型上下文协议（MCP）服务，可在 Claude Desktop 中为 Perforce（P4）操作提供简洁的接口。此服务封装了 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：从 depot 同步文件

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

Stream 操作

• p4_stream_list：列出 depot 中的 stream

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

• p4_stream_info：获取详细的 stream 信息

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

• p4_stream_switch：将工作区切换到其他 stream

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

• p4_stream_create：创建新的 stream

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

• p4_stream_edit：编辑 stream 规格

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

• p4_stream_graph：显示 stream 层级结构

  "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. Fork 此仓库
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 文件

致谢

• 基于 Model Context Protocol SDK 构建
• 源于在 AI 助手中更好地集成 Perforce 的需求

支持

• 问题：GitHub Issues
• 讨论：GitHub Discussions

---

为苦于使用 P4 命令行操作的 AI 倾心打造 ❤️