Visão geral do MCP

O Pathrule fala o Model Context Protocol. É por esse protocolo que o seu assistente de programação com IA chama ferramentas externas e lê estado externo. Para o assistente, o Pathrule aparece como um servidor MCP comum, então qualquer cliente que fale MCP pode usá-lo.

Existem duas formas de se conectar. O servidor local vem com o Pathrule CLI e a extensão do Pathrule para VS Code: o assistente se comunica com ele via stdio e, em um espaço de trabalho Cloud, o runtime se comunica com o Pathrule Cloud via HTTPS. Para clientes que se conectam a servidores hospedados, o Remote MCP aceita uma conexão direta via Streamable HTTP, com login por OAuth e acesso restrito ao seu espaço de trabalho. O stdio local e o Remote MCP têm catálogos de ferramentas e schemas diferentes. Consulte tools/list no servidor conectado. O Pathrule não envia automaticamente o código-fonte do seu repositório; as ferramentas locais de aprendizado do projeto podem inspecionar arquivos anexados a uma descoberta para validá-la.

O que o servidor expõe

A superfície MCP do Pathrule é tipada e organizada em torno do modelo de dados. As ferramentas principais abaixo cobrem os fluxos do dia a dia de contexto, conteúdo e atividade; a referência de ferramentas é o inventário oficial.

O servidor local anuncia o conjunto completo, leitura e escrita, já no primeiro tools/list, então nada precisa ser desbloqueado antes da primeira escrita e a lista não muda no meio da sessão. Um modo lazy, que segura as ferramentas de escrita até que sejam necessárias, está disponível de forma opcional; veja Controle local de escrita lazy.

Ferramentas de leitura

• pathrule_get_context. O ponto de entrada principal. A partir do diretório de trabalho atual e da intenção do usuário, retorna a fatia certa de memórias, regras e skills para aquele caminho. A resposta traz a visão geral do espaço de trabalho, as regras e memórias que já correspondem e uma dica do que ler em seguida.
• pathrule_read_memory, pathrule_read_rule, pathrule_read_skill. Buscam o conteúdo completo de um nó específico pelo id quando o assistente quer citá-lo ou segui-lo.
• pathrule_get_tree, pathrule_get_node. Inspecionam a estrutura do espaço de trabalho ou um nó específico.
• pathrule_list_memories. Lista as memórias sob um caminho, útil para prompts de descoberta.

Ferramentas de escrita

• pathrule_write_memory, pathrule_write_rule, pathrule_write_skill. Criam conteúdo em um caminho do espaço de trabalho. Nós que faltam ao longo do caminho são criados sob demanda.
• pathrule_update_memory, pathrule_update_rule, pathrule_update_skill. Editam um registro existente. A concorrência otimista é garantida por um id de versão.
• pathrule_delete_memory, pathrule_delete_rule, pathrule_delete_skill. Exclusão lógica, com janela de trinta dias para desfazer.

Atividade e manutenção

• pathrule_log_activity. Chamada após qualquer resposta que modifique arquivos, para que a equipe veja o que o assistente fez e onde.
• pathrule_goto. Muda o nó de trabalho do assistente quando o usuário pede conteúdo de outro escopo.
• pathrule_ping. Uma verificação de saúde que confirma que o servidor está conectado e mostra como o runtime enxerga o diretório de trabalho.

Onde os hooks entram

Em clientes que suportam hooks, são eles que mantêm o assistente rápido com o Pathrule. No início da sessão e em torno das chamadas de ferramenta, o supervisor de hooks lê uma fatia em cache para o diretório de trabalho atual e a entrega ao agente como contexto. Isso evita uma ida e volta síncrona ao MCP no caso mais comum. O hook de início de sessão também entrega o próprio protocolo do Pathrule, então, em um cliente com suporte a hooks, o arquivo de instruções no seu repositório continua sendo uma nota curta.

Nem todo cliente é alcançado da mesma forma:

• Claude Code e Codex têm hooks, incluindo um hook de envio de prompt, então o conhecimento relevante chega com cada prompt, antes de o agente agir.
• Cursor e GitHub Copilot têm hooks de sessão e de ferramenta, mas nenhum hook de envio de prompt. O contexto chega no início da sessão e em torno das chamadas de ferramenta.
• Windsurf não tem hooks. Ele lê um arquivo de regras do Pathrule no início da sessão e usa as ferramentas MCP para todo o resto.

Quando o hook basta, o assistente não precisa chamar pathrule_get_context. Ele já tem a fatia certa. As ferramentas MCP ficam reservadas para dois cenários.

1. O assistente quer mais do que o hook trouxe. Por exemplo, um prompt de descoberta que precisa do conteúdo completo de uma memória, ou uma refatoração que mexe em um caminho que o hook não previu.
2. Algo vale a pena guardar. O assistente propõe uma memória, regra ou skill e a grava depois que você confirma, ou você pede que ele grave diretamente. As escritas passam pelas ferramentas de escrita, e cada uma é marcada como escrita pelo assistente e versionada, para que você possa revisá-la ou desfazê-la.

Veja Como os hooks funcionam para entender o mecanismo por trás.

Integrações com agentes

O Pathrule é a camada de inteligência; o seu agente de programação continua sendo o mecanismo de execução e mantém o próprio provedor de modelo. O CLI e a extensão para VS Code conectam os agentes que você já usa ao mesmo espaço de trabalho, por meio dos hooks, arquivos de instruções e MCP que cada cliente suporta.

• Claude Code e Codex: hooks, incluindo um hook de envio de prompt, arquivos de instruções e o servidor MCP local. Ambos também podem se conectar ao Remote MCP.
• Cursor e GitHub Copilot: hooks de sessão e de ferramenta, arquivos de instruções e o servidor MCP local. A extensão para VS Code registra o servidor para o modo agente do Copilot.
• Windsurf: um arquivo de regras do Pathrule e o servidor MCP local, sem hooks.
• Qualquer outro cliente MCP: conecta-se via stdio. Adicione o comando MCP do Pathrule à configuração do seu cliente e ele verá a mesma superfície de ferramentas.
• Clientes que se conectam a servidores hospedados: aponte-os para o Remote MCP via Streamable HTTP e entre com OAuth. O Remote MCP não instala hooks nem grava arquivos locais.

O que ler em seguida

• Como os hooks funcionam, para entender o que acontece entre o cache e o editor.
• Conceitos principais, para conhecer o modelo de dados sobre o qual as ferramentas operam.
• Instalação do CLI, para configurar o runtime que hospeda o servidor.