Vault MCP

Um plugin do Obsidian que incorpora um servidor MCP para interagir com suas anotações usando IA.

GitHub
13
Experimente este MCPPatrocinado

Documentação

Vault MCP

Validate GitHub release Downloads

Este plugin do Obsidian incorpora um servidor MCP (Model Context Protocol) diretamente no Obsidian, fornecendo uma maneira simplificada para aplicativos interagirem com seu vault.

Somente Desktop

Instalação • Recursos • Uso • Desenvolvimento • Guia de Esquema Notas

obsidian-settings

Recursos

  • Servidor MCP Embutido: Hospeda o servidor MCP dentro do próprio Obsidian como um plugin, simplificando a configuração e melhorando o desempenho
  • Acesso ao Vault via MCP: Expõe seu vault por meio de ferramentas padronizadas
  • Suporte a Dados Estruturados: Defina esquemas personalizados para criação e validação de notas estruturadas
  • Operações de Arquivo:
    • Ler e escrever arquivos
    • Pesquisa difusa em todo o vault
    • Navegar pela estrutura do vault programaticamente
    • Armazenamento e acesso a dados estruturados
  • Configurável: Personalize configurações do servidor, disponibilidade de ferramentas e autenticação
  • Autenticação Opcional: Proteja seu servidor com autenticação opcional por token Bearer.

tool-selection

auth-settings

Contexto

O Vault MCP começou como um pequeno componente de um projeto maior que precisava de uma alternativa aos métodos tradicionais de RAG. Era necessário algo que LLMs pudessem usar para recuperar e atualizar dados estruturados e legíveis por humanos, sem depender de bancos de dados vetoriais imprevisíveis ou da imprecisão de embeddings.

Os servidores MCP existentes para Obsidian não eram uma boa opção. Eram fortemente baseados em REST, complexos e não adequados para modelos de linguagem interagirem naturalmente. Portanto, este plugin foi criado para resolver isso: uma interface leve para trabalhar com vaults do Obsidian de uma forma que é natural para LLMs e transparente para humanos.

Instalação

Plugins da Comunidade (Recomendado)

  1. Abra Configurações do Obsidian > Plugins da Comunidade
  2. Pesquise por "Vault MCP"
  3. Clique em Instalar e depois em Ativar
  4. Configure as configurações conforme necessário

Instalação Manual

  1. Baixe o zip da versão mais recente
  2. Extraia para <vault>/.obsidian/plugins/
  3. Ative nas configurações do Obsidian

Uso

Configuração Básica

  1. Ative o plugin na seção Plugins da Comunidade do Obsidian
  2. Abra as configurações do plugin para configurar:
  • Porta do Servidor (padrão: 3000)
  • Host de Ligação (padrão: 127.0.0.1; use 0.0.0.0 para acesso LAN)
  1. (Opcional) Ativar Autenticação:
    • Alterne Ativar Autenticação
    • Copie o Token de Autenticação fornecido
    • Inclua o token nos cabeçalhos HTTP: Authorization: Bearer <your_token>
  2. Clique em Reiniciar Servidor para aplicar as alterações

Métodos de Conexão

O plugin atualmente suporta apenas conexões Server-Sent Events (SSE) e StreamHTTP. Para aplicações que exigem conexões stdio (como Claude Desktop), você precisará usar um proxy. Você pode seguir o guia do Cloudflare para configurar um proxy local usando mcp-remote.

Aqui está um exemplo de claude_desktop_config.json para usar o proxy local mcp-remote.

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:<your_server_port>/sse"]
    }
  }
}

Você pode encontrar a URL correta no painel de configurações do plugin, na seção de endpoints.

Ferramentas Disponíveis

  • obsidian-mcp-read-file: Obter conteúdo de arquivos
  • obsidian-mcp-diff-edit-file: Editar arquivos usando udiff simplificado (veja abaixo)
  • obsidian-mcp-search-contents: Pesquisa difusa no conteúdo de todos os arquivos do seu vault
  • obsidian-mcp-search-filenames: Pesquisa difusa em todos os nomes de arquivos do seu vault
  • obsidian-mcp-list-files: Listar arquivos e diretórios no seu vault com profundidade e limites de resultados personalizáveis
  • obsidian-mcp-upsert-file: Criar ou atualizar arquivos
  • obsidian-mcp-rollback-edit: Reverter a última edição em um arquivo markdown (reverte a última alteração feita por ferramentas suportadas)

Ferramentas em destaque

obsidian-mcp-diff-edit-file

