P4 MCP Server

Se você tiver o uv instalado, pode executar o P4 MCP Server diretamente sem nenhuma instalação manual:

# Run the server
uvx p4mcp-server

# Check version
uvx p4mcp-server --version

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

Isso busca e executa automaticamente a versão mais recente do PyPI. Não é necessária configuração de ambiente virtual Python ou gerenciamento de dependências.

Requisitos:

• uv instalado no seu sistema
• Python 3.11+ (o uv cuidará disso automaticamente)

Baixe o binário apropriado para o seu sistema operacional:

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

Extraia e use o executável diretamente. Nenhuma instalação do Python é necessária.

# 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+ (com Tkinter)

Compilar:

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

Saída:

• macOS e Linux: p4-mcp-server-<versão>.tgz
• Windows: p4-mcp-server-<versão>.zip

Execute o P4 MCP Server diretamente na sua máquina usando o transporte STDIO padrão.

Adicione o seguinte ao seu 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 exemplo mostra valores explícitos de env. Se P4CONFIG estiver definido, você pode omiti-los e usar o exemplo de configuração genérica na seção MCP client configuration.

Execute o P4 MCP Server a partir de um contêiner Docker com transporte STDIO, permitindo que clientes MCP gerenciem o ciclo de vida do contêiner.

Nota: A execução baseada em Docker é atualmente suportada apenas em macOS e Linux.

Pré-requisitos

• Docker instalado e em execução
• Credenciais P4 válidas e acesso a um servidor P4

Baixar a imagem Docker

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

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

Configurar o Cliente MCP

Adicione o seguinte ao seu 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"
            ]
        }
    }
}

Opções de Configuração

Autenticação

Usando tickets P4:

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

Nota: Use o caminho completo para o seu arquivo de tickets (não ~). Após executar p4 login, reinicie o servidor MCP para aplicar o novo ticket.

Nota: Por padrão, o contêiner inicia como root, copia o arquivo de tickets montado por bind para um local legível pelo mcpuser não-root e, em seguida, reduz privilégios (via gosu) para que o servidor execute como mcpuser. Essa cópia automática permite que um arquivo de tickets com restrição de proprietário (0600) pertencente a um uid estrangeiro funcione em runtimes que preservam a propriedade do host (Docker/podman Linux nativo). Uma montagem por bind :ro do ticket é suportada — o arquivo é copiado, não modificado no local (isso é distinto de um sistema de arquivos raiz somente leitura; veja abaixo). Observe que a cópia automática é executada apenas quando o contêiner inicia como root (o padrão); forçar um uid não-root ou um sistema de arquivos raiz somente leitura altera esse comportamento, conforme descrito abaixo.

Kubernetes / perfis restritos (com aplicação de não-root): a imagem intencionalmente inicia como root e reduz para mcpuser (uid 1000) via gosu, então o servidor sempre executa como não-root — ambos os caminhos são suportados. Para runAsNonRoot / PodSecurity restrito / SCC restrito do OpenShift, defina securityContext.runAsUser: 1000 (e fsGroup: 1000 ao montar o ticket). Nesse modo, a cópia do ticket exclusiva do root no entrypoint é ignorada, então o ticket montado já deve ser legível pelo uid 1000 (montagem com correspondência de proprietário, -e P4PASSWD="your_ticket_content" ou podman -v <host>:/home/mcpuser/.p4tickets:U).

Sistema de arquivos raiz somente leitura (--read-only / readOnlyRootFilesystem): forneça um /home/mcpuser gravável/tmpfs (ex.: --tmpfs /home/mcpuser) para que a cópia do ticket possa ser gravada; caso contrário, a cópia do ticket falha e o P4 relatará um erro de autenticação normal.

Usando uma senha:

-e P4PASSWD="your_password"

Restrições de Host do Workspace

⚠️ Importante: Os contêineres Docker têm seu próprio hostname, que difere da sua máquina local. Se o seu workspace P4 estiver restrito a um host específico, operações como sync falharão.

Para resolver isso, defina o hostname do contêiner para corresponder à restrição de host do seu workspace:

--hostname your-hostname

Para descobrir o nome do host do seu workspace:

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

Montagem do Client Root para Operações de Escrita

⚠️ Importante: Por padrão, o contêiner Docker não pode acessar os arquivos do seu workspace local. Para operações de escrita como sync, submit ou reconcile, você deve montar o diretório client root no contêiner no mesmo caminho.

Adicione uma montagem de volume para o seu client root:

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

Exemplo de configuração com client root montado:

