Obsidian Semantic MCP Server

Um servidor MCP otimizado por IA para Obsidian que consolida mais de 21 ferramentas em 5 operações inteligentes com dicas contextuais de fluxo de trabalho.

GitHub
36
Experimente este MCPPatrocinado

Documentação

Servidor MCP Semântico para Obsidian

🎉 Novidades emocionantes! Pegamos tudo o que aprendemos com este projeto e criamos algo ainda melhor! Conheça o novo Plugin MCP para Obsidian - um plugin nativo do Obsidian que roda diretamente dentro do seu cofre, com desempenho aprimorado, configuração simplificada e recursos aprimorados. Recomendamos que você experimente!

npm version

Um servidor MCP semântico e otimizado para IA no Obsidian que consolida 20 ferramentas em 5 operações inteligentes com dicas contextuais de fluxo de trabalho.

🚀 Experimente Nosso Novo Plugin Nativo!

Este servidor MCP nos ensinou lições valiosas sobre integração de IA com o Obsidian. Aplicamos esses insights para criar o Plugin MCP para Obsidian, que oferece:

  • Integração Nativa: Roda diretamente dentro do Obsidian (sem dependências externas!)
  • Melhor Desempenho: Acesso direto ao cofre sem a sobrecarga da API REST
  • Configuração Mais Fácil: Instale como qualquer plugin do Obsidian - sem chaves de API ou servidores externos
  • Recursos Aprimorados: Acesso completo às APIs internas e recursos de busca do Obsidian
  • Confiabilidade Melhorada: Sem mais problemas de conexão ou tempos limite

👉 Obtenha o Plugin MCP para Obsidian

Obsidian Semantic Server MCP server

Pré-requisitos

Instalação

npm install -g obsidian-semantic-mcp

Ou use diretamente com npx (recomendado):

npx obsidian-semantic-mcp

Veja no npm: https://www.npmjs.com/package/obsidian-semantic-mcp

Início Rápido

  1. Instale o Plugin do Obsidian:

    • Abra Configurações do Obsidian → Plugins da Comunidade
    • Navegue e pesquise por "Local REST API"
    • Instale o plugin Local REST API por Adam Coddington
    • Ative o plugin
    • Nas configurações do plugin, copie sua chave de API (você precisará dela para a configuração)

  2. Configure o Claude Desktop:

    O comando npx é usado automaticamente na configuração do Claude Desktop. Adicione isto ao seu arquivo de configuração do Claude Desktop (geralmente encontrado em ~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

    {
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-semantic-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_VAULT_NAME": "your-vault-name"
      }
    }
  }
}

Recursos

Este servidor consolida as ferramentas MCP tradicionais em uma interface semântica otimizada para IA, facilitando que agentes de IA entendam e usem as operações do Obsidian de forma eficaz.

Principais Benefícios

  • Interface Simplificada: 5 operações semânticas em vez de 21+ ferramentas individuais
  • Fluxos de Trabalho Contextuais: Dicas inteligentes guiam agentes de IA para a próxima ação lógica
  • Rastreamento de Estado: Sistema baseado em tokens previne operações inválidas
  • Recuperação de Erros: Dicas inteligentes de recuperação quando operações falham
  • Correspondência Difusa: Edição de texto resiliente que lida com pequenas variações
  • Recuperação de Fragmentos: Retorna automaticamente seções relevantes de arquivos grandes para economizar tokens

Por que Operações Semânticas?

Servidores MCP tradicionais expõem muitas ferramentas granulares (20+), o que pode sobrecarregar agentes de IA e levar a uma seleção ineficiente de ferramentas. Nossa abordagem semântica:

  • Consolida 20 ferramentas em 5 operações semânticas baseadas na intenção
  • Fornece dicas contextuais de fluxo de trabalho para guiar as próximas ações
  • Rastreia o estado com tokens (inspirado em redes de Petri) para prevenir sugestões sem sentido
  • Oferece dicas de recuperação quando operações falham

As 5 Operações Semânticas

  1. vault - Operações de arquivos e pastas

    • Ações: list, read, create, update, delete, search, fragments

  2. edit - Edição inteligente de conteúdo

    • Ações: window (correspondência difusa), append, patch, at_line, from_buffer

  3. view - Visualização e navegação de conteúdo

    • Ações: window (com contexto), open_in_obsidian

  4. workflow - Obter sugestões guiadas

    • Ações: suggest

  5. system - Operações do sistema

    • Ações: info, commands, fetch_web
    • Nota: fetch_web busca e converte conteúdo web para markdown (usa apenas o parâmetro url)