Esta ferramenta edita um único arquivo aplicando um udiff simplificado. É basicamente assim que Cursor e outros editores de código baseados em LLM funcionam. É melhor para modelos mais inteligentes, pois os menores tendem a ter dificuldade em criar os diffs com precisão. Para ajudar com esse problema, a ferramenta retorna um diff das alterações reais aplicadas ao arquivo. Isso ajuda o modelo a determinar se as alterações aplicadas corresponderam às suas expectativas.

Um exemplo deste formato de udiff simplificado é o seguinte:

--- example.md
+++ example.md
@@ ... @@
-Old line of text
+New line of text

Este sistema de diff simplificado é inspirado no formato de diff simplificado do Aider; você pode ler mais sobre o trabalho deles aqui

obsidian-mcp-rollback-edit

Esta ferramenta permite reverter a última alteração feita em um arquivo markdown por ferramentas suportadas de escrita de arquivos (obsidian-mcp-diff-edit-file, obsidian-mcp-upsert-file ou ferramentas de atualização estruturada). Antes que qualquer uma dessas ferramentas modifique um arquivo, o conteúdo anterior é salvo em um armazenamento de reversão. Você pode usar obsidian-mcp-rollback-edit para restaurar o arquivo ao seu estado anterior.

Se uma reversão estiver disponível, o arquivo será restaurado ao conteúdo anterior, e você receberá uma mensagem com o timestamp e o motivo da última alteração. Caso contrário, você receberá uma mensagem de erro.

Edições de Dados Estruturados (ferramentas dinâmicas)

Crie e atualize conteúdo estruturado de forma segura quanto a tipos usando ferramentas.

TL;DR LLMs não são confiáveis para editar diretamente formatos estruturados como JSON ou YAML. Eles quebram a formatação ou esquecem campos. Em vez disso, o Vault MCP define um esquema para seus dados e o expõe como uma ferramenta. O modelo então edita a estrutura por meio de chamadas de ferramenta.

Se quiser escrever um esquema, vá aqui: Escreva Seus Próprios Esquemas

Como funciona

LLMs simplesmente não são bons em trabalhar com dados estruturados. Eles quebram a formatação, injetam sua própria formatação, esquecem coisas, etc.

O Vault MCP adota uma abordagem um tanto inovadora para lidar com dados estruturados: cria uma ferramenta que o LLM pode chamar para fazer atualizações em uma estrutura de dados.

Quando o LLM deseja editar os dados estruturados, ele faz uma chamada de ferramenta onde os parâmetros da chamada correspondem aos campos da estrutura de dados.

A maioria dos modelos "bons" é treinada especificamente para fazer chamadas de ferramenta, então este é um sistema muito mais estável.

Esse mapeamento dos dados estruturados para a ferramenta é feito em algumas etapas:

  1. Você define um esquema usando JSON Schema (draft-07), escrito em YAML.
  2. O Vault MCP valida usando um metaschema embutido.
  3. O esquema é convertido em um zod.
  4. Uma ferramenta é criada dinamicamente a partir desse esquema.

Esquemas

Cada esquema tem duas seções:

  1. metadata Define detalhes de nomenclatura e armazenamento de arquivos
  2. fields Define a estrutura dos seus dados (usado para gerar a ferramenta Zod)

Os esquemas são JSON Schema draft 07, mas escritos em YAML para melhor usabilidade. Para conseguir gerar essa ferramenta dinâmica, o plugin precisa saber tanto a estrutura dos dados estruturados quanto alguns metadados sobre nomes de arquivos, locais, etc.

Esquemas de Usuário

Aqui está um exemplo de um esquema definido pelo usuário para armazenar receitas 
metadata:
  schemaName: "Recipe"
  description: |
    Updates a recipe file given a schema and identifiers. Creates the file if it doesn't exist.
    Uses the Recipe Schema. It merges new non-default data into existing frontmatter.
  identifierField: "recipe_id"
  pathTemplate: "Recipes/${category}/${recipe_id}/Recipe.md"
  pathComponents:
    - category
    - recipe_id

fields:
  recipe_id:
    type: "string"
    description: "Unique identifier for the recipe (e.g., `chocolate_chip_cookies`)."
    optional: false

  category:
    type: "string"
    description: "Recipe category for organizing files (e.g., `Desserts`)."
    optional: false

  title:
    type: "string"
    description: "Name of the recipe (e.g., `Chocolate Chip Cookies`)."
    optional: true

  description:
    type: "string"
    description: "Brief description of the recipe and its highlights."
    optional: true

  servings:
    type: "number"
    description: "Number of servings the recipe yields (must be at least 1)."
    optional: true
    minimum: 1
    maximum: 100
    default: 4

  ingredients:
    type: "array"
    description: "List of ingredients required for the recipe."
    optional: true
    items:
      type: "object"
      properties:
        name:
          type: "string"
          description: "The name of the ingredient (e.g., `all-purpose flour`)."
          optional: false
        quantity:
          type: "string"
          description: "Amount needed (e.g., `2 cups`, `1 tsp`)."
          optional: true

          
