MCP Perforce Server

Un servidor para operaciones de control de versiones de Perforce (P4), que envuelve comandos de P4 para un uso más fácil y confiable.

GitHub
29
Prueba este MCPPatrocinado

Documentación

MCP Perforce Server

Un servidor de Model Context Protocol (MCP) que proporciona una interfaz limpia para operaciones de Perforce (P4) en Claude Desktop. Este servidor envuelve los comandos P4 para hacerlos más fiables y fáciles de usar para Claude, eliminando problemas con prompts interactivos y gestión de estado compleja.

Características

  • Operaciones no interactivas: Todos los comandos están envueltos para evitar prompts interactivos
  • Respuestas estructuradas: Salida limpia y analizable en lugar de la salida P4 cruda
  • Soporte multi-proyecto: Utiliza automáticamente archivos .p4config para configuraciones por proyecto
  • Operaciones comunes: Añadir, editar, eliminar, enviar, revertir, sincronizar y más
  • Gestión de changelists: Crear y enviar changelists con parámetros explícitos
  • Manejo de errores: Manejo de errores elegante con mensajes de error claros

Instalación

Requisitos previos

  • Node.js 18+ instalado
  • Cliente de línea de comandos de Perforce (p4) instalado y en tu PATH
  • Archivos .p4config en los directorios de tu proyecto (recomendado)

Instalación rápida con 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

¡Eso es todo! Claude Code configurará automáticamente el servidor por ti.

Instalación manual

Vía NPM (cuando se publique)

npm install -g @cocoon-ai/mcp-perforce

Instalar desde el código fuente

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

Configuración

Configuración básica

Añade el servidor a tu archivo de configuración de 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"
      }
    }
  }
}

Configuración de archivos .p4config

El servidor utiliza el mecanismo P4CONFIG integrado de Perforce para cambiar automáticamente entre diferentes servidores Perforce según tu directorio actual. Crea un archivo .p4config en la raíz de cada proyecto:

# ~/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

¡Ahora el servidor MCP utilizará automáticamente la configuración de Perforce correcta según el directorio del proyecto en el que estés trabajando!

Comandos disponibles

Una vez configurado, puedes pedirle a Claude que use estas operaciones P4. Todos los comandos utilizarán automáticamente la configuración .p4config de tu directorio de proyecto actual.

Operaciones básicas de archivos

  • p4_status: Comprueba el estado del workspace y los cambios pendientes

    "Show me my pending P4 changes"
"Check P4 status in the gamedev directory"

  • p4_add: Añade archivos a Perforce

    "Add all .js files in the src directory to Perforce"

  • p4_edit: Abre archivos para edición

    "Open config.json for editing in Perforce"

  • p4_delete: Marca archivos para eliminación

    "Delete the old_module.py file from Perforce"

  • p4_sync: Sincroniza archivos desde el depot

    "Sync all files in the project"
"Force sync the src directory"

  • p4_revert: Revierte archivos o changelists completos

    "Revert all files in changelist 12345"
"Revert changes to config.json"

  • p4_diff: Muestra diferencias de archivos

    "Show me the diff for all my open files"

Operaciones de changelist

  • p4_changelist_create: Crea un nuevo changelist

    "Create a new changelist with description 'Fix login bug'"

  • p4_changelist_submit: Envía un changelist

    "Submit changelist 12345"

  • p4_move_to_changelist: Mueve archivos entre changelists

    "Move all my open files to changelist 12345"

Operaciones de stream

  • p4_stream_list: Lista los streams en un depot

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

  • p4_stream_info: Obtiene información detallada del stream

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

  • p4_stream_switch: Cambia el workspace a un stream diferente

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

  • p4_stream_create: Crea un nuevo stream

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

  • p4_stream_edit: Edita la especificación del stream

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

  • p4_stream_graph: Muestra la jerarquía de streams

    "Show the stream hierarchy for //depot"

