Notemd MCP

Un servidor backend para el plugin Notemd de Obsidian, que ofrece procesamiento de texto y gestión de conocimiento impulsados por IA.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Notemd MCP (Mission Control Platform) Server

==================================================
  _   _       _   _ ___    __  __ ___
 | \ | | ___ | |_| |___|  |  \/  |___ \
 |  \| |/ _ \| __| |___|  | |\/| |   | |
 | |\  | (_) | |_| |___   | |  | |___| |
 |_| \_|\___/ \__|_|___|  | |  | |____/
==================================================
   AI-Powered Backend for Your Knowledge Base
==================================================

¡Bienvenido al servidor Notemd MCP! Este proyecto proporciona un potente servidor backend independiente que expone las funcionalidades principales de procesamiento de texto impulsadas por IA y gestión del conocimiento del Plugin de Obsidian Notemd.

English | 简体中文

Construido con Python y FastAPI, este servidor le permite descargar tareas computacionales pesadas del cliente y proporciona una API robusta para interactuar con su base de conocimiento de forma programática.

Características

  • Enriquecimiento de contenido impulsado por IA: Procesa automáticamente contenido Markdown para identificar conceptos clave y crear [[wiki-links]], construyendo un grafo de conocimiento profundamente interconectado.
  • Generación automatizada de documentación: Genera documentación completa y estructurada a partir de un solo título o palabra clave, utilizando opcionalmente investigación web para contexto.
  • Investigación web integrada y resumen: Realiza búsquedas web usando Tavily o DuckDuckGo y utiliza un LLM para proporcionar resúmenes concisos sobre cualquier tema.
  • Flujos de trabajo de diagramas (Canónico + Alias de compatibilidad): Soporta generate_diagram como flujo canónico además de generate_experimental_diagram como alias de compatibilidad heredado alineado con las superficies de comandos modernas de NotEMD.
  • Utilidades de traducción y extracción: Añade operaciones de traducción de primera clase, extracción de conceptos y extracción de texto original verbatim para pipelines de automatización.
  • Integridad del grafo de conocimiento: Incluye endpoints para actualizar o eliminar automáticamente backlinks cuando los archivos se renombran o eliminan, evitando enlaces rotos.
  • Corrección de sintaxis: Proporciona una utilidad para corregir por lotes errores comunes de sintaxis de Mermaid.js y LaTeX que se encuentran a menudo en contenido generado por LLM.
  • Altamente configurable: Todas las características principales, claves de API, rutas de archivos y parámetros de modelo se gestionan fácilmente en un archivo central config.py.
  • Soporte multi-LLM: Compatible con cualquier API compatible con OpenAI, incluidos modelos locales mediante LMStudio y Ollama, y proveedores en la nube como DeepSeek, Anthropic, Google y más.
  • Documentación API interactiva: Incluye documentación API interactiva generada automáticamente mediante Swagger UI.

Cómo funciona

El servidor está construido sobre una arquitectura simple y lógica:

  • main.py (Capa de API): Define todos los endpoints de la API utilizando el framework FastAPI. Maneja las solicitudes entrantes, valida los datos usando Pydantic y llama a las funciones apropiadas de la capa de lógica central.
  • notemd_core.py (Capa de lógica): El motor de la aplicación. Contiene toda la lógica de negocio para interactuar con LLMs, procesar texto, realizar búsquedas web y gestionar archivos dentro de su base de conocimiento.
  • config.py (Espacio definido por el usuario): El centro de configuración central. Aquí es donde define sus rutas de archivos, claves de API y ajusta el comportamiento del servidor para adaptarlo a sus necesidades.
  • cli.js (Puente MCP): Una interfaz de línea de comandos basada en Node.js que actúa como puente hacia el servidor Python. Utiliza el @modelcontextprotocol/sdk para crear un servidor que puede ser llamado por otras herramientas. Inicia el servidor FastAPI y luego se comunica con él mediante solicitudes HTTP.

Primeros pasos

Siga estos pasos para poner en marcha el servidor Notemd MCP en su máquina local.

Requisitos previos

  • Para ejecución con Python: Python 3.8+ y pip o uv.
  • Para ejecución con NPX: Node.js y npx.

