Obsidian Semantic MCP Server

Un servidor MCP optimizado para IA en Obsidian que consolida más de 21 herramientas en 5 operaciones inteligentes con sugerencias contextuales de flujo de trabajo.

GitHub
36
Prueba este MCPPatrocinado

Documentación

Servidor MCP Semántico de Obsidian

🎉 ¡Noticias emocionantes! Hemos tomado todo lo que aprendimos de este proyecto y hemos creado algo aún mejor. ¡Echa un vistazo al nuevo Plugin MCP de Obsidian - un plugin nativo de Obsidian que se ejecuta directamente dentro de tu bóveda con mejor rendimiento, configuración simplificada y funciones mejoradas. ¡Te animamos a probarlo!

npm version

Un servidor MCP semántico y optimizado para IA de Obsidian que consolida 20 herramientas en 5 operaciones inteligentes con sugerencias contextuales de flujo de trabajo.

🚀 ¡Prueba Nuestro Nuevo Plugin Nativo!

Este servidor MCP nos enseñó lecciones valiosas sobre la integración de IA con Obsidian. Hemos aplicado estos conocimientos para crear el Plugin MCP de Obsidian, que ofrece:

  • Integración Nativa: Se ejecuta directamente dentro de Obsidian (¡sin dependencias externas!)
  • Mejor Rendimiento: Acceso directo a la bóveda sin la sobrecarga de la API REST
  • Configuración Más Fácil: Se instala como cualquier plugin de Obsidian - sin claves API ni servidores externos
  • Funciones Mejoradas: Acceso completo a las APIs internas y capacidades de búsqueda de Obsidian
  • Fiabilidad Mejorada: Sin más problemas de conexión ni tiempos de espera

👉 Obtén el Plugin MCP de Obsidian

Obsidian Semantic Server MCP server

Requisitos Previos

Instalación

npm install -g obsidian-semantic-mcp

O úsalo directamente con npx (recomendado):

npx obsidian-semantic-mcp

Ver en npm: https://www.npmjs.com/package/obsidian-semantic-mcp

Inicio Rápido

  1. Instala el Plugin de Obsidian:

    • Abre Configuración de Obsidian → Plugins de la Comunidad
    • Navega y busca "Local REST API"
    • Instala el plugin Local REST API de Adam Coddington
    • Habilita el plugin
    • En la configuración del plugin, copia tu clave API (la necesitarás para la configuración)

  2. Configura Claude Desktop:

    El comando npx se usa automáticamente en la configuración de Claude Desktop. Añade esto a tu configuración de Claude Desktop (normalmente se encuentra en ~/Library/Application Support/Claude/claude_desktop_config.json en 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"
      }
    }
  }
}

Características

Este servidor consolida las herramientas MCP tradicionales en una interfaz semántica optimizada para IA que facilita que los agentes de IA comprendan y utilicen las operaciones de Obsidian de manera efectiva.

Beneficios Clave

  • Interfaz Simplificada: 5 operaciones semánticas en lugar de 21+ herramientas individuales
  • Flujos de Trabajo Contextuales: Sugerencias inteligentes guían a los agentes de IA hacia la siguiente acción lógica
  • Seguimiento de Estado: Sistema basado en tokens previene operaciones inválidas
  • Recuperación de Errores: Sugerencias inteligentes de recuperación cuando fallan las operaciones
  • Coincidencia Difusa: Edición de texto resiliente que maneja variaciones menores
  • Recuperación de Fragmentos: Devuelve automáticamente secciones relevantes de archivos grandes para conservar tokens

¿Por Qué Operaciones Semánticas?

Los servidores MCP tradicionales exponen muchas herramientas granulares (20+), lo que puede abrumar a los agentes de IA y llevar a una selección ineficiente de herramientas. Nuestro enfoque semántico:

  • Consolida 20 herramientas en 5 operaciones semánticas basadas en la intención
  • Proporciona sugerencias contextuales de flujo de trabajo para guiar las siguientes acciones
  • Realiza seguimiento del estado con tokens (inspirado en redes de Petri) para prevenir sugerencias sin sentido
  • Ofrece sugerencias de recuperación cuando fallan las operaciones

Las 5 Operaciones Semánticas

  1. vault - Operaciones de archivos y carpetas

    • Acciones: list, read, create, update, delete, search, fragments

  2. edit - Edición inteligente de contenido

    • Acciones: window (coincidencia difusa), append, patch, at_line, from_buffer

  3. view - Visualización y navegación de contenido

    • Acciones: window (con contexto), open_in_obsidian

  4. workflow - Obtener sugerencias guiadas

    • Acciones: suggest

  5. system - Operaciones del sistema

    • Acciones: info, commands, fetch_web
    • Nota: fetch_web obtiene y convierte contenido web a markdown (usa solo el parámetro url)

Ejemplo de Uso

En lugar de elegir entre get_vault_file, get_active_file, read_file_content, etc., simplemente usas:

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

La respuesta incluye sugerencias inteligentes de flujo de trabajo:

{
  "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"
      }
    ]
  }
}

Sugerencias Conscientes del Estado

El sistema realiza seguimiento de tokens de contexto para proporcionar sugerencias relevantes:

  • Después de leer un archivo con [[links]], sugiere seguirlos
  • Después de una edición fallida, ofrece opciones de recuperación del búfer
  • Después de una búsqueda, sugiere refinar o leer los resultados

