# obsidian-mcp

MCP server para Obsidian vaults — gerenciador multi-brain com templates, registry persistente, busca, CRUD, frontmatter, wikilinks e context bundling.

Funciona com **Hermes Agent** e **Claude Code** simultaneamente, compartilhando os mesmos vaults via registry cross-tool.

## Features

- **Multi-brain** — crie, remova e gerencie múltiplos vaults (cérebros) sem restart
- **Registry persistente** — `~/.obsidian-mcp/vault-registry.json` como fonte da verdade cross-tool
- **4 templates** — roteirista, genérico, pesquisa, minimal
- **22 tools MCP** — lifecycle de vaults, CRUD de notas, busca, backlinks, context bundle
- **Frontmatter-aware** — parse, serialize, update de YAML frontmatter
- **Wikilinks** — extração, resolução, backlinks automáticos
- **Installer cross-tool** — configura Hermes + Claude Code com um comando
- **124 testes** — cobertura completa (pytest)

## Instalação Rápida

```bash
# Clone o projeto
git clone https://github.com/SEU_USUARIO/obsidian-mcp.git
cd obsidian-mcp

# Instale o MCP server (Hermes + Claude Code)
uv run install.py

# Instale as skills do agente
uv run scripts/install-skills.py

# Verifique
uv run install.py --status
uv run scripts/install-skills.py --status
```

Reinicie o Hermes e/ou Claude Code após a instalação.

## Requisitos

- Python 3.10+
- [uv](https://docs.astral.sh/uv/)
- Hermes Agent e/ou Claude Code

## Tools MCP (22)

### Vault Lifecycle

| Tool | Descrição |
|------|-----------|
| `create_vault` | Cria um novo cérebro a partir de um template |
| `remove_vault` | Remove (arquiva por padrão) ou deleta um cérebro |
| `vault_status` | Status de um ou todos os cérebros |
| `list_vault_templates` | Lista templates disponíveis |

### Vault Info

| Tool | Descrição |
|------|-----------|
| `list_vaults` | Lista cérebros registrados |
| `vault_overview` | Visão estrutural (pastas, tags, recentes) |
| `vault_briefing` | Briefing legível para início de sessão |

### Notas — CRUD

| Tool | Descrição |
|------|-----------|
| `read_note` | Lê uma nota por nome |
| `create_note` | Cria nota (com template opcional) |
| `update_frontmatter` | Atualiza campos YAML sem tocar no body |
| `append_to_note` | Adiciona conteúdo ao final da nota |

### Notas — Busca

| Tool | Descrição |
|------|-----------|
| `search_notes` | Busca textual com filtros (tags, folder, status) |
| `context_bundle` | Gather completo sobre um tema (busca + wikilinks) |
| `get_backlinks` | Notas que linkam para a nota dada |

### Notas — Listagem

| Tool | Descrição |
|------|-----------|
| `list_by_tag` | Filtra notas por tag |
| `list_by_stage` | Filtra notas por etapa/status |

### Infra

| Tool | Descrição |
|------|-----------|
| `refresh_index` | Re-scan do vault (após mudanças externas) |

## Templates de Vault

| Template | Pastas | Uso |
|----------|--------|-----|
| `roteirista` | 11 | Roteiros, blog, conteúdo (estilo Ensinamentos da Vida) |
| `generico` | 6 | Conhecimento pessoal (método PARA) |
| `pesquisa` | 5 | Pesquisa acadêmica / investigação |
| `minimal` | 0 | Vault livre (só HOME.md) |

## Arquitetura

```
~/.obsidian-mcp/vault-registry.json   ← registry cross-tool (fonte da verdade)

src/obsidian_mcp/
├── server.py       ← FastMCP server + 22 tools
├── vault.py        ← VaultIndex (scan/search/CRUD) + VaultManager (lifecycle)
├── registry.py     ← VaultRegistry (JSON persistente)
├── templates.py    ← 4 templates de vault
├── frontmatter.py  ← YAML frontmatter parse/serialize/update
├── links.py        ← wikilink extraction, resolution, backlinks
└── models.py       ← Note, SearchResult, VaultOverview

skills/
├── obsidian-mcp/           ← skill MESTRE (dossiê do agente)
└── obsidian-mcp-install/   ← skill de instalação guiada

scripts/
└── install-skills.py       ← instalador de skills (Hermes + Claude Code)

install.py                  ← instalador do MCP server (Hermes + Claude Code)
```

### Fluxo de dados

```
Registry JSON → VaultManager carrega vaults → VaultIndex indexa notas
create_vault / remove_vault → atualizam registry + memória (hot-reload)
Hermes e Claude Code → leem do MESMO registry → mesmos cérebros
```

### Startup do server

Prioridade: registry → env vars (seed) → auto-discovery (seed)

## Configuração

### Hermes Agent

`~/.hermes/config.yaml`:

```yaml
mcp_servers:
  obsidian:
    command: uv
    args:
      - run
      - --project
      - C:/Users/fernando/Downloads/obsidian-mcp
      - obsidian-mcp
```

> ⚠️ `args` DEVE ser lista YAML, nunca string JSON.

### Claude Code

`~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["run", "--project", "C:/Users/fernando/Downloads/obsidian-mcp", "obsidian-mcp"]
    }
  }
}
```

### Installer

```bash
uv run install.py              # configura Hermes + Claude Code
uv run install.py --hermes     # só Hermes
uv run install.py --claude     # só Claude Code
uv run install.py --status     # mostra status
uv run install.py --remove     # remove config
```

## Skills do Agente

### obsidian-mcp (skill MESTRE)

Dossiê completo: 22 tools com exemplos, gatilhos → ações, comportamento do agente, convenções de conteúdo, segurança, pitfalls. O agente carrega essa skill pra operar o sistema sem "viajar na maionese".

### obsidian-mcp-install

Guia de instalação passo a passo para usuários leigos. Pré-requisitos, instalação automática/manual, troubleshooting, desinstalação.

### Instalar skills

```bash
uv run scripts/install-skills.py              # instala em ambos
uv run scripts/install-skills.py --hermes     # só Hermes
uv run scripts/install-skills.py --claude     # só Claude Code
uv run scripts/install-skills.py --status     # mostra status
```

## Desenvolvimento

```bash
cd obsidian-mcp

# Testes (124, ~2s)
uv run pytest -v

# Inspect server
OBSIDIAN_VAULT_PATH="C:/path/to/vault" uv run fastmcp inspect mcp_server.py:mcp

# Testar vault via Python
uv run python -c "
from obsidian_mcp.vault import VaultIndex
vi = VaultIndex('C:/path/to/vault')
print(vi.briefing())
"
```

## Pitfalls Conhecidos

1. **YAML args** — `hermes config set` escreve args como string JSON. Precisa ser lista YAML.
2. **Index stale** — mudanças via terminal/Obsidian app não atualizam o index. Chame `refresh_index`.
3. **Sem delete_note** — não existe tool de deletar nota. Use `rm` + `refresh_index`.
4. **fastmcp call** — não herda env vars do shell. Teste via Python direto.
5. **fastmcp inspect** — use `mcp_server.py` wrapper (relative imports quebram direto).

## Licença

MIT