# Bots com IA

O Claude (e outros assistentes) escreve um bot do Zynko inteiro, desde que leia a documentação
do Zynko. Sem ela, ele vai pelo que conhece de parecido, o Discord, e o código não funciona: os
opcodes, os intents, as permissões e as interações do Zynko são outros.

Esta página mostra três jeitos de dar a documentação a ele, do mais simples ao mais completo.

## 1. Numa conversa: llms.txt

Toda a documentação existe também em texto puro, feita para assistentes:

| Endereço | O que tem |
|---|---|
| [`docs.zynko.org/llms.txt`](https://docs.zynko.org/llms.txt) | O resumo: o que não confundir com o Discord, e cada página com uma linha de descrição. |
| [`docs.zynko.org/llms-full.txt`](https://docs.zynko.org/llms-full.txt) | Todas as páginas num arquivo só. |
| `docs.zynko.org/<página>.md` | Uma página em Markdown, como [`/bots/comandos.md`](https://docs.zynko.org/bots/comandos.md) ou [`/api/index.md`](https://docs.zynko.org/api/index.md). |

No [claude.ai](https://claude.ai), comece a conversa assim:

```
Leia https://docs.zynko.org/llms-full.txt e me ajude a fazer um bot do Zynko em Python
que dá as boas-vindas a quem entra no servidor e tem um comando /regras.
```

Se o assistente não consegue abrir links, baixe o `llms-full.txt` e anexe na conversa. Em
cada página daqui, o botão **Copiar para IA**, no topo, copia aquela página em Markdown.

## 2. No projeto: CLAUDE.md

No [Claude Code](https://claude.com/claude-code) (e em editores com IA, como o Cursor), um
arquivo na raiz do projeto diz ao assistente o que ele precisa saber em toda conversa. Crie um
`CLAUDE.md` (ou `AGENTS.md`) no projeto do bot:

````md
# Bot do Zynko

Este projeto é um bot para o Zynko (https://zynko.org). O Zynko lembra o Discord, mas não é:
não use discord.js, discord.py nem a API do Discord, e não deduza nada a partir deles.

- Documentação: https://docs.zynko.org/llms.txt (índice, com o link de cada página em Markdown).
  Antes de usar uma rota, evento ou função da biblioteca, confira na página dela.
- Biblioteca: `zynko` (npm). Guia: https://docs.zynko.org/bots/javascript.md
- O token fica em `ZYNKO_TOKEN`, no `.env` (fora do git). Nunca escreva um token no código,
  em logs ou em exemplos.
- Intents: só os que o bot usa (`Intents.GUILDS | Intents.MESSAGES` lê mensagens).
- Comandos com "/" são cadastrados ao conectar, com `client.setCommands([...])`, que troca a
  lista inteira.
- Limite: 10 mensagens a cada 10 s por bot. Não mande mensagens em laço.
````

Troque a linha da biblioteca se o bot for em [Python](https://docs.zynko.org/bots/python.md), [Go](https://docs.zynko.org/bots/go.md) ou
[Rust](https://docs.zynko.org/bots/rust.md).

## 3. Com ferramentas: o servidor MCP

O [MCP](https://modelcontextprotocol.io) deixa o assistente usar ferramentas. O `zynko-mcp`
dá a ele a documentação para consultar quando precisar e, com o token de um bot, a API do
Zynko: ver em que servidores o bot está, ler e mandar mensagens, ouvir os eventos do gateway
e trocar os comandos. Assim ele escreve o bot e também testa.

Precisa do [Node.js 22](https://nodejs.org) ou mais novo.

### Claude Code

Só a documentação:

```sh
claude mcp add zynko -- npx -y zynko-mcp
```

Com o token do bot, para o Claude testar:

```sh
claude mcp add zynko --env ZYNKO_TOKEN=bot_... -- npx -y zynko-mcp
```

Para deixar configurado no projeto, sem o token no arquivo, crie um `.mcp.json` na raiz. O
Claude Code troca `${ZYNKO_TOKEN}` pelo valor da variável de ambiente:

```json
{
  "mcpServers": {
    "zynko": {
      "command": "npx",
      "args": ["-y", "zynko-mcp"],
      "env": { "ZYNKO_TOKEN": "${ZYNKO_TOKEN}" }
    }
  }
}
```

### Claude Desktop

Em **Configurações › Desenvolvedor › Editar configuração**, no `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zynko": {
      "command": "npx",
      "args": ["-y", "zynko-mcp"],
      "env": { "ZYNKO_TOKEN": "bot_..." }
    }
  }
}
```

Reinicie o Claude Desktop. No Windows, se o servidor não iniciar, use
`"command": "cmd"` e `"args": ["/c", "npx", "-y", "zynko-mcp"]`.

Outros clientes MCP (Cursor, VS Code, Windsurf) usam o mesmo comando, `npx -y zynko-mcp`, com a
variável `ZYNKO_TOKEN`.

### As ferramentas

| Ferramenta | Token | O que faz |
|---|---|---|
| `docs_search` | não | Busca na documentação e devolve as seções que combinam. |
| `docs_read` | não | Lê uma página (ou uma seção dela). Sem argumentos, lista as páginas. |
| `invite_link` | não* | Monta o link de convite com as permissões escolhidas. |
| `bot_overview` | sim | O bot, os servidores e canais em que está, o que pode fazer em cada canal, os comandos e o link de convite. |
| `read_messages` | sim | Lê as mensagens de um canal. |
| `send_message` | sim | Manda uma mensagem, com cartões e botões, como o bot. |
| `watch_events` | sim | Ouve o gateway por alguns segundos e mostra os eventos que chegaram, com o JSON. |
| `commands` | sim | Mostra ou troca os comandos com "/". |
| `api_request` | sim | Qualquer rota da [API](https://docs.zynko.org/api/rotas.md), como o bot. |

\* Sem token, `invite_link` pede o id do bot.

No Claude Code, o MCP também traz o comando `/mcp__zynko__novo_bot`, que monta um projeto de
bot do zero a partir da sua ideia.

> **O MCP age como o bot, de verdade**
>
> Com o token, o que o assistente faz pelo MCP acontece nos servidores do bot: mensagens
> enviadas todos veem, e `commands` troca os comandos de verdade. Teste com um bot de testes num
> servidor seu, e leia o que o assistente vai fazer antes de aprovar cada ferramenta.
>
> Enquanto `bot_overview` e `watch_events` rodam, o bot aparece online por alguns segundos.

## O token

- Não cole o token numa conversa. Ele vai na configuração do MCP ou no `.env`, que o
  assistente usa sem precisar ver.
- Colou, ou foi parar num commit? Gere outro em [dev.zynko.org](https://dev.zynko.org): o
  antigo para de funcionar na hora.
- Use um bot só para testes enquanto desenvolve, e o token do bot de verdade só onde ele roda.