yabadoo-mcp 0.6.0

MCP Server para o Yabadoo — segundo cérebro pessoal conectado ao Claude

yabadoo-mcp

MCP Server oficial do Yabadoo — conecta o Claude ao seu segundo cérebro pessoal.

O que é?

Com este plugin, o Claude passa a ter acesso direto ao seu cérebro no Yabadoo:

• Busca memórias — encontra documentos, notas, decisões e memórias pelo conteúdo
• Explora o grafo — vê as conexões Zettelkasten entre seus temas e projetos (aceita nome legível)
• Consulta entidades — dossiê de pessoas, empresas e projetos (fatos, linha do tempo, relações)
• Busca por relação — pares de entidades ligados por um vínculo ("quem é sócio de quem?")
• Lê action items — acessa suas tarefas pendentes e em andamento
• Cria tarefas — registra novos action items direto pelo Claude
• Vê lembretes — consulta agendamentos e automações ativas
• Captura pensamentos — envia notas e ideias para o Brain Agent processar e armazenar
• Lê o diário — acessa as entradas recentes do seu diário pessoal
• Consulta o inbox — lista capturas brutas ainda não processadas (WhatsApp, web, desktop)

Instalação

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

Configuração

1. Gere uma API Key

Acesse yabadoo.io → Settings → API Keys → Gerar nova key.

Copie a chave gerada (ela só é exibida uma vez).

2. Configure o 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"
      }
    }
  }
}

Após salvar, reinicie o Claude Desktop. As tools do Yabadoo aparecerão automaticamente.

3. Configure o 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 adicione ao .mcp.json do projeto (compartilhável via git):

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

Modo remoto (Claude.ai web)

Para usar via Claude.ai, prefira o servidor SSE oficial embutido na API do Yabadoo (não precisa rodar nada local). Se ainda assim quiser expor este pacote via HTTP:

YABADOO_API_KEY=sk-yaba-... yabadoo-mcp --http --port 8001

Atenção: o modo HTTP não tem autenticação própria — qualquer pessoa que alcance a porta opera o seu cérebro com a API key configurada. O servidor binda em 127.0.0.1 por padrão; só use --host 0.0.0.0 (ou um túnel público) atrás de uma camada de autenticação sua.

Depois adicione http://localhost:8001/sse em Claude.ai → Settings → Integrations.

Tools disponíveis

Tool	O que faz
buscar_memorias	Busca cross-layer: docs, memórias, action items e grafo
buscar_grafo	Conexões Zettelkasten a partir de termo, título, tag ou node_key
consultar_entidade	Dossiê de pessoa/empresa/projeto: fatos + timeline + relações
consultar_eventos	Reuniões/eventos por período ISO e/ou tema, com participantes e doc de origem
buscar_por_relacao	Pares de entidades por verbo de relação (sócio, mentor...)
listar_action_items	Tarefas por status (pendente/em_andamento/concluido)
criar_action_item	Cria nova tarefa com prioridade e data
concluir_action_item / atualizar_action_item / deletar_action_item	CRUD de tarefa por id
listar_lembretes	Agendamentos e automações ativas
buscar_diario	Entradas recentes do diário pessoal
buscar_inbox	Capturas brutas (não processadas) filtrando por status, canal, tipo ou conteúdo

Read-layer cru (JSON exaustivo, para navegar o cérebro programaticamente)

Tool	O que faz
dump_grafo	Nós + arestas do grafo em JSON cru, paginado (sem o trim da visualização)
listar_entidades	Todas as entidades do store (id/tipo/nome/aliases + contagens), paginado
obter_entidade	Detalhe completo de uma entidade por slug: fatos/eventos/relações + histórico bi-temporal
vizinhanca	Adjacência crua de um nó do grafo, até N hops
listar_fatos	Fatos vivos do cérebro com entidade dona + proveniência, paginado
listar_memorias	Memórias do blob user_memory ({id, content, topics}), paginado

Write-layer aditivo (o Claude do cliente escreve direto no cérebro — sem agente nosso)

Tool	O que faz
adicionar_fato	Adiciona um fato a uma entidade (que nasce implícita por slug canônico); lote via itens
adicionar_relacao	Liga duas entidades por um verbo de relação (origem → destino)
adicionar_evento	Adiciona um evento datado a uma entidade
adicionar_memoria	Grava uma memória no user_memory (o mesmo lugar da memória automática)

Escrita só aditiva (nunca apaga) e sem confirmação: leia antes (obter_entidade/listar_fatos) para não duplicar, o reconcile determinístico dedupa exatos. Mutação/delete/merge ficam no app/UI.

Variáveis de ambiente

Variável	Descrição	Padrão
YABADOO_API_KEY	Sua API key (obrigatório)	—
YABADOO_API_URL	URL da API	http://localhost:8000
YABADOO_API_TIMEOUT	Override global do timeout HTTP, em segundos	30

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