# vault-mcp-server

MCP server genérico pra consultar e alimentar um vault Obsidian (ou qualquer
pasta de arquivos `.md`). Não sabe nada sobre a estrutura de nenhum vault
específico — isso é responsabilidade do `AGENTS.md`/convenções de cada vault,
lido pelo agente que usa as tools, não codificado aqui.

## Ferramentas

| Módulo | Ferramenta | Descrição |
|---|---|---|
| Busca | `search_notes(query, subfolder=None, max_results=None)` | Busca texto (regex, cai pra literal se inválido) em `.md`, opcionalmente só numa subpasta |
| Busca | `search_by_tag(tag, subfolder=None)` | Busca notas com a tag no frontmatter (`tags:`) ou inline (`#tag`) |
| Busca | `get_backlinks(path)` | Notas que linkam pra essa via `[[wikilink]]` |
| Leitura | `read_note(path)` | Conteúdo bruto de uma nota (frontmatter incluso) |
| Leitura | `list_notes(subfolder=None)` | Lista recursiva de `.md` com frontmatter de preview |
| Leitura | `list_folders(subfolder=None)` | Subpastas de um nível |
| Leitura | `get_note_metadata(path)` | Só o frontmatter parseado |
| Escrita | `write_note(path, content, mode="append")` | Cria (`mode="create"`, falha se já existir) ou concatena (`mode="append"`, cria se não existir) |
| Escrita | `rename_note(path, new_filename)` | Renomeia, mesma pasta |
| Escrita | `move_note(path, new_path)` | Move/renomeia pra qualquer caminho no vault |
| Escrita | `delete_note(path)` | Soft delete — move pra `.trash/`, não apaga de verdade |

**Limitação conhecida:** `rename_note`/`move_note` não reescrevem
`[[wikilinks]]` que outras notas tenham pra elas (diferente do Obsidian, que
faz isso automaticamente pela UI). Rode `get_backlinks` antes de renomear pra
saber o que pode quebrar.

**`write_note` não faz git.** Só grava o arquivo — commit/push continua
manual (mesmo fluxo que o `AGENTS.md` de cada vault já deve documentar pra
agentes com acesso a shell).

## Variáveis de ambiente

| Variável | Default | Faz |
|---|---|---|
| `VAULT_MCP_ROOT` | `~/vault` | Raiz do vault a servir — trocar aponta pra qualquer outro vault |
| `VAULT_MCP_SEARCH_MAX_RESULTS` | `50` | Limite de resultados de busca (1-500) |
| `VAULT_MCP_SEARCH_CONTEXT_CHARS` | `120` | Tamanho do trecho retornado por match (20-1000) |
| `VAULT_MCP_WRITE_MAX_CHARS` | `20000` | Limite de tamanho de conteúdo em `write_note` (1-200000) |
| `VAULT_MCP_BLOCKED_FOLDERS` | (vazio) | CSV de pastas de topo extras a bloquear pra leitura/escrita, além de `.git`/`.obsidian`/`.trash` (sempre bloqueados) |

## Segurança

Todo caminho é resolvido e validado contra escapar da raiz do vault (sem
`..`, sem caminho absoluto fora do vault). Só arquivos `.md` são
lidos/escritos. Pastas de topo em `VAULT_MCP_BLOCKED_FOLDERS` (+ as três
padrão) ficam fora tanto de leitura quanto de escrita.

## Registro

Pra este vault específico (`~/vault`), bloqueando também `_scripts/` (é
tooling, não notas):

```
claude mcp add --scope user vault \
  --env VAULT_MCP_ROOT=$HOME/vault \
  --env VAULT_MCP_BLOCKED_FOLDERS=_scripts \
  -- uv run --directory ~/dev/pessoal/vault-mcp-server server.py
```

`--scope user` deixa disponível em qualquer sessão do Claude Code, em
qualquer repo — não só quando se está dentro do vault. O mesmo binário serve
qualquer outro vault só trocando `VAULT_MCP_ROOT`.

Codex CLI ainda não está instalado nesta máquina; quando estiver, o mesmo
servidor se registra via entrada `mcp_servers` no `config.toml` do Codex,
apontando pro mesmo comando (`uv run --directory ... server.py`) com as
mesmas env vars.