# Integração com agentes

> Conecte seu agente de código à documentação da Rogue. Busque, leia uma seção e confira a fonte por um servidor MCP de leitura.

[Página canônica](https://rogueon.ai/pt-br/docs/agent-integration)

## Conecte um cliente MCP

O endpoint público é `https://rogueon.ai/mcp`. Escolha Streamable HTTP no cliente MCP. A leitura da documentação não exige chave de API, conta, OAuth ou assinatura de modelo. Deixe o cliente negociar o protocolo; o endpoint aceita o protocolo 2026-07-28 e clientes compatíveis de 2025.

No Cursor, acrescente a entrada abaixo ao `.cursor/mcp.json` do projeto, preservando servidores existentes. Recarregue a configuração MCP e confirme a presença de `list_docs`, `search_docs` e `get_doc`. Outros editores podem usar um formato de configuração diferente para o mesmo endpoint.

**Cursor · .cursor/mcp.json**

```json
{
  "mcpServers": {
    "rogue-docs": {
      "url": "https://rogueon.ai/mcp"
    }
  }
}
```

- [Referência de configuração MCP do Cursor](https://cursor.com/docs/mcp)

## Claude Code

Execute no projeto em que quer disponibilizar a documentação. O comando registra o servidor remoto; não gera nem publica um app. Use `/mcp` no Claude Code para inspecionar a conexão. Se `rogue-docs` já estiver configurado, confira ou atualize essa entrada em vez de criar uma duplicata.

**Claude Code · terminal**

```bash
claude mcp add --transport http rogue-docs https://rogueon.ai/mcp
```

- [Referência HTTP MCP do Claude Code](https://code.claude.com/docs/en/mcp)

## Contrato das ferramentas

Todas as ferramentas aceitam `locale`: `en` ou `pt-br`, com padrão `en`. Os resultados incluem URLs de referência. Recursos Markdown também são descobertos por `resources/list` e lidos por `resources/read`.

| Ferramenta | Argumentos | Resultado |
| --- | --- | --- |
| `list_docs` | `locale?` | Catálogo com slugs, URLs, seções e hashes do conteúdo. |
| `search_docs` | `query`, `locale?`, `limit?` | Trechos ordenados por relevância e links canônicos para seções. Limite 1–16; padrão 8. |
| `get_doc` | `slug`, `locale?`, `section?` | Markdown completo ou uma seção quando seu ID é informado, com hash SHA-256. |

**get_doc · arguments**

```json
{
  "slug": "project-architecture",
  "locale": "pt-br",
  "section": "runtime-services"
}
```

## Busque → leia → verifique

1. **Encontre a fonte relevante**

   Use search_docs com uma consulta específica. A busca exige correspondência de todas as palavras, ignora acentos e retorna trechos; um trecho não é a referência completa.

2. **Leia a menor seção suficiente**

   Use o slug do documento e o ID da seção em get_doc. Omita section quando precisar do contexto completo. Preserve as condições sobre formato, runtime e disponibilidade ao resumir.

3. **Preserve a fonte e a revisão**

   Cite a URL canônica retornada e guarde o SHA-256 junto do contexto em cache. Confira o manifesto antes de reutilizar conteúdo antigo. O hash identifica conteúdo, não uma versão do produto ou data de atualização.

**Contexto de tarefa para um agente de código**

```text
Antes de alterar um projeto gerado pela Rogue:
1. Identifique o formato real do artefato pelos arquivos.
2. Busque nas docs o contrato de runtime ou exportação relevante.
3. Leia a seção com get_doc e preserve a URL canônica.
4. Separe comportamento documentado de premissas sobre este projeto.
5. Implemente a alteração solicitada e valide os critérios de aceite.
6. Relate fonte, arquivos alterados, validação e dependências pendentes.
```

## Consulte Markdown por HTTP

Cada artigo tem uma URL explícita terminada em `/markdown`. HTML e Markdown são gerados da mesma fonte; a resposta Markdown declara a URL HTML canônica. Esse caminho funciona com um cliente HTTP comum quando MCP não está disponível ou não é necessário.

**Ler a documentação de arquitetura**

```bash
curl -fsSL https://rogueon.ai/pt-br/docs/project-architecture/markdown
```

- [Arquitetura · Markdown](https://rogueon.ai/pt-br/docs/project-architecture/markdown)

## Use o hash do conteúdo no cache

O manifesto JSON usa `schemaVersion: 1` e lista `slug`, `url`, `markdownUrl`, `sha256`, quantidade de bytes e IDs de seção. O hash do documento corresponde ao corpo exato da resposta Markdown em UTF-8; hashes de seção correspondem ao Markdown daquela seção. O ETag HTTP identifica a representação do manifesto e aceita `If-None-Match` com resposta 304.

**manifest.json · HTTP**

```bash
curl -fsS -D - https://rogueon.ai/pt-br/docs/manifest.json
```

- [Abrir manifesto da documentação](https://rogueon.ai/pt-br/docs/manifest.json)

## Descoberta e corpus completo

`llms.txt` é o índice compacto de descoberta. `llms-full.txt` reúne os guias públicos nos dois idiomas. Prefira uma página ou seção nas consultas comuns; use o corpus completo quando uma tarefa offline precisar de cobertura ampla. Esses arquivos são recursos de descoberta, não regras de permissão de crawler nem garantia de ingestão.

- [llms.txt](https://rogueon.ai/llms.txt)
- [llms-full.txt](https://rogueon.ai/llms-full.txt)

## Transporte, limites e escopo

As ferramentas apenas leem conteúdo e não chamam modelos de linguagem. Seu agente de código continua tendo consumo e permissões próprios. Um Origin explícito de navegador precisa estar na lista aceita pelo servidor; clientes MCP de servidor podem conectar sem esse cabeçalho. Confira configuração e erros de protocolo antes de repetir, em vez de acrescentar credenciais que esse endpoint não exige.

| Contrato | Comportamento |
| --- | --- |
| HTTP | POST para MCP; chamadas bem-sucedidas retornam JSON. Sem stream SSE persistente, ID de sessão ou assinatura. GET retorna 405. |
| Entrada | Máximo de 16 KiB por requisição. Busca: 1–200 caracteres, até 12 palavras. Apenas slugs e IDs de seção do catálogo são aceitos. |
| Saída | Até 16 resultados de busca; máximo de 64 KiB de Markdown por documento. Falhas de validação retornam erros, sem conteúdo presumido. |
| Acesso | Somente documentação pública. Sem dados de contas, projetos privados ou ferramentas de execução, geração e publicação. |

## Guias relacionados

- [Arquitetura do projeto e do runtime](https://rogueon.ai/pt-br/docs/project-architecture)
- [Exportação e desenvolvimento externo](https://rogueon.ai/pt-br/docs/exporting)
- [Autenticação, dados e permissões](https://rogueon.ai/pt-br/docs/data-and-permissions)