P4 MCP Server

Si tiene uv instalado, puede ejecutar P4 MCP Server directamente sin ninguna instalación manual:

# Run the server
uvx p4mcp-server

# Check version
uvx p4mcp-server --version

# Run with arguments
uvx p4mcp-server --readonly --allow-usage

Esto obtiene y ejecuta automáticamente la última versión desde PyPI. No se necesita configuración de entorno virtual de Python ni gestión de dependencias.

Requisitos:

• uv instalado en su sistema
• Python 3.11+ (uv lo gestionará automáticamente)

Descargue el binario apropiado para su sistema operativo:

• macOS: p4-mcp-server-mac.zip
• Windows: p4-mcp-server-win.zip
• Linux: p4-mcp-server-linux.zip

Extraiga y use el ejecutable directamente. No se requiere instalación de Python.

# macOS / Linux
unzip p4-mcp-server-mac.zip   # or p4-mcp-server-linux.zip
./p4-mcp-server --help

# Windows
Expand-Archive p4-mcp-server-win.zip -DestinationPath .
.\p4-mcp-server.exe --help

Requisitos:

• Python 3.11+ (con Tkinter)

Compilar:

• macOS: chmod +x build.sh && ./build.sh package
• Linux: chmod +x build.sh && ./build.sh package
• Windows: build.bat package

Salida:

• macOS y Linux: p4-mcp-server-<version>.tgz
• Windows: p4-mcp-server-<version>.zip

Ejecute P4 MCP Server directamente en su máquina usando el transporte STDIO predeterminado.

Agregue lo siguiente a su mcp.json:

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

Nota: Este ejemplo muestra valores explícitos de env. Si P4CONFIG está configurado, puede omitirlos y usar el ejemplo de configuración genérica en la sección MCP client configuration.

Ejecute P4 MCP Server desde un contenedor Docker con transporte STDIO, permitiendo que los clientes MCP gestionen el ciclo de vida del contenedor.

Nota: La ejecución basada en Docker actualmente solo es compatible con macOS y Linux.

Requisitos previos

• Docker instalado y en ejecución
• Credenciales P4 válidas y acceso a un servidor P4

Obtener la imagen Docker

docker pull ghcr.io/perforce/p4mcp-server:latest

cd /path/to/p4mcp-server
docker build -t ghcr.io/perforce/p4mcp-server .

Configurar el cliente MCP

Agregue lo siguiente a su mcp.json:

{
    "servers": {
        "perforce-p4mcp-docker": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "--hostname", "your-hostname",
                "-e", "P4PORT=ssl:perforce.example.com:1666",
                "-e", "P4USER=your_username",
                "-e", "P4CLIENT=your_workspace",
                "-e", "P4DAM_API_KEY=your_api_key",
                "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro",
                "ghcr.io/perforce/p4mcp-server:latest"
            ]
        }
    }
}

Opciones de configuración

Autenticación

Usando tickets de P4:

# macOS/Linux
-v /Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro

Nota: Use la ruta completa a su archivo de tickets (no ~). Después de ejecutar p4 login, reinicie el servidor MCP para que tome el nuevo ticket.

Nota: Por defecto, el contenedor se inicia como root, copia el archivo de tickets montado por bind a una ubicación legible por el usuario no root mcpuser, y luego reduce privilegios (mediante gosu) para que el servidor se ejecute como mcpuser. Esta copia automática permite que un archivo de tickets de solo propietario (0600) propiedad de un uid extranjero funcione en runtimes que preservan la propiedad del host (Docker/podman nativo en Linux). Se admite un montaje bind de :ro del ticket: el archivo se copia, no se modifica en su lugar (esto es distinto de un sistema de archivos raíz de solo lectura; consulte a continuación). Tenga en cuenta que la copia automática se ejecuta solo cuando el contenedor se inicia como root (el valor predeterminado); forzar un uid no root o un sistema de archivos raíz de solo lectura cambia este comportamiento, como se describe a continuación.

Kubernetes / perfiles restringidos (con aplicación de no root): la imagen se inicia intencionalmente como root y reduce a mcpuser (uid 1000) mediante gosu, por lo que el servidor siempre se ejecuta como no root: ambas rutas son compatibles. Para runAsNonRoot / PodSecurity restringido / SCC restringido de OpenShift, configure securityContext.runAsUser: 1000 (y fsGroup: 1000 al montar el ticket). En ese modo, la copia del ticket solo para root del entrypoint se omite, por lo que el ticket montado ya debe ser legible por el uid 1000 (montaje con coincidencia de propietario, -e P4PASSWD="your_ticket_content", o podman -v <host>:/home/mcpuser/.p4tickets:U).

Sistema de archivos raíz de solo lectura (--read-only / readOnlyRootFilesystem): proporcione un /home/mcpuser escribible/tmpfs (p. ej., --tmpfs /home/mcpuser) para que la copia del ticket pueda escribirse; de lo contrario, la copia del ticket falla y P4 informará un error de autenticación normal.

Usando una contraseña:

-e P4PASSWD="your_password"

Restricciones de host del workspace

⚠️ Importante: Los contenedores Docker tienen su propio nombre de host, que difiere del de su máquina local. Si su workspace de P4 está restringido a un host específico, operaciones como sync fallarán.

Para resolver esto, configure el nombre de host del contenedor para que coincida con la restricción de host de su workspace:

--hostname your-hostname

Para encontrar el nombre de host de su workspace:

# macOS/Linux
p4 client -o your_workspace | grep "^Host:"

Montaje de la raíz del cliente para operaciones de escritura

⚠️ Importante: Por defecto, el contenedor Docker no puede acceder a los archivos de su workspace local. Para operaciones de escritura como sync, submit o reconcile, debe montar el directorio raíz de su cliente en el contenedor en la misma ruta.

Agregue un montaje de volumen para la raíz de su cliente:

-v /path/to/your/client/root:/path/to/your/client/root

Ejemplo de configuración con la raíz del cliente montada:

{
    "servers": {
        "perforce-p4mcp-docker": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "--hostname", "your-hostname",
                "-e", "P4PORT=ssl:perforce.example.com:1666",
                "-e", "P4USER=your_username",
                "-e", "P4CLIENT=your_workspace",
                "-e", "P4DAM_API_KEY=your_api_key",
                "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets",
                "-v", "/path/to/client/root:/path/to/client/root",
                "ghcr.io/perforce/p4mcp-server:latest"
            ]
        }
    }
}

Para encontrar la raíz de su cliente:

p4 client -o your_workspace | grep "^Root:"

Nota: La ruta de montaje dentro del contenedor debe coincidir exactamente con la ruta raíz del cliente, ya que P4 rastrea los archivos por sus rutas absolutas.

Ejecute el servidor MCP en una VM usando el transporte HTTP, permitiendo que los clientes se conecten a través de la red.

Inicie el servidor en la VM:

P4PORT=ssl:perforce.example.com:1666 P4USER=your_username P4PASSWD=YOUR_TICKET ./p4-mcp-server --readonly --transport http --port 8000

Configure el cliente MCP:

Agregue lo siguiente a su mcp.json:

{
    "servers": {
        "perforce-p4-mcp": {
            "type": "http",
            "url": "http://<ip-or-hostname>:8000/mcp"
        }
    }
}

Nota: Asegúrese de que el firewall de la VM permita conexiones entrantes en el puerto elegido. Para uso en producción, considere colocar el servidor detrás de un proxy inverso con TLS.

Ejecute el servidor MCP en un contenedor Docker usando transporte HTTP y exponga el endpoint MCP a través de un puerto del host.

Inicie el contenedor:

docker run --rm -p 8000:8000 \
  -e P4PORT=ssl:perforce.example.com:1666 \
  -e P4USER=your_username \
  -e P4PASSWD=YOUR_TICKET \
  -e P4DAM_API_KEY=your_api_key \
  ghcr.io/perforce/p4mcp-server:latest \
  python3 -m p4mcp.main --readonly --transport http --port 8000

Configure el cliente MCP:

Agregue lo siguiente a su mcp.json:

{
  "servers": {
    "perforce-p4-mcp": {
      "type": "http",
      "url": "http://<ip-or-hostname>:8000/mcp"
    }
  }
}

Nota: Docker también admite el despliegue basado en HTTP. La imagen del contenedor usa transporte STDIO por defecto, por lo que el comando de inicio HTTP debe anular explícitamente el comando predeterminado. Si necesita operaciones de escritura, también monte las rutas de la raíz del cliente y del archivo de tickets en el contenedor.

Consulta la documentación de integración VCS del Asistente de IA de JetBrains para conocer los pasos de configuración detallados.

Consulta la documentación de MCP de Claude Code para obtener más información.

Usando uvx (sin necesidad de instalación):

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "uvx",
      "args": [
        "p4mcp-server",
        "--readonly", "--allow-usage"
      ],
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      }
    }
  }
}

Usando el binario precompilado:

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

Consulta la documentación de MCP de Cursor para obtener más información.

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

Consulta la documentación de MCP de Eclipse para obtener más información.

{
  "servers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

Consulta la documentación de MCP de Kiro para obtener más información.

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

Consulta la documentación de VS Code para obtener más información.

{
  "servers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

Consulta la documentación de MCP de Windsurf para obtener más información.

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace",
        "P4DAM_API_KEY": "your_api_key"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

Para evitar el acceso a todos los miembros de un grupo específico:

p4 property -a -n mcp.enabled -v false -g noaccessgroup

Puedes establecer múltiples restricciones de grupo de la misma manera.

Cuando un usuario pertenece a múltiples grupos con configuraciones conflictivas, la resolución de propiedades de P4 determina qué valor gana.

Gana el número de secuencia más alto (-s). Con números de secuencia iguales, gana el nombre de grupo alfabéticamente primero.

Ejemplo:

p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
p4 property -a -n mcp.enabled -v true  -s2 -g accessgroup

En este ejemplo, accessgroup gana porque -s2 es más alto que -s1.

Para bloquear a un usuario específico independientemente de la membresía de grupo:

p4 property -a -n mcp.enabled -v false -u noaccessuser

Al mismo número de secuencia, las propiedades a nivel de usuario tienen prioridad sobre las configuraciones a nivel de grupo y globales (el desempate de alcance de P4).

Ejemplo: Incluso si noaccessuser está en accessgroup (donde MCP está habilitado), la propiedad de usuario en la misma secuencia tiene prioridad y MCP queda deshabilitado.

Nota: Una propiedad de grupo con un valor de -s más alto puede anular una propiedad de usuario con un número de secuencia más bajo. Para garantizar que una propiedad a nivel de usuario siempre gane, asígnele un valor de -s alto o asegúrese de que ninguna propiedad de grupo use una secuencia más alta.

Restrinja qué herramientas están disponibles en todo el servidor usando mcp.toolsets.allowed. Solo las herramientas listadas estarán habilitadas; todas las demás quedan bloqueadas.

Herramientas disponibles: server, changelists, files, jobs, reviews, shelves, workspaces, streams

Permitir solo changelists y archivos:

p4 property -a -n mcp.toolsets.allowed -v changelists,files

Elimine la lista de permitidos para restaurar todas las herramientas:

p4 property -d -n mcp.toolsets.allowed

Deshabilite todas las operaciones de escritura (herramientas de modificación) mientras mantiene disponibles las operaciones de lectura (herramientas de consulta):

p4 property -a -n mcp.toolsets.write -v false

Rehabilite las escrituras:

p4 property -a -n mcp.toolsets.write -v true

Cuando write=false, todas las herramientas de modify_* están bloqueadas, pero todas las herramientas de query_* continúan funcionando.

Habilite o deshabilite herramientas individuales para un grupo específico.

Deshabilite una herramienta para un grupo específico:

p4 property -a -n mcp.toolset.changelists.enabled -v false -g reviewers

Los usuarios en reviewers están bloqueados de los changelists. Los usuarios en otros grupos (sin configuración explícita) conservan el acceso predeterminado.

Para restringir una herramienta a un solo grupo, deshabilítela para cada otro grupo que no deba tener acceso:

p4 property -a -n mcp.toolset.files.enabled -v false -g reviewers
p4 property -a -n mcp.toolset.files.enabled -v false -g interns
# Only groups without an explicit "false" retain default access to files

Nota: Todas las herramientas están habilitadas por defecto. Establecer enabled=true para un grupo es redundante a menos que esté anulando explícitamente una configuración previa de false. Al mismo número de secuencia, una propiedad de grupo anula una propiedad global (el desempate de alcance de P4), por lo que un enabled=true de grupo puede anular un enabled=false global. Para garantizar que una configuración global no pueda ser anulada, asígnele un valor de -s alto. Para aislar una herramienta a grupos específicos, deshabilítela para los grupos que desee bloquear.

Controle el acceso de escritura para cada herramienta a nivel de grupo.

Deshabilite las escrituras para una herramienta específica por grupo:

p4 property -a -n mcp.toolset.workspaces.write -v false -g reviewers

Esto bloquea modify_workspaces para el grupo mientras query_workspaces permanece accesible.

Restrinja un grupo a herramientas específicas dentro de un conjunto de herramientas usando mcp.toolset.<name>.tools.

Permita solo query_files (bloquee modify_files) para desarrolladores:

p4 property -a -n mcp.toolset.files.tools -v query_files -g developers

Permita tanto consulta como modificación para líderes:

p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads

Las anulaciones específicas de herramientas pueden restringir el acceso incluso cuando las escrituras están habilitadas:

p4 property -a -n mcp.toolsets.write -v true
p4 property -a -n mcp.toolset.files.tools -v query_files -g developers
# Result: modify_files is BLOCKED — tool list restricts

Nota: Las anulaciones específicas de herramientas no pueden eludir las restricciones de escritura. El servidor verifica los permisos de escritura antes de evaluar las listas de herramientas. Si write=false está establecido en cualquier nivel, las herramientas de escritura están bloqueadas independientemente de la lista de herramientas.

Cuando un usuario pertenece a múltiples grupos con configuraciones conflictivas, P4 resuelve cada propiedad a un solo valor. El servidor MCP no realiza su propia lógica multi-grupo — usa el valor que P4 devuelva.

Las reglas de resolución de P4 para un nombre de propiedad dado:

1. El -s más alto (número de secuencia) gana. Esta es la clave de ordenamiento principal.
2. Al mismo número de secuencia: alcance de usuario > alcance de grupo > alcance global.
3. Entre grupos en la misma secuencia: el nombre de grupo alfabéticamente primero gana.

P4 no compara valores. Elige la entrada ganadora por posición, no por contenido.

Ejemplo — grupos en la misma secuencia (predeterminado):

p4 property -a -n mcp.toolset.files.enabled -v true -g developers
p4 property -a -n mcp.toolset.files.enabled -v false -g leads
# User in both groups → resolved value is "true"
# Reason: "developers" < "leads" alphabetically, so developers wins

Intercambiar los valores daría false — developers aún gana independientemente del valor.

Ejemplo — solo un grupo tiene una configuración:

p4 property -a -n mcp.toolset.files.enabled -v false -g leads
# developers has no setting
# User in developers + leads → resolved value is "false"
# Reason: leads is the only group with a value, so it wins

Ejemplo — acceso de escritura:

p4 property -a -n mcp.toolset.files.write -v false -g developers
p4 property -a -n mcp.toolset.files.write -v true -g leads
# User in both groups → resolved value is "false"
# Reason: "developers" < "leads" alphabetically, not because false is "more restrictive"

Ejemplo — listas de herramientas (sin unión):

p4 property -a -n mcp.toolset.reviews.tools -v query_reviews -g developers
p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads
# User in both groups → resolved value is "query_reviews"
# Reason: "developers" wins alphabetically. P4 returns one value, not a union.

Ejemplo — usando -s para controlar qué grupo gana:

p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
p4 property -a -n mcp.enabled -v true  -s2 -g accessgroup
# accessgroup wins because -s2 > -s1 (highest sequence wins)

Consejo: Para obtener resultados predecibles con múltiples grupos, use siempre valores explícitos de -s en lugar de depender del orden alfabético de los nombres de grupo.

Deshabilite una sola herramienta para todos los usuarios sin afectar a otras:

p4 property -a -n mcp.toolset.reviews.enabled -v false

Esto bloquea tanto query_reviews como modify_reviews para todos los usuarios. Otras herramientas no se ven afectadas.

Restrinja un grupo específico a solo lectura sin afectar a otros grupos:

p4 property -a -n mcp.toolsets.write -v false -g problematic_group

Los usuarios en otros grupos conservan acceso completo de escritura. Si un usuario pertenece tanto al grupo restringido como a un grupo no restringido, la resolución de propiedades de P4 determina el resultado — típicamente el nombre de grupo alfabéticamente primero gana en números de secuencia iguales. Use valores explícitos de -s para resultados predecibles.

• Acciones:
  • server_info - Obtener versión de P4, tiempo de actividad y configuración
  • current_user - Obtener información del usuario actual y permisos
• Casos de uso - Diagnóstico del servidor, verificación de usuario, prueba de conexión

• Acciones:
  • list - Listar todos los espacios de trabajo (opcionalmente filtrados por usuario)
  • get - Obtener una especificación detallada del espacio de trabajo
  • type - Verificar tipo y configuración del espacio de trabajo
  • status - Verificar estado de sincronización del espacio de trabajo
• Parámetros: workspace_name, user, max_results
• Casos de uso: Descubrimiento de espacios de trabajo, revisión de configuración, verificación de estado

• Acciones:
  • get - Obtener información detallada del changelist (archivos, descripción, trabajos)
  • list - Listar changelists con filtros (estado, usuario, espacio de trabajo)
• Parámetros: changelist_id, status (pendiente/enviado), workspace_name, max_results
• Casos de uso: Revisión de código, seguimiento de historial, análisis de changelists

• Acciones:
  • content - Obtener contenido del archivo en una revisión específica
  • history - Obtener historial de revisiones del archivo y registros de integración
  • info - Obtener detalles básicos del archivo (tipo, tamaño, permisos)
  • metadata - Obtener metadatos del archivo (atributos, tamaño de archivo, etc.)
  • diff - Comparar versiones de archivos (depot a depot o mixto)
  • annotations - Obtener anotaciones del archivo con información de blame
  • search - Buscar archivos por patrón de nombre (coincidencia con comodines)
  • grep - Buscar archivos por patrón de contenido (búsqueda de texto)
• Parámetros: file_path, file2 (para diff), pattern (para búsqueda/grep), case_insensitive (para grep), max_results, diff2 (booleano), ranges (para contenido)
  • ranges - Lista opcional de pares de líneas de [start, end], basados en 1 e inclusivos (por ejemplo, [[10, 20], [50, 60]]). Se aplica solo a la acción de content. Cuando se establece, la respuesta devuelve un array de chunks con una entrada por rango en lugar del archivo completo.
• Casos de uso: Análisis de código, comparación de archivos, seguimiento de historial, análisis de blame, descubrimiento de archivos, búsqueda de contenido, recuperación de rangos de líneas específicos de archivos grandes

• Acciones:
  • list_jobs - Listar trabajos asociados a un changelist
  • get_job - Obtener información detallada del trabajo y su estado
• Parámetros: changelist_id, job_id, max_results
• Casos de uso: Seguimiento de defectos, trazabilidad de requisitos, gestión de proyectos

• Acciones:
  • list - Listar todas las revisiones con filtrado opcional
  • dashboard - Obtener el panel de revisiones del usuario actual (mis revisiones, requiere atención)
  • get - Obtener información detallada de la revisión
  • transitions - Obtener transiciones de estado disponibles para una revisión
  • files_readby - Obtener estado de lectura de archivos por usuario
  • files - Obtener archivos en una revisión (con rango de versiones opcional)
  • activity - Obtener historial de actividad de la revisión
  • comments - Obtener comentarios sobre una revisión
• Parámetros:
  • review_id - ID de revisión (requerido para get, transitions, files_readby, files, comments, activity)
  • review_fields - Campos separados por comas a devolver (ej., "id,description,author,state")
  • comments_fields - Campos para comentarios (predeterminado: "id,body,user,time")
  • up_voters - Lista de votantes positivos para transiciones
  • from_version, to_version - Rango de versiones para la acción de archivos
  • max_results - Resultados máximos (predeterminado: 10)
• Casos de uso: Descubrimiento de revisiones de código, seguimiento de estado de revisiones, recuperación de comentarios, monitoreo de actividad de revisiones

• Acciones:
  • list - Listar streams con filtros opcionales (patrón de ruta, propietario, tipo)
  • get - Obtener una especificación detallada del stream
  • children - Obtener streams secundarios de un stream dado
  • parent - Obtener el stream principal
  • graph - Obtener el gráfico completo del stream (principal + secundarios)
  • integration_status - Obtener estado de integración entre stream y principal (p4 istat)
  • get_workspace - Obtener una especificación de espacio de trabajo vinculado a un stream
  • list_workspaces - Listar espacios de trabajo vinculados a un stream
  • validate_file - Validar rutas de archivo contra la vista de un stream
  • validate_submit - Validar archivos abiertos para enviar en un espacio de trabajo de stream
  • check_resolve - Verificar conflictos pendientes de especificación de stream
  • interchanges - Listar changelists pendientes de integración entre streams
• Parámetros:
  • stream_name - Ruta de depósito del stream (requerida para get, children, parent, graph, check_resolve, interchanges)
  • stream_path - Patrón(es) de ruta para listar (ej., ["//depot/..."])
  • filter - Expresión de filtro para listar (ej., "Owner=alice&Type=development")
  • fields - Campos a devolver para listar (ej., ["Stream", "Owner", "Type"])
  • workspace - Nombre del espacio de trabajo para get_workspace, validate_file, validate_submit
  • file_paths - Rutas de archivo para validate_file
  • view_without_edit - Ver especificación de stream bloqueada sin abrir para edición
  • at_change - Recuperar especificación histórica de stream en un número de changelist
  • both_directions - Mostrar estado de integración en ambas direcciones
  • force_refresh - Forzar actualización de caché de istat
  • reverse, long_output, limit - Opciones para interchanges
  • unloaded, all_streams, viewmatch - Filtros para listar
  • max_results - Resultados máximos
• Casos de uso: Exploración de jerarquía de streams, seguimiento de estado de integración, validación de espacios de trabajo, verificación de compatibilidad de vistas

• Parámetros: search_term, project_ids, repository_ids, path, tag, file_extension, user, all_revisions, max_results, offset
• Casos de uso: Descubrimiento de activos, filtrado por proyecto/repositorio/etiqueta/extensión, navegación de contenido P4 DAM. Úselo cuando aún no tenga una ruta de depósito.

• Parámetros: depot_path (requerido), identifier, project_id, repository_id, include
• Casos de uso: Obtener información de confirmación, paquetes de activos, enlaces web, atributos personalizados y coincidencias de proyecto/repositorio para un activo conocido. Úselo después de query_p4dam_assets para obtener detalles completos de un archivo específico.

• Parámetros: search_term, limit, offset
• Casos de uso: Descubrir proyectos disponibles antes de crear un paquete de activos o revisión de archivos, resolver IDs de proyecto para otras llamadas.

• Parámetros: project_id (requerido), search_term, limit, offset
• Casos de uso: Encontrar el tipo de repositorio (helix_stream o helix_classic) y linked_streams — necesario para proporcionar stream_path o descubrir ramas al crear paquetes de activos o revisiones de archivos.

• Parámetros: project_id (requerido), repository_id (requerido), limit, offset
• Casos de uso: Encontrar el ID de rama requerido al crear un paquete de activos o revisión de archivos en un repositorio Helix Classic.

• Parámetros: url (requerido — thumbnail_url, preview_url, sprite_url o file_url de resultados de activos)
• Casos de uso: Renderizar miniaturas, vistas previas y hojas de sprites para activos de imagen directamente en el cliente. Para archivos que no son imágenes, devuelve tipo MIME y tamaño en lugar de contenido de imagen. Pase URLs de resultados de query_p4dam_assets o query_p4dam_asset — solo thumbnail_url, preview_url y sprite_url están presentes para archivos de imagen.

• Parámetros: project_id (requerido), depot_path, include, limit, offset
• Casos de uso: Navegar revisiones activas en un proyecto, filtrar por ruta de depósito, descubrir UUIDs de revisión para consultas de detalle.

• Parámetros: project_id (requerido), review_id (requerido)
• Casos de uso: Recuperar detalle completo de la revisión — estado, view_paths, asset_bundle, creador y download_url para revisiones de paquetes.

• Parámetros: include, limit, offset
• Casos de uso: Descubrir flujos de trabajo disponibles y sus estados. Pase include=['states'] para obtener todos los estados en una sola llamada — use el estado short_name como parámetro state en operaciones de revisión de archivos.

• Parámetros: workflow_id (requerido), include
• Casos de uso: Inspeccionar los estados de un flujo de trabajo (kind: open/review/done, color, position) y reglas de transición.

• Parámetros: workflow_id (requerido), limit, offset
• Casos de uso: Listar todos los estados con short_name, kind, color y position. El short_name es el valor a pasar como state al crear o actualizar una revisión de archivos.

• Parámetros: project_id (requerido)
• Casos de uso: Descubrir atributos personalizados disponibles antes de establecer valores — devuelve el UUID, nombre, tipo (text, single-select, multi-select, checkbox) y available_values de cada plantilla para tipos de selección. Pase el UUID a update_p4dam_asset_custom_attributes.

• Acciones - create, update, delete, switch
• Parámetros - name, specs (objeto WorkspaceSpec con View, Root, Options, etc.)
• Requiere - Modo solo lectura deshabilitado, permisos apropiados
• Casos de uso - Configuración de entorno, mantenimiento de espacios de trabajo, cambio de rama

• Acciones - create, update, submit, delete, move_files
• Parámetros - changelist_id, description, file_paths
• Seguridad - Verificaciones de propiedad, indicación interactiva PROCEED/CANCEL para operaciones de eliminación con detalles de elementos
• Casos de uso - Envío de código, organización de trabajo, agrupación de archivos

• Acciones - shelve, unshelve, update, delete, unshelve_to_changelist
• Parámetros - changelist_id, file_paths, target_changelist, force
• Casos de uso - Almacenamiento temporal, compartición de código, respaldo antes de experimentos

• Acciones - link_job, unlink_job
• Parámetros - changelist_id, job_id
• Casos de uso - Integración con seguimiento de defectos, vinculación de requisitos

• Acciones:
  • create - Crear una nueva revisión a partir de un changelist
  • refresh_projects - Actualizar las asociaciones de proyecto
  • vote - Votar en una revisión (a favor, en contra, limpiar)
  • transition - Cambiar el estado de la revisión (needsRevision, needsReview, approved, committed, rejected, archived)
  • append_participants - Añadir revisores/grupos a una revisión
  • replace_participants - Reemplazar todos los participantes
  • delete_participants - Eliminar participantes de una revisión
  • add_comment - Añadir un comentario a una revisión
  • reply_comment - Responder a un comentario existente
  • edit_comment - Editar el cuerpo y/o el estado de tarea de un comentario existente
  • append_change - Añadir un changelist a una revisión existente
  • replace_with_change - Reemplazar el contenido de la revisión con un changelist
  • join - Unirse a una revisión como participante
  • leave - Abandonar una revisión
  • archive_inactive - Archivar revisiones inactivas
  • mark_comment_read / mark_comment_unread - Marcar el estado de lectura de un comentario individual
  • mark_all_comments_read / mark_all_comments_unread - Marcar el estado de lectura de todos los comentarios
  • update_author - Cambiar el autor de la revisión
  • update_description - Actualizar la descripción de la revisión
  • obliterate - Eliminar permanentemente una revisión
• Parámetros:
  • review_id - ID de revisión (requerido para la mayoría de las acciones)
  • change_id - ID de changelist (requerido para crear, añadir_cambio, reemplazar_con_cambio)
  • description - Descripción de la revisión
  • reviewers, required_reviewers - Listas de nombres de usuario de revisores
  • reviewer_groups - Grupos de revisores con requisitos
  • vote_value - Valor del voto: up, down, clear
  • version - Versión de la revisión para votar
  • transition - Estado objetivo: needsRevision, needsReview, approved, committed, approved:commit, rejected, archived
  • jobs, fix_status, cleanup - Opciones de vinculación de trabajos y limpieza para transiciones
  • users, groups - Datos estructurados de participantes para añadir/reemplazar/eliminar
  • body - Texto del cuerpo del comentario
  • task_state - Estado de tarea del comentario: open, comment, addressed, verified. add_comment acepta solo open y comment; addressed y verified son accesibles mediante edit_comment.
  • notify - Modo de notificación: immediate, delayed
  • comment_id - ID de comentario para respuestas, ediciones o marcar como leído/no leído
  • context - Contexto del comentario (archivo, números de línea, contenido, versión)
  • not_updated_since, max_reviews - Filtros para archivar_inactivos
  • new_author, new_description - Valores para acciones de actualización
• Casos de uso: Flujo de trabajo de revisión de código, gestión del estado de revisiones, comentarios colaborativos, gestión de participantes, limpieza de revisiones

• Acciones:
  • create - Crear un nuevo stream (mainline, development, release, task, virtual, etc.)
  • update - Actualizar propiedades del stream (nombre, descripción, opciones, rutas, parent_view)
  • delete - Eliminar un stream
  • edit_spec - Abrir la especificación del stream para edición (p4 stream edit)
  • resolve_spec - Resolver conflictos de especificación del stream
  • revert_spec - Revertir ediciones de la especificación del stream
  • shelve_spec - Hacer shelving de ediciones de la especificación del stream en un changelist numerado
  • unshelve_spec - Deshacer shelving de ediciones de la especificación del stream
  • copy - Copiar cambios entre streams padre e hijo
  • merge - Fusionar cambios entre streams padre e hijo
  • integrate - Integrar cambios con opciones avanzadas
  • populate - Poblar un nuevo stream con archivos (branch)
  • switch - Cambiar un espacio de trabajo a un stream diferente
  • create_workspace - Crear un nuevo espacio de trabajo vinculado a un stream
• Parámetros:
  • stream_name - Ruta del depósito del stream (requerida para crear, actualizar, eliminar, editar_especificación, resolver_especificación, revertir_especificación, cambiar)
  • stream_type - Tipo de stream para crear: mainline, development, sparsedev, release, sparserel, task, virtual
  • parent - Stream padre para creación que no sea mainline
  • name, description - Nombre visible y descripción del stream
  • options - Opciones del stream: allsubmit/ownersubmit, unlocked/locked, toparent/notoparent, fromparent/nofromparent, mergedown/mergeany
  • parent_view - Tratamiento de la vista padre: inherit o noinherit
  • paths, remapped, ignored - Mapeos de vista del stream
  • changelist - Changelist para operaciones de edición de especificación o propagación
  • resolve_mode - Modo de resolución para resolver_especificación: auto, accept_theirs, accept_yours
  • parent_stream - Anular padre para propagación (bandera -P)
  • branch - Especificación de branch para integrar/poblar (bandera -b)
  • file_paths - Rutas de archivo para propagación
  • preview - Solo vista previa, sin cambios (bandera -n)
  • force - Forzar operación (bandera -f)
  • reverse - Invertir dirección (bandera -r)
  • max_files - Limitar archivos procesados (bandera -m)
  • quiet - Suprimir mensajes informativos (bandera -q)
  • output_base - Mostrar revisión base con resolución programada (bandera -Ob para merge/integrate) o listar archivos creados (bandera -o para populate)
  • virtual - Copiar usando stream virtual (bandera -v, solo copia)
  • schedule_branch_resolve - Programar resoluciones de branch en lugar de branch automático (bandera -Rb, solo integrate)
  • integrate_around_deleted - Integrar omitiendo revisiones eliminadas (bandera -Di, solo integrate)
  • skip_cherry_picked - Omitir revisiones cherry-picked ya integradas (bandera -Rs, solo integrate)
  • source_path, target_path - Rutas de origen y destino para populate
  • workspace - Nombre del espacio de trabajo para cambiar
  • workspace_name, root, host, alt_roots - Parámetros de creación del espacio de trabajo
• Seguridad: Validación de existencia del stream, detección de streams bloqueados, advertencias de espacios de trabajo vinculados, comprobaciones de archivos abiertos para cambios que afectan la vista
• Casos de uso: Creación y gestión de streams, propagación de branches (merge/copy/integrate), resolución de conflictos de especificación, aprovisionamiento de espacios de trabajo

• Parámetros: depot_path (requerido, debe terminar en .p4bundle), project (requerido), repository (requerido), view_paths (requerido), stream_path, helix_classic_branch, description, hero_file_path
• Casos de uso: Crear una colección nombrada y con alcance de archivos de depósito para revisión. Proporcione stream_path para repositorios Helix Stream, helix_classic_branch para repositorios Helix Classic.

• Parámetros: bundle_id (requerido), description, view_paths, hero_file_path
• Casos de uso: Cambiar la descripción de un paquete, ajustar su alcance de archivos (view_paths) o actualizar la imagen de portada. depot_path es inmutable después de la creación.

• Parámetros: bundle_id (requerido)
• Casos de uso: Eliminar un paquete de activos que ya no se necesita. Irreversible.

• Parámetros: view_paths (requerido), workspace_root (requerido), client_name, bundle_id, stream_path
• Casos de uso: Descargar los archivos con alcance de un paquete de activos mediante p4 sync. Crea o reutiliza un cliente P4 nombrado: las sincronizaciones posteriores son incrementales. Use stream_path para repositorios Helix Stream (aplica LimitView, requiere Perforce 2025.2+).

• Parámetros: project_id (requerido), name (requerido), depot_path (requerido), view_paths (requerido), state (requerido), repository, helix_classic_branch, asset_bundle, hero_file_path, description, position, base_commit_id, head_commit_id
• Casos de uso: Abrir una revisión para un solo activo o un paquete de activos (.p4bundle). Para revisiones de paquetes, asset_bundle se detecta automáticamente desde depot_path cuando se omite.

• Parámetros: project_id (requerido), review_id (requerido), state, name, view_paths, hero_file_path, description, position
• Casos de uso: Transicionar una revisión a un nuevo estado de flujo de trabajo, actualizar su nombre o descripción, ajustar el alcance de la vista. Las transiciones de estado deben estar permitidas por el flujo de trabajo del proyecto para el usuario actual.

• Parámetros: project_id (requerido), review_id (requerido)
• Casos de uso: Eliminar una revisión que ya no se necesita. Irreversible. La API devuelve el objeto de revisión eliminado en caso de éxito.

• Parámetros: paths (obligatorio — lista de {path, identifier?}), create, delete, delete_auto, propagatable, identifier
• Casos de uso: Etiquetar uno o varios activos en una sola llamada. Admite archivos individuales, revisiones específicas y rutas de carpetas recursivas (//depot/folder/...). create añade etiquetas de usuario, delete elimina etiquetas de usuario, delete_auto elimina etiquetas generadas automáticamente. Establezca propagatable=true para aplicar etiquetas a la última revisión y a todas las revisiones futuras.

• Parámetros: type (obligatorio), content (obligatorio), project, repository, file_review, commit, path, stream_path, helix_classic_branch, comment
• Casos de uso: Comentar en una revisión de archivo de paquete de activos (file_review), un archivo específico dentro de una revisión (file_review_file), un archivo confirmado o paquete de activos sin revisión (commit_file), o responder a un comentario existente (comment). Los parámetros obligatorios dependen del tipo — consulte la descripción de type.

• Parámetros: paths (obligatorio — lista de {path, identifier?}), create (lista de {uuid, value}), delete (lista de UUIDs de atributos a eliminar), propagatable
• Casos de uso: Establecer o limpiar metadatos personalizados en uno o más activos. Descubra primero los atributos disponibles y sus UUIDs con query_p4dam_custom_attribute_templates. value es una cadena para tipos text/single-select/checkbox y una lista de cadenas para multi-select.

• Parámetros: depot_path (obligatorio), commit_id (obligatorio)
• Casos de uso: Volver a activar la generación de vista previa cuando falta o está desactualizada. commit_id es el número de changeset de los resultados de query_p4dam_asset.

Síntomas: El sistema operativo no puede encontrar o ejecutar el binario; el error incluye ENOENT o "No such file or directory".
Soluciones:

1. Verifique la ruta: Asegúrese de que el campo command use la ruta absoluta correcta para su sistema operativo:
   • macOS/Linux: /absolute/path/to/p4-mcp-server
   • Windows: C:\absolute\path\to\p4-mcp-server.exe
2. Asegúrese de que el binario exista y sea ejecutable:
   • macOS/Linux:

     ls -l /absolute/path/to/p4-mcp-server && chmod +x /absolute/path/to/p4-mcp-server
     

   • Windows:

     dir C:\absolute\path\to\p4-mcp-server.exe
     

3. En Windows, asegúrese de que el binario no esté bloqueado:
   • Haga clic derecho en el archivo .exe, seleccione Propiedades y, si está presente, haga clic en Desbloquear.

Síntomas: No se puede conectar al servidor P4
Soluciones:

1. Verifique la variable de entorno P4PORT: echo $P4PORT (macOS) o echo $env:P4PORT (Windows)
2. Pruebe la conexión directa: p4 info
3. Verifique la disponibilidad del servidor: ping perforce.example.com
4. Verifique el puerto y el protocolo (prefijo ssl: para conexiones SSL).

Síntomas: Errores de confianza SSL al conectarse al servidor P4 Soluciones:

1. Confíe en el servidor: p4 trust -f -y
2. Verifique el estado de confianza: p4 trust -l
3. Para problemas persistentes, verifique la configuración SSL.

Síntomas: Errores CERTIFICATE_VERIFY_FAILED al usar herramientas de revisión Soluciones:

1. Almacén de confianza del sistema: Por defecto, el servidor usa el almacén de confianza del sistema operativo a través de truststore. Asegúrese de que su CA corporativa esté instalada en el almacén de certificados del sistema operativo.
2. Paquete de CA personalizado: Para usar un certificado CA personalizado, debe primero establecer P4MCP_TLS_CA_MODE=certifi (para deshabilitar truststore), luego proporcionar la ruta de CA a través de --ca-bundle /path/to/ca.pem o P4MCP_CA_BUNDLE. En el modo system predeterminado, truststore anula los paquetes de CA personalizados y se ignoran silenciosamente.
3. Deshabilitar la verificación: Use --ssl-no-verify o establezca P4MCP_SSL_VERIFY=false (no recomendado para producción). Esto funciona en ambos modos TLS.

Nota: Estos ajustes SSL solo se aplican cuando la URL de Swarm usa HTTPS. Si Swarm está configurado con una URL http://, la verificación SSL no se realiza y estos ajustes no tienen efecto.

Síntomas: Fallos de autenticación
Soluciones:

1. Inicie sesión en P4: p4 login -a
2. Verifique el estado de inicio de sesión: p4 login -s
3. Verifique que el usuario exista: p4 users -m 1 your_username
4. Para problemas persistentes, verifique la contraseña o use autenticación basada en tickets.

Síntomas: Fallos de inicio de sesión
Soluciones:

1. Restablezca la contraseña a través de un administrador de P4.
2. Use autenticación basada en tickets: p4 login -a
3. Verifique que el nombre de usuario sea correcto: p4 info

Síntomas: Errores de espacio de trabajo no encontrado
Soluciones:

1. Liste los espacios de trabajo disponibles: p4 clients
2. Verifique la variable de entorno P4CLIENT.
3. Cree un espacio de trabajo si es necesario: p4 client workspace_name
4. Verifique la propiedad del espacio de trabajo: p4 client -o workspace_name

Síntomas: Los archivos están fuera del mapeo del espacio de trabajo
Soluciones:

1. Verifique la vista de cliente: p4 client -o workspace_name
2. Actualice el mapeo del espacio de trabajo para incluir las rutas requeridas.
3. Use p4 where file_path para verificar el mapeo.

Síntomas: Permisos insuficientes para operaciones
Soluciones:

1. Verifique la propiedad del archivo: p4 opened file_path
2. Verifique los permisos del usuario: p4 protects file_path
3. Asegure la membresía adecuada del grupo.
4. Para operaciones de administración, verifique los permisos de administrador.

Síntomas: Conflictos de bloqueo exclusivo
Soluciones:

1. Verifique quién tiene el archivo abierto: p4 opened file_path
2. Contacte al usuario para resolver conflictos.
3. El administrador puede forzar operaciones si es necesario.

Síntomas: Tiempos de respuesta largos
Soluciones:

1. Use el parámetro max_results para limitar el tamaño de la consulta.
2. Use rutas de archivo específicas en lugar de comodines.
3. Verifique la conectividad de red con P4.
4. Monitoree el rendimiento del servidor.

Síntomas: Alto uso de memoria
Soluciones:

1. Reduzca max_results para consultas grandes.
2. Procese archivos en lotes.
3. Reinicie el servidor MCP periódicamente para sesiones de larga duración.

Síntomas: Conflicto con herramientas integradas u otras herramientas MCP
Soluciones:

1. Deshabilite cualquier herramienta integrada o en conflicto del servidor MCP en su entorno o configuración.
2. Asegúrese de que las herramientas del servidor P4 MCP estén correctamente registradas y habilitadas.
3. Reinicie el servidor MCP después de aplicar cambios de configuración para cargar las herramientas correctas.

Síntomas: Contexto no válido o historial de sesión desactualizado
Soluciones:

1. Proporcione un contexto relacionado con P4 al escribir indicaciones.
2. Inicie una nueva sesión si la sesión existente es antigua o contiene un historial de indicaciones conflictivo.