---

Isso gera uma ferramenta MCP que se parece com isto:

mcp-schema-tool

Quando você a usa para colocar dados no Obsidian, o resultado se parece com isto:

Obsidian-schema-tool

Meta Esquema

Para validar que o esquema definido pelo usuário contém os componentes necessários, temos um meta esquema definido em JSON Schema. Você pode ler o arquivo aqui

Ele também ajuda a restringir os tipos para algo que possa ser convertido mais claramente em Zod.

Você pode usá-lo para ver uma lista de tipos e modificadores que pode usar, como valores default, minimum e maximum etc.

Aqui está a versão YAML do meta esquema 
"$schema": http://json-schema.org/draft-07/schema#
title: MCP Structured Document Schema (JSON Schema Valid)
description: Strict meta-schema for structured tools using zod compatible fields.
type: object
required:
  - metadata
  - fields
properties:
metadata:
  type: object
  required:
    - schemaName
    - description
    - identifierField
    - pathTemplate
    - pathComponents
  properties:
    schemaName:
      type: string
    description:
      type: string
    identifierField:
      type: string
    pathTemplate:
      type: string
    pathComponents:
      type: array
      items:
        type: string
  additionalProperties: false
fields:
  type: object
  patternProperties:
    "^[a-zA-Z_][a-zA-Z0-9_]*$":
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - date
            - array
            - object
            - literal
            - unknown
            - any
        description:
          type: string
        default: {}
        minimum:
          type: number
        maximum:
          type: number
        enum:
          type: array
          items: {}
        items:
          type: object
        properties:
          type: object
        required:
          type: array
          items:
            type: string
      additionalProperties: true
  additionalProperties: false
additionalProperties: false

Escrevendo seus próprios esquemas

Comece pensando em duas coisas:

  • Where and how will the file be stored?

Use metadados para descrever modelos de nomes de arquivos e como identificar um arquivo (por exemplo, por ID).

  • What structured data will be in the file?

Use campos para definir a estrutura usando tipos como string, number, array, object, e modificadores como default, minimum, etc.

Uma vez definido, seu esquema automaticamente se tornará uma ferramenta que o LLM pode usar para atualizar esse tipo de arquivo.

Coloque o esquema que você escreveu em um diretório "schema" no seu vault do Obsidian. O esquema deve ser definido em um arquivo markdown contido em um bloco de código com a sintaxe configurada assim:

```yaml schema

Pode haver outro texto no mesmo markdown, como notas ou descrições, mas o Vault MCP usará apenas o YAML definido no bloco de código especificado acima.

Coloque o caminho desse diretório nas configurações de ferramentas dinâmicas nas configurações do Vault MCP e reinicie o plugin para analisar e gerar as ferramentas dinâmicas. Elas aparecerão no painel de configurações assim:

dynamic settings

A ferramenta list-schemas é criada automaticamente quando as ferramentas dinâmicas são geradas, para permitir que clientes vejam os esquemas diretamente se necessário.

O Obsidian renderizará a estrutura YAML como um frontmatter formatado ou bloco incorporado no seu markdown.

Ao escrever esquemas, achei esta ferramenta particularmente útil stefanterdell.github.io/json-schema-to-zod-react. O Vault MCP a usa internamente para gerar o zod, mas este é um método mais visual para ajudar na solução de problemas.

Desenvolvimento

Pré-requisitos

Um flake nix é fornecido para criar um ambiente de desenvolvimento padronizado.

Configurar Ambiente de Desenvolvimento


git clone https://github.com/jlevere/obsidian-mcp-plugin.git
cd obsidian-mcp-plugin

nix develop

# for cool people who use direnv
# echo "use flake" > .envrc && direnv allow

pnpm install

pnpm build:dev

Estrutura do Projeto

  • src/: Código-fonte
    • managers/: Gerenciadores de funcionalidades principais
    • structured-tools/: Validação de esquema e ferramentas
    • utils/: Utilidades auxiliares
    • vault/: Código de interação com o vault
  • tests/: Arquivos de teste

Build de Produção

pnpm run build

Notas

  • Este plugin é suportado apenas no Obsidian desktop.
  • Tokens de autenticação Bearer são armazenados no arquivo data.json do plugin. Esse token pode ser renovado sob demanda.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir uma issue ou pull request.

Créditos

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.