AI导哈

Perforce Node.js REST API

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

  • by halfcurry
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 halfcurry/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

端点 方法 描述 参数
/health GET 健康检查 -
/api/info GET 服务器信息 -
/api/files GET 列出仓库文件 path, max
/api/files/content GET 获取文件内容 path, revision
/api/files/history GET 文件历史记录 path, max
/api/changes GET 列表更改 max, status, user
/api/changes/:id GET 更改详细信息 -
/api/users GET 列出用户 -
/api/sync POST 同步文件 path, force
/api/docs 获取 API文档 -

使用示例

使用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

  2. 检查日志：

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

  3. 直接测试API：

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

MCP服务器问题

  1. 测试MCP服务器：

    cd mcp-server
node test.js

  2. 检查依赖关系：

    npm list @modelcontextprotocol/sdk

  3. 在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许可证-有关详细信息，请参阅许可证文件。

相关 MCP