MCP Perforce

MCP性能服务器

一种模型上下文协议（MCP）服务器，为Claude Desktop中的Perforce（P4）操作提供干净的接口。该服务器封装了P4命令，使其更可靠，更易于克劳德使用，消除了交互式提示和复杂状态管理的问题。

特性

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

安装

先决条件

• 已安装Node.js 18+
• Perforce命令行客户端（p4）已安装并位于PATH中
• .p4config 项目目录中的文件（推荐）

使用Claude代码快速安装

# 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\ 视窗: %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：从仓库同步文件

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

流操作

• p4_stream_list：列出仓库中的流

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

• p4_stream_info：获取详细的流信息

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

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

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

• p4_stream_create：创建新流

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

• p4_stream_edit：编辑流规范

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

• p4_stream_graph：显示流层次结构

  "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中的示例用法

以下是与克劳德的一些对话示例：

示例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

执行身份验证错误

1. 检查你的 .p4config 文件存在并且具有正确的设置
2. 在Claude之外测试您的连接： p4 info
3. 请确保您已登录： p4 login
4. 验证P4CONFIG是否被识别： p4 set P4CONFIG

使用了错误的Perforce服务器

1. 检查服务器使用的目录 .p4config 从当前目录或父目录
2. 跑 p4 info 查看正在使用的配置
3. 使用 p4_info Claude中的调试命令：“显示我的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. 更新中的switch语句 src/handlers/index.ts
4. 遵循现有的模式进行参数验证和错误处理

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/new-command)
3. 提交您的更改(git commit -am 'Add new P4 command')
4. 推到分支(git push origin feature/new-command)
5. 创建拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• 建立在 模型上下文协议SDK
• 受AI助手中更好的Perforce集成需求的启发

支持

• 问题:
• 讨论:

______________________________________________________________________

由以下材料制成❤️ 适用于在P4命令行操作中苦苦挣扎的AI