mcp-perforce-server

mcp-perforce-server é um servidor do Model Context Protocol para Perforce (p4) com padrões seguros, respostas JSON estruturadas e fluxos de trabalho no estilo nativo e otimizados para MCP.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Perforce

mcp-perforce-server é um servidor Model Context Protocol para Perforce (p4) com padrões seguros, respostas JSON estruturadas e fluxos de trabalho no estilo nativo e otimizados para MCP.

Ele foi projetado para assistentes de IA e integrações com IDEs que precisam de acesso ao Perforce sem depender de scripts de shell frágeis.

O Que Ele Oferece

59 ferramentas MCP abrangendo inspeção de repositório, operações de arquivo, changelists, reviews, jobs, labels, streams, análises e conformidade.
Suporte a transporte duplo: stdio (IDE/CLI) e SSE (servidor HTTP para clientes web).
Comportamento seguro por padrão em tempo de execução:
- P4_READONLY_MODE=true
- P4_DISABLE_DELETE=true
Entradas com suporte a lote na superfície de ferramentas onde o p4 nativo suporta uso com múltiplos alvos.
Helpers compostos específicos do MCP que reduzem idas e voltas para fluxos comuns de revisão e busca.
Respostas estruturadas com ok, result, error opcional, warnings opcional e configUsed.
Clientes MCP veem nomes de ferramentas seguros com sublinhado, por exemplo p4_changes.
Chamadas recebidas também aceitam os nomes históricos com pontos, por exemplo p4.changes.

Fluxos de Trabalho em Destaque

O servidor inclui helpers de nível superior sobre comandos p4 brutos.

p4.review.bundle: changelists de revisão pendentes com detalhes e revisores opcionais
p4.change.inspect: describe + fixes + reviews + diff opcional + histórico de arquivo opcional
p4.path.synccheck: análise de divergência e estado de sincronização entre dois caminhos de depot
p4.file.inspect: metadados por arquivo, histórico, conteúdo opcional e blame opcional
p4.workspace.snapshot: informações do workspace, status, configuração opcional, arquivos abertos e alterações recentes
p4.search.inspect: resultados de busca agrupados com metadados de arquivo e pré-visualizações de conteúdo opcionais
p4.review.prepare: changelists explícitos ou descobertos preparados em pacotes prontos para revisão

Instalação

npm install -g mcp-perforce-server

Requisitos:

Node.js 18+
CLI do Perforce disponível como p4 ou p4.exe
Ambiente Perforce válido via .p4config ou env do MCP

Início Rápido

Instale o CLI do Perforce e garanta que p4 esteja no PATH.
Configure as credenciais do Perforce em .p4config ou via env do MCP.
Adicione o servidor ao seu cliente MCP.
Inicie no perfil seguro padrão antes de habilitar qualquer ferramenta com capacidade de escrita.

Exemplo de .p4config:

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

Exemplo de configuração MCP usando o servidor instalado globalmente:

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

Exemplo de configuração MCP com credenciais explícitas:

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

Exemplo de repositório local no Windows:

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

Modos de Transporte

O servidor suporta dois modos de transporte:

Transporte Stdio (Padrão)

Transporte de entrada/saída padrão para integração com IDE e CLI. Cada cliente MCP inicia seu próprio processo de servidor.

Melhor para:

Integração com VS Code, Cursor, Claude Desktop
Ferramentas CLI e automação local
Fluxos de trabalho de usuário único
Modelo de segurança com isolamento de processo

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

Transporte SSE (Servidor HTTP)

O transporte Server-Sent Events executa um servidor HTTP para clientes baseados na web.

Melhor para:

Dashboards web e UIs de análise
Ferramentas de colaboração em equipe
Implantações centralizadas
Ambientes multiusuário
Integrações de API

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

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

Configuração SSE:

