ADK MCP

O ADK Assembly MCP

Esta página é sobre a coisa que você entrega a outro agente quando quer que ele ajude com ADK sem fazer suposições.

O site de documentação é para humanos. A referência da API é para humanos. A seção Assembly é para humanos que conseguem ler uma página, manter três restrições na cabeça e voltar ao editor com a forma certa. Agentes de codificação não funcionam assim. Eles precisam do mesmo conhecimento, mas precisam dele no lugar onde já estão trabalhando: dentro do loop de ferramentas deles.

É isso que o ADK MCP é.

A versão curta

Instale este servidor MCP no seu agente de codificação e peça ao agente para usar as ferramentas ADK antes de escrever código de configuração ADK.

Recomendado para equipes e configuração compartilhada de projetos:

npx -y @nhtio/adk@1.20260921.0

Teste rápido:

npx -y @nhtio/adk

O que é

O ADK MCP é um servidor local do Model Context Protocol incluído no pacote npm @nhtio/adk. Quando um agente de codificação compatível com MCP o inicia, o servidor abre uma conexão stdio e expõe ferramentas, recursos e prompts específicos do ADK.

Ele carrega um corpus de documentação empacotado criado no momento da publicação:

• as páginas de documentação escritas manualmente;
• a referência da API TypeDoc gerada;
• o changelog copiado para a compilação da documentação;
• a Skill de assembly do ADK e suas notas de referência.

A palavra importante é empacotado. O servidor MCP não acessa o site de documentação ao vivo, não chama uma API de busca hospedada e não depende do acesso web do seu editor depois que o pacote npm for resolvido. A documentação que ele serve é a que foi enviada com aquela versão do @nhtio/adk.

O alinhamento de versão é o ponto principal

Se o seu agente instala o @nhtio/adk@1.20260921.0, o servidor MCP responde com a documentação e a referência da API empacotadas com o @nhtio/adk@1.20260921.0. Essa é a diferença entre "procurar ADK" e "procurar o ADK que eu estou realmente usando".

O que não é

Não é um segundo site de documentação. A prosa canônica ainda vive aqui. O MCP é a cópia portátil, em formato de ferramenta, para um runtime de agente.

Não é um modelo. Ele não raciocina por conta própria. Seu agente de codificação escolhe quando chamá-lo, lê o resultado e decide o que fazer em seguida.

Não é uma ferramenta privilegiada de workspace. Ele não precisa de um caminho de projeto ADK. Ele não escreve arquivos. Ele lê o corpus empacotado e revisa o código que você cola ou que o agente passa para ele.

Não é uma ferramenta de introspecção de projeto. Ele não inspeciona seu repositório nem infere qual versão do ADK você usa. Ele só conhece a versão do pacote que você iniciou. É por isso que a configuração MCP fixada importa.

Não substitui a compreensão da costura. Ele vai lembrar o agente de que callbacks de armazenamento são obrigatórios, que o executor deve ack() ou nack(), e que o histórico pertence ao middleware de entrada. Ele não vai tornar uma integração vaga correta por mágica.

Servidores MCP locais ainda são código

Todo servidor MCP stdio é um processo local. Este é intencionalmente simples — ele serve markdown empacotado e ferramentas de revisão básicas — mas seu cliente MCP está certo em pedir confiança antes de iniciá-lo.

Postura de segurança e confiança

Clientes MCP costumam fazer servidores locais parecerem mais assustadores do que são, porque estão aprovando a inicialização de um processo, não lendo o código-fonte do servidor. Aqui está a forma deste:

• Rede: nenhum acesso à rede é necessário depois que o npm resolve o pacote.
• Corpus: markdown/JSON somente leitura empacotado com o pacote npm instalado.
• Sistema de arquivos: lê apenas o próprio arquivo de corpus empacotado; não lê seus arquivos de projeto nem seu diretório pessoal.
• Shell: não executa comandos de shell depois que seu cliente MCP o inicia.
• Ferramentas: lista de ferramentas determinística com entradas de string simples; sem descoberta dinâmica de ferramentas ocultas pela rede.

Por que seu cliente ainda pede aprovação

O prompt de confiança ainda está correto. Iniciar o npx -y @nhtio/adk@1.20260921.0 significa que seu cliente está executando código local do npm. Fixe a versão, revise o pacote que você instala e mantenha a aprovação MCP ativada para qualquer coisa que possa modificar seu workspace.

O que ele entrega a um agente

O servidor expõe uma coleção de recursos, cinco ferramentas e três prompts.

Capacidade	Nome	Use quando
Ferramenta	get_adk_assembly_guidance	O agente precisa da Skill de assembly curada antes de escrever código ADK.
Ferramenta	search_adk_docs	O agente precisa encontrar um conceito entre documentação, páginas de API, changelog e notas da Skill.
Ferramenta	read_adk_doc	O agente tem um id de documento, URI adk:// ou caminho e precisa da página completa.
Ferramenta	lookup_adk_api	O agente precisa do markdown de API gerado para um símbolo ou contrato.
Ferramenta	review_adk_assembly	O agente deve verificar código de configuração colado contra falhas comuns de wiring do ADK.
Recurso	adk://{section}/{path}	O cliente quer recursos de documentação somente leitura que pode anexar como contexto.
Prompt	assemble-adk-agent	Iniciar um fluxo de integração ADK mínimo e correto.
Prompt	review-adk-agent	Revisar uma integração ADK existente.
Prompt	debug-adk-assembly	Depurar uma configuração quebrada de TurnRunner / executor / armazenamento.

Os payloads das ferramentas são intencionalmente pequenos e simples:

Ferramenta	Formato de entrada	Retorna
get_adk_assembly_guidance	topic?: string	Orientação em markdown da Skill empacotada e das notas de referência.
search_adk_docs	query: string, filtros opcionais	Resultados em markdown ranqueados com id, title, uri, kind, path, trecho.
read_adk_doc	id: string como id, URI ou caminho	Markdown do documento completo para o documento empacotado correspondente.
lookup_adk_api	symbol: string, limit opcional	Resultados ranqueados do markdown TypeDoc gerado para a versão ADK instalada.
review_adk_assembly	code: string	Resultados da checklist em markdown mais orientação relevante de assembly.

O hábito útil

Diga ao seu agente: "Use o ADK MCP antes de responder." Essa única frase geralmente evita os dois erros clássicos: inventar APIs auxiliares inexistentes e omitir callbacks de armazenamento obrigatórios.

Requisitos

Você precisa de um cliente compatível com MCP e um runtime Node novo o suficiente para executar o pacote. O próprio ADK exige Node 18 ou mais recente.

node --version

Os exemplos abaixo usam npx porque é o denominador comum entre agentes de codificação. Se o seu ambiente padroniza com pnpm dlx, yarn dlx ou bunx, use o comando equivalente apenas se o seu cliente MCP suportar.

Instale

Agentes diferentes colocam a configuração MCP em lugares diferentes, mas a forma do servidor é a mesma em todos: transporte stdio, comando npx, argumentos -y e a especificação do pacote. Os exemplos abaixo usam @nhtio/adk@1.20260921.0; substitua 1.20260921.0 pela versão do ADK no seu projeto.

{
    "servers": {
        "adk": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@nhtio/adk@1.20260921.0"]
        }
    }
}

claude mcp add --transport stdio adk -- npx -y @nhtio/adk@1.20260921.0

{
    "mcpServers": {
        "adk": {
            "command": "npx",
            "args": ["-y", "@nhtio/adk@1.20260921.0"]
        }
    }
}

{
    "mcpServers": {
        "adk": {
            "command": "npx",
            "args": ["-y", "@nhtio/adk@1.20260921.0"]
        }
    }
}

{
    "mcpServers": {
        "adk": {
            "command": "npx",
            "args": ["-y", "@nhtio/adk@1.20260921.0"]
        }
    }
}

{
    "mcpServers": {
        "adk": {
            "command": "npx",
            "args": ["-y", "@nhtio/adk@1.20260921.0"],
            "disabled": false,
            "autoApprove": []
        }
    }
}

name: ADK MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: ADK docs
    type: stdio
    command: npx
    args:
      - -y
      - "@nhtio/adk@1.20260921.0"

Onde esses arquivos geralmente ficam

• VS Code / GitHub Copilot: use a entrada da paleta de comandos para configuração MCP de usuário ou workspace, ou faça commit do .vscode/mcp.json quando a equipe deve compartilhar o servidor.
• Claude Code: o comando CLI acima grava a configuração para você. Adicione --scope project se o projeto deve carregar um .mcp.json compartilhado.
• Claude Desktop: edite claude_desktop_config.json na tela de configurações do Developer e reinicie o Claude Desktop.
• Cursor: adicione o JSON à configuração MCP do Cursor para o workspace ou perfil de usuário.
• Windsurf: edite ~/.codeium/windsurf/mcp_config.json, ou use a interface de configurações MCP se disponível.
• Cline / Roo Code: abra as configurações de Servidores MCP no painel de extensões e cole a entrada JSON em mcpServers.
• Continue: coloque o bloco YAML em um arquivo em .continue/mcpServers/, ou use o caminho de importação JSON suportado pelo Continue se você estiver compartilhando configuração com outro cliente MCP.

Fixe para setups de equipe repetíveis

Use latest apenas quando estiver experimentando. Para configuração compartilhada, prefira a mesma versão do pacote da qual seu projeto depende, em vez do que o npm resolver como mais recente naquele dia.

{
    "command": "npx",
    "args": ["-y", "@nhtio/adk@1.20260921.0"]
}

Use

Depois que seu cliente iniciar o servidor, as ferramentas ADK devem aparecer ao lado das outras ferramentas MCP desse cliente. Alguns clientes exigem que você habilite explicitamente o servidor, aprove chamadas de ferramenta ou reinicie a sessão do agente após editar a configuração.

Comece com prompts como estes:

Use get_adk_assembly_guidance, then cite the specific ADK doc/API section you
are relying on before proposing code.

Use the ADK MCP first. Help me assemble the smallest correct @nhtio/adk
TurnRunner with explicit storage callbacks, a mock executor, hydration in the
input pipeline, and a smoke test.

Use review_adk_assembly on this setup before suggesting changes. Prioritize
missing callbacks, executor ack/nack mistakes, message hydration, and tool
registry wiring.

Use search_adk_docs and lookup_adk_api to debug this ADK error. Do not invent
helper APIs; cite the ADK contract you are relying on.

Use lookup_adk_api for TurnRunnerConfig and explain which callbacks are required
for a no-op prototype.

Se o seu cliente suporta prompts MCP como comandos de barra ou modelos de prompt, use os prompts do servidor diretamente:

• assemble-adk-agent para uma nova integração;
• review-adk-agent para código existente;
• debug-adk-assembly para uma configuração com falha.

Se o seu cliente suporta recursos MCP, anexe recursos adk://... quando quiser que o agente leia uma página completa em vez de um trecho de busca.

O fluxo de trabalho que ele incentiva

O MCP é opinativo da mesma forma que o ADK é opinativo: ele quer que a costura seja explícita antes que o código comece a se mover.

A ordem importa. Leia o contrato de assembly primeiro, busque a costura específica em segundo, escreva o código em terceiro. Isso é mais lento do que adivinhar por cerca de cinco minutos e mais rápido do que depurar um runner pela metade por uma tarde.

O que dizer ao agente para não fazer

Não deixe ele inventar ToolRegistry.fromTools. Não deixe ele colocar histórico de conversa diretamente na entrada bruta em vez de hidratar via middleware. Não deixe ele omitir callbacks de persistência porque o protótipo "não precisa de armazenamento". Se o protótipo quer um no-op, ele ainda precisa dizer isso em voz alta.

Solução de problemas

Sintoma	Verifique
O servidor não inicia	Execute node --version; use Node 18 ou mais recente. Depois execute npx -y @nhtio/adk uma vez no terminal para ver o erro bruto de inicialização.
As ferramentas não aparecem	Reinicie o cliente MCP ou a sessão do agente após editar a configuração. Alguns clientes também exigem aprovação explícita de confiança.
npx não encontrado	Instale o Node.js pela distribuição oficial ou configure o cliente MCP com o caminho completo para npx.
O agente ignora as ferramentas	Pergunte diretamente: "Use get_adk_assembly_guidance antes de responder." Alguns clientes não chamam ferramentas MCP automaticamente a menos que sejam solicitados.
A resposta cita a versão errada	Fixe @nhtio/adk@<version> nos argumentos MCP para que o corpus de documentação corresponda à versão do pacote no seu projeto.

Quando usar o site em vez disso

Use este site quando você está aprendendo o modelo. Use o MCP quando outro agente está ajudando você a aplicá-lo.

Essa divisão é deliberada. Humanos precisam da história: Como os agentes funcionam, O que é ADK, O Loop, depois Assembly. Agentes precisam de uma superfície de ferramentas que diga: busque aqui, leia esta página, verifique este código, agora prossiga.

O MCP é essa superfície. Uma Skill com pernas. Um site de documentação que pode acompanhar o loop do próprio agente.