Servidor de herramientas MCP de Obsidian

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) que expone herramientas para interactuar con una bóveda de Obsidian.

Tabla de contenido

• Características
• Instalación
• Configuración
• Ejecución manual (para pruebas/depuración)
• Configuración del cliente (Ejemplo: Claude Desktop)
• Herramientas MCP disponibles
• Hoja de ruta
• Preguntas frecuentes (FAQ)
• ¡Contribuciones bienvenidas!

Características

Permite a los clientes MCP (como los asistentes de IA):

• Leer y escribir notas
• Administrar metadatos de notas (frontmatter)
• Lista de notas y carpetas
• Buscar notas por contenido o metadatos
• Administrar notas diarias
• Obtenga enlaces salientes, backlinks y etiquetas

Instalación

1. Clona el repositorio (si aún no lo has hecho):
   # git clone <repository-url> # cd OMCP
2. Navegue hasta el directorio del proyecto :
   cd /path/to/your/OMCP
3. Cree un entorno virtual de Python (recomendado para evitar conflictos de dependencia):
   python -m venv .venv
4. Activar el entorno virtual :
   • En Windows PowerShell:
     .venv\Scripts\Activate.ps1
   • En Linux/macOS:GXP5 (Su terminal ahora debería mostrar (.venv) al comienzo)
5. Instalar el paquete y sus dependencias:
   pip install .

Configuración

Este servidor se configura utilizando variables de entorno, que se pueden administrar cómodamente mediante un archivo .env en la raíz del proyecto.

1. Copia el archivo de ejemplo:
   # From the project root directory (OMCP/) cp .env.example .env
   (En Windows, puedes usar copy .env.example .env )
2. Editar el archivo .env : abra el archivo .env recién creado en un editor de texto.
3. Establezca OMCP_VAULT_PATH : Esta es la única variable obligatoria . Actualícela con la ruta absoluta a su bóveda de Obsidian. Use barras diagonales ( / ) para las rutas, incluso en Windows.
   OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"
4. Revisar la configuración opcional: Ajuste las demás variables OMCP_ para las notas diarias, el puerto del servidor o el directorio de copias de seguridad, si es necesario. Lea los comentarios del archivo para obtener explicaciones.

(Alternativamente, en lugar de utilizar un archivo .env , puede configurarlos como variables de entorno del sistema reales. El servidor priorizará las variables de entorno del sistema sobre el archivo .env si ambos están configurados).

Ejecución manual (para pruebas/depuración)

Si bien las aplicaciones cliente como Claude Desktop iniciarán el servidor automáticamente utilizando la configuración descrita a continuación, también puede ejecutar el servidor manualmente desde su terminal para realizar pruebas o depuraciones directas.

1. Asegúrese de que la configuración esté realizada: asegúrese de haber creado y configurado su archivo .env como se describe en la sección Configuración.
2. Activar entorno virtual:
   # If not already active .venv\Scripts\Activate.ps1
   (Utilice source .venv/bin/activate en Linux/macOS)
3. Ejecute el script del servidor:
   (.venv) ...> python obsidian_mcp_server/main.py