Instalación y ejecución

Elija el método que mejor se adapte a su flujo de trabajo.

Método 1: Usando npx (Recomendado para inicio rápido)

Esta es la forma más sencilla de iniciar el servidor. npx descargará y ejecutará temporalmente el paquete. Este método ahora soporta modo stdio, lo que significa que verá los registros del servidor FastAPI directamente en su terminal.

# This single command will download the package and start the server.
npx notemd-mcp-server

Método 2: Instalación local con uv o pip

Este método es para usuarios que desean clonar el repositorio y gestionar los archivos localmente.

  1. Clonar el repositorio:

    git clone https://github.com/your-repo/notemd-mcp.git
cd notemd-mcp

  2. Instalar dependencias:

    • Usando uv (Recomendado): 
      uv venv
uv pip install -r requirements.txt
    • Usando pip: 
      python -m venv .venv
# Activate the environment (e.g., source .venv/bin/activate)
pip install -r requirements.txt

  3. Ejecutar el servidor:

    uvicorn main:app --reload

Método 3: Configuración MCP

Para integrar Notemd MCP con su configuración de Mission Control Platform (MCP), añada lo siguiente al objeto mcpServers en su archivo settings.json:

 {
   "mcpServers": {
     "notemd-mcp": {
       "description": "Notemd MCP Server - AI-powered text processing and knowledge management
 for your Markdown files.",
       "command": "npx",
       "args": [
         "-y",
         "notemd-mcp-server"
       ],
       "env": {
         "OPENAI_API_KEY": "your_openai_api_key_here",
         "DEEPSEEK_API_KEY": "your_deepseek_api_key_here"
       }
     }
   }
 }

Uso

La mejor manera de explorar e interactuar con la API es a través de la documentación generada automáticamente.

  • Navegue a http://127.0.0.1:8000/docs en su navegador web.

Verá una interfaz Swagger UI completa e interactiva donde puede ver los detalles de cada endpoint, consultar los modelos de solicitud e incluso enviar solicitudes de prueba directamente desde su navegador.

Endpoints de la API

EndpointMétodoDescripciónCuerpo de solicitudRespuesta
/process_contentPOSTToma un bloque de texto y lo enriquece con [[wiki-links]].{"content": "string", "cancelled": "boolean"}{"processed_content": "string"}
/generate_titlePOSTGenera documentación completa a partir de un solo título.{"title": "string", "cancelled": "boolean"}{"generated_content": "string"}
/research_summarizePOSTRealiza una búsqueda web sobre un tema y devuelve un resumen generado por IA.{"topic": "string", "cancelled": "boolean"}{"summary": "string"}
/execute_custom_promptPOSTEjecuta un prompt definido por el usuario con el contenido proporcionado.{"prompt": "string", "content": "string", "cancelled": "boolean"}{"response": "string"}
/translate_contentPOSTTraduce texto/markdown a un idioma de destino.{"content": "string", "target_language": "string", "cancelled": "boolean"}{"translated_content": "string"}
/summarize_as_mermaidPOSTResume contenido como un mindmap de Mermaid.{"content": "string", "target_language": "string", "cancelled": "boolean"}{"mermaid_summary": "string"}
/generate_diagramPOSTEndpoint canónico de generación de diagramas.{"content": "string", "diagram_intent": "string", "target_language": "string", "compatibility_mode": "string", "cancelled": "boolean"}{"diagram": "string"}
/generate_experimental_diagramPOSTAlias de compatibilidad heredado para generación de diagramas.{"content": "string", "diagram_intent": "string", "target_language": "string", "cancelled": "boolean"}{"diagram": "string"}
/preview_diagramPOSTEndpoint canónico de vista previa de diagramas (sin efectos secundarios en archivos).{"content": "string", "diagram_intent": "string", "target_language": "string", "compatibility_mode": "string", "cancelled": "boolean"}{"diagram": "string"}
/preview_experimental_diagramPOSTAlias de vista previa heredado para compatibilidad.{"content": "string", "diagram_intent": "string", "target_language": "string", "cancelled": "boolean"}{"diagram": "string"}
/extract_conceptsPOSTExtrae lista de conceptos centrales deduplicados.{"content": "string", "cancelled": "boolean"}{"concepts": ["..."]}
/extract_original_textPOSTExtrae coincidencias verbatim para la entrada del usuario a partir del contenido de referencia.{"reference_content": "string", "user_input": "string", "cancelled": "boolean"}{"extracted_text": "string"}
/check_duplicatesPOSTDevuelve términos duplicados normalizados detectados en el contenido.{"content": "string"}{"duplicates": ["..."], "count": 0}
/handle_file_renamePOSTActualiza todos los backlinks en el vault cuando un archivo se renombra.{"old_path": "string", "new_path": "string"}{"status": "success"}
/handle_file_deletePOSTElimina todos los backlinks a un archivo que ha sido eliminado.{"path": "string"}{"status": "success"}
/batch_fix_mermaidPOSTEscanea una carpeta y corrige errores comunes de sintaxis de Mermaid.js y LaTeX en archivos .md.{"folder_path": "string"}{"errors": [], "modified_count": "integer"}
/healthGETUna verificación de salud simple para confirmar que el servidor está en ejecución.(Ninguno){"status": "ok"}

