mcp-perforce-server

mcp-perforce-server es un servidor del Protocolo de Contexto de Modelo para Perforce (p4) con valores predeterminados seguros, respuestas JSON estructuradas y flujos de trabajo tanto de estilo nativo como optimizados para MCP.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP Perforce

mcp-perforce-server es un servidor de Protocolo de Contexto de Modelo (MCP) para Perforce (p4) con valores predeterminados seguros, respuestas JSON estructuradas y flujos de trabajo tanto de estilo nativo como optimizados para MCP.

Está diseñado para asistentes de IA e integraciones de IDE que necesitan acceso a Perforce sin depender de scripts de shell frágiles.

Qué Proporciona

59 herramientas MCP que abarcan inspección de repositorios, operaciones de archivos, changelists, revisiones, trabajos, etiquetas, streams, análisis y cumplimiento.
Soporte de transporte dual: stdio (IDE/CLI) y SSE (servidor HTTP para clientes web).
Comportamiento en tiempo de ejecución seguro por defecto:
- P4_READONLY_MODE=true
- P4_DISABLE_DELETE=true
Entradas con capacidad de procesamiento por lotes para la superficie de herramientas donde p4 nativo admite uso multiobjetivo.
Helpers compuestos específicos de MCP que reducen los viajes de ida y vuelta para flujos de trabajo comunes de revisión y búsqueda.
Respuestas estructuradas con ok, result, error opcional, warnings opcional y configUsed.
Los clientes MCP ven nombres de herramientas seguros con guiones bajos, por ejemplo p4_changes.
Las llamadas entrantes también aceptan los nombres históricos con puntos, por ejemplo p4.changes.

Flujos de Trabajo Destacados

El servidor incluye helpers de nivel superior sobre los comandos p4 sin procesar.

p4.review.bundle: changelists de revisión pendientes con detalles y revisores opcionales
p4.change.inspect: describe + fixes + reviews + diff opcional + historial de archivos opcional
p4.path.synccheck: análisis de desviación y estado de sincronización entre dos rutas de depósito
p4.file.inspect: metadatos por archivo, historial, contenido opcional y blame opcional
p4.workspace.snapshot: información del espacio de trabajo, estado, configuración opcional, archivos abiertos y cambios recientes
p4.search.inspect: resultados de búsqueda agrupados con metadatos de archivos y vistas previas de contenido opcionales
p4.review.prepare: changelists explícitos o descubiertos preparados en paquetes listos para revisión

Instalación

npm install -g mcp-perforce-server

Requisitos:

Node.js 18+
CLI de Perforce disponible como p4 o p4.exe
Entorno de Perforce válido mediante .p4config o MCP env

Inicio Rápido

Instale la CLI de Perforce y asegúrese de que p4 esté en PATH.
Configure las credenciales de Perforce en .p4config o mediante MCP env.
Agregue el servidor a su cliente MCP.
Inicie en el perfil seguro predeterminado antes de habilitar cualquier herramienta con capacidad de escritura.

Ejemplo de .p4config:

P4PORT=ssl:perforce.example.com:1666
P4USER=your-username
P4CLIENT=your-workspace-name
P4PASSWD=your-password-or-ticket

Ejemplo de configuración MCP usando el servidor instalado globalmente:

{
  "mcpServers": {
    "perforce": {
      "command": "mcp-perforce-server"
    }
  }
}

Ejemplo de configuración MCP con credenciales explícitas:

{
  "mcpServers": {
    "perforce": {
      "command": "mcp-perforce-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your-username",
        "P4CLIENT": "your-workspace-name",
        "P4PASSWD": "your-password-or-ticket",
        "P4_READONLY_MODE": "true",
        "P4_DISABLE_DELETE": "true"
      }
    }
  }
}

Ejemplo de repositorio local en Windows:

{
  "mcpServers": {
    "perforce": {
      "command": "node",
      "args": ["C:\\Tools\\git-projects\\mcp-perforce-server\\dist\\server.js"]
    }
  }
}

Modos de Transporte

El servidor admite dos modos de transporte:

Transporte Stdio (Predeterminado)

Transporte de entrada/salida estándar para integración con IDE y CLI. Cada cliente MCP genera su propio proceso de servidor.

Mejor para:

Integración con VS Code, Cursor, Claude Desktop
Herramientas CLI y automatización local
Flujos de trabajo de un solo usuario
Modelo de seguridad con aislamiento de procesos

# Default mode (no flag needed)
mcp-perforce-server

Transporte SSE (Servidor HTTP)

El transporte de Eventos Enviados por el Servidor (SSE) ejecuta un servidor HTTP para clientes basados en web.

Mejor para:

Paneles web y interfaces de análisis
Herramientas de colaboración en equipo
Implementaciones centralizadas
Entornos multiusuario
Integraciones de API

# Start SSE server
mcp-perforce-server --transport=sse

# With custom configuration
MCP_SSE_PORT=8080 MCP_SSE_ENABLE_AUTH=true mcp-perforce-server --transport=sse