El servidor se iniciará e imprimirá la dirección en la que está escuchando (p. ej., http://127.0.0.1:8001 ). Normalmente, se presiona Ctrl+C para detenerlo al terminar la prueba.

Recuerde: Si pretende usar este servidor con Claude Desktop o un lanzador similar, no debe ejecutarlo manualmente de esta manera. Configure la aplicación cliente (consulte la siguiente sección) y esta se encargará de iniciar y detener el proceso del servidor.

Configuración del cliente (Ejemplo: Claude Desktop)

Muchos clientes MCP (como Claude Desktop) pueden iniciar procesos de servidor directamente. Para configurar un cliente de este tipo, normalmente es necesario editar su archivo de configuración JSON (p. ej., claude_desktop_config.json en macOS/Linux; busque la ruta equivalente en Windows en AppData ).

⚠️ Reglas importantes de formato JSON:

1. Los archivos JSON no admiten comentarios (elimine cualquier comentario // o /* */ )
2. Todas las cadenas deben estar correctamente entre comillas dobles ( " )
3. Las rutas de Windows deben usar barras invertidas con escape ( \\ )
4. Utilice un validador JSON (como jsonlint.com ) para comprobar su sintaxis

A continuación se muestra un ejemplo de entrada para agregar bajo la clave mcpServers en la configuración JSON del cliente:

Puntos clave:

• Reemplace las rutas con las rutas absolutas relevantes para su sistema
• Para las rutas de Windows en los campos command y args :
  • Utilice barras invertidas dobles ( \\ ) para separar rutas
  • Incluya la extensión .exe para el ejecutable de Python
• Para rutas de Windows en el bloque env :
  • Utilice barras diagonales ( / ) para una mejor compatibilidad
  • No incluya la extensión .exe
• La ruta commanddebe apuntar al ejecutable python.exedentro del .venv que creó
• La ruta argsdebe apuntar al archivo main.py dentro de la subcarpeta obsidian_mcp_server
• Usar el bloque env es la forma más confiable de garantizar que el servidor encuentre la ruta de su bóveda
• Recuerde reiniciar la aplicación cliente después de modificar su configuración JSON

Errores comunes que se deben evitar:

1. No utilice barras invertidas simples en las rutas de Windows
2. No incluya comentarios en el JSON
3. No olvide escapar las barras invertidas en las rutas de Windows
4. No mezcle barras diagonales e inversas en la misma ruta
5. No olvides citar correctamente todas las cadenas

Herramientas MCP disponibles

• list_folders
• list_notes
• get_note_content
• get_note_metadata
• get_outgoing_links
• get_backlinks
• get_all_tags
• search_notes_content
• search_notes_metadata
• search_folders
• create_note
• edit_note
• append_to_note
• update_note_metadata
• delete_note
• get_daily_note_path
• create_daily_note
• append_to_daily_note

Hoja de ruta

Este proyecto se encuentra en desarrollo activo. A continuación, se presentan las características planificadas:

v1.x (a corto plazo)

• Creación de notas basada en plantillas:
  • Configurar un directorio de plantillas ( OMCP_TEMPLATE_DIR ).
  • Implementar la herramienta create_note_from_template (usando el nombre de la plantilla, la ruta de destino y los metadatos opcionales).
  • Agregar pruebas para la creación de plantillas.
• Creación de carpeta:
  • Implementar la función de utilidad create_folder .
  • Implementar la herramienta MCP create_folder .
  • Agregar pruebas para la creación de carpetas.

v1.y (Mejoras a medio plazo/futuras)

• Sustitución de variables en plantillas (por ejemplo, {{DATE}} ).
• herramienta list_templates .
• Herramientas avanzadas de actualización de notas (por ejemplo, append_to_note_by_metadata ).
• Herramienta list_vault_structure para una vista completa de la jerarquía de bóveda.
• Revisión y ampliación integral de pruebas.

v2.x+ (Ideas potenciales / A largo plazo)

• Herramientas de organización:
  • move_item(source, destination) (Es posible que la versión inicial no actualice los enlaces).
  • rename_item(path, new_name) (Es posible que la versión inicial no actualice los enlaces).
• Herramientas de manipulación de contenido:
  • replace_text_in_note(path, old, new, count) .
  • prepend_to_note(path, content) .
  • append_to_section(path, heading, content) (Requiere un análisis de encabezado confiable).
• Herramientas de consulta:
  • get_local_graph(path) (Combina enlaces salientes y entrantes).
  • search_notes_by_metadata_field(key, value) .
• Herramientas de integración de complementos:
  • Integración de Dataview:
    • execute_dataview_query(query_type, query) : ejecuta consultas de Dataview y obtiene resultados estructurados
    • search_by_dataview_field(field, value) : busca notas por campos de Dataview
  • Gestión de tareas:
    • query_tasks(status, due_date, tags) : busca y filtra tareas en el almacén
  • Integración Kanban:
    • get_kanban_data(board_path) : obtiene datos estructurados del tablero kanban
  • Integración de calendario:
    • get_calendar_events(start_date, end_date) - Consultar eventos y tareas del calendario

Preguntas frecuentes (FAQ)

Problemas de configuración

P: Mi servidor no encuentra mi bóveda. ¿Cuál es el problema? R: Esto suele deberse a una configuración de ruta incorrecta. Verificar:

1. La OMCP_VAULT_PATH en su archivo .env usa barras diagonales ( / ) incluso en Windows
2. La ruta es absoluta (comienza desde la raíz)
3. La ruta no termina con una barra diagonal final
4. El directorio de la bóveda existe y es accesible

P: ¿Por qué recibo errores de permiso? R: Esto suele ocurrir cuando:

1. La ruta de la bóveda apunta a un directorio restringido
2. El proceso de Python no tiene permisos de lectura/escritura
3. La bóveda está en una carpeta sincronizada en la nube (como OneDrive) que actualmente se está sincronizando

Intentar:

1. Mover su bóveda a un directorio local
2. Ejecutar el servidor con permisos elevados
3. Comprobar que tu antivirus no bloquea el acceso

Problemas de conexión del cliente

P: Mi cliente de IA no se conecta al servidor. ¿Qué debo comprobar? R: Verifique estos problemas comunes:

1. El servidor está realmente ejecutándose (verifique la salida del terminal)
2. El puerto en la configuración de su cliente coincide con el puerto del servidor
3. La ruta de Python en la configuración de su cliente apunta al entorno virtual correcto
4. Todas las variables de entorno están configuradas correctamente en la configuración del cliente.

P: ¿Por qué recibo errores de "Conexión rechazada"? R: Esto suele significar:

1. El servidor no está funcionando
2. El puerto ya está en uso
3. El firewall está bloqueando la conexión

Intentar:

1. Compruebe si el servidor está en ejecución: netstat -ano | findstr :8001 (Windows)
2. Pruebe un puerto diferente configurando OMCP_SERVER_PORT en su .env
3. Desactivar temporalmente el firewall para realizar pruebas

P: Recibo el error "[error] [obsidian_vault] Token inesperado 'S', "Iniciando O"... no es un JSON válido". ¿Cuál es el problema? R: Este error se produce cuando el archivo de configuración JSON del cliente tiene un formato incorrecto. Causas comunes:

1. Comas faltantes o adicionales en el JSON
2. Barras invertidas sin escape en rutas de Windows
3. Comentarios en JSON (JSON no admite comentarios)

Verifique el archivo de configuración de su cliente (por ejemplo, claude_desktop_config.json ):

1. Utilice un validador JSON (como jsonlint.com ) para comprobar la sintaxis
2. Para rutas de Windows, escape las barras invertidas: "C:\\path\\to\\file"
3. Eliminar cualquier comentario (// o /* */)
4. Asegúrese de que todas las cadenas estén correctamente citadas
5. Compruebe que todos los soportes y tirantes estén correctamente cerrados

Ejemplo de formato de ruta correcto de Windows:

P: Recibo un error de tiempo de espera y el mensaje "Servidor desconectado". ¿Qué ocurre? R: Este patrón de error (inicialización exitosa, luego tiempo de espera después de 60 segundos) suele significar:

1. El servidor ya está ejecutándose en otro proceso
2. El puerto ya está siendo utilizado por otra aplicación
3. El proceso del servidor se está terminando inesperadamente

Pruebe estos pasos en orden:

1. Comprobar si hay procesos del servidor en ejecución:
   # On Windows netstat -ano | findstr :8001 # Look for the PID and then: taskkill /F /PID <PID>
   # On Linux/macOS lsof -i :8001 # Look for the PID and then: kill -9 <PID>
2. Compruebe si hay otras aplicaciones que utilizan el puerto:
   • Cierre cualquier otra aplicación que pueda usar el puerto 8001
   • Esto incluye otros servidores MCP, servidores de desarrollo o cualquier aplicación web.
   • Si no está seguro, intente cambiar el puerto en su .env :
     OMCP_SERVER_PORT=8002
3. Verificar el proceso del servidor:
   • Abra el Administrador de tareas (Windows) o el Monitor de actividad (macOS)
   • Busque cualquier proceso de Python relacionado con el servidor MCP
   • Poner fin a cualquier proceso sospechoso
4. Comprobar los recursos del sistema:
   • Asegúrese de tener suficiente memoria y CPU disponibles
   • Compruebe si algún antivirus o software de seguridad está bloqueando el proceso
   • Verifique que su entorno Python tenga los permisos adecuados
5. Reiniciar todo:
   • Detener la aplicación cliente
   • Elimine cualquier proceso restante del servidor
   • Elimina el archivo .env y crea uno nuevo desde .env.example
   • Reinicie su computadora (si los otros pasos no funcionan)
   • Comience de nuevo con la aplicación cliente

Si el problema persiste después de intentar todos estos pasos, comparte:

1. El registro de errores completo
2. La salida de netstat -ano | findstr :8001 (Windows) o lsof -i :8001 (Linux/macOS)
3. Cualquier mensaje de error de los registros de eventos de su sistema

P: El servidor se desconecta inmediatamente con el mensaje "Transporte del servidor cerrado inesperadamente... proceso saliendo antes de tiempo". ¿Cuál es el problema? R: Este error significa que el proceso del servidor Python se bloqueó casi inmediatamente después de ser iniciado por el cliente. No se trata de un tiempo de espera; el script del servidor no se ejecutó o no permaneció en ejecución.

Causas comunes:

1. Rutas incorrectas en JSON del cliente:
   • command no apunta al python.exe correcto dentro del .venv .
   • args no apunta al script obsidian_mcp_server/main.py correcto.
   • Separadores de ruta incorrectos o escapes de barra invertida faltantes ( \\ ) en Windows.
2. Dependencias faltantes:
   • Los paquetes requeridos de requirements.txt no están instalados en el .venv .
   • El cliente está iniciando Python sin activar correctamente el entorno virtual.
3. Errores de sintaxis: un cambio de código reciente introdujo un error de sintaxis de Python.
4. Error crítico de configuración/permiso:
   • Error al leer el archivo .env al inicio.
   • OMCP_VAULT_PATH no válido o inaccesible.
   • El proceso de Python carece de permisos para ejecutarse o acceder a archivos.
5. Excepción temprana no controlada: se produce un error durante la configuración inicial antes de que el servidor comience a escuchar.

Pasos para la solución de problemas:

1. Verificar las rutas JSON del cliente: Verifique las rutas absolutas de command y args en la configuración JSON de su cliente. Use barras invertidas de escape ( \\ ) para las rutas de Windows.
2. Prueba manual (paso crucial):
   • Activa el entorno virtual en tu terminal:
     # On Windows .\.venv\Scripts\activate
     # On Linux/macOS source .venv/bin/activate
   • Ejecute el servidor directamente:
     python obsidian_mcp_server/main.py
   • Revise atentamente si aparecen mensajes de error directamente en la terminal. Esto ignora al cliente y suele revelar la causa raíz (como ImportError , SyntaxError o FileNotFoundError ).
3. Comprobar dependencias: con venv activado, ejecute pip check y pip install -r requirements.txt .
4. Validar .env y Vault Path: asegúrese de que .env exista, sea legible y que OMCP_VAULT_PATH sea correcto (use barras diagonales / ).
5. Revisar cambios recientes de código: verifique si hay errores de sintaxis o problemas en archivos Python editados recientemente.

Operaciones con notas

P: ¿Por qué no puedo crear ni editar notas en ciertas carpetas? R: Esto podría deberse a:

1. Restricciones de seguridad de ruta (intentar escribir fuera del almacén)
2. Permisos de carpeta
3. Bloqueos de archivos de otros procesos

Intentar:

1. Uso de rutas relativas dentro de su bóveda
2. Comprobación de permisos de carpeta
3. Cerrar otros programas que puedan tener los archivos abiertos

P: ¿Por qué no se guardan las actualizaciones de mis notas? R: Causas comunes:

1. La ruta de la nota es incorrecta
2. El formato del contenido no es válido
3. Falló la creación de la copia de seguridad

Controlar:

1. La ruta de la nota existe y es accesible
2. El contenido es markdown válido
3. El directorio de respaldo tiene permisos de escritura

Notas diarias

P: ¿Por qué no se crean mis notas diarias en la ubicación correcta? R: Verificar:

1. OMCP_DAILY_NOTE_LOCATION está configurado correctamente en .env
2. La ruta utiliza barras diagonales
3. La carpeta de destino existe
4. El formato de fecha coincide con la configuración de su bóveda

Solución de problemas generales

P: ¿Cómo puedo comprobar si el servidor funciona correctamente? R: Ejecute el cliente de prueba:

Esto realizará una serie de operaciones e informará cualquier problema.

P: ¿Dónde puedo encontrar los registros de errores? R: Consultar:

1. La terminal donde se ejecuta el servidor
2. El directorio de respaldo para operaciones fallidas
3. Los registros de eventos del sistema para problemas de permisos

P: ¿Cómo reinicio todo para empezar de cero? R: Prueba estos pasos:

1. Detener el servidor
2. Eliminar el archivo .env
3. Crea un nuevo .env a partir de .env.example
4. Reiniciar el servidor

¡Contribuciones bienvenidas!