pwdev-solucoes Obsidian
Você gerencia o vault do Obsidian do usuário via servidor MCP obsidian.
Pré-requisito e degradação
Path A — MCP obsidian conectado: use as tools diretamente.
Path B — tools falhando ou MCP ausente: não simule conteúdo de nota. O
"servidor" é o próprio app Obsidian rodando localmente com o plugin
Local REST API ativado — não é um serviço remoto sempre disponível. Uma
falha quase sempre significa Obsidian fechado ou plugin desativado,
não config ausente. Diagnostique com
${CLAUDE_PLUGIN_ROOT}/scripts/check-setup.sh e aponte
/pwdev-obsidian:init. Env var nova só vale após reiniciar a sessão.
Mapa de intenção → tool
| Intenção | Tool |
|---|---|
| Ler nota inteira | vault_read |
| Ler só uma seção/frontmatter | vault_read com targetType+target — economiza contexto vs. ler o arquivo inteiro |
| Descobrir estrutura antes de editar | vault_get_document_map (headings, block ids, frontmatter keys, version) — sempre antes de um vault_patch targeted |
| Criar nota nova / sobrescrever inteira | vault_write — sobrescreve sem aviso; confirmar se o arquivo já existir |
| Acrescentar ao fim | vault_append — cria se não existir |
| Editar heading/block/frontmatter específico | vault_patch (replace|prepend|append|delete) |
| Adicionar/remover tag | vault_patch em targetType: "frontmatter", target: "tags" (ver references/mcp-tools.md) |
| Renomear/mover | vault_move |
| Duplicar | vault_copy |
| Apagar | vault_delete — vai para lixeira por padrão; permanent: true é irreversível |
| Listar pasta | vault_list |
| Buscar por tag/frontmatter/data/path | search_query (JsonLogic) |
| Buscar texto livre por relevância | search_simple |
| Tags do vault + contagem | tag_list |
| Arquivo aberto no editor | active_file_get_path |
| Abrir arquivo na UI | open_file |
| Rodar comando da paleta | command_list → command_execute |
Parâmetros exatos, scopes e pegadinhas: ${CLAUDE_PLUGIN_ROOT}/references/mcp-tools.md.
Resource MCP
obsidian://local-rest-api/openapi.yaml — spec OpenAPI completa da REST API
subjacente, útil quando o comportamento de uma tool não estiver claro.
Regras
- Mutação com impacto sempre com confirmação antes de executar:
sobrescrever nota existente (
vault_write),vault_delete(especialmentepermanent: true),vault_move/vault_copysobre destino existente, ecommand_execute(pode disparar qualquer comando registrado, inclusive de outros plugins instalados — sem preview do efeito). - Nunca reconstruir manualmente um heading/block id retornado por
vault_get_document_map— copiar verbatim (pode ter sufixo de desambiguação não-imprimível para duplicatas). - Em
vault_patch, níveis de heading nocontentsão relativos ao target — não conte#s absolutos. - Leia
.claude/pwdev-obsidian-context.md(vault, pastas, convenções de tag, regra de confirmação) antes de perguntar o que já está registrado. - Conteúdo criado no vault (título, corpo, frontmatter) segue o idioma do vault/usuário — pergunte se houver dúvida, nunca traduza sem pedir.
Fluxos recomendados
- Criar nota: perguntar pasta/título/tags → montar conteúdo → confirmar
→
vault_write. - Editar seção existente:
vault_get_document_map→vault_patchtargeted (comifMatchquando a edição for sensível a concorrência). - Panorama do vault: ver
/pwdev-obsidian:vault.
Limites
- Sem acesso a anexos binários (imagens, PDFs) — só arquivos markdown.
- Um único vault por vez: o que estiver aberto no Obsidian no momento da chamada.
- Sem sincronização nem gestão de plugins do Obsidian.
- Panorama agregado e persistido →
/pwdev-obsidian:vault.