Variável	Padrão	Descrição
`MCP_SSE_PORT`	`3000`	Porta do servidor HTTP
`MCP_SSE_HOST`	`0.0.0.0`	Endereço de bind do servidor
`MCP_SSE_PATH`	`/mcp`	Caminho do endpoint SSE
`MCP_SSE_CORS_ORIGIN`	`*`	Origens permitidas para CORS
`MCP_SSE_ENABLE_AUTH`	`false`	Habilitar autenticação por token
`MCP_SSE_AUTH_TOKEN`	(vazio)	Token Bearer para autenticação

Endpoints SSE:

Principal: GET http://localhost:3000/mcp
Saúde: GET http://localhost:3000/health
Post: POST http://localhost:3000/mcp

Exemplo SSE em Produção:

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

📘 Para o guia completo de implantação SSE, consulte SSE_SETUP_GUIDE.md

Referências rápidas:

Exemplos de Configuração MCP - Snippets rápidos de configuração
Guia de Configuração SSE - Guia abrangente de implantação com Docker, Kubernetes e exemplos de produção

Modelo de Segurança

O perfil de tempo de execução padrão é conservador.

Configuração	Padrão	Efeito
`P4_READONLY_MODE`	`true`	Bloqueia ferramentas com capacidade de escrita.
`P4_DISABLE_DELETE`	`true`	Bloqueia `p4.delete` mesmo quando o modo de escrita está habilitado.

Ferramentas com capacidade de escrita incluem:

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

Superfície de Ferramentas

Principais categorias:

Inspeção de repositório e workspace
Operações de arquivo e diff
Changelists e submissões
Fluxos de merge, shelving e resolve
Busca e descoberta
Compostos de revisão e fluxo de trabalho
Usuários, clientes, streams, labels, jobs e fixes
Conformidade, auditoria e diagnósticos operacionais

Melhorias notáveis de paridade nativa:

Entradas no estilo lote para comandos como sync, opened, filelog, annotate, grep, files, dirs, print, fstat, sizes, have, users, streams, jobs e fixes
Cobertura expandida de flags nativos para ferramentas como sync, interchanges, fstat, files, dirs, streams, clients, labels, jobs e sizes
Suporte para diff voltado ao workspace e depot-para-depot via p4.diff e p4.diff2

Configuração

A maioria das instalações precisa apenas de um pequeno conjunto de variáveis.

Variável	Padrão	Finalidade
`P4_READONLY_MODE`	`true`	Mantém o serviver somente leitura por padrão.
`P4_DISABLE_DELETE`	`true`	Impede operações de exclusão a menos que explicitamente habilitadas.
`P4CONFIG`	`.p4config`	Nome do arquivo de configuração usado durante a descoberta ascendente.
`P4_PATH`	`p4` / `p4.exe`	Caminho personalizado para o CLI do Perforce.
`P4_PERFORMANCE_MODE`	`fast`	Predefinição: `fast`, `balanced`, `secure`.
`P4_WORKFLOW_CONCURRENCY`	`6`	Máximo de subchamadas concorrentes para ferramentas compostas.
`P4_RESPONSE_CACHE`	`true`	Habilitar cache de respostas de leitura.
`P4_RESPONSE_CACHE_TTL_MAP`	não definido	Substituições de TTL de cache por ferramenta.
`LOG_LEVEL`	`warn`	Nível de log do servidor.

Variáveis de conexão do Perforce:

P4PORT
P4USER
P4CLIENT
P4PASSWD
P4CHARSET
P4COMMANDCHARSET
P4LANGUAGE

Para tabelas de configuração completas e exemplos, consulte:

Desenvolvimento

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

Linha de base de verificação atual:

npm run build
npm test
npm run test:integration

Documentação

Configuração de Transporte SSE: SSE_SETUP_GUIDE.md - Guia completo para implantações HTTP/web
Catálogo de ferramentas e descrições: AGENTS.md
Índice de documentação: docs/README.md
Configuração do Perforce: PERFORCE_SETUP.md
Exemplos de configuração de cliente MCP: MCP_CONFIG_EXAMPLES.md
Fluxo de publicação: PUBLISHING.md
Rascunho de notas de versão: RELEASE_NOTES.md

Licença

MIT