Doc Lib MCP

Un servidor MCP para ingesta de documentos, fragmentación, búsqueda semántica y gestión de notas.

Documentación

Servidor MCP doc-lib-mcp

Un servidor de Model Context Protocol (MCP) para la ingesta de documentos, fragmentación, búsqueda semántica y gestión de notas.

Componentes

Recursos

Implementa un sistema simple de almacenamiento de notas con:
- Esquema de URI personalizado note:// para acceder a notas individuales
- Cada recurso de nota tiene un nombre, descripción y tipo MIME text/plain

Prompts

Proporciona un prompt:
- summarize-notes: Crea resúmenes de todas las notas almacenadas
  - Argumento opcional "style" para controlar el nivel de detalle (breve/detallado)
  - Genera un prompt que combina todas las notas actuales con la preferencia de estilo

Herramientas

El servidor implementa una amplia gama de herramientas:

add-note: Agrega una nueva nota al almacén de notas en memoria
- Argumentos: name (cadena), content (cadena)
ingest-string: Ingiere y fragmenta una cadena de markdown o texto plano proporcionada mediante mensaje
- Argumentos: content (cadena, obligatorio), source (cadena, opcional), tags (lista de cadenas, opcional)
ingest-markdown: Ingiere y fragmenta un archivo markdown (.md)
- Argumentos: path (cadena)
ingest-python: Ingiere y fragmenta un archivo Python (.py)
- Argumentos: path (cadena)
ingest-openapi: Ingiere y fragmenta un archivo JSON de OpenAPI
- Argumentos: path (cadena)
ingest-html: Ingiere y fragmenta un archivo HTML
- Argumentos: path (cadena)
ingest-html-url: Ingiere y fragmenta contenido HTML desde una URL (opcionalmente usando Playwright para contenido dinámico)
- Argumentos: url (cadena), dynamic (booleano, opcional)
smart_ingestion: Extrae todo el contenido técnicamente relevante de un archivo usando Gemini, luego lo fragmenta usando lógica markdown robusta.
- Argumentos:
  - path (cadena, obligatorio): Ruta del archivo a ingerir.
  - prompt (cadena, opcional): Prompt personalizado para usar con Gemini.
  - tags (lista de cadenas, opcional): Lista opcional de etiquetas para clasificación.
- Usa Gemini 2.0 Flash 001 para extraer solo código, configuración, estructura markdown y definiciones técnicas (sin resúmenes ni comentarios).
- Pasa el contenido extraído a un fragmentador basado en mistune 3.x que preserva tanto los bloques de código como el contenido markdown/narrativo como fragmentos separados.
- Cada fragmento se incrusta y almacena para búsqueda semántica y recuperación.
search-chunks: Búsqueda semántica sobre el contenido ingerido
- Argumentos:
  - query (cadena): La consulta de búsqueda semántica.
  - top_k (entero, opcional, predeterminado 3): Número de resultados principales a devolver.
  - type (cadena, opcional): Filtrar resultados por tipo de fragmento (p. ej., code, html, markdown).
  - tag (cadena, opcional): Filtrar resultados por etiqueta en los metadatos del fragmento.
- Devuelve los fragmentos más relevantes para una consulta dada, opcionalmente filtrados por tipo y/o etiqueta.
delete-source: Elimina todos los fragmentos de una fuente dada
- Argumentos: source (cadena)
delete-chunk-by-id: Elimina uno o más fragmentos por id
- Argumentos: id (entero, opcional), ids (lista de enteros, opcional)
- Puedes eliminar un solo fragmento especificando id, o eliminar varios fragmentos a la vez especificando ids.
update-chunk-type: Actualiza el atributo de tipo de un fragmento por id
- Argumentos: id (entero, obligatorio), type (cadena, obligatorio)
ingest-batch: Ingiere y fragmenta múltiples archivos de documentación (markdown, OpenAPI JSON, Python) en lote
- Argumentos: paths (lista de cadenas)
list-sources: Lista todas las fuentes únicas (rutas de archivo) que han sido ingeridas y almacenadas en memoria, con filtrado opcional por etiqueta o búsqueda semántica.
- Argumentos:
  - tag (cadena, opcional): Filtrar fuentes por etiqueta en los metadatos del fragmento.
  - query (cadena, opcional): Consulta de búsqueda semántica para encontrar fuentes relevantes.
  - top_k (entero, opcional, predeterminado 10): Número de fuentes principales a devolver al usar la consulta.
get-context: Recupera fragmentos de contenido relevantes (solo contenido) para usar como contexto de IA, con filtrado por etiqueta, tipo y similitud semántica.
- Argumentos:
  - query (cadena, opcional): La consulta de búsqueda semántica.
  - tag (cadena, opcional): Filtrar resultados por una etiqueta específica en los metadatos del fragmento.
  - type (cadena, opcional): Filtrar resultados por tipo de fragmento (p. ej., 'code', 'markdown').
  - top_k (entero, opcional, predeterminado 5): El número de fragmentos relevantes principales a recuperar.