Exemplo de Uso

Em vez de escolher entre get_vault_file, get_active_file, read_file_content, etc., você simplesmente usa:

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "daily-notes/2024-01-15.md"
  }
}

A resposta inclui dicas inteligentes de fluxo de trabalho:

{
  "result": { /* file content */ },
  "workflow": {
    "message": "Read file: daily-notes/2024-01-15.md",
    "suggested_next": [
      {
        "description": "Edit this file",
        "command": "edit(action='window', path='daily-notes/2024-01-15.md', ...)",
        "reason": "Make changes to content"
      },
      {
        "description": "Follow linked notes",
        "command": "vault(action='read', path='{linked_file}')",
        "reason": "Explore connected knowledge"
      }
    ]
  }
}

Sugestões Cientes do Estado

O sistema rastreia tokens de contexto para fornecer sugestões relevantes:

  • Após ler um arquivo com [[links]], ele sugere segui-los
  • Após uma edição falha, ele oferece opções de recuperação do buffer
  • Após uma busca, ele sugere refinar ou ler os resultados

Recursos Avançados

Buffer de Conteúdo

A ação de edição window armazena automaticamente seu novo conteúdo em buffer antes de tentar a edição. Se a edição falhar ou você quiser refiná-la, pode recuperar do buffer:

{
  "operation": "edit",
  "action": "from_buffer",
  "params": {
    "path": "notes/meeting.md"
  }
}

Edição com Janela Difusa

O editor semântico usa correspondência difusa para encontrar e substituir conteúdo:

{
  "operation": "edit",
  "action": "window",
  "params": {
    "path": "daily/2024-01-15.md",
    "oldText": "meting notes",  // typo will be fuzzy matched
    "newText": "meeting notes",
    "fuzzyThreshold": 0.8
  }
}

Operações PATCH Inteligentes

Direcione estruturas específicas do documento:

{
  "operation": "edit",
  "action": "patch",
  "params": {
    "path": "projects/todo.md",
    "operation": "append",
    "targetType": "heading",
    "target": "## In Progress",
    "content": "- [ ] New task"
  }
}

Recuperação de Fragmentos para Documentos Grandes

O sistema usa automaticamente a recuperação inteligente de fragmentos ao ler arquivos, reduzindo significativamente o consumo de tokens enquanto mantém a relevância:

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "large-document.md"
  }
}

Retorna fragmentos relevantes em vez do arquivo inteiro:

{
  "result": {
    "content": [
      {
        "id": "file:large-document.md:frag0",
        "content": "Most relevant section...",
        "score": 0.95,
        "lineStart": 145,
        "lineEnd": 167
      }
    ],
    "fragmentMetadata": {
      "totalFragments": 5,
      "strategy": "adaptive",
      "originalContentLength": 135662
    }
  }
}

Estratégias de Busca de Fragmentos:

  • adaptativa - Correspondência de palavras-chave TF-IDF (padrão para consultas curtas)
  • proximidade - Encontra fragmentos onde os termos da consulta aparecem próximos
  • semântica - Divide documentos em seções significativas

Você pode buscar fragmentos explicitamente em todo o seu cofre:

{
  "operation": "vault",
  "action": "fragments",
  "params": {
    "query": "project roadmap timeline",
    "maxFragments": 10,
    "strategy": "proximity"
  }
}

Para recuperar o arquivo completo (quando necessário), use:

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "document.md",
    "returnFullFile": true
  }
}

Exemplos de Fluxo de Trabalho

Fluxo de Nota Diária

  1. Criar a nota de hoje → 2. Adicionar modelo → 3. Vincular a nota de ontem

Fluxo de Pesquisa

  1. Buscar tópico → 2. Ler resultados → 3. Criar nota de síntese → 4. Vincular fontes

Fluxo de Refatoração

  1. Encontrar todas as menções → 2. Atualizar links → 3. Renomear/mesclar notas

Configuração

As dicas semânticas de fluxo de trabalho são definidas em src/config/workflows.json e podem ser personalizadas de acordo com suas preferências de fluxo de trabalho.

Configuração de Recuperação de Fragmentos

