PHPGraph MCP

phpgraph

Um grafo de conhecimento do seu código PHP, para agentes de IA de codificação.
Análise estática servida via MCP para Sherpa, Claude Code, Codex, Cursor e qualquer cliente MCP.
Sem LLM, sem rede, sem embeddings: fatos determinísticos, cada um com um nível de confiança.

English · Français

Por que phpgraph?

Um agente de IA inserido em um projeto PHP desconhecido lê arquivos um a um e procura por nomes. Ele perde o que mais importa em um código real: quem chama o quê, qual handler recebe uma mensagem, qual controller atende uma rota, o que quebra se um método mudar e qual camada depende de qual.

O phpgraph analisa o projeto inteiro uma vez (com nikic/php-parser) e responde a essas perguntas a partir de um grafo:

• Fatos determinísticos, não suposições. Cada relação é EXTRACTED (lida no código), INFERRED (resolvida a partir de tipos declarados) ou AMBIGUOUS (uma suposição, rotulada como tal).
• Ele diz o que não sabe. Chamadas não resolvidas, vendor/ ausentes, mensagens sem handlers: as lacunas são relatadas, para que o agente saiba quando ler o código ele mesmo.
• Feito para DDD e arquitetura hexagonal, depois microsserviços, depois PHP em geral: Symfony, Laravel, Ecotone, PrestaShop, WordPress ou PHP puro.
• Privado por design. Seu código nunca sai da sua máquina, e o phpgraph nunca o executa: ele apenas o analisa.

Recursos

• Grafo de chamadas com inferência de tipos: tipos de retorno, chamadas encadeadas ($a->b()->c()), variáveis locais, docblocks (@return, @var) e assinaturas das suas dependências vendor/, para que as cadeias passem por APIs do Doctrine, Symfony ou Laravel.
• Arquitetura: camadas DDD e hexagonais, contextos delimitados, regras de camada verificadas no CI (phpgraph check) e análise de impacto (impact_of): o que depende de uma classe ou método e quais testes executar.
• Mensagens e eventos: remetente → mensagem → handler para Symfony Messenger, jobs e eventos do Laravel, Ecotone, CQRS do PrestaShop, hooks do WordPress, eventos de domínio e seus próprios barramentos, a partir de atributos, configuração de serviços (YAML, XML, PHP) ou formato do código.
• HTTP: rotas (atributos do Symfony, arquivos de rota YAML e PHP, recursos da API Platform, arquivos de rota do Laravel, controllers nomeados por id de serviço do container) vinculadas a controllers, e chamadas HTTP vinculadas às rotas que alcançam. Uma rota cuja classe de controller não existe nem no projeto nem em vendor/ é relatada com seu arquivo de rota.
• Injeção de dependência: o que a configuração do container Symfony injeta além dos tipos de construtor, cada serviço de uma tag (tagged_iterator, #[AutowireIterator]) ou um serviço nomeado por id, a partir de configuração PHP, YAML ou XML, incluindo helpers chamados com argumentos literais (Wiring::wire($services, 'sales', ...), avaliados, nunca executados): um validador é vinculado às regras que recebe. Uma regra que declara o que aceita (supports(object $input): bool { return $input instanceof CreateEstimateQuery; }, também canHandle, accepts…) é mantida fora dos casos de uso que passam outra entrada para o pipeline compartilhado, incluindo as classes que as propriedades da entrada contêm. Uma entrada tipada por uma interface é qualquer classe do projeto que a implementa e os tipos de parâmetro para os quais é passada (QueryInterface $query dado a setUp(CreateEstimateQueryInterface $query): um CreateEstimateQuery); uma proteção que não consegue ler, ou uma regra que roda apenas para algumas dessas classes, é mantida, marcada como supports() not resolved.
• Microsserviços: um espaço de ids por serviço e links entre serviços por meio de seus contratos: classes de mensagem compartilhadas, chaves de roteamento, rotas HTTP.
• Esquemas de API: as operações de documentos OpenAPI (Swagger) vinculadas às rotas que as implementam ou, para um documento de outra API, às chamadas HTTP do seu cliente; os rpcs de serviços protobuf vinculados às classes que implementam sua interface gerada. O que está documentado e não implementado, e as rotas que nenhum documento descreve, são relatados. impact lista as operações por trás de uma mudança (o contrato no qual seus clientes dependem), outline aquelas que um recurso atende.
• Servidor MCP de configuração zero: construído no primeiro uso, reconstruído incrementalmente quando o código muda (cerca de 3 s por edição em um projeto de 8.400 arquivos).

Início rápido

1. Instale. Um único executável, sem necessidade de PHP (Linux e macOS em x86_64 e ARM, Windows em x86_64):

curl -fsSL https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.sh | sh                  # latest release
curl -fsSL https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.sh | sh -s -- 0.2.0     # a given release
curl -fsSL https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.sh | sh -s -- dev-main  # the main branch

irm https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.ps1 | iex                       # Windows
$env:PHPGRAPH_VERSION = "dev-main"; irm https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.ps1 | iex

O script baixa o binário, verifica seu SHA-256 e o coloca em ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\phpgraph, adicionado ao PATH); PHPGRAPH_INSTALL_DIR muda o diretório. Execute novamente para atualizar. dev-main é reconstruído a cada push para main (o pré-lançamento edge). O binário é um runtime PHP estático com phpgraph dentro, construído com static-php-cli.

Com PHP 8.2+ instalado, ou com Docker:

composer require --dev hbenabdallah/phpgraph       # or: composer global require hbenabdallah/phpgraph
curl -LO https://github.com/hbenabdallah/phpgraph/releases/latest/download/phpgraph.phar
docker pull ghcr.io/hbenabdallah/phpgraph          # nothing else to install

2. Conecte seu agente. mcp-config imprime uma configuração pronta para colar com os caminhos preenchidos (vendor/bin/phpgraph quando instalado com Composer):

phpgraph mcp-config sherpa    # Sherpa: ~/.config/sherpa/mcp.json, one declaration for every project
phpgraph mcp-config claude    # Claude Code: a `claude mcp add` command, or .mcp.json
phpgraph mcp-config codex     # Codex: ~/.codex/config.toml
phpgraph mcp-config cursor    # Cursor: .cursor/mcp.json, shareable with the team
phpgraph mcp-config json      # any other MCP client over stdio

Com Sherpa, um agente de codificação de terminal, uma declaração em ~/.config/sherpa/mcp.json atende a todos os projetos: o Sherpa inicia seus servidores MCP a partir do projeto em que executa.

{
  "mcpServers": {
    "phpgraph": { "command": "/home/you/.local/bin/phpgraph", "args": ["serve"] }
  }
}

Com Claude Code (caminhos absolutos, como mcp-config os imprime):

claude mcp add phpgraph -- /home/you/.local/bin/phpgraph serve /path/to/project

3. Pergunte ao seu agente algo como "Me dê uma visão geral deste projeto", "Como um pedido é feito?" ou "O que quebra se eu mudar OrderRepository::save?". O grafo é construído na primeira chamada e depois mantido atualizado.

Ferramentas MCP

O servidor diz ao agente para chamar overview primeiro. Um caminho, como um agente o vê, em php-ddd-example:

Shortest path (4 hops):
  PUT /courses/{id} --handled_by--> CoursesPutController::__invoke()
    --dispatches--> CreateCourseCommand --handled_by--> CreateCourseCommandHandler::__invoke()
    --calls--> CourseCreator::__invoke()

Linha de comando

phpgraph build [path]                        # phpgraph-out/graph.json and GRAPH_REPORT.md
phpgraph overview                            # stack, structure and gaps
phpgraph impact "OrderRepository::save"      # what depends on it, and the tests to run (--all, --section tests, --format json)
phpgraph check                               # layer rules, for CI: exit code 1 on a new violation
phpgraph explain "PlaceOrderHandler"         # a node and its relations (-d in|out)
phpgraph path "StockChecker" "DbalOrderRepository"
phpgraph query "how is stock checked"
phpgraph outline "notification validation"   # the outline of a feature (--section flow, --format json)
phpgraph serve [path]                        # the MCP server, over stdio
phpgraph mcp-config claude|codex|cursor|json [--docker image]

Opções de build: -e para excluir caminhos (repetível), --no-vendor para não ler dependências, --no-cache para analisar todos os arquivos novamente. vendor, node_modules, var, .git e os arquivos ignorados pelos próprios arquivos .gitignore do projeto são ignorados; um repositório git acima do projeto nunca aplica suas regras, então um projeto copiado para um diretório ignorado ainda é lido. Quando o diretório contém arquivos PHP, mas todos são excluídos, build falha e diz isso, e toda resposta MCP começa com esse aviso em vez de servir um grafo vazio. A memória é ilimitada por padrão; PHPGRAPH_MEMORY_LIMIT=2G define um limite. Com PHP instalado, opcache e seu JIT tornam as construções cerca de 20% mais rápidas: php -d opcache.enable_cli=1 -d opcache.jit=tracing -d opcache.jit_buffer_size=128M vendor/bin/phpgraph build (a imagem Docker e os comandos impressos por mcp-config já os usam).

O que o grafo contém

Cada relação carrega um nível de confiança:

phpgraph check --generate-baseline   # accept today's violations in phpgraph-baseline.json
phpgraph check                       # fail on new ones only

services:
  - services/billing
  - services/shipping

Medido em projetos reais

phpgraph é desenvolvido contra um corpus de projetos de código aberto fixados em um commit, e cada mudança é julgada por seus números (composer corpus:measure). Apenas código de aplicação; receptor tipado é a parcela de chamadas de método cujo tipo de receptor o phpgraph pôde determinar.

Quatro projetos de microsserviços completam o corpus: dois serviços Laravel sobre RabbitMQ, ligados por 4 contratos de mensagem; quatro serviços Laravel sobre HTTP, onde o phpgraph encontrou um POST enviado a uma rota apenas GET; reserva de ingressos do Spiral, serviços chamando uns aos outros por serviços gRPC declarados em arquivos .proto; e StayHub, sete serviços Laravel atrás de um gateway de API descrito por um arquivo OpenAPI. Os dois últimos medem esquemas de API como contratos: todas as 45 operações do documento do StayHub e todos os 14 rpcs da reserva de ingressos estão ligados ao que os implementa. Zero falhas de análise em cerca de 26.600 arquivos. Os detalhes por projeto, incluindo mensagens, rotas e serviços, estão em corpus/RESULTS.md.

Com um agente

Medido em um projeto privado Symfony/DDD de 4.800 arquivos, 3 execuções por configuração, o mesmo agente (Sherpa) com e sem phpgraph 1.0.2:

Os intervalos das execuções com e sem phpgraph não se sobrepõem.

Comparado com outros grafos de código

Sylius (o commit do corpus), outubro de 2026, sem qualquer LLM: phpgraph 1.0.2, codebase-memory-mcp 0.11.0 e graphify 0.9.76 (--code-only), na mesma máquina, em Docker. As chamadas foram comparadas site por site (arquivo, linha, método), e amostras das diferenças foram verificadas no código.

• codebase-memory-mcp concorda com phpgraph em 99,7 % das chamadas que resolve a partir de tipos. O resto de suas arestas é adivinhado a partir do nome do método (confiança 0,04 a 0,44): onde ambos ligam a mesma chamada, eles discordam em 9.400 sites, e suas 11.300 arestas extras são principalmente chamadas para vendor/ anexadas a um método do projeto com o mesmo nome (19 de 20 verificados).
• graphify liga $this->other->foo() a foo() da classe atual: correto para $this->foo(), errado para as 10 de 10 diferenças verificadas.
• O que eles têm e o phpgraph não tem: outras linguagens, busca de texto completo e vetorial, consultas Cypher (codebase-memory-mcp), uma visualização interativa e documentos no grafo (graphify).

FAQ

O phpgraph envia meu código para algum lugar? Não. Ele roda localmente, não faz nenhuma chamada de rede e não usa LLM.

Ele executa meu código? Não. Ele analisa arquivos PHP e lê configuração JSON, YAML e XML. Até autoload_classmap.php e configuradores de serviço PHP são analisados, não incluídos.

Quais versões de PHP ele pode analisar? Qualquer coisa que nikic/php-parser 5 analise: sintaxe PHP 7 e 8. O phpgraph em si precisa de PHP 8.2 ou mais novo.

Com quais agentes ele funciona? Qualquer cliente MCP sobre stdio: Sherpa, Claude Code, Codex, Cursor, Claude Desktop, e outros. mcp-config imprime a configuração para os comuns.

Quão grande um projeto ele pode lidar? O maior projeto do corpus, Akeneo, tem 8.400 arquivos: cerca de 10 s e 500 MB para uma construção completa, cerca de 3 s para uma reconstrução após uma edição.

Limitações

• Apenas PHP é lido: overview nomeia os outros idiomas de um repositório misto (suas chamadas para a parte PHP não são vinculadas), e as instruções do MCP dizem imediatamente quando um projeto não tem PHP algum.
• Chamadas para funções globais não são arestas do grafo, embora o que uma função retorna tipa as chamadas sobre ela (now()->addDay(), response()->json()); chamadas dinâmicas ($this->$name(), __call) são resolvidas apenas através dos métodos que uma classe documenta (@method, @mixin).
• Genéricos são lidos de docblocks (@template, @extends Repository<Order>, @return Collection<int, Item>, ScalarNodeDefinition<$this>), no projeto e em vendor/: um template é vinculado pelo tipo do receptor e pelos pais que o repassam, e um foreach percorre os elementos de qualquer coleção tipada. Uma união (Response|ResponseFactory, documentada ou declarada) é chamada no membro que declara o método, e somente quando um membro o faz; um closure passado a um método recebe os parâmetros que o método documenta passar (@param callable($this): mixed, o when(fn ($query) => ...) do Laravel); @use HasFactory<HotelFactory> em um uso de trait vincula seus templates. Um template de um método é vinculado pelos argumentos de cada chamada: a classe que um argumento nomeia (getRepository(Order::class) com @param class-string<T>), o tipo de um valor (@param T $value), o que um closure retorna (@param callable(): T, suas declarações de retorno ou tipo nativo). @phpstan-return e @psalm-return são lidos antes de @return; uma condição que os argumentos não decidem (TAsync is false ? Response : PromiseInterface) dá a união de seus ramos. Propriedades mágicas documentadas com @property e @property-read carregam cadeias adiante; em um modelo Eloquent, também o fazem os casts ('paid_at' => 'datetime' é um Carbon, um enum, o TGet de uma classe de cast), os timestamps e as relações lidas como propriedades ($page->book, o que book()->getResults() retorna). Um método que não declara tipo de retorno retorna o que o método que ele sobrescreve declara (@inheritDoc). Condições sobre um tipo ($id is array ? Collection : Model) não são avaliadas, e um método de facade documentado como mixed (DB::transaction()) permanece desconhecido.
• Cadeias param em métodos mágicos e em dependências sem um tipo de retorno utilizável. As próprias classes do PHP (DateTime, ArrayObject, SplObjectStorage, PDO...) são conhecidas a partir de assinaturas geradas uma vez (tools/internal-classes.php); aquelas das extensões intl e mysqli não são.
• Sem um vendor/ instalado, cadeias de chamadas param na primeira dependência.
• Serviços construídos em tempo de execução (passes de compilador, extensões de bundle, ids computados a partir de valores conhecidos apenas em tempo de execução), rotas XML, recursos da API Platform declarados em XML ou YAML, e esquemas de API diferentes de OpenAPI e protobuf (GraphQL, AsyncAPI) não são lidos; um caminho OpenAPI reescrito por um gateway não é seguido; injeções que não podem ser vinculadas são listadas por overview.
• Dois serviços que declaram uma classe de mensagem com o mesmo nome são considerados como compartilhando-a.

Contribuindo

Issues e pull requests são bem-vindos. Veja CONTRIBUTING.md: composer check deve passar (php-cs-fixer, PHPStan nível máximo, PHPUnit), e mudanças na análise são julgadas no corpus. Sem PHP instalado, bin/dev composer check executa tudo em Docker.

O que permanece estável entre versões (comandos, ferramentas MCP, o formato graph.json) está listado em docs/STABILITY.md; mudanças estão no changelog.

Lançamentos são publicados ao enviar uma tag de versão: o workflow de lançamento constrói o PHAR, os executáveis para Linux, macOS e Windows (tools/build-binary.sh), e a imagem Docker ghcr.io/hbenabdallah/phpgraph.

Licença

phpgraph é de código-fonte disponível sob a PolyForm Shield License 1.0.0: você pode usar, modificar e redistribuir, inclusive em uma empresa, para qualquer propósito que não concorra com o phpgraph. Fornecer um produto concorrente a partir deste código não é permitido. Esta não é uma licença de código aberto aprovada pela OSI.