update-chunk-metadata: Actualiza el campo de metadatos de un fragmento por id
- Argumentos: id (entero), metadata (objeto)
tag-chunks-by-source: Agrega etiquetas especificadas a los metadatos de todos los fragmentos asociados con una fuente dada (URL o ruta de archivo). Se fusiona con las etiquetas existentes.
- Argumentos: source (cadena), tags (lista de cadenas)
list-notes: Lista todas las notas actualmente almacenadas y su contenido.

Fragmentación y Extracción de Código

Los archivos Markdown, Python, OpenAPI y HTML se dividen en fragmentos lógicos para una recuperación y búsqueda eficientes.
El fragmentador de markdown usa la API AST de mistune 3.x y regex para dividir robustamente el contenido por bloques de código y narrativa, preservando todo el formato original.
Tanto los bloques de código como el contenido markdown/narrativo se preservan como fragmentos separados.
El fragmentador de HTML usa la biblioteca readability-lxml para extraer primero el contenido principal, luego extrae fragmentos de código de bloque de las etiquetas <pre> como fragmentos dedicados de "código". El contenido en línea <code> permanece como parte de los fragmentos narrativos.

Búsqueda Semántica

La herramienta search-chunks realiza búsqueda semántica basada en vectores sobre todo el contenido ingerido, devolviendo los fragmentos más relevantes para una consulta dada.
Admite argumentos opcionales type y tag para filtrar resultados por tipo de fragmento (p. ej., code, html, markdown) y/o por etiqueta en los metadatos del fragmento, antes de la clasificación semántica.
Esto permite una recuperación altamente específica, como "todos los fragmentos de código etiquetados con 'langfuse' relevantes para 'costo y uso'".

Gestión de Metadatos

Los fragmentos incluyen un campo metadata para categorización y etiquetado.
La herramienta update-chunk-metadata permite actualizar metadatos de cualquier fragmento por su id.
La herramienta tag-chunks-by-source permite agregar etiquetas a todos los fragmentos de una fuente específica en una sola operación. El etiquetado fusiona nuevas etiquetas con las existentes, preservando las etiquetas anteriores.

Configuración

El servidor requiere las siguientes variables de entorno (se pueden configurar en un archivo .env):

Configuración de Ollama

OLLAMA_HOST: Nombre de host para la API de Ollama (predeterminado: localhost)
OLLAMA_PORT: Puerto para la API de Ollama (predeterminado: 11434)
RAG_AGENT: Modelo de Ollama a usar para respuestas RAG (predeterminado: llama3)
OLLAMA_MODEL: Modelo de Ollama a usar para embeddings (predeterminado: nomic-embed-text-v2-moe)

Configuración de la Base de Datos

HOST: Host de la base de datos PostgreSQL (predeterminado: localhost)
DB_PORT: Puerto de la base de datos PostgreSQL (predeterminado: 5432)
DB_NAME: Nombre de la base de datos PostgreSQL (predeterminado: doclibdb)
DB_USER: Usuario de la base de datos PostgreSQL (predeterminado: doclibdb_user)
DB_PASSWORD: Contraseña de la base de datos PostgreSQL (predeterminado: doclibdb_password)

Configuración del Reranker

RERANKER_MODEL_PATH: Ruta al modelo de reranker (predeterminado: /srv/samba/fileshare2/AI/models/bge-reranker-v2-m3)
RERANKER_USE_FP16: Si usar FP16 para el reranker (predeterminado: True)

Inicio Rápido

Instalación

Claude Desktop

En MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json En Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuración de servidores no publicados/desarrollo

``` "mcpServers": { "doc-lib-mcp": { "command": "uv", "args": [ "--directory", "/home/administrator/python-share/doc-lib-mcp", "run", "doc-lib-mcp" ] } } ```

Configuración de servidores publicados

``` "mcpServers": { "doc-lib-mcp": { "command": "uvx", "args": [ "doc-lib-mcp" ] } } ```

Desarrollo

Compilación y Publicación

Para preparar el paquete para distribución:

Sincronizar dependencias y actualizar el archivo de bloqueo:

uv sync

Compilar distribuciones del paquete:

uv build

Esto creará distribuciones de fuente y wheel en el directorio dist/.

Publicar en PyPI:

uv publish

Nota: Necesitarás configurar credenciales de PyPI mediante variables de entorno o banderas de comando:

Token: --token o UV_PUBLISH_TOKEN
O nombre de usuario/contraseña: --username/UV_PUBLISH_USERNAME y --password/UV_PUBLISH_PASSWORD

Depuración

Dado que los servidores MCP se ejecutan sobre stdio, la depuración puede ser desafiante. Para la mejor experiencia de depuración, recomendamos encarecidamente usar el MCP Inspector.

Puedes lanzar el MCP Inspector a través de npm con este comando:

npx @modelcontextprotocol/inspector uv --directory /home/administrator/python-share/doc-lib-mcp run doc-lib-mcp

Al lanzarlo, el Inspector mostrará una URL que puedes acceder en tu navegador para comenzar a depurar.