Configuración

Toda la configuración se maneja en el archivo config.py. Aquí puede establecer claves de API, rutas de archivos y otros ajustes.

Configuración principal

La función notemd_core.set_settings en main.py inicializa las funcionalidades principales del servidor utilizando los siguientes parámetros, obtenidos principalmente de config.py:

  • DEFAULT_PROVIDERS: Una lista de diccionarios, cada uno definiendo un proveedor de LLM con su name, apiKey, baseUrl, model, temperature y apiVersion opcional (para Azure OpenAI).
  • ACTIVE_PROVIDER: El nombre del proveedor de LLM que se utilizará por defecto para todas las operaciones.
  • CHUNK_WORD_COUNT: El número máximo de palabras por fragmento al procesar contenido para wiki-linking.
  • MAX_TOKENS: El número máximo de tokens permitidos para interacciones con LLM.
  • ENABLE_DUPLICATE_DETECTION: Booleano para habilitar/deshabilitar la detección de conceptos duplicados durante el wiki-linking.

Configuración de rutas de archivos

Estos ajustes definen la estructura de directorios para su base de conocimiento y registros:

  • VAULT_ROOT: La ruta absoluta a su vault de Obsidian o el directorio raíz de sus archivos Markdown.
  • CONCEPT_NOTE_FOLDER: La subcarpeta dentro de VAULT_ROOT donde se almacenarán las notas de conceptos generadas.
  • PROCESSED_FILE_FOLDER: La subcarpeta donde se moverán los archivos Markdown procesados.
  • CONCEPT_LOG_FOLDER: La subcarpeta para almacenar registros de generación de conceptos.
  • CONCEPT_LOG_FILE_NAME: El nombre del archivo de registro para la generación de conceptos.

Configuración de búsqueda

Ajustes relacionados con la investigación web y el resumen:

  • TAVILY_API_KEY: Su clave de API para Tavily, si SEARCH_PROVIDER está establecido en "tavily".
  • SEARCH_PROVIDER: Especifica el motor de búsqueda web a utilizar ("tavily" o "duckduckgo").
  • DDG_MAX_RESULTS: Número máximo de resultados a obtener de DuckDuckGo.
  • DDG_FETCH_TIMEOUT: Tiempo de espera en segundos para búsquedas de DuckDuckGo.
  • MAX_RESEARCH_CONTENT_TOKENS: Tokens máximos para contenido utilizado en investigación.
  • ENABLE_RESEARCH_IN_GENERATE_CONTENT: Booleano para habilitar/deshabilitar la investigación web al generar contenido a partir de un título.
  • TAVILY_MAX_RESULTS: Número máximo de resultados a obtener de Tavily.
  • TAVILY_SEARCH_DEPTH: Profundidad de búsqueda para Tavily ("basic" o "advanced").

Configuración de llamadas API estables

Estos ajustes controlan el mecanismo de reintento para llamadas API de LLM:

  • ENABLE_STABLE_API_CALL: Booleano para habilitar/deshabilitar llamadas API estables con reintentos.
  • API_CALL_INTERVAL: Intervalo en segundos entre reintentos de llamadas API.
  • API_CALL_MAX_RETRIES: Número máximo de reintentos para una llamada API fallida.

