P4 Test

Perforce Node.js REST API

容器化的Perforce服务器，带有Node.js REST API，便于集成和测试。

建筑

• Perforce服务器: sourcegraph/helix-p4d -全性能Helix Core服务器
• Node.js API：基于表达式的REST API，具有全面的Perforce集成
• Docker Compose：具有网络和持久性的编排容器

快速开始

先决条件

• Docker和Docker Compose
• curl 和 jq （用于测试）

设置

docker-compose build
docker-compose up -d

API终点

基本URL: http://localhost:3000

使用示例

使用curl

# Health check
curl http://localhost:3000/health

# List recent files
curl "http://localhost:3000/api/files?max=10" | jq

# Get file content
curl "http://localhost:3000/api/files/content?path=//depot/main/README.md" | jq

# List recent changes
curl "http://localhost:3000/api/changes?max=5" | jq

# Sync files
curl -X POST http://localhost:3000/api/sync \
  -H "Content-Type: application/json" \
  -d '{"path": "//depot/...", "force": false}'

穿孔连接详图

• 服务器: localhost:1666
• 用户: super
• 密码: YourStrongPassword123! (⚠️ 改变这个！)
• 客户端: nodejs-client

与P4V或P4 CLI连接

# Set environment
export P4PORT=localhost:1666
export P4USER=super
export P4PASSWD=YourStrongPassword123!

# Test connection
p4 info

# List files
p4 files //depot/...

# Get changes
p4 changes -m 10

发展

手动Docker命令

# Build and start
docker-compose build
docker-compose up -d

# View logs
docker-compose logs -f nodejs-api
docker-compose logs -f perforce-server

# Execute commands
docker-compose exec nodejs-api bash
docker-compose exec perforce-server p4 info

# Stop and clean
docker-compose down
docker-compose down -v  # with volumes

容器中的文件结构

性能服务器：

• 数据： /p4 （持续体积）
• 仓库： //depot/...

Node.js API：

• 工作区： /workspace
• 应用程序： /app

错误处理

API提供一致的错误响应：

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message"
}

Perforce MCP服务器

模型上下文协议（MCP）服务器，通过Node.js API为AI代理提供对Perforce版本控制系统的访问。

特性

• 服务器信息：获取Perforce服务器状态和配置
• 文件操作：列出文件、获取内容和查看修订历史记录
• 变更管理：列出最近的更改并获取详细的更改信息
• 用户管理：列出Perforce用户
• 同步操作：从仓库同步文件
• 证券分析：分析潜在敏感内容的最新变化

建筑

AI Agent (Claude) → MCP Server → Node.js API → Perforce Server

安装说明

1.项目结构

创建以下目录结构：

your-project/
├── nodejs-api/           # Your existing Node.js API
│   ├── server.js
│   ├── package.json
│   └── Dockerfile
├── mcp-server/           # New MCP server
│   ├── index.js
│   ├── package.json
│   ├── test.js
│   └── Dockerfile
└── docker-compose.yml    # Updated compose file

2.安装依赖项

在 mcp-server 目录：

cd mcp-server
npm install

3.测试设置

# Test the MCP server functionality
npm test

# Or run directly
node test.js

4.启动服务

# Start all services (Perforce, Node.js API, MCP Server)
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs mcp-server

5.配置克劳德桌面

将MCP服务器添加到Claude Desktop配置文件中：

地点：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "perforce": {
      "command": "node",
      "args": ["/path/to/your/mcp-server/index.js"],
      "env": {
        "PERFORCE_API_URL": "http://localhost:3000/api"
      }
    }
  }
}

对于Docker设置：

{
  "mcpServers": {
    "perforce": {
      "command": "docker",
      "args": ["exec", "-i", "perforce-mcp-server", "node", "index.js"],
      "env": {
        "PERFORCE_API_URL": "http://nodejs-api:3000/api"
      }
    }
  }
}

可用工具

基本操作

get_server_info

获取Perforce服务器信息和状态。

