doc-lib-mcp

doc-lib-mcp Servidor MCP

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

Componentes

Recursos

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

Indicaciones

• Proporciona un mensaje:
  • resumir-notas : crea resúmenes de todas las notas almacenadas
    • Argumento opcional "estilo" para controlar el nivel de detalle (breve/detallado)
    • Genera un mensaje 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 texto sin formato o de rebajas proporcionada mediante un mensaje
  • Argumentos: content (cadena, obligatorio), source (cadena, opcional), tags (lista de cadenas, opcional)
• ingest-markdown : ingerir y fragmentar un archivo markdown (.md)
  • Argumentos: path (cadena)
• ingest-python : ingerir y fragmentar un archivo Python (.py)
  • Argumentos: path (cadena)
• ingest-openapi : ingerir y fragmentar un archivo JSON de OpenAPI
  • Argumentos: path (cadena)
• ingest-html : ingerir y fragmentar un archivo HTML
  • Argumentos: path (cadena)
• ingest-html-url : ingerir y fragmentar 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 y luego lo divide en fragmentos usando una lógica de rebajas robusta.
  • Argumentos:
    • path (cadena, obligatoria): ruta del archivo a ingerir.
    • prompt (cadena, opcional): mensaje personalizado para usar con Gemini.
    • tags (lista de cadenas, opcional): Lista opcional de etiquetas para clasificación.
  • Utiliza Gemini 2.0 Flash 001 para extraer solo código, configuración, estructura de rebajas y definiciones técnicas (sin resúmenes ni comentarios).
  • Pasa el contenido extraído a un fragmentador basado en mistune 3.x que conserva tanto los bloques de código como el contenido markdown/narrativo como fragmentos separados.
  • Cada fragmento se integra y almacena para su búsqueda y recuperación semántica.
• fragmentos de búsqueda : 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): filtra los resultados por tipo de fragmento (por ejemplo, code , html , markdown ).
    • tag (cadena, opcional): filtra los resultados por etiqueta en los metadatos del fragmento.
  • Devuelve los fragmentos más relevantes para una consulta determinada, opcionalmente filtrados por tipo y/o etiqueta.
• delete-source : elimina todos los fragmentos de una fuente determinada
  • Argumentos: source (cadena)
• delete-chunk-by-id : elimina uno o más fragmentos por id
  • Argumentos: id (entero, opcional), ids (lista de enteros, opcional)
  • Puede eliminar un solo fragmento especificando id , o eliminar varios fragmentos a la vez especificando ids .
• update-chunk-type : actualiza el atributo de tipo para 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 lotes
  • Argumentos: paths (lista de cadenas)
• list-sources : enumera todas las fuentes únicas (rutas de archivos) que se han ingerido y almacenado en la memoria, con filtrado opcional por etiqueta o búsqueda semántica.
  • Argumentos:
    • tag (cadena, opcional): filtra las 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 cuando se usa 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): filtra los resultados por una etiqueta específica en los metadatos del fragmento.
    • type (cadena, opcional): filtra los resultados por tipo de fragmento (por ejemplo, 'código', 'markdown').
    • top_k (entero, opcional, predeterminado 5): la cantidad de fragmentos relevantes principales para recuperar.
• update-chunk-metadata : actualiza el campo de metadatos de un fragmento por id
  • Argumentos: id (entero), metadata (objeto)
• tag-chunks-by-source : Añade las etiquetas especificadas a los metadatos de todos los fragmentos asociados a una fuente dada (URL o ruta de archivo). Se fusiona con las etiquetas existentes.
  • Argumentos: source (cadena), tags (lista de cadenas)
• list-notes : enumera todas las notas almacenadas actualmente 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 rebajas utiliza la API AST y las expresiones regulares de mistune 3.x para dividir de forma robusta el contenido por bloques de código y narrativa, preservando todo el formato original.
• Tanto los bloques de código como el contenido narrativo/de rebajas se conservan como fragmentos separados.
• El fragmentador HTML utiliza la biblioteca readability-lxml para extraer primero el contenido principal y, a continuación, extrae fragmentos de código de las etiquetas <pre> como fragmentos de código dedicados. El contenido <code> en línea forma parte de los fragmentos narrativos.

Búsqueda semántica

• La herramienta search-chunks realiza una búsqueda semántica basada en vectores en todo el contenido ingerido y devuelve los fragmentos más relevantes para una consulta determinada.
• Admite argumentos type y tag opcionales para filtrar resultados por tipo de fragmento (por ejemplo, code , html , markdown ) y/o por etiqueta en los metadatos del fragmento, antes de la clasificación semántica.
• Esto permite una recuperación muy 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 los metadatos de cualquier fragmento mediante su identificación.
• La herramienta de tag-chunks-by-source permite agregar etiquetas a todos los fragmentos de un origen específico en una sola operación. El etiquetado fusiona las etiquetas nuevas con las existentes, conservando las anteriores.

Configuración

[TODO: Agregar detalles de configuración específicos para su implementación]

Inicio rápido

Instalar

Escritorio de Claude

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

Desarrollo

Construcción y publicación

Para preparar el paquete para su distribución:

1. Sincronizar dependencias y actualizar archivo de bloqueo:

2. Distribuciones de paquetes de compilación:

Esto creará distribuciones de origen y de rueda en el directorio dist/ .

3. Publicar en PyPI:

Nota: Deberás configurar las credenciales de PyPI a través de variables de entorno o indicadores 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 en stdio, la depuración puede ser complicada. Para una experiencia óptima, recomendamos usar el Inspector MCP .

Puede iniciar el Inspector MCP a través de npm con este comando:

Al iniciarse, el Inspector mostrará una URL a la que podrá acceder en su navegador para comenzar a depurar.