Metadata-Version: 2.5
Name: yabadoo-mcp
Version: 0.8.0
Summary: MCP Server para o Yabadoo — segundo cérebro pessoal conectado ao Claude
Project-URL: Homepage, https://yabadoo.io
Project-URL: Repository, https://github.com/HENRIQUE4345/yabadoo-brain
Author-email: Yabadoo <contato@pique.digital>
License: MIT
License-File: LICENSE
Keywords: ai,claude,mcp,second-brain,yabadoo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# yabadoo-mcp

MCP Server oficial do [Yabadoo](https://yabadoo.io) — 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:

| Cliente | Como |
|---------|------|
| **Claude.ai / celular / Claude Desktop** | Configurações → Conectores → Adicionar conector personalizado → URL `https://api.yabadoo.io/api/v1/mcp?token=sk-yaba-sua-chave` (a key vai na URL: trate o link como senha) |
| **Claude Code** | `claude mcp add --transport http yabadoo https://api.yabadoo.io/api/v1/mcp --header "Authorization: Bearer sk-yaba-sua-chave"` |
| **Cursor / outros clientes MCP** | URL acima com o header `Authorization: Bearer sk-yaba-...` |

Este pacote (`yabadoo-mcp`) é a alternativa **local/STDIO**: útil sem acesso ao servidor remoto ou pra rodar do checkout do repositório. As tools são as mesmas (paridade travada por teste).

## Alternativa local (STDIO)

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

### Claude Desktop

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

```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)

```bash
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`):

| Prompt | O que faz |
|--------|-----------|
| `bom-dia` | Briefing do dia: estado do cérebro, pendências (atrasadas primeiro), ontem, o que entrou |
| `encerrar-sessao` | Extrai desta conversa fatos/relações/eventos/decisões/tarefas/memórias e grava com dedup |
| `registrar-reuniao` | Transforma transcrição/notas em fatos, relações, eventos, decisões, tarefas e ata |
| `faxina` | Acha duplicatas, fatos errados e memórias repetidas e propõe correções |

## Tools (46)

### Busca e leitura

| Tool | O que faz |
|------|-----------|
| `buscar_memorias` | Busca global: docs, tarefas, memórias, nós do grafo e entidades (com handles pra encadear) |
| `buscar_conhecimento` | Busca semântica (vetorial) no conteúdo dos documentos |
| `buscar_grafo` | Conexões Zettelkasten a partir de termo, título, tag ou node_key |
| `consultar_entidade` | Dossiê de pessoa/empresa/projeto por nome (homônimos viram lista pra escolher) |
| `consultar_eventos` | Reuniões/eventos do grafo por período ISO e/ou tema |
| `buscar_por_relacao` | Pares de entidades por verbo de relação |
| `estado_do_cerebro` | Retrato numérico do cérebro: contagens, temas, último diário, lixeira, dia local |

### Documentos

| Tool | O que faz |
|------|-----------|
| `listar_documentos` | Lista paginada (JSON) por categoria/status/busca, com preview |
| `ler_documento` | Documento INTEIRO por id, caminho indexado ou título |
| `criar_documento` | Cria doc pela pipeline completa (embedding + nó no grafo) |
| `atualizar_documento` / `arquivar_documento` | Corretivas (toggle do dono) |

### Read-layer cru (JSON exaustivo)

| Tool | O que faz |
|------|-----------|
| `dump_grafo` | Nós + arestas do grafo, paginado |
| `listar_entidades` / `obter_entidade` | Entidades do store; detalhe por slug (fatos, eventos, relações, histórico) |
| `vizinhanca` | Adjacência crua de um nó, até N hops |
| `listar_fatos` / `listar_eventos` / `listar_memorias` | Fatos, eventos de entidade e memórias, paginados |

### Escrita aditiva (sem confirmação)

| Tool | O que faz |
|------|-----------|
| `adicionar_fato` / `adicionar_relacao` / `adicionar_evento` / `adicionar_memoria` | Escrita estruturada; lote via `itens`; ancore por `entity_id` |
| `capturar_inbox` | Pensamento cru no inbox (o dono tria depois) |
| `anotar_diario` | Notas manuais e/ou humor no dia |
| `registrar_decisao` / `consultar_decisoes` | Decisão como nó com histórico (supersede) |
| `criar_action_item` / `concluir_action_item` / `atualizar_action_item` / `deletar_action_item` / `listar_action_items` | CRUD de tarefas (com notas e subitens) |
| `criar_lembrete` / `listar_lembretes` | Lembretes no WhatsApp (planos pagos) |
| `buscar_diario` / `buscar_inbox` | Diário (por período) e inbox |

### Corretivas (gated pelo dono)

Ligadas em **Configurações → API Keys** (2 toggles, desligados por padrão):

| Tool | O que faz |
|------|-----------|
| `mesclar_entidade` | Funde duplicatas (store + grafo, histórico preservado) |
| `invalidar_fato` / `invalidar_evento` / `remover_relacao` | Retração: sai do vivo, vai pro histórico, nunca volta |
| `editar_entidade` | Descrição, aliases e tipo |
| `deletar_entidade` / `restaurar_entidade` / `listar_lixeira` | Lixeira de 30 dias; purga permanente em 2 passos (toggle 2) |
| `editar_memoria` / `apagar_memoria` | Memórias do user_memory |

## Variáveis de ambiente (modo local)

| 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` (escritas 120) |

## Desenvolvimento local

```bash
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):

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