O sistema de recuperação de fragmentos é ativado automaticamente ao ler arquivos para economizar tokens. Você pode controlar esse comportamento:

  • Comportamento padrão: Retorna até 5 fragmentos relevantes ao ler arquivos
  • Acesso ao arquivo completo: Use o parâmetro returnFullFile: true para obter o conteúdo completo
  • Seleção de estratégia: O sistema seleciona automaticamente com base no comprimento da consulta, ou você pode especificar:
    • adaptive para correspondência de palavras-chave (consultas de 1-2 palavras)
    • proximity para encontrar termos relacionados juntos (consultas de 3-5 palavras)
    • semantic para divisão conceitual (consultas mais longas)

Recuperação de Erros

Quando as operações falham, a interface semântica fornece dicas inteligentes de recuperação:

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File not found: daily/2024-01-15.md",
    "recovery_hints": [
      {
        "description": "Create this file",
        "command": "vault(action='create', path='daily/2024-01-15.md')"
      },
      {
        "description": "Search for similar files",
        "command": "vault(action='search', query='2024-01-15')"
      }
    ]
  }
}

Variáveis de Ambiente

O servidor carrega automaticamente variáveis de ambiente de um arquivo .env se presente. As variáveis podem ser definidas em ordem de precedência:

  1. Variáveis de ambiente existentes (maior prioridade)
  2. Arquivo .env no diretório de trabalho atual
  3. Arquivo .env no diretório do servidor

Variáveis obrigatórias:

  • OBSIDIAN_API_KEY - Sua chave de API do plugin Local REST API

Variáveis opcionais:

  • OBSIDIAN_API_URL - URL da API (padrão: https://localhost:27124)
    • Suporta HTTP (porta 27123) e HTTPS (porta 27124)
    • HTTPS usa certificados autoassinados que são aceitos automaticamente
  • OBSIDIAN_VAULT_NAME - Nome do cofre para contexto

Exemplo de arquivo .env:

OBSIDIAN_API_KEY=your-api-key-here
OBSIDIAN_API_URL=http://127.0.0.1:27123
OBSIDIAN_VAULT_NAME=MyVault

Operações PATCH

As operações PATCH (patch_active_file e patch_vault_file) permitem manipulação sofisticada de conteúdo:

  • Tipos de Alvo:

    • heading: Direcionar conteúdo sob cabeçalhos específicos usando caminhos como "Cabeçalho 1::Subcabeçalho"
    • block: Direcionar referências de bloco específicas
    • frontmatter: Direcionar campos de frontmatter

  • Operações:

    • append: Adicionar conteúdo após o alvo
    • prepend: Adicionar conteúdo antes do alvo
    • replace: Substituir o conteúdo do alvo

Exemplo: Adicionar conteúdo sob um cabeçalho específico:

{
  "operation": "append",
  "targetType": "heading",
  "target": "Daily Notes::Today",
  "content": "- New task added"
}

Desenvolvimento

# Clone and install
git clone https://github.com/aaronsb/obsidian-semantic-mcp.git
cd obsidian-semantic-mcp
npm install

# Development mode
npm run dev

# Testing
npm test              # Run all tests
npm run test:coverage # With coverage report

# Build
npm run build         # Build the server
npm run build:full    # Test + Build

# Start
npm start             # Start the server

Arquitetura

O sistema semântico consiste em:

  • Roteador Semântico (src/semantic/router.ts) - Roteia operações para manipuladores
  • Tokens de Estado (src/semantic/state-tokens.ts) - Rastreia o estado do contexto
  • Configuração de Fluxo de Trabalho (src/config/workflows.json) - Define dicas e sugestões
  • Utilitários Principais (src/utils/) - Funcionalidades compartilhadas como leitura de arquivos e correspondência difusa

Testes

O projeto inclui testes Jest abrangentes para o sistema semântico:

npm test                    # Run all tests
npm test semantic-router    # Test routing logic
npm test semantic-tools     # Test integration

Problemas Conhecidos

  • Funcionalidade de busca: A operação de busca pode ocasionalmente expirar em cofres grandes devido a limitações da API no plugin Local REST API do Obsidian.

Contribuindo

Contribuições são bem-vindas! Áreas de interesse:

  • Padrões adicionais de fluxo de trabalho em workflows.json
  • Novas operações semânticas
  • Rastreamento de estado aprimorado
  • Integração com plugins do Obsidian

Licença

MIT