Operaciones de cliente/workspace

  • p4_client_list: Lista todos los clientes/workspaces

    "List all my Perforce workspaces"
"Show clients for user jsmith"

  • p4_client_info: Obtiene detalles del cliente/workspace

    "Show me details about my current workspace"
"Show info for client gamedev-workspace"

  • p4_client_create: Crea un nuevo cliente/workspace

    "Create a new workspace called dev-feature in /home/user/p4/feature"
"Create a stream client for //depot/main-stream"

  • p4_client_edit: Edita la especificación del cliente

    "Edit the view mappings for client dev-workspace"

  • p4_client_delete: Elimina un cliente/workspace

    "Delete the old-feature workspace"
"Force delete the broken-client workspace"

  • p4_client_switch: Cambia a un cliente diferente

    "Switch to the production-client workspace"

Operaciones de información

  • p4_info: Muestra la configuración actual de Perforce

    "Show me which P4 server and workspace I'm using"

  • mcp_perforce_version: Muestra la versión del servidor MCP Perforce

    "What version of mcp-perforce is running?"

Ejemplo de uso en Claude

Aquí hay algunos ejemplos de conversaciones con Claude:

Ejemplo 1: Crear y enviar un cambio

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]

Ejemplo 2: Sincronizar y revisar cambios

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]

Solución de problemas

El servidor no aparece en Claude

  1. Reinicia Claude Desktop después de modificar la configuración
  2. Comprueba que el archivo de configuración es JSON válido
  3. Verifica que el servidor MCP está instalado: npm list -g @cocoon-ai/mcp-perforce

Errores de autenticación de Perforce

  1. Comprueba que tu archivo .p4config existe y tiene la configuración correcta
  2. Prueba tu conexión fuera de Claude: p4 info
  3. Asegúrate de haber iniciado sesión: p4 login
  4. Verifica que P4CONFIG está siendo reconocido: p4 set P4CONFIG

Se está usando el servidor Perforce incorrecto

  1. Comprueba en qué directorio estás: el servidor utiliza .p4config del directorio actual o de los directorios padre
  2. Ejecuta p4 info para ver qué configuración se está usando
  3. Usa el comando p4_info en Claude para depurar: "Muéstrame mi configuración de P4"

El comando no funciona como se esperaba

  1. Comprueba la respuesta de Claude para ver mensajes de error
  2. Verifica que el comando P4 funciona en tu terminal desde el mismo directorio
  3. Habilita el registro de depuración (ver más abajo)

Registro de depuración

Para habilitar la salida de depuración, añade a tu configuración:

{
  "mcpServers": {
    "perforce": {
      "command": "npx",
      "args": ["-y", "@cocoon-ai/mcp-perforce"],
      "env": {
        "P4CONFIG": ".p4config",
        "DEBUG": "mcp:*"
      }
    }
  }
}

Desarrollo

Compilar desde el código fuente

git clone https://github.com/Cocoon-AI/mcp-perforce.git
cd mcp-perforce
npm install
npm run build

Ejecutar pruebas

npm test

Añadir nuevos comandos

  1. Añade la definición de la herramienta en el archivo correspondiente bajo src/tools/
  2. Añade la función de manejo en el archivo correspondiente bajo src/handlers/
  3. Actualiza la sentencia switch en src/handlers/index.ts
  4. Sigue el patrón existente para la validación de parámetros y el manejo de errores

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

  1. Haz un fork del repositorio
  2. Crea una rama de características (git checkout -b feature/new-command)
  3. Haz commit de tus cambios (git commit -am 'Add new P4 command')
  4. Haz push a la rama (git push origin feature/new-command)
  5. Crea un Pull Request

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles

Agradecimientos

  • Construido sobre el Model Context Protocol SDK
  • Inspirado por la necesidad de una mejor integración de Perforce en asistentes de IA

Soporte

Hecho con ❤️ para las IAs que luchan con las operaciones de línea de comandos de P4