Configuración multi-modelo y específica de tareas

Estos ajustes permiten un control detallado sobre qué proveedor de LLM y modelo se utilizan para tareas específicas:

  • ADD_LINKS_PROVIDER: El proveedor de LLM a utilizar para la operación process_content (añadir enlaces).
  • RESEARCH_PROVIDER: El proveedor de LLM a utilizar para la operación research_summarize.
  • GENERATE_TITLE_PROVIDER: El proveedor de LLM a utilizar para la operación generate_title.
  • TRANSLATE_PROVIDER: Proveedor para translate_content.
  • SUMMARIZE_TO_MERMAID_PROVIDER: Proveedor para summarize_as_mermaid.
  • EXTRACT_CONCEPTS_PROVIDER: Proveedor para extract_concepts.
  • EXTRACT_ORIGINAL_TEXT_PROVIDER: Proveedor para extract_original_text.
  • DIAGRAM_PROVIDER: Proveedor para generate_diagram.
  • ADD_LINKS_MODEL: Modelo específico a utilizar para añadir enlaces (anula el predeterminado del proveedor si se establece).
  • RESEARCH_MODEL: Modelo específico a utilizar para investigación (anula el predeterminado del proveedor si se establece).
  • GENERATE_TITLE_MODEL: Modelo específico a utilizar para generación de títulos (anula el predeterminado del proveedor si se establece).
  • TRANSLATE_MODEL, SUMMARIZE_TO_MERMAID_MODEL, EXTRACT_CONCEPTS_MODEL, EXTRACT_ORIGINAL_TEXT_MODEL, DIAGRAM_MODEL: Anulaciones de modelo específicas de tareas.

Configuración de post-procesamiento

  • REMOVE_CODE_FENCES_ON_ADD_LINKS: Booleano para eliminar cercas de código del contenido después de añadir enlaces.

Configuración de idioma

  • LANGUAGE: El idioma predeterminado para el procesamiento de contenido.
  • AVAILABLE_LANGUAGES: Una lista de idiomas soportados.

Configuración de prompts personalizados

Estos ajustes le permiten habilitar y definir prompts personalizados para varias operaciones:

  • ENABLE_GLOBAL_CUSTOM_PROMPTS: Booleano para habilitar/deshabilitar el uso de prompts personalizados globalmente.
  • CUSTOM_PROMPT_ADD_LINKS: Cadena de prompt personalizado para la operación process_content (añadir enlaces).
  • CUSTOM_PROMPT_GENERATE_TITLE: Cadena de prompt personalizado para la operación generate_title.
  • CUSTOM_PROMPT_RESEARCH_SUMMARIZE: Cadena de prompt personalizado para la operación research_summarize.
  • CUSTOM_PROMPT_TRANSLATE: Cadena de prompt personalizado para translate_content.
  • CUSTOM_PROMPT_SUMMARIZE_TO_MERMAID: Cadena de prompt personalizado para summarize_as_mermaid.
  • CUSTOM_PROMPT_GENERATE_DIAGRAM: Cadena de prompt personalizado para generate_diagram.
  • CUSTOM_PROMPT_EXTRACT_CONCEPTS: Cadena de prompt personalizado para extract_concepts.
  • CUSTOM_PROMPT_EXTRACT_ORIGINAL_TEXT: Cadena de prompt personalizado para extract_original_text.

Publicación (npm + PyPI)

Utilice este comando de una línea para incrementar una versión compartida y publicar tanto npm como PyPI de forma sincronizada:

npm run release:sync-publish -- 0.6.1

Prueba en seco (sin publicar):

npm run release:sync-publish -- 0.6.1 --dry-run

Notas:

  • El comando actualiza la versión de npm (package.json + package-lock.json) y sincroniza las versiones de Python/servidor en setup.py, main.py y cli.js.
  • Asegúrate de que la autenticación de npm esté lista (npm login o NPM_TOKEN) y que la autenticación de PyPI esté lista (~/.pypirc o TWINE_USERNAME + TWINE_PASSWORD).
  • Compila los artefactos de Python y ejecuta twine check antes de la subida.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.