# cerebro-mcp

Servidor **MCP** (Model Context Protocol) que expõe o seu **segundo cérebro** — a pasta de Markdown criada pelo kit [astra-2cerebro](https://github.com/inematds/astra-2cerebro) — como ferramentas para qualquer cliente MCP: **Claude Code, Codex, Claude Desktop, n8n, bots** e scripts.

Um cérebro. Vários clientes. Nenhuma cópia.

## 📖 Guia de uso

Guia completo (landing + passo a passo): **https://inematds.github.io/cerebro-mcp/guia/**

```
                     ┌──────────────┐
  Claude Code ──┐    │              │
  Codex ────────┼──► │  cerebro-mcp │ ──► ~/meu-cerebro/  (AGENTS.md, contexto/, wiki/, decisoes/ ...)
  Claude Desktop┤    │   (stdio ou  │
  n8n / bot ────┘    │    HTTP)     │
                     └──────────────┘
```

## Por quê

O kit astra-2cerebro guarda quem você é, o que faz, suas prioridades, decisões, projetos e uma wiki interligada — tudo em arquivos Markdown. Isso funciona muito bem para o agente que abre a pasta. Mas o Codex no terminal, o Claude Desktop no notebook, um fluxo no n8n e um bot no celular não abrem a pasta.

O `cerebro-mcp` resolve isso: sobe um servidor MCP apontado para a pasta e cada cliente passa a ter `cerebro_contexto`, `cerebro_buscar`, `cerebro_ler`, `cerebro_registrar_decisao` e as demais ferramentas. O cérebro continua sendo só arquivos; quem muda é quem consegue lê-los.

## Instalação em 1 minuto

Precisa de Node.js 20 ou superior.

```bash
git clone https://github.com/inematds/cerebro-mcp.git
cd cerebro-mcp
npm install
npm test                      # 42 testes contra a fixture em test/fixture

# aponte para o seu cérebro e teste por stdio
CEREBRO_DIR=~/meu-cerebro node scripts/teste-stdio.mjs ~/meu-cerebro
```

Registrar no **Claude Code** (uma linha):

```bash
claude mcp add cerebro -e CEREBRO_DIR=/caminho/do/cerebro -- node /caminho/cerebro-mcp/bin/cerebro-mcp.mjs
```

Codex, Claude Desktop, `.mcp.json` do projeto e modo HTTP: veja **[INSTALAR.md](INSTALAR.md)**.

## Como funciona

```bash
cerebro-mcp [--dir <pasta>] [--escrita] [--http <porta>] [--host <ip>]
```

| Configuração | Como | Padrão |
|---|---|---|
| Pasta do cérebro | `--dir <pasta>` ou `CEREBRO_DIR` | pasta atual, se tiver `AGENTS.md` ou `CLAUDE.md`; senão erro claro |
| Escrita | `--escrita` ou `CEREBRO_ESCRITA=1` | desligada (somente leitura) |
| Transporte | `--http <porta>` | stdio |
| Endereço HTTP | `--host <ip>` | `127.0.0.1` |

Sem `--http` o servidor fala MCP por **stdio** — é o que Claude Code, Codex e Claude Desktop usam. Com `--http` ele sobe um endpoint **Streamable HTTP** (`POST /mcp`, sem sessão) para n8n, bots e scripts na mesma máquina.

## Ferramentas

| Ferramenta | O que faz | Escrita? |
|---|---|---|
| `cerebro_contexto()` | `contexto/sobre-mim.md` + `sobre-o-trabalho.md` + `prioridades.md`, concatenados com os caminhos | não |
| `cerebro_prioridades()` | Só `contexto/prioridades.md` | não |
| `cerebro_rotas()` | A seção "Mapa de rotas" do `AGENTS.md` (ou `CLAUDE.md`) | não |
| `cerebro_buscar(consulta, limite?)` | Busca por termos em todos os `.md` (título > caminho > wikilinks > frontmatter > corpo), com trecho | não |
| `cerebro_ler(caminho)` | Conteúdo de um arquivo (ou listagem de uma pasta) dentro do cérebro | não |
| `cerebro_wiki_indice()` | `wiki/index.md` | não |
| `cerebro_wiki_pagina(slug)` | Página da wiki pelo slug, em `entidades/`, `conceitos/` ou `fontes/` | não |
| `cerebro_projetos()` | Cada `projetos/<nome>/README.md` com a linha de estado | não |
| `cerebro_conexoes()` | A tabela de `conexoes.md` | não |
| `cerebro_rotinas(limite?)` | Rotinas ativas e últimas execuções de `rotinas/registro.md` | não |
| `cerebro_registrar_decisao(titulo, decisao, porque, alternativas?, responsavel?)` | Acrescenta entrada datada em `decisoes/registro.md` | **sim** |
| `cerebro_adicionar_fonte(nome, conteudo)` | Grava `fontes/AAAA-MM-DD-<slug>.md` sem sobrescrever | **sim** |
| `cerebro_registrar_execucao(id, resultado, saida?, observacao?)` | Nova linha no topo do "Registro de execuções" | **sim** |

As três de escrita só aparecem quando o servidor sobe com `--escrita`. Detalhes, parâmetros e exemplos de retorno: **[docs/ferramentas.md](docs/ferramentas.md)**.

Além das ferramentas, cada `.md` é exposto como **recurso** `cerebro://<caminho>` (por exemplo `cerebro://wiki/entidades/empresa-x.md`), para clientes que preferem "anexar" uma nota.

## Exemplos de conversa

Com o servidor registrado, o agente decide sozinho quando chamar cada ferramenta.

> **Você:** Quais são as minhas prioridades deste trimestre?
> **Agente:** *(chama `cerebro_prioridades`)* Três, segundo `contexto/prioridades.md`: entregar a fase 2 do Projeto Alfa até o fim de outubro, lançar o site novo e reduzir o relatório semanal de 4 horas para 1.

> **Você:** Por que decidimos fazer o site em gerador estático?
> **Agente:** *(chama `cerebro_buscar("site estático")`, depois `cerebro_ler("decisoes/registro.md")`)* Em 2026-08-20 você registrou: custo zero e pouca manutenção; mudaria de ideia se precisasse de área logada.

> **Você:** Registra que vamos aceitar a fase 2 com prazo em outubro.
> **Agente:** *(servidor com `--escrita`; chama `cerebro_registrar_decisao`)* Registrado em `decisoes/registro.md` com a data de hoje. Quer que eu anote as alternativas consideradas?

> **Você:** O que a Empresa X pediu na última reunião?
> **Agente:** *(chama `cerebro_wiki_pagina("empresa-x")`, segue os links para a fonte)* Aprovou o escopo da fase 2 e ficou de definir quem valida os relatórios semanais.

## Segurança

- **Leitura por padrão.** Sem `--escrita`, as ferramentas de escrita nem são registradas — o cliente não as vê. E mesmo com elas registradas, o núcleo confere a flag de novo antes de gravar.
- **Só dentro da pasta.** Todo caminho passa por `caminhoSeguro`: resolve, confere o prefixo, segue symlinks e confere de novo. `../`, caminhos absolutos de fora e links apontando para fora são recusados.
- **`.env`, `.git` e `node_modules` são invisíveis**, mesmo para leitura.
- **HTTP só em `127.0.0.1`** por padrão, sem autenticação. Se expor em outra interface, coloque um proxy com autenticação na frente — e lembre que um cérebro contém dados pessoais.
- **Nada sai da máquina.** O servidor não faz requisições externas.

Detalhes em **[docs/seguranca.md](docs/seguranca.md)**.

## Testes

```bash
npm test            # node --test: núcleo, escrita e servidor (cliente MCP em memória)
npm run teste:stdio # sobe o binário de verdade e conversa em JSON-RPC por stdio
npm run teste:http  # sobe --http em porta livre e faz as chamadas que um n8n faria
```

Resultado real da fumaça por stdio (`node scripts/teste-stdio.mjs`, contra `test/fixture`):

```
[servidor] [cerebro-mcp] pronto por stdio — cérebro em .../test/fixture (escrita desligada)
OK  initialize → servidor cerebro-mcp 1.0.0 (protocolo 2025-06-18)
OK  tools/list → 10 ferramentas: cerebro_contexto, cerebro_prioridades, cerebro_rotas, cerebro_buscar, cerebro_ler, cerebro_projetos, cerebro_conexoes, cerebro_rotinas, cerebro_wiki_indice, cerebro_wiki_pagina
OK  tools/call cerebro_buscar → 2 resultado(s) para "empresa x":
OK  tools/call cerebro_rotas → seção encontrada
OK  tools/call cerebro_ler ../../etc/passwd → isError (Erro: Acesso negado: "../../etc/passwd" está fora do cérebro.)
OK  resources/list → 27 recursos cerebro://
```

Com `--escrita`, o `tools/list` devolve 13 ferramentas (as 10 acima mais `cerebro_registrar_decisao`, `cerebro_adicionar_fonte` e `cerebro_registrar_execucao`). O `npm test` cobre: busca (relevância, acentos, wikilinks, pastas ignoradas), leitura com bloqueio de traversal/symlink/`.env`, extração de rotas e prioridades, projetos, conexões, rotinas, wiki, recursos, escrita bloqueada sem `--escrita` e funcionando com ela (em cópia temporária da fixture).

## Documentação

- [INSTALAR.md](INSTALAR.md) — Claude Code, Codex, Claude Desktop, `.mcp.json`, HTTP, e instruções para um agente instalar sozinho.
- [docs/arquitetura.md](docs/arquitetura.md) — como o código está organizado.
- [docs/ferramentas.md](docs/ferramentas.md) — cada ferramenta com parâmetros, retorno e exemplo.
- [docs/seguranca.md](docs/seguranca.md) — o que é bloqueado e por quê.
- [docs/exemplos.md](docs/exemplos.md) — n8n, bot e site chamando o servidor em modo HTTP.
- [docs/faq.md](docs/faq.md) — perguntas frequentes.

## FAQ curta

**Preciso do kit astra-2cerebro?** O servidor lê a estrutura que o kit cria. Qualquer pasta com `AGENTS.md` ou `CLAUDE.md` sobe, mas as ferramentas de contexto, wiki e rotinas esperam os arquivos do kit.

**Posso apontar dois clientes para o mesmo cérebro?** Sim. Cada cliente sobe o próprio processo do servidor; todos leem a mesma pasta. Escrita simultânea é rara e as três operações só acrescentam texto.

**O servidor indexa em algum lugar?** Não. A busca varre os `.md` a cada chamada. Para cérebros com centenas de notas é instantâneo; para milhares ainda é aceitável.

**Funciona no Windows?** Sim, com Node 20+. Nos exemplos, troque os caminhos.

Mais em [docs/faq.md](docs/faq.md).

## Créditos e licença

Construído para o kit **[astra-2cerebro](https://github.com/inematds/astra-2cerebro)** — a estrutura de pastas, o formato das decisões, rotinas, conexões e wiki vêm de lá. Usa o SDK oficial `@modelcontextprotocol/sdk`.

MIT — Copyright (c) 2026 inematds.