yabadoo-mcp

MCP Server oficial do Yabadoo — conecta qualquer Claude (claude.ai, celular, Desktop, Claude Code) ao seu segundo cérebro.

Como conectar (recomendado: servidor remoto, sem instalar nada)

O Yabadoo expõe um servidor MCP remoto (Streamable HTTP) em https://api.yabadoo.io/api/v1/mcp. Gere uma API Key em app.yabadoo.io → Configurações → API Keys e escolha o cliente:

Este pacote (yabadoo-mcp) é a alternativa local/STDIO: conecta por REST à API; também exige rede e backend. As tools são as mesmas (paridade travada por teste).

Paginação (0.10.0)

consultar_eventos, buscar_por_relacao e consultar_decisoes aceitam limite e offset (defaults 15/30/20, máximo 100). A resposta informa faixa/total e a chamada para a próxima página. Decisões vêm em ordem de criação, com estado vigente/histórico por item. consultar_entidade continua um resumo com orientação para aprofundar cada seção. Requer o backend da Task 559; esta versão também inclui o undo por procedência da 557 (0.9.1 não publicada).

Encadeamento de entidades (Task 561)

listar_entidades(busca='nome ou alias') aceita termos literais, sem diferença de caixa ou acentos, combinados com tipo/limite/offset. O total é do filtro, não da página. consultar_entidade fornece entity_id; resultados graph-only fornecem node_key. Use o ID exato em obter_entidade(slug=...) e o graph_node.node_key retornado em vizinhanca. graph_link.status explicita vínculo ausente, ambiguidade ou conflito; não invente uma chave nem confunda nó sem vínculo com entidade inexistente. Requer o backend da 561.

Correções de contrato (0.11.1 — requer backend 562/563/565/566/567)

Use 0.11.1 ou superior: 0.11.0 aceitava SDK MCP 2.x incompatível em instalação limpa. O pacote usa o SDK 1.x (mcp<2); discovery STDIO do wheel é testado antes de publicar.

Tarefas rejeitam título vazio, prioridade desconhecida, ID inválido e datas fora de YYYY-MM-DD. obter_entidade aceita limite/offset/secao; siga proximas_chamadas por seção. compacto=True omite metadados nulos/confidence high, preservando conteúdo e handles; default mantém campos. 500 é teto de itens, não quantidade garantida: existe budget de ~64KB (um item indivisível pode exceder). Busca semântica tem piso de relevância; vazio não prova ausência. Confira o documento antes de afirmar. Continuam 46 tools e 4 prompts: cancelar lembrete, desfazer decisão e editar/remover inbox ainda não são cobertos.

Alternativa local (STDIO)

pip install yabadoo-mcp
# ou, sem instalar:
uvx yabadoo-mcp

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "yabadoo": {
      "command": "uvx",
      "args": ["yabadoo-mcp"],
      "env": {
        "YABADOO_API_URL": "https://api.yabadoo.io",
        "YABADOO_API_KEY": "sk-yaba-sua-chave-aqui"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add yabadoo \
  --env YABADOO_API_URL=https://api.yabadoo.io \
  --env YABADOO_API_KEY=sk-yaba-sua-chave-aqui \
  -- uvx yabadoo-mcp

Ou no .mcp.json do projeto (compartilhável via git — sem a key, use variável de ambiente).

O método: prompts do servidor

O servidor expõe 4 prompts que aparecem como slash commands no cliente (no Claude Code: /mcp__yabadoo__bom-dia):

Tools (46)

Busca e leitura

Documentos

Read-layer cru (JSON exaustivo)

Escrita aditiva (sem confirmação)

adicionar_evento.data aceita dia válido YYYY-MM-DD ou ausência. Resolva datas relativas no contexto antes de chamar; não invente dia para mês/ano. data_invalida não cria ficha nem grava aquele item; em lote os válidos continuam. Leia erros mesmo quando ok=true. Datas antigas continuam intactas; o dossiê ordena as interpretáveis e sinaliza as desconhecidas.

Corretivas (procedência e toggles do dono)

Undo de conteúdo criado via MCP é livre no tenant. Edição/merge/lixeira e undo de outras origens exigem Configurações → API Keys (2 toggles, desligados por padrão). Ler a lixeira é livre.

Variáveis de ambiente (modo local)

Desenvolvimento local

cd apps/mcp
uv sync --extra test
uv run pytest tests/ -v

# rodar contra a API local
YABADOO_API_KEY=sk-yaba-... YABADOO_API_URL=http://localhost:8000 uv run yabadoo-mcp

Instalação direto do repositório (sem PyPI):

uvx --from "git+https://github.com/HENRIQUE4345/yabadoo-brain#subdirectory=apps/mcp" yabadoo-mcp