No parameters required

list_files

列出Perforce仓库中的文件。

参数：

• path （可选）：列出文件的仓库路径（默认值： //depot/...)
• max （可选）：要返回的最大文件数（1-1000，默认值：100）

get_file_content

获取特定文件的内容。

参数：

• path （必填）：文件的完整仓库路径
• revision （可选）：要检索的特定修订号

get_file_history

获取特定文件的修订历史记录。

参数：

• path （必填）：文件的完整仓库路径
• max （可选）：历史记录条目的最大数量（1-100，默认值：10）

变更管理

list_changes

列出Perforce中最近的更改/提交。

参数：

• max （可选）：返回的最大更改次数（1-100，默认值：20）
• status （可选）：按状态筛选(pending 或 submitted)
• user （可选）：按特定用户筛选更改

get_change_details

获取有关特定更改的详细信息。

参数：

• changeId （必填）：获取详细信息的更改编号

用户管理

list_users

列出Perforce系统中的所有用户。

No parameters required

同步操作

sync_files

从Perforce仓库同步文件。

参数：

• path （可选）：要同步的仓库路径（默认值： //depot/...)
• force （可选）：即使文件是最新的，也强制同步（默认值：false）

证券分析

analyze_sensitive_changes

分析最近的更改以查找潜在的敏感内容。

参数：

• maxChanges （可选）：要分析的最近更改的最大数量（1-50，默认值：10）
• keywords （可选）：要搜索的关键字数组（默认值：\[“密码”、“秘密”、“密钥”、“令牌”、“凭证”、“身份验证”\]）

使用示例

基本文件操作

Ask Claude: "List the recent files in our depot"
Tool used: list_files

Ask Claude: "Show me the content of //depot/main/config.txt"
Tool used: get_file_content with path="//depot/main/config.txt"

变化分析

Ask Claude: "What are the last 10 changes in our repository?"
Tool used: list_changes with max=10

Ask Claude: "Show me details for change 1234"
Tool used: get_change_details with changeId=1234

证券分析

Ask Claude: "Analyze recent changes for any sensitive content"
Tool used: analyze_sensitive_changes

Ask Claude: "Check the last 20 changes for passwords or keys"
Tool used: analyze_sensitive_changes with maxChanges=20, keywords=["password", "key"]

故障排除

连接问题

1. 检查服务状态：

   docker-compose ps
   curl http://localhost:3000/health

1. 检查日志：

   docker-compose logs nodejs-api
   docker-compose logs mcp-server

1. 直接测试API：

   curl http://localhost:3000/api/info

MCP服务器问题

1. 测试MCP服务器：

   cd mcp-server
   node test.js

1. 检查依赖关系：

   npm list @modelcontextprotocol/sdk

1. 在Claude Desktop中验证配置：

- 确保路径正确 - 检查环境变量 - 配置更改后重新启动Claude Desktop

常见错误消息

• “网络错误：无法访问Perforce API服务器”

- 检查Node.js API是否在正确的端口上运行 - 验证PERFORCE_API_URL环境变量

• “API错误：500-获取服务器信息失败”

- 检查Node.js API中的Perforce服务器连接 - 验证Perforce凭据和服务器状态

• “工具执行失败”

- 检查MCP服务器日志以获取详细的错误消息 - 确保提供所有必需的参数

发展

添加新工具

1. 在中添加工具定义 setupToolHandlers() 方法
2. 实施相应的方法
3. 用使用示例更新此README
4. 在中添加测试 test.js

环境变量

• PERFORCE_API_URL：Node.js Perforce API的URL（默认值：http://localhost:3000/api)
• NODE_ENV：环境模式（开发/生产）

安全考虑

• MCP服务器使用与Node.js API相同的权限运行
• 敏感的变更分析有助于识别潜在的安全问题
• 如果暴露在本地主机之外，请考虑实施身份验证
• 仔细审查变更分析结果——它们可能包含误报

许可证

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