{
    "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 descobrir o seu client root:

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

Nota: O caminho de montagem dentro do contêiner deve corresponder exatamente ao caminho do client root, pois o P4 rastreia arquivos por seus caminhos absolutos.

Execute o servidor MCP em uma VM usando o transporte HTTP, permitindo que clientes se conectem pela rede.

Inicie o servidor na VM:

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

Configure o cliente MCP:

Adicione o seguinte ao seu mcp.json:

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

Nota: Certifique-se de que o firewall da VM permita conexões de entrada na porta escolhida. Para uso em produção, considere colocar o servidor atrás de um proxy reverso com TLS.

Execute o servidor MCP em um contêiner Docker usando transporte HTTP e exponha o endpoint MCP em uma porta do host.

Inicie o contêiner:

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 o cliente MCP:

Adicione o seguinte ao seu mcp.json:

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

Nota: O Docker também suporta implantação baseada em HTTP. A imagem do contêiner usa transporte STDIO por padrão, então o comando de inicialização HTTP deve substituir explicitamente o comando padrão. Se você precisar de operações de escrita, monte também os caminhos do client root e do arquivo de tickets no contêiner.

Consulte a documentação de integração VCS do JetBrains AI Assistant para etapas de configuração detalhadas.

Consulte a documentação de MCP do Claude Code para mais informações.

Usando uvx (sem necessidade de instalação):

{
  "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 binário pré-compilado:

{
  "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"
      ]
    }
  }
}

Consulte a documentação de MCP do Cursor para mais informações.

{
  "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"
      ]
    }
  }
}

Consulte a documentação de MCP do Eclipse para mais informações.

{
  "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"
      ]
    }
  }
}

Consulte a documentação de MCP do Kiro para mais informações.

{
  "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"
      ]
    }
  }
}

Consulte a documentação do VS Code para mais informações.

{
  "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"
      ]
    }
  }
}

Consulte a documentação de MCP do Windsurf para mais informações.

{
  "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 impedir o acesso de todos os membros de um grupo específico:

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

Você pode definir várias restrições de grupo da mesma maneira.

Quando um usuário pertence a vários grupos com configurações conflitantes, a resolução de propriedades do P4 determina qual valor vence.

O maior número de sequência (-s) vence. Em números de sequência iguais, o nome de grupo alfabeticamente primeiro vence.

Exemplo:

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

Neste exemplo, accessgroup vence porque -s2 é maior que -s1.

Para bloquear um usuário específico independentemente da associação ao grupo:

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

No mesmo número de sequência, propriedades de nível de usuário sobrescrevem configurações de grupo e globais (desempate de escopo do P4).

Exemplo: Mesmo se noaccessuser estiver em accessgroup (onde MCP está habilitado), a propriedade de usuário no mesmo número de sequência tem precedência e o MCP é desabilitado.

Nota: Uma propriedade de grupo com valor de -s maior pode sobrescrever uma propriedade de usuário com número de sequência menor. Para garantir que uma propriedade de nível de usuário sempre vença, atribua a ela um valor alto de -s ou garanta que nenhuma propriedade de grupo use uma sequência maior.

Restrinja quais toolsets estão disponíveis em todo o servidor usando mcp.toolsets.allowed. Apenas os toolsets listados serão habilitados; todos os demais serão bloqueados.

Toolsets disponíveis: server, changelists, files, jobs, reviews, shelves, workspaces, streams

Permitir apenas changelists e arquivos:

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

Remova a lista de permissões para restaurar todos os toolsets:

p4 property -d -n mcp.toolsets.allowed

Desabilite todas as operações de escrita (ferramentas de modificação) mantendo as operações de leitura (ferramentas de consulta) disponíveis:

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

Reabilite as escritas:

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

Quando write=false, todas as ferramentas modify_* são bloqueadas, mas todas as ferramentas query_* continuam funcionando.

Habilite ou desabilite toolsets individuais para um grupo específico.

Desabilite um toolset para um grupo específico:

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

Usuários em reviewers são bloqueados de changelists. Usuários em outros grupos (sem configuração explícita) mantêm o acesso padrão.

Para restringir um toolset a apenas um grupo, desabilite-o para todos os outros grupos que não devem ter acesso:

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: Todos os toolsets são habilitados por padrão. Definir enabled=true para um grupo é redundante, a menos que você esteja explicitamente sobrescrevendo uma configuração anterior de false. No mesmo número de sequência, uma propriedade de grupo sobrescreve uma propriedade global (desempate de escopo do P4), então um enabled=true de grupo pode sobrescrever um enabled=false global. Para garantir que uma configuração global não possa ser sobrescrita, atribua a ela um valor alto de -s. Para isolar um toolset a grupos específicos, desabilite-o para os grupos que você deseja bloquear.

Controle o acesso de escrita para cada toolset no nível de grupo.

Desabilite escritas para um toolset específico por grupo:

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

Isso bloqueia modify_workspaces para o grupo enquanto query_workspaces permanece acessível.

Restrinja um grupo a ferramentas específicas dentro de um toolset usando mcp.toolset.<name>.tools.

Permitir apenas query_files (bloquear modify_files) para desenvolvedores:

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

Permitir consulta e modificação para líderes:

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

Substituições específicas por ferramenta podem restringir o acesso mesmo quando as escritas estão 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: Substituições específicas por ferramenta não podem contornar restrições de escrita. O servidor verifica as permissões de escrita antes de avaliar as listas de ferramentas. Se write=false estiver definido em qualquer nível, as ferramentas de escrita são bloqueadas independentemente da lista de ferramentas.

Quando um usuário pertence a múltiplos grupos com configurações conflitantes, o P4 resolve cada propriedade para um único valor. O servidor MCP não executa sua própria lógica de múltiplos grupos — ele usa o valor que o P4 retorna.

Regras de resolução do P4 para um determinado nome de propriedade:

1. Maior -s (número de sequência) vence. Esta é a chave de ordenação primária.
2. No mesmo número de sequência: escopo de usuário > escopo de grupo > escopo global.
3. Entre grupos na mesma sequência: o nome do grupo em ordem alfabética primeiro vence.

O P4 não compara valores. Ele escolhe a entrada vencedora pela posição, não pelo conteúdo.

Exemplo — grupos na mesma sequência (padrão):

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

Trocar os valores daria false — developers ainda vence independentemente do valor.

Exemplo — apenas um grupo tem uma configuração:

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

Exemplo — acesso de escrita:

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"

Exemplo — listas de ferramentas (sem união):

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.

Exemplo — usando -s para controlar qual grupo vence:

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)