Configuración SSE:

Variable	Predeterminado	Descripción
`MCP_SSE_PORT`	`3000`	Puerto del servidor HTTP
`MCP_SSE_HOST`	`0.0.0.0`	Dirección de enlace del servidor
`MCP_SSE_PATH`	`/mcp`	Ruta del endpoint SSE
`MCP_SSE_CORS_ORIGIN`	`*`	Orígenes permitidos por CORS
`MCP_SSE_ENABLE_AUTH`	`false`	Habilitar autenticación por token
`MCP_SSE_AUTH_TOKEN`	(vacío)	Token Bearer para autenticación

Endpoints SSE:

Principal: GET http://localhost:3000/mcp
Salud: GET http://localhost:3000/health
Publicación: POST http://localhost:3000/mcp

Ejemplo SSE de Producción:

export MCP_SSE_ENABLE_AUTH=true
export MCP_SSE_AUTH_TOKEN="your-secret-token"
export MCP_SSE_CORS_ORIGIN="https://your-dashboard.com"
export P4_READONLY_MODE=true
mcp-perforce-server --transport=sse

📘 Para la guía completa de implementación SSE, consulte SSE_SETUP_GUIDE.md

Referencias rápidas:

Ejemplos de Configuración MCP - Fragmentos de configuración rápidos
Guía de Configuración SSE - Guía integral de implementación con Docker, Kubernetes y ejemplos de producción

Modelo de Seguridad

El perfil de tiempo de ejecución predeterminado es conservador.

Configuración	Predeterminado	Efecto
`P4_READONLY_MODE`	`true`	Bloquea herramientas con capacidad de escritura.
`P4_DISABLE_DELETE`	`true`	Bloquea `p4.delete` incluso cuando el modo de escritura está habilitado.

Las herramientas con capacidad de escritura incluyen:

p4.add, p4.edit, p4.delete, p4.revert, p4.sync
p4.changelist.create, p4.changelist.update, p4.changelist.submit, p4.submit
p4.resolve, p4.shelve, p4.unshelve
p4.copy, p4.move, p4.integrate, p4.merge

Superficie de Herramientas

Categorías principales:

Inspección de repositorio y espacio de trabajo
Operaciones de archivos y comparación de diferencias
Changelists y envíos
Flujos de fusión, shelving y resolución
Búsqueda y descubrimiento
Compuestos de revisión y flujo de trabajo
Usuarios, clientes, streams, etiquetas, trabajos y correcciones
Cumplimiento, auditoría y diagnósticos operativos

Mejoras notables de paridad nativa:

Entradas de estilo por lotes para comandos como sync, opened, filelog, annotate, grep, files, dirs, print, fstat, sizes, have, users, streams, jobs y fixes
Cobertura ampliada de banderas nativas para herramientas como sync, interchanges, fstat, files, dirs, streams, clients, labels, jobs y sizes
Soporte tanto para comparación orientada al espacio de trabajo como de depósito a depósito mediante p4.diff y p4.diff2

Configuración

La mayoría de las instalaciones solo necesitan un pequeño conjunto de variables.

Variable	Predeterminado	Propósito
`P4_READONLY_MODE`	`true`	Mantener el servidor de solo lectura por defecto.
`P4_DISABLE_DELETE`	`true`	Prevenir operaciones de eliminación a menos que se habiliten explícitamente.
`P4CONFIG`	`.p4config`	Nombre del archivo de configuración utilizado durante el descubrimiento ascendente.
`P4_PATH`	`p4` / `p4.exe`	Ruta personalizada a la CLI de Perforce.
`P4_PERFORMANCE_MODE`	`fast`	Preajuste: `fast`, `balanced`, `secure`.
`P4_WORKFLOW_CONCURRENCY`	`6`	Máximo de subllamadas concurrentes para herramientas compuestas.
`P4_RESPONSE_CACHE`	`true`	Habilitar caché de respuestas de lectura.
`P4_RESPONSE_CACHE_TTL_MAP`	sin establecer	Anulaciones de TTL de caché por herramienta.
`LOG_LEVEL`	`warn`	Nivel de registro del servidor.

Variables de conexión de Perforce:

P4PORT
P4USER
P4CLIENT
P4PASSWD
P4CHARSET
P4COMMANDCHARSET
P4LANGUAGE

Para tablas de configuración completas y ejemplos, consulte:

Desarrollo

npm install
npm run build
npm test
npm run test:integration

Línea base de verificación actual:

npm run build
npm test
npm run test:integration

Documentación

Configuración de Transporte SSE: SSE_SETUP_GUIDE.md - Guía completa para implementaciones HTTP/web
Catálogo de herramientas y descripciones: AGENTS.md
Índice de documentación: docs/README.md
Configuración de Perforce: PERFORCE_SETUP.md
Ejemplos de configuración de cliente MCP: MCP_CONFIG_EXAMPLES.md
Flujo de trabajo de publicación: PUBLISHING.md
Borrador de notas de versión: RELEASE_NOTES.md

Licencia

MIT