MCP Perforce Server

Um servidor para operações de controle de versão Perforce (P4), encapsulando comandos P4 para uso mais fácil e confiável.

GitHub
29
Experimente este MCPPatrocinado

Documentação

MCP Perforce Server

Um servidor Model Context Protocol (MCP) que fornece uma interface limpa para operações Perforce (P4) no Claude Desktop. Este servidor encapsula comandos P4 para torná-los mais confiáveis e fáceis de usar pelo Claude, eliminando problemas com prompts interativos e gerenciamento complexo de estado.

Recursos

  • Operações não interativas: Todos os comandos são encapsulados para evitar prompts interativos
  • Respostas estruturadas: Saída limpa e analisável em vez da saída bruta do P4
  • Suporte a múltiplos projetos: Usa automaticamente arquivos .p4config para configurações por projeto
  • Operações comuns: Adicionar, editar, excluir, submeter, reverter, sincronizar e mais
  • Gerenciamento de changelists: Criar e submeter changelists com parâmetros explícitos
  • Tratamento de erros: Tratamento gracioso de erros com mensagens claras

Instalação

Pré-requisitos

  • Node.js 18+ instalado
  • Cliente de linha de comando Perforce (p4) instalado e no seu PATH
  • Arquivos .p4config nos diretórios do seu projeto (recomendado)

Instalação rápida com Claude Code

# Install the package globally
npm install -g @cocoon-ai/mcp-perforce

# Add to Claude Code
claude mcp add perforce @cocoon-ai/mcp-perforce

É isso! O Claude Code configurará automaticamente o servidor para você.

Instalação manual

Via NPM (quando publicado)

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

Instalar a partir do código-fonte

git clone https://github.com/Cocoon-AI/mcp-perforce.git
cd mcp-perforce
npm install
npm run build
npm link  # Makes 'mcp-perforce' available globally

Configuração

Configuração básica

Adicione o servidor ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

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

Configurando arquivos .p4config

O servidor usa o mecanismo P4CONFIG integrado do Perforce para alternar automaticamente entre diferentes servidores Perforce com base no seu diretório atual. Crie um arquivo .p4config na raiz de cada projeto:

# ~/projects/gamedev/.p4config
P4PORT=perforce-game.company.com:1666
P4CLIENT=gamedev-workspace
P4USER=your-username

# ~/projects/web/.p4config
P4PORT=perforce-web.company.com:1666
P4CLIENT=web-workspace
P4USER=your-username

Agora o servidor MCP usará automaticamente as configurações corretas do Perforce com base no diretório do projeto em que você está trabalhando!

Comandos disponíveis

Depois de configurado, você pode pedir ao Claude para usar estas operações P4. Todos os comandos usarão automaticamente as configurações .p4config do diretório do seu projeto atual.

Operações básicas de arquivo

  • p4_status: Verificar o status do workspace e alterações pendentes

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

  • p4_add: Adicionar arquivos ao Perforce

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

  • p4_edit: Abrir arquivos para edição

    "Open config.json for editing in Perforce"

  • p4_delete: Marcar arquivos para exclusão

    "Delete the old_module.py file from Perforce"

  • p4_sync: Sincronizar arquivos do depot

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

  • p4_revert: Reverter arquivos ou changelists inteiros

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

  • p4_diff: Mostrar diferenças de arquivos

    "Show me the diff for all my open files"

Operações de changelist

  • p4_changelist_create: Criar uma nova changelist

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

  • p4_changelist_submit: Submeter uma changelist

    "Submit changelist 12345"

  • p4_move_to_changelist: Mover arquivos entre changelists

    "Move all my open files to changelist 12345"

Operações de stream

  • p4_stream_list: Listar streams em um depot

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

  • p4_stream_info: Obter informações detalhadas do stream

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

  • p4_stream_switch: Alternar o workspace para um stream diferente

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

  • p4_stream_create: Criar um novo stream

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

  • p4_stream_edit: Editar a especificação do stream

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

  • p4_stream_graph: Mostrar a hierarquia de streams

    "Show the stream hierarchy for //depot"

Operações de cliente/workspace

  • p4_client_list: Listar todos os clientes/workspaces

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

  • p4_client_info: Obter detalhes do cliente/workspace

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

  • p4_client_create: Criar um novo cliente/workspace

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

  • p4_client_edit: Editar a especificação do cliente

    "Edit the view mappings for client dev-workspace"

  • p4_client_delete: Excluir um cliente/workspace

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

  • p4_client_switch: Alternar para um cliente diferente

    "Switch to the production-client workspace"

Operações de informação

  • p4_info: Mostrar a configuração atual do Perforce

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

  • mcp_perforce_version: Mostrar a versão do servidor MCP Perforce

    "What version of mcp-perforce is running?"

Exemplo de uso no Claude

Aqui estão alguns exemplos de conversas com o Claude:

Exemplo 1: Criando e submetendo uma alteração

You: "I've modified server.js and config.json. Create a changelist for these fixes"
Claude: I'll help you create a changelist for your changes. Let me first check the status...
[Uses p4_status, p4_changelist_create, p4_submit]

Exemplo 2: Sincronizando e revisando alterações

You: "Sync the latest changes and show me what files I have open"
Claude: I'll sync your workspace and check your open files...
[Uses p4_sync, p4_status]

Solução de problemas

Servidor não aparecendo no Claude

  1. Reinicie o Claude Desktop após modificar a configuração
  2. Verifique se o arquivo de configuração é um JSON válido
  3. Verifique se o servidor MCP está instalado: npm list -g @cocoon-ai/mcp-perforce

Erros de autenticação do Perforce

  1. Verifique se o arquivo .p4config existe e tem as configurações corretas
  2. Teste sua conexão fora do Claude: p4 info
  3. Certifique-se de que você está conectado: p4 login
  4. Verifique se o P4CONFIG está sendo reconhecido: p4 set P4CONFIG

Servidor Perforce errado em uso

  1. Verifique em qual diretório você está - o servidor usa .p4config do diretório atual ou dos diretórios pai
  2. Execute p4 info para ver qual configuração está sendo usada
  3. Use o comando p4_info no Claude para depurar: "Mostre-me minha configuração P4"

Comando não funcionando como esperado

  1. Verifique a resposta do Claude para mensagens de erro
  2. Verifique se o comando P4 funciona no seu terminal a partir do mesmo diretório
  3. Ative o registro de depuração (veja abaixo)

Registro de depuração

Para ativar a saída de depuração, adicione à sua configuração:

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

Desenvolvimento

Compilando a partir do código-fonte

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

Executando testes

npm test

Adicionando novos comandos

  1. Adicione a definição da ferramenta no arquivo apropriado em src/tools/
  2. Adicione a função de manipulação no arquivo correspondente em src/handlers/
  3. Atualize a instrução switch em src/handlers/index.ts
  4. Siga o padrão existente para validação de parâmetros e tratamento de erros

Contribuindo

Contribuições são bem-vindas! Por favor:

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/new-command)
  3. Faça commit das suas alterações (git commit -am 'Add new P4 command')
  4. Envie para o branch (git push origin feature/new-command)
  5. Crie um Pull Request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes

Agradecimentos

Suporte

Feito com ❤️ para IAs que enfrentam dificuldades com operações de linha de comando do P4