Funciones Avanzadas

Búfer de Contenido

La acción de edición window almacena automáticamente tu nuevo contenido en el búfer antes de intentar la edición. Si la edición falla o quieres refinarla, puedes recuperarla del búfer:

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

Edición con Ventana Difusa

El editor semántico utiliza coincidencia difusa para encontrar y reemplazar contenido:

{
  "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
  }
}

Operaciones PATCH Inteligentes

Apunta a estructuras específicas del documento:

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

Recuperación de Fragmentos para Documentos Grandes

El sistema utiliza automáticamente la recuperación inteligente de fragmentos al leer archivos, reduciendo significativamente el consumo de tokens mientras mantiene la relevancia:

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

Devuelve fragmentos relevantes en lugar del archivo completo:

{
  "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
    }
  }
}

Estrategias de Búsqueda de Fragmentos:

  • adaptativa - Coincidencia de palabras clave TF-IDF (predeterminada para consultas cortas)
  • proximidad - Encuentra fragmentos donde los términos de la consulta aparecen cerca
  • semántica - Divide los documentos en secciones significativas

Puedes buscar fragmentos explícitamente en tu bóveda:

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

Para recuperar el archivo completo (cuando sea necesario), usa:

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

Ejemplos de Flujos de Trabajo

Flujo de Trabajo de Notas Diarias

  1. Crear la nota de hoy → 2. Añadir plantilla → 3. Enlazar la nota de ayer

Flujo de Trabajo de Investigación

  1. Buscar tema → 2. Leer resultados → 3. Crear nota de síntesis → 4. Enlazar fuentes

Flujo de Trabajo de Refactorización

  1. Encontrar todas las menciones → 2. Actualizar enlaces → 3. Renombrar/fusionar notas

Configuración

Las sugerencias semánticas de flujo de trabajo se definen en src/config/workflows.json y se pueden personalizar según tus preferencias de flujo de trabajo.

Configuración de Recuperación de Fragmentos

El sistema de recuperación de fragmentos se activa automáticamente al leer archivos para conservar tokens. Puedes controlar este comportamiento:

  • Comportamiento predeterminado: Devuelve hasta 5 fragmentos relevantes al leer archivos
  • Acceso al archivo completo: Usa el parámetro returnFullFile: true para obtener el contenido completo
  • Selección de estrategia: El sistema selecciona automáticamente según la longitud de la consulta, o puedes especificar:
    • adaptive para coincidencia de palabras clave (consultas de 1-2 palabras)
    • proximity para encontrar términos relacionados juntos (consultas de 3-5 palabras)
    • semantic para división conceptual (consultas más largas)

Recuperación de Errores

Cuando fallan las operaciones, la interfaz semántica proporciona sugerencias inteligentes de recuperación:

{
  "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')"
      }
    ]
  }
}

Variables de Entorno

El servidor carga automáticamente las variables de entorno desde un archivo .env si está presente. Las variables se pueden establecer en orden de precedencia:

  1. Variables de entorno existentes (mayor prioridad)
  2. Archivo .env en el directorio de trabajo actual
  3. Archivo .env en el directorio del servidor

Variables requeridas:

  • OBSIDIAN_API_KEY - Tu clave API del plugin Local REST API

Variables opcionales:

  • OBSIDIAN_API_URL - URL de la API (predeterminado: https://localhost:27124)
    • Soporta tanto HTTP (puerto 27123) como HTTPS (puerto 27124)
    • HTTPS usa certificados autofirmados que se aceptan automáticamente
  • OBSIDIAN_VAULT_NAME - Nombre de la bóveda para contexto

Ejemplo de archivo .env:

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

Operaciones PATCH

Las operaciones PATCH (patch_active_file y patch_vault_file) permiten una manipulación sofisticada del contenido:

  • Tipos de Destino:

    • heading: Apunta a contenido bajo encabezados específicos usando rutas como "Encabezado 1::Subencabezado"
    • block: Apunta a referencias de bloques específicos
    • frontmatter: Apunta a campos de frontmatter

  • Operaciones:

    • append: Añadir contenido después del destino
    • prepend: Añadir contenido antes del destino
    • replace: Reemplazar el contenido del destino

Ejemplo: Añadir contenido bajo un encabezado específico:

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

Desarrollo

# 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

Arquitectura

El sistema semántico consiste en:

  • Enrutador Semántico (src/semantic/router.ts) - Enruta operaciones a los manejadores
  • Tokens de Estado (src/semantic/state-tokens.ts) - Realiza seguimiento del estado del contexto
  • Configuración de Flujo de Trabajo (src/config/workflows.json) - Define sugerencias y recomendaciones
  • Utilidades Principales (src/utils/) - Funcionalidad compartida como lectura de archivos y coincidencia difusa

Pruebas

El proyecto incluye pruebas Jest completas para el sistema semántico:

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

Problemas Conocidos

  • Funcionalidad de búsqueda: La operación de búsqueda puede agotar el tiempo ocasionalmente en bóvedas grandes debido a limitaciones de la API en el plugin Obsidian Local REST API.

Contribuciones

¡Las contribuciones son bienvenidas! Áreas de interés:

  • Patrones adicionales de flujo de trabajo en workflows.json
  • Nuevas operaciones semánticas
  • Seguimiento de estado mejorado
  • Integración con plugins de Obsidian

Licencia

MIT