Dica: Para obter resultados previsíveis com múltiplos grupos, sempre use valores explícitos de -s em vez de depender da ordenação alfabética dos nomes de grupo.

Desabilite um único toolset para todos os usuários sem afetar os demais:

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

Isso bloqueia tanto query_reviews quanto modify_reviews para todos os usuários. Outros toolsets permanecem inalterados.

Restrinja um grupo específico a somente leitura sem afetar outros grupos:

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

Usuários em outros grupos mantêm acesso total de escrita. Se um usuário pertencer tanto ao grupo restrito quanto a um grupo não restrito, a resolução de propriedades do P4 determina o resultado — tipicamente o nome do grupo em ordem alfabética primeiro vence em números de sequência iguais. Use valores explícitos de -s para resultados previsíveis.

• Ações:
  • server_info - Obter versão do P4, tempo de atividade e configuração
  • current_user - Obter informações do usuário atual e permissões
• Casos de uso - Diagnóstico do servidor, verificação de usuário, teste de conexão

• Ações:
  • list - Listar todos os workspaces (opcionalmente filtrados por usuário)
  • get - Obter uma especificação detalhada do workspace
  • type - Verificar tipo e configuração do workspace
  • status - Verificar status de sincronização do workspace
• Parâmetros: workspace_name, user, max_results
• Casos de uso: Descoberta de workspaces, revisão de configuração, verificação de status

• Ações:
  • get - Obter informações detalhadas do changelist (arquivos, descrição, jobs)
  • list - Listar changelists com filtros (status, usuário, workspace)
• Parâmetros: changelist_id, status (pendente/enviado), workspace_name, max_results
• Casos de uso: Revisão de código, rastreamento de histórico, análise de changelists

• Ações:
  • content - Obter conteúdo do arquivo em uma revisão específica
  • history - Obter histórico de revisões do arquivo e registros de integração
  • info - Obter detalhes básicos do arquivo (tipo, tamanho, permissões)
  • metadata - Obter metadados do arquivo (atributos, tamanho do arquivo, etc.)
  • diff - Comparar versões de arquivo (depot-para-depot ou misto)
  • annotations - Obter anotações do arquivo com informações de blame
  • search - Pesquisar arquivos por padrão de nome (correspondência com curingas)
  • grep - Pesquisar arquivos por padrão de conteúdo (pesquisa de texto)
• Parâmetros: file_path, file2 (para diff), pattern (para pesquisa/grep), case_insensitive (para grep), max_results, diff2 (booleano), ranges (para conteúdo)
  • ranges - Lista opcional de pares de linhas [start, end], baseada em 1 e inclusiva (ex.: [[10, 20], [50, 60]]). Aplica-se apenas à ação content. Quando definido, a resposta retorna um array chunks com uma entrada por intervalo em vez do arquivo inteiro.
