O serviço MCP

O AWR expõe o seu ledger de trabalho via MCP (Model Context Protocol), o protocolo padrão que permite a um host de agente — como um assistente de codificação ou um cliente de IA de desktop — descobrir e chamar ferramentas. O serviço MCP é como o seu agente lê o status do projeto, compila contexto, registra evidências e move o trabalho para a frente sem recorrer à CLI diretamente. Há duas maneiras de executá-lo:

• stdio — um processo local que o seu cliente inicia diretamente, um projeto por vez. Esta é a configuração clássica e continua disponível.
• HTTP compartilhado — um único endpoint Streamable HTTP atendendo vários projetos e vários clientes independentes. Os pacotes npm e PyPI incluem essa capacidade.

Este artigo foca no serviço HTTP compartilhado, que é o que você executa quando mais de uma pessoa ou agente precisa dos mesmos projetos. Para o que os agentes fazem com essas ferramentas uma vez conectados, veja Agentes. Para o equivalente voltado a humanos das mesmas operações, veja A CLI do AWR.

Como o serviço compartilhado funciona

Você inicializa cada projeto no servidor com awr init e depois registra a sua raiz absoluta canônica junto com o project_id retornado por:

awr --json status

O AWR verifica essa identidade na inicialização e em cada requisição. Os arquivos-fonte e o banco .awr de cada projeto permanecem separados — o serviço não clona repositórios, não monta sistemas de arquivos de clientes nem mescla ledgers de projetos. Os clientes precisam de acesso de rede ao serviço, não de um executável AWR local, e os arquivos do projeto precisam ser legíveis no servidor: um caminho no laptop de um cliente não se torna legível remotamente. Não existe um "projeto atual" compartilhado — toda ferramenta de projeto recebe um argumento project explícito, e não há ferramenta para abrir um caminho arbitrário do servidor.

Configurando o serviço

Crie um arquivo TOML de propriedade do operador fora do repositório público:

version = 1
allowed_hosts = ["awr.internal.example"]

[[projects]]
key = "billing"
root = "/srv/projects/billing"
project_id = "<actual project ID>"

[[projects]]
key = "support"
root = "/srv/projects/support"
project_id = "<actual project ID>"

[[clients]]
id = "engineering"
token_env = "AWR_ENGINEERING_TOKEN"
write = ["billing", "support"]

[[clients]]
id = "reviewer"
token_env = "AWR_REVIEWER_TOKEN"
read = ["billing"]

Cada entrada de cliente nomeia uma variável de ambiente que guarda a sua credencial bearer. Forneça credenciais distintas, geradas aleatoriamente, com pelo menos 32 caracteres. Uma concessão write inclui acesso de leitura; uma concessão read não pode modificar projetos. Mantenha os IDs de cliente estáveis entre rotações de credenciais — os vínculos de conversa e requisição se anexam ao ID do cliente, e mudá-lo cria um escopo distinto. Mudanças de configuração só entram em vigor após uma reinicialização do serviço.

Executando o serviço

awr-mcp --registry /etc/awr/service.toml --listen 127.0.0.1:8080

Toda requisição HTTP é autenticada. O mecanismo embutido é autenticação bearer estática — não um servidor de autorização OAuth nem um provedor de identidade corporativo. Para acesso remoto, termine o HTTPS em uma fronteira de implantação autenticada e restrinja o acesso direto ao backend. Controles de acesso adicionais:

• Origens são negadas a menos que estejam explicitamente listadas em allowed_origins; clientes nativos normalmente omitem o cabeçalho Origin.
• O SDK verifica allowed_hosts, usando hosts de loopback como padrão quando nenhum está configurado.
• O serviço valida o Origin, mas não implementa o preflight CORS de navegadores, então um frontend de navegador precisa de um gateway apropriado.

No Unix, SIGTERM e Ctrl-C param de aceitar requisições de forma graciosa e drenam o trabalho HTTP ativo. Desconectar um cliente ou reiniciar o serviço nunca encerra uma sessão de trabalho AWR — conexões de protocolo e sessões persistentes são identidades separadas. O AWR não instala um daemon de sistema — use o supervisor de processos da sua implantação para inicialização e reinício. Para uso local, com um único cliente, o comando stdio continua sendo:

awr-mcp --project /absolute/project

Conectando um cliente

Configure cada cliente MCP para Streamable HTTP com a mesma URL do serviço usando o caminho /mcp, mais a sua própria credencial bearer em um cabeçalho Authorization: Bearer … entregue pelo mecanismo de credenciais daquele cliente. Uma vez conectado, chame awr_projects_list para descobrir as chaves de projeto para as quais a sua credencial está autorizada. Toda ferramenta de projeto então exige project:

{"project": "billing", "work": "INVOICE-001"}

As ferramentas

O serviço HTTP compartilhado expõe 21 ferramentas no total (20 via stdio, que omite a ferramenta de listagem de projetos). Elas se dividem em três grupos.

Ferramentas de trabalho e contexto

Estas espelham as ações cotidianas da CLI:

Ferramentas de sessão e continuação

As sessões vinculam uma conversa a uma unidade de trabalho. Forneça um identificador conversation estável do seu host — não um identificador de conexão HTTP. A mesma string de conversa sob outro projeto ou cliente é um vínculo separado.

Uma espera pendente bloqueia transições de trabalho e resume até que o host registre uma resposta. A resposta remove esse bloqueio, mas não muda o status do trabalho nem agenda o próximo turno do host — o seu host inspeciona a sessão, compila contexto novo e decide se continua ou cria um sucessor.

Escritas, revisões e resultados incertos

Toda escrita no HTTP compartilhado exige duas coisas:

• um request_id estável gerado pelo cliente (até 256 bytes),
• o expected_revision que você observou por último.

{
  "project": "billing",
  "request_id": "host-turn-42-start",
  "expected_revision": 120,
  "work": "INVOICE-001",
  "conversation": "invoice-review",
  "agent": "billing-assistant",
  "provider": "example-provider",
  "model": "example-model",
  "claim": true
}

Repetir exatamente o mesmo ID de requisição e argumentos retorna o resultado registrado sem executar a ação de novo, então uma nova tentativa após um timeout é segura. Argumentos alterados exigem um novo ID. Guarde o project_revision retornado para a sua próxima escrita e nunca calcule a próxima revisão somando um: o journal de requisições e a operação de domínio consomem revisões.

Após um timeout ou desconexão, chame awr_operation_get com o mesmo projeto e ID de requisição. Uma requisição inacabada reporta write_outcome: unknown; uma escrita interrompida pode já ter sido confirmada, então nunca infira falha a partir de um fluxo de resposta HTTP fechado. awr_operation_recover pode registrar um resultado confirmado somente quando um evento terminal inequívoco está vinculado à requisição — ele nunca reinvoca a ferramenta original. Leituras podem rodar em paralelo; escritas são serializadas por projeto, e projetos diferentes têm travas independentes. Uma escrita desatualizada retorna um conflito — leia o estado atual e reconsidere antes de tentar de novo.

Leituras de workstream (em desenvolvimento)

A fonte em desenvolvimento adiciona um registro version = 2 que concede aos clientes acesso somente leitura a workstreams imutáveis explicitamente listados, para projetos que usam o ledger de workstreams em YAML. Essas são permissões de propriedade do operador: concessões read/write no nível do projeto sozinhas não autorizam nenhum workstream isolado.

[[clients.workstreams]]
project = "billing"
workstream_id = "<actual immutable workstream ID>"
authority_version = 1

Clientes autorizados usam a ferramenta awr_workstream, exclusiva do serviço compartilhado, começando com action: "capabilities" e action: "list" para descobrir o que podem ler. Esteja ciente dos limites atuais: esta extensão concede apenas leituras — sem mutações, leituras de arquivos de conteúdo ou operações do PostgreSQL de Equipe — e projetos que a habilitam rejeitam as ferramentas compartilhadas legadas, incluindo todas as escritas, até que uma implementação autorizada esteja disponível. Habilitação e reindexação são ações locais do operador neste estágio.

Para onde ir a seguir

• Agentes — como um agente usa sessões, claims e checkpoints sobre estas ferramentas.
• A CLI do AWR — as mesmas operações de domínio pela linha de comando, para operadores e depuração.
• Solução de problemas — conflitos de revisão, fontes desatualizadas e recuperação.