MCP Perforce 服务器

这是一个提供 Perforce（P4）操作干净接口的 Model Context Protocol (MCP) 服务器。该服务器封装了 P4 命令，使其更加可靠且易于在 Claude Desktop 中使用，消除了交互式提示和复杂状态管理的问题。

功能

• 非交互式操作：所有命令都被封装以避免交互式提示
• 结构化响应：清晰、可解析的输出而不是原始的 P4 输出
• 多项目支持：自动使用 .p4config 文件进行每个项目的设置
• 常见操作：添加、编辑、删除、提交、回退、同步等
• 变更列表管理：使用明确参数创建和提交变更列表
• 错误处理：优雅的错误处理并带有清晰的错误信息

安装

先决条件

• 已安装 Node.js 18+
• 已安装 Perforce 命令行客户端 (p4) 并将其添加到 PATH 中
• 在项目目录中存在 .p4config 文件（推荐）

使用 Claude Code 快速安装

# 全局安装包
npm install -g @cocoon-ai/mcp-perforce

# 添加到 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  # 使 'mcp-perforce' 可全局使用

配置

基本设置

将服务器添加到您的 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：检查工作区状态和待处理更改

  "显示我待处理的 P4 更改"
  "检查 gamedev 目录中的 P4 状态"
  

• p4_add：向 Perforce 添加文件

  "将 src 目录中的所有 .js 文件添加到 Perforce"
  

• p4_edit：打开文件进行编辑

  "在 Perforce 中打开 config.json 进行编辑"
  

• p4_delete：标记文件以供删除

  "从 Perforce 删除 old_module.py 文件"
  

• p4_sync：从仓库同步文件

  "同步项目中的所有文件"
  "强制同步 src 目录"
  

• p4_revert：恢复文件或整个变更列表

  "恢复变更列表 12345 中的所有文件"
  "恢复对 config.json 的更改"
  

• p4_diff：显示文件差异

  "显示我所有打开文件的差异"
  

变更列表操作

• p4_changelist_create：创建新的变更列表

  "创建一个新的变更列表，描述为 '修复登录错误'"
  

• p4_changelist_submit：提交变更列表

  "提交变更列表 1_2345"
  

• p4_move_to_changelist：在变更列表之间移动文件

  "将我所有打开的文件移动到变更列表 12345"
  

流操作

• p4_stream_list：列出仓库中的流

  "列出 //depot 中的所有流"
  "显示匹配 'feature' 的开发流"
  

• p4_stream_info：获取详细的流信息

  "显示关于 //depot/main 流的详细信息"
  

• p4_stream_switch：切换工作区到不同的流

  "切换到 //depot/dev 流"
  "强制切换到 //depot/release-2.0"
  

• p4_stream_create：创建新的流

  "从 //depot/main 创建开发流 //depot/feature-xyz"
  

• p4_stream_edit：编辑流规范

  "编辑 //depot/feature-xyz 流规范"
  

• p4_stream_graph：显示流层次结构

  "显示 //depot 的流层次结构"
  

客户端/工作区操作

• p4_client_list：列出所有客户端/工作区

  "列出我的所有 Perforce 工作区"
  "显示用户 jsmith 的客户端"
  

• p4_client_info：获取客户端/工作区详情

  "显示我当前工作区的详细信息"
  "显示 gamedev-workspace 客户端的信息"
  

• p4_client_create：创建新的客户端/工作区

  "在 /home/user/p4/feature 创建名为 dev-feature 的新工作区"
  "为 //depot/main-stream 创建流客户端"
  

• p4_client_edit：编辑客户端规范

  "编辑 dev-workspace 客户端的视图映射"
  

• p4_client_delete：删除客户端/工作区

  "删除 old-feature 工作区"
  "强制删除 broken-client 工作区"
  

• p4_client_switch：切换到不同的客户端

  "切换到 production-client 工作区"
  

信息操作

• p4_info：显示当前 Perforce 配置

  "显示我正在使用的 P4 服务器和工作区"
  

• mcp_perforce_version：显示 MCP Perforce 服务器版本

  "运行的是哪个版本的 mcp-perforce？"
  

在 Claude 中的示例用法

这里有一些与 Claude 的示例对话：

示例 1：创建并提交更改

您: "我已经修改了 server.js 和 config.json。为这些修复创建一个变更列表"
Claude: 我会帮助您为您的更改创建一个变更列表。让我先检查一下状态...
[使用 p4_status, p4_changelist_create, p4_submit]

示例 2：同步并查看更改

您: "同步最新的更改并显示我有哪些文件是打开的"
Claude: 我会同步您的工作区并检查您的打开文件...
[使用 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. 分叉存储库
2. 创建功能分支 (git checkout -b feature/new-command)
3. 提交您的更改 (git commit -am '添加新的 P4 命令')
4. 推送到分支 (git push origin feature/new-command)
5. 创建拉取请求

许可证

MIT 许可证 - 详情见 LICENSE 文件

致谢

• 基于 Model Context Protocol SDK
• 受到在 AI 助手中更好地集成 Perforce 的需求启发

支持

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

---

为在 P4 命令行操作中挣扎的 AI 制作，充满爱心