• Casos de uso: Análise de código, comparação de arquivos, rastreamento de histórico, análise de blame, descoberta de arquivos, pesquisa de conteúdo, recuperação de intervalos específicos de linhas de arquivos grandes

• Ações:
  • list_jobs - Listar jobs associados a um changelist
  • get_job - Obter informações detalhadas do job e status
• Parâmetros: changelist_id, job_id, max_results
• Casos de uso: Rastreamento de defeitos, rastreabilidade de requisitos, gerenciamento de projetos

• Ações:
  • list - Listar todas as revisões com filtragem opcional
  • dashboard - Obter o painel de revisões do usuário atual (minhas revisões, precisa de atenção)
  • get - Obter informações detalhadas da revisão
  • transitions - Obter transições de estado disponíveis para uma revisão
  • files_readby - Obter status de leitura de arquivos por usuários
  • files - Obter arquivos em uma revisão (com intervalo de versão opcional)
  • activity - Obter histórico de atividades da revisão
  • comments - Obter comentários em uma revisão
• Parâmetros:
  • review_id - ID da revisão (obrigatório para get, transitions, files_readby, files, comments, activity)
  • review_fields - Campos separados por vírgula para retornar (ex.: "id,description,author,state")
  • comments_fields - Campos para comentários (padrão: "id,body,user,time")
  • up_voters - Lista de votantes positivos para transições
  • from_version, to_version - Intervalo de versão para a ação de arquivos
  • max_results - Máximo de resultados (padrão: 10)
• Casos de uso: Descoberta de revisão de código, acompanhamento de status de revisão, recuperação de comentários, monitoramento de atividades de revisão

• Ações:
  • list - Listar streams com filtros opcionais (padrão de caminho, proprietário, tipo)
  • get - Obter uma especificação detalhada do stream
  • children - Obter streams filhos de um determinado stream
  • parent - Obter o stream pai
  • graph - Obter o grafo completo do stream (pai + filhos)
  • integration_status - Obter status de integração entre stream e pai (p4 istat)
  • get_workspace - Obter uma especificação de workspace vinculada a um stream
  • list_workspaces - Listar workspaces vinculados a um stream
  • validate_file - Validar caminhos de arquivo contra a view de um stream
  • validate_submit - Validar arquivos abertos para submit em um workspace de stream
  • check_resolve - Verificar conflitos pendentes de especificação de stream
  • interchanges - Listar changelists aguardando integração entre streams
• Parâmetros:
  • stream_name - Caminho do depot do stream (obrigatório para get, children, parent, graph, check_resolve, interchanges)
  • stream_path - Padrão(ns) de caminho para list (ex.: ["//depot/..."])
  • filter - Expressão de filtro para list (ex.: "Owner=alice&Type=development")
  • fields - Campos para retornar em list (ex.: ["Stream", "Owner", "Type"])
  • workspace - Nome do workspace para get_workspace, validate_file, validate_submit
  • file_paths - Caminhos de arquivo para validate_file
  • view_without_edit - Visualizar especificação de stream bloqueada sem abrir para edição
  • at_change - Recuperar especificação histórica de stream em um número de changelist
  • both_directions - Mostrar status de integração em ambas as direções
  • force_refresh - Forçar atualização do cache istat
  • reverse, long_output, limit - Opções para interchanges
  • unloaded, all_streams, viewmatch - Filtros para list
  • max_results - Máximo de resultados
• Casos de uso: Exploração de hierarquia de streams, acompanhamento de status de integração, validação de workspace, verificações de compatibilidade de view

• Parâmetros: search_term, project_ids, repository_ids, path, tag, file_extension, user, all_revisions, max_results, offset
• Casos de uso: Descoberta de ativos, filtragem por projeto/repositório/tag/extensão, navegação no conteúdo P4 DAM. Use quando você ainda não tiver um caminho de depot.

• Parâmetros: depot_path (obrigatório), identifier, project_id, repository_id, include
• Casos de uso: Buscar informações de commit, bundles de ativos, weblinks, atributos personalizados e correspondências de projeto/repositório para um ativo conhecido. Use após query_p4dam_assets para obter detalhes completos de um arquivo específico.

• Parâmetros: search_term, limit, offset
• Casos de uso: Descobrir projetos disponíveis antes de criar um bundle de ativos ou revisão de arquivo, resolver IDs de projeto para outras chamadas.

• Parâmetros: project_id (obrigatório), search_term, limit, offset
• Casos de uso: Encontrar o tipo de repositório (helix_stream ou helix_classic) e linked_streams — necessário para fornecer stream_path ou descobrir branches ao criar bundles de ativos ou revisões de arquivo.

• Parâmetros: project_id (obrigatório), repository_id (obrigatório), limit, offset
• Casos de uso: Encontrar o ID do branch necessário ao criar um bundle de ativos ou revisão de arquivo em um repositório Helix Classic.

• Parâmetros: url (obrigatório — thumbnail_url, preview_url, sprite_url ou file_url dos resultados de ativos)
• Casos de uso: Renderizar miniaturas, pré-visualizações e folhas de sprites para ativos de imagem diretamente no cliente. Para arquivos que não são imagem, retorna o tipo MIME e o tamanho em vez do conteúdo da imagem. Passe URLs dos resultados de query_p4dam_assets ou query_p4dam_asset — apenas thumbnail_url, preview_url e sprite_url estão presentes para arquivos de imagem.

• Parâmetros: project_id (obrigatório), depot_path, include, limit, offset
• Casos de uso: Navegar por revisões ativas em um projeto, filtrar por caminho de depot, descobrir UUIDs de revisão para consultas de detalhes.

• Parâmetros: project_id (obrigatório), review_id (obrigatório)
• Casos de uso: Recuperar detalhes completos da revisão — estado, view_paths, asset_bundle, criador e download_url para revisões de bundle.

• Parâmetros: include, limit, offset
• Casos de uso: Descobrir workflows disponíveis e seus estados. Passe include=['states'] para obter todos os estados em uma única chamada — use o estado short_name como o parâmetro state em operações de revisão de arquivo.

• Parâmetros: workflow_id (obrigatório), include
• Casos de uso: Inspecionar os estados de um workflow (kind: open/review/done, color, position) e regras de transição.

• Parâmetros: workflow_id (obrigatório), limit, offset
• Casos de uso: Listar todos os estados com short_name, kind, color e position. O short_name é o valor a ser passado como state ao criar ou atualizar uma revisão de arquivo.

• Parâmetros: project_id (obrigatório)
• Casos de uso: Descobrir atributos personalizados disponíveis antes de definir valores — retorna o UUID, nome, tipo (text, single-select, multi-select, checkbox) e available_values de cada modelo para tipos select. Passe o UUID para update_p4dam_asset_custom_attributes.

• Ações - create, update, delete, switch
• Parâmetros - name, specs (objeto WorkspaceSpec com View, Root, Options, etc.)
• Requisitos - Modo somente leitura desativado, permissões apropriadas
• Casos de uso - Configuração de ambiente, manutenção de workspace, troca de branch

• Ações - create, update, submit, delete, move_files
• Parâmetros - changelist_id, description, file_paths
• Segurança - Verificações de propriedade, prompt interativo de PROCEED/CANCEL para operações de exclusão com detalhes dos itens
• Casos de uso - Submissão de código, organização de trabalho, agrupamento de arquivos

• Ações - shelve, unshelve, update, delete, unshelve_to_changelist
• Parâmetros - changelist_id, file_paths, target_changelist, force
• Casos de uso - Armazenamento temporário, compartilhamento de código, backup antes de experimentos

• Ações - link_job, unlink_job
• Parâmetros - changelist_id, job_id
• Casos de uso - Integração com rastreamento de defeitos, vinculação de requisitos

• Ações:
  • create - Criar um novo review a partir de um changelist
  • refresh_projects - Atualizar associações de projeto
  • vote - Votar em um review (positivo, negativo, limpar)
  • transition - Alterar o estado do review (needsRevision, needsReview, approved, committed, rejected, archived)
  • append_participants - Adicionar revisores/grupos a um review
  • replace_participants - Substituir todos os participantes
  • delete_participants - Remover participantes de um review
  • add_comment - Adicionar um comentário a um review
  • reply_comment - Responder a um comentário existente
  • edit_comment - Editar o corpo e/ou o estado da tarefa de um comentário existente
  • append_change - Adicionar um changelist a um review existente
  • replace_with_change - Substituir o conteúdo do review por um changelist
  • join - Participar de um review como participante
  • leave - Sair de um review
  • archive_inactive - Arquivar reviews inativos
  • mark_comment_read / mark_comment_unread - Marcar o status de leitura de um comentário individual
  • mark_all_comments_read / mark_all_comments_unread - Marcar o status de leitura de todos os comentários
  • update_author - Alterar o autor do review
  • update_description - Atualizar a descrição do review
  • obliterate - Excluir permanentemente um review
• Parâmetros:
  • review_id - ID do review (obrigatório para a maioria das ações)
  • change_id - ID do changelist (obrigatório para create, append_change, replace_with_change)
  • description - Descrição do review
  • reviewers, required_reviewers - Listas de nomes de usuário dos revisores
  • reviewer_groups - Grupos de revisores com requisitos
  • vote_value - Valor do voto: up, down, clear
  • version - Versão do review para votação
  • transition - Estado de destino: needsRevision, needsReview, approved, committed, approved:commit, rejected, archived
  • jobs, fix_status, cleanup - Opções de vinculação de jobs e limpeza para transições
  • users, groups - Dados estruturados de participantes para append/replace/delete
  • body - Texto do corpo do comentário
  • task_state - Estado da tarefa do comentário: open, comment, addressed, verified. add_comment aceita apenas open e comment; addressed e verified são alcançáveis por meio de edit_comment.
  • notify - Modo de notificação: immediate, delayed
  • comment_id - ID do comentário para respostas, edições ou marcação de lido/não lido
  • context - Contexto do comentário (arquivo, números de linha, conteúdo, versão)
  • not_updated_since, max_reviews - Filtros para archive_inactive
  • new_author, new_description - Valores para ações de atualização
• Casos de uso: Fluxo de trabalho de revisão de código, gerenciamento de estado de review, comentários colaborativos, gerenciamento de participantes, limpeza de reviews

• Ações:
  • create - Criar um novo stream (mainline, development, release, task, virtual, etc.)
  • update - Atualizar propriedades do stream (nome, descrição, opções, paths, parent_view)
  • delete - Excluir um stream
  • edit_spec - Abrir o spec do stream para edição (p4 stream edit)
  • resolve_spec - Resolver conflitos de spec do stream
  • revert_spec - Reverter edições do spec do stream
  • shelve_spec - Fazer shelve das edições do spec do stream em um changelist numerado
  • unshelve_spec - Fazer unshelve das edições do spec do stream
  • copy - Copiar alterações entre streams pai e filho
  • merge - Mesclar alterações entre streams pai e filho
  • integrate - Integrar alterações com opções avançadas
  • populate - Popular um novo stream com arquivos (branch)
  • switch - Alternar um workspace para um stream diferente
  • create_workspace - Criar um novo workspace vinculado a um stream
• Parâmetros:
  • stream_name - Caminho do depot do stream (obrigatório para create, update, delete, edit_spec, resolve_spec, revert_spec, switch)
  • stream_type - Tipo de stream para create: mainline, development, sparsedev, release, sparserel, task, virtual
  • parent - Stream pai para create em streams não-mainline
  • name, description - Nome de exibição e descrição do stream
  • options - Opções do stream: allsubmit/ownersubmit, unlocked/locked, toparent/notoparent, fromparent/nofromparent, mergedown/mergeany
  • parent_view - Tratamento da view do pai: inherit ou noinherit
  • paths, remapped, ignored - Mapeamentos da view do stream
  • changelist - Changelist para operações de edição de spec ou propagação
  • resolve_mode - Modo de resolução para resolve_spec: auto, accept_theirs, accept_yours
  • parent_stream - Substituir pai para propagação (flag -P)
  • branch - Spec de branch para integrate/populate (flag -b)
  • file_paths - Caminhos de arquivo para propagação
  • preview - Somente pré-visualização, sem alterações (flag -n)
  • force - Forçar operação (flag -f)
  • reverse - Inverter direção (flag -r)
  • max_files - Limitar arquivos processados (flag -m)
  • quiet - Suprimir mensagens informativas (flag -q)
  • output_base - Mostrar revisão base com resolução agendada (flag -Ob para merge/integrate) ou listar arquivos criados (flag -o para populate)
  • virtual - Copiar usando stream virtual (flag -v, somente copy)
  • schedule_branch_resolve - Agendar resolves de branch em vez de branching automático (flag -Rb, somente integrate)
  • integrate_around_deleted - Integrar ignorando revisões excluídas (flag -Di, somente integrate)
  • skip_cherry_picked - Pular revisões cherry-picked já integradas (flag -Rs, somente integrate)
  • source_path, target_path - Caminhos de origem e destino para populate
  • workspace - Nome do workspace para switch
  • workspace_name, root, host, alt_roots - Parâmetros de criação do workspace
• Segurança: Validação de existência do stream, detecção de streams bloqueados, avisos de workspace vinculado, verificações de arquivos abertos para alterações que afetam a view
• Casos de uso: Criação e gerenciamento de streams, propagação de branches (merge/copy/integrate), resolução de conflitos de spec, provisionamento de workspaces

• Parâmetros: depot_path (obrigatório, deve terminar com .p4bundle), project (obrigatório), repository (obrigatório), view_paths (obrigatório), stream_path, helix_classic_branch, description, hero_file_path
• Casos de uso: Criar uma coleção nomeada e com escopo de arquivos do depot para revisão. Forneça stream_path para repositórios Helix Stream, helix_classic_branch para repositórios Helix Classic.

• Parâmetros: bundle_id (obrigatório), description, view_paths, hero_file_path
• Casos de uso: Alterar a descrição de um pacote, ajustar seu escopo de arquivos (view_paths) ou atualizar a imagem de capa. depot_path é imutável após a criação.

• Parâmetros: bundle_id (obrigatório)
• Casos de uso: Remover um pacote de assets que não é mais necessário. Irreversível.

• Parâmetros: view_paths (obrigatório), workspace_root (obrigatório), client_name, bundle_id, stream_path
• Casos de uso: Baixar os arquivos com escopo de um pacote de assets via p4 sync. Cria ou reutiliza um cliente P4 nomeado — sincronizações subsequentes são incrementais. Use stream_path para repositórios Helix Stream (aplica LimitView, requer Perforce 2025.2+).

• Parâmetros: project_id (obrigatório), name (obrigatório), depot_path (obrigatório), view_paths (obrigatório), state (obrigatório), repository, helix_classic_branch, asset_bundle, hero_file_path, description, position, base_commit_id, head_commit_id
• Casos de uso: Abrir um review para um único asset ou um pacote de assets (.p4bundle). Para reviews de pacotes, asset_bundle é detectado automaticamente a partir de depot_path quando omitido.

• Parâmetros: project_id (obrigatório), review_id (obrigatório), state, name, view_paths, hero_file_path, description, position
• Casos de uso: Transicionar um review para um novo estado de fluxo de trabalho, atualizar seu nome ou descrição, ajustar o escopo da view. As transições de estado devem ser permitidas pelo fluxo de trabalho do projeto para o usuário atual.

• Parâmetros: project_id (obrigatório), review_id (obrigatório)
• Casos de uso: Remover um review que não é mais necessário. Irreversível. A API retorna o objeto do review excluído em caso de sucesso.

• Parâmetros: paths (obrigatório — lista de {path, identifier?}), create, delete, delete_auto, propagatable, identifier
• Casos de uso: Marcar um ou vários ativos em uma única chamada. Suporta arquivos individuais, revisões específicas e caminhos de pasta recursivos (//depot/folder/...). create adiciona tags de usuário, delete remove tags de usuário, delete_auto remove tags geradas automaticamente. Defina propagatable=true para aplicar tags à revisão mais recente e a todas as revisões futuras.

• Parâmetros: type (obrigatório), content (obrigatório), project, repository, file_review, commit, path, stream_path, helix_classic_branch, comment
• Casos de uso: Comentar em uma revisão de arquivo de pacote de ativos (file_review), um arquivo específico dentro de uma revisão (file_review_file), um arquivo ou pacote de ativos confirmado sem revisão (commit_file), ou responder a um comentário existente (comment). Os parâmetros obrigatórios dependem do tipo — consulte a descrição de type.

• Parâmetros: paths (obrigatório — lista de {path, identifier?}), create (lista de {uuid, value}), delete (lista de UUIDs de atributos a remover), propagatable
• Casos de uso: Definir ou limpar metadados personalizados em um ou mais ativos. Descubra os atributos disponíveis e seus UUIDs primeiro com query_p4dam_custom_attribute_templates. value é uma string para tipos text/single-select/checkbox e uma lista de strings para multi-select.

• Parâmetros: depot_path (obrigatório), commit_id (obrigatório)
• Casos de uso: Reacionar a geração de pré-visualização quando uma pré-visualização está ausente ou desatualizada. commit_id é o número do changeset dos resultados de query_p4dam_asset.

Sintomas: O sistema operacional não consegue encontrar ou executar o binário; o erro inclui ENOENT ou "No such file or directory".
Soluções:

1. Verifique o caminho: Certifique-se de que o campo command usa o caminho absoluto correto para o seu sistema operacional:
   • macOS/Linux: /absolute/path/to/p4-mcp-server
   • Windows: C:\absolute\path\to\p4-mcp-server.exe
2. Garanta que o binário existe e é executável:
   • 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. No Windows, garanta que o binário não está bloqueado:
   • Clique com o botão direito no arquivo .exe, selecione Propriedades e, se presente, clique em Desbloquear.

Sintomas: Não é possível conectar ao servidor P4
Soluções:

1. Verifique a variável de ambiente P4PORT: echo $P4PORT (macOS) ou echo $env:P4PORT (Windows)
2. Teste a conexão direta: p4 info
3. Verifique a disponibilidade do servidor: ping perforce.example.com
4. Verifique a porta e o protocolo (prefixo ssl: para conexões SSL).

Sintomas: Erros de confiança SSL ao conectar ao servidor P4 Soluções:

1. Confie no servidor: p4 trust -f -y
2. Verifique o status de confiança: p4 trust -l
3. Para problemas persistentes, verifique a configuração SSL.

Sintomas: Erros CERTIFICATE_VERIFY_FAILED ao usar ferramentas de revisão Soluções:

1. Repositório de confiança do sistema: Por padrão, o servidor usa o repositório de confiança do sistema operacional via truststore. Certifique-se de que o CA corporativo esteja instalado no repositório de certificados do sistema operacional.
2. Pacote de CA personalizado: Para usar um certificado CA personalizado, você deve primeiro definir P4MCP_TLS_CA_MODE=certifi (para desativar truststore) e, em seguida, fornecer o caminho do CA via --ca-bundle /path/to/ca.pem ou P4MCP_CA_BUNDLE. No modo system padrão, truststore substitui os pacotes de CA personalizados e eles são silenciosamente ignorados.
3. Desativar verificação: Use --ssl-no-verify ou defina P4MCP_SSL_VERIFY=false (não recomendado para produção). Isso funciona em ambos os modos TLS.

Observação: Essas configurações SSL se aplicam somente quando a URL do Swarm usa HTTPS. Se o Swarm estiver configurado com uma URL http://, a verificação SSL não é executada e essas configurações não têm efeito.

Sintomas: Falhas de autenticação
Soluções:

1. Conecte-se ao P4: p4 login -a
2. Verifique o status de login: p4 login -s
3. Verifique se o usuário existe: p4 users -m 1 your_username
4. Para problemas persistentes, verifique a senha ou use autenticação baseada em ticket.

Sintomas: Falhas de login
Soluções:

1. Redefina a senha por meio de um administrador do P4.
2. Use autenticação baseada em ticket: p4 login -a
3. Verifique se o nome de usuário está correto: p4 info

Sintomas: Erros de workspace não encontrado
Soluções:

1. Liste os workspaces disponíveis: p4 clients
2. Verifique a variável de ambiente P4CLIENT.
3. Crie um workspace se necessário: p4 client workspace_name
4. Verifique a propriedade do workspace: p4 client -o workspace_name

Sintomas: Arquivos estão fora do mapeamento do workspace
Soluções:

1. Verifique a visão do cliente: p4 client -o workspace_name
2. Atualize o mapeamento do workspace para incluir os caminhos necessários.
3. Use p4 where file_path para verificar o mapeamento.

Sintomas: Permissões insuficientes para operações
Soluções:

1. Verifique a propriedade do arquivo: p4 opened file_path
2. Verifique as permissões do usuário: p4 protects file_path
3. Garanta a associação adequada ao grupo.
4. Para operações de administrador, verifique as permissões de administrador.

Sintomas: Conflitos de bloqueio exclusivo
Soluções:

1. Verifique quem tem o arquivo aberto: p4 opened file_path
2. Entre em contato com o usuário para resolver conflitos.
3. O administrador pode forçar operações, se necessário.

Sintomas: Tempos de resposta longos
Soluções:

1. Use o parâmetro max_results para limitar o tamanho da consulta.
2. Use caminhos de arquivo específicos em vez de curingas.
3. Verifique a conectividade de rede com o P4.
4. Monitore o desempenho do servidor.

Sintomas: Alto uso de memória
Soluções:

1. Reduza max_results para consultas grandes.
2. Processe arquivos em lotes.
3. Reinicie o servidor MCP periodicamente para sessões de longa duração.

Sintomas: Conflito com ferramentas MCP integradas ou outras
Soluções:

1. Desative quaisquer ferramentas MCP integradas ou conflitantes em seu ambiente ou configuração.
2. Garanta que as ferramentas do servidor MCP P4 estejam devidamente registradas e habilitadas.
3. Reinicie o servidor MCP após aplicar alterações de configuração para carregar as ferramentas corretas.

Sintomas: Contexto inválido ou histórico de sessão desatualizado
Soluções:

1. Forneça um contexto relacionado ao P4 ao escrever prompts.
2. Inicie uma nova sessão se a sessão existente for antiga ou contiver histórico de prompts conflitantes.