# Olist MCP

Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) open source e auto-hospedável para a **API V2 do Olist ERP (Tiny)**. Funciona por `stdio`, portanto pode ser usado pelo Codex, Claude Desktop e qualquer cliente/harness compatível com MCP.

> A API V2 permanece funcional, mas a Olist informa que ela não receberá novos recursos. Este projeto usa a documentação pública V2, pois não há especificação OpenAPI publicada.

## Recursos

- Uma ferramenta MCP individual para cada um dos **92 endpoints REST V2** que a documentação pública apresenta com URL REST, como `olist_produto_obter`, `olist_nota_fiscal_pesquisa` e `olist_conta_receber_baixar`;
- Schemas de entrada e descrições dos parâmetros extraídos da página oficial de cada serviço;
- Proteção contra escrita: ferramentas que incluem, alteram, atualizam, baixam, lançam, estornam, emitem, excluem, cancelam, geram, enviam ou concluem exigem `confirmar: true`.

As chamadas são feitas por `POST` com `application/x-www-form-urlencoded`, incluindo `token` e `formato=JSON`, exatamente no formato apresentado pela documentação V2.

## Pré-requisitos

- Node.js 20 ou superior;
- um token da API Olist/Tiny, gerado no ERP. Não envie esse token em conversas nem o versiona em arquivos.

## Instalação e execução local

```bash
git clone <URL_DESTE_REPOSITORIO> olist-mcp
cd olist-mcp
npm install
npm run build
export OLIST_API_TOKEN='seu-token'
npm start
```

O processo não abre porta HTTP: o cliente MCP inicia o executável e conversa por entrada/saída padrão. Para desenvolvimento, use `npm run dev`.

Para instalar globalmente após publicar o pacote no npm, o comando será `npm install -g olist-mcp`; até lá, prefira apontar o harness para o `dist/index.js` deste clone.

## Configuração no Codex

Depois do `npm run build`, adicione uma entrada ao arquivo de configuração MCP do Codex (substitua o caminho absoluto e o token):

```toml
[mcp_servers.olist]
command = "node"
args = ["/caminho/absoluto/olist-mcp/dist/index.js"]

[mcp_servers.olist.env]
OLIST_API_TOKEN = "seu-token"
```

Reinicie a sessão do Codex. Nunca use `npm start` como `command`: MCP precisa iniciar o processo diretamente, sem um shell intermediário.

## Configuração no Claude Desktop

No arquivo de configuração do Claude Desktop, inclua (ou mescle) o bloco abaixo:

```json
{
  "mcpServers": {
    "olist": {
      "command": "node",
      "args": ["/caminho/absoluto/olist-mcp/dist/index.js"],
      "env": {
        "OLIST_API_TOKEN": "seu-token"
      }
    }
  }
}
```

Reinicie o Claude Desktop após salvar. Em Windows, use barras duplas no caminho JSON, por exemplo `C:\\Projetos\\olist-mcp\\dist\\index.js`.

## Qualquer outro harness MCP

Configure um transporte `stdio` com:

```text
command: node
args: ["/caminho/absoluto/olist-mcp/dist/index.js"]
env: { OLIST_API_TOKEN: "seu-token" }
```

## Ferramentas, schemas e atualização do catálogo

Não há uma ferramenta genérica: cada endpoint REST documentado vira uma ferramenta MCP própria. Os campos obrigatórios, tipos (`string`, `int`, `decimal` e objeto JSON) e descrições vêm da tabela “Parâmetros do serviço” de sua página oficial. `token` e `formato` não aparecem no schema porque o servidor os inclui automaticamente.

Para atualizar o catálogo quando a Olist modificar a documentação:

```bash
npm run generate:catalog
npm run check && npm test && npm run build
```

O gerador salva o resultado versionado em `src/generated/catalog.ts`; portanto a instalação normal não precisa acessar a internet. Das 127 páginas `api2-*` referenciadas no índice atual, 92 expõem uma URL REST e geram ferramentas. As demais são páginas explicativas (limites, token, webhooks, fluxos ou tabelas auxiliares), não endpoints invocáveis.

Operações de escrita requerem `confirmar: true`, mesmo que o agente já tenha recebido instrução em linguagem natural. Esse é um último guard rail; ele não substitui a revisão dos parâmetros pelo usuário.

## Endpoints e documentação

A Olist publica a lista de serviços e páginas individuais em HTML, no padrão `https://tiny.com.br/api-docs/api2-*`. Como não existe um OpenAPI oficial, este servidor não tenta inventar schemas para todos os endpoints: a ferramenta genérica encaminha os parâmetros documentados e os atalhos cobrem as consultas mais frequentes.

Referências oficiais:

- [Índice da API V2](https://tiny.com.br/api-docs/)
- [Informações da conta](https://tiny.com.br/api-docs/api2-info)
- [Pesquisa de contatos](https://tiny.com.br/api-docs/api2-contatos-pesquisar)
- [Pesquisa de produtos](https://tiny.com.br/api-docs/api2-produtos-pesquisar)
- [Pesquisa de pedidos](https://tiny.com.br/api-docs/api2-pedidos-pesquisar)

## Desenvolvimento

```bash
npm test
npm run check
npm run build
```

Para testes automatizados, defina `OLIST_API_BASE_URL` para um mock/proxy local, se necessário. Não há telemetria e o token só é usado na chamada à API Olist.

## Licença

[MIT](LICENSE).