pergamos

Servidor MCP de Calibre

GitHubPrueba este MCPPatrocinado

Documentación

Pergamos

Tests

Pergamos es un servidor MCP de solo lectura que permite a Claude Desktop buscar e inspeccionar una biblioteca de Calibre a través del Calibre Content Server.

Requisitos

  • macOS con Python 3.10 o superior
  • Calibre con el Content Server en ejecución
  • El SDK oficial de MCP para Python, instalado mediante la configuración del proyecto que se indica a continuación

Inicie el Calibre Content Server desde Compartir/Conectar > Iniciar Content server. La dirección predeterminada es http://127.0.0.1:8080.

Instalación

cd /path/to/pergamos
python3 -m venv .venv
.venv/bin/python -m pip install -e .

Configurar Claude Desktop

Agregue una entrada de servidor al archivo de configuración de Claude Desktop, generalmente ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pergamos-calibre": {
      "command": "/path/to/pergamos/.venv/bin/pergamos",
      "env": {
        "CALIBRE_SERVER_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

Para un Content Server con autenticación, agregue CALIBRE_USERNAME y CALIBRE_PASSWORD al mismo objeto env. CALIBRE_REQUEST_TIMEOUT puede establecerse en un número positivo de segundos. Se admite un prefijo de URL como http://127.0.0.1:8080/calibre.

Reinicie Claude Desktop después de cambiar su configuración.

Para las herramientas RAG opcionales, agregue la variable de entorno PERGAMOS_RAG_DIR si desea que el almacén de vectores se ubique en un lugar distinto al directorio predeterminado .pergamos_index:

{
  "mcpServers": {
    "pergamos-calibre": {
      "command": "/path/to/pergamos/.venv/bin/pergamos",
      "env": {
        "CALIBRE_SERVER_URL": "http://127.0.0.1:8080",
        "PERGAMOS_RAG_DIR": "/path/to/pergamos/.pergamos_index"
      }
    }
  }
}

Herramientas

  • list_libraries: verifica el servidor y devuelve la fuente OPDS raíz.
  • search_books: realiza una búsqueda en toda la biblioteca de Calibre a través de los campos de metadatos indexados por Calibre, incluidos títulos, autores, etiquetas, comentarios e identificadores. Acepta query, limit (1-100) y offset, y sigue la paginación OPDS hasta el límite solicitado.
  • get_book_details: devuelve metadatos y enlaces de formatos disponibles para un identificador de libro de Calibre.
  • index_book_content: descarga un archivo de libro seleccionado, extrae el texto, lo divide en fragmentos y almacena las incrustaciones para la recuperación semántica.
  • search_book_content: busca en los fragmentos de texto indexados uno o más ID de libro mediante una consulta semántica.

El servidor no modifica la biblioteca ni descarga archivos. Las URL de formato se devuelven como metadatos para que Claude pueda identificar las ediciones disponibles.

La búsqueda del Content Server de Calibre es una búsqueda de metadatos. No busca el texto completo de archivos EPUB, PDF u otros archivos de libro.

Flujo de trabajo de ejemplo

Este es el patrón recomendado para realizar RAG con una biblioteca de Calibre:

# 1) Discover likely books by metadata
search = {
    "query": "distributed systems",
    "limit": 5,
    "offset": 0,
}

# 2) Inspect the chosen book and pick the format to index
book = {
    "id": "42",
    "title": "Distributed Systems",
    "formats": [
        {"format": "epub", "url": "http://127.0.0.1:8080/get/42/epub"},
    ],
}

# 3) Index the full text of the selected book
index_book_content(
    book_id="42",
    title="Distributed Systems",
    download_url="http://127.0.0.1:8080/get/42/epub",
    format_name="epub",
)

# 4) Run semantic search over the indexed text for that book
search_book_content(
    query="What does the book say about consensus?",
    book_ids=["42"],
    k=5,
)

En la práctica, Claude Desktop puede llamar a las herramientas en ese orden:

  1. search_books para encontrar libros candidatos
  2. get_book_details para obtener los metadatos exactos y las URL de formato
  3. index_book_content para agregar el contenido del libro al índice RAG
  4. search_book_content para responder consultas de tipo pregunta sobre el texto indexado

Esto le brinda recuperación de metadatos más recuperación de contenido semántico sin reemplazar la capa de búsqueda de Calibre.

Patrón RAG de doble capa

Para un RAG real, mantenga Pergamos como la capa de metadatos/descubrimiento y agregue un indexador de contenido separado para los archivos de libro reales. El servidor de metadatos debe responder preguntas como "¿qué libros coinciden con este tema?" mientras que la capa de contenido descarga el EPUB/PDF seleccionado, extrae el texto, lo divide en fragmentos, lo incrusta y almacena los vectores para la búsqueda semántica.

Se incluye una implementación inicial mínima en src/pergamos/rag/:

  • extractors.py maneja la extracción de texto y la división en fragmentos
  • indexer.py descarga un libro, extrae el texto e indexa las incrustaciones
  • search.py expone un envoltorio simple de búsqueda semántica

Instale los extras RAG opcionales con:

python3 -m pip install -e '.[rag]'

Esto mantiene la capa de navegación de la biblioteca en modo solo lectura mientras habilita un pipeline de recuperación de texto completo sobre los mismos metadatos de libros.

Ejemplos ejecutables

El repositorio incluye algunos ejemplos listos para ejecutar en examples/:

  • examples/rag_example.py: ejemplo completo de orquestación que utiliza las herramientas de metadatos + contenido en secuencia.
  • examples/one_book_index.py: indexa un solo libro en el almacén de vectores local.

Ejecútelos con:

.venv/bin/python examples/rag_example.py
.venv/bin/python examples/one_book_index.py

Docker Compose

Se puede iniciar una pila mínima con Docker Compose para el desarrollo local:

docker compose up --build

Esto inicia:

  • pergamos: el servidor MCP
  • calibre: el servidor web de contenido de Calibre

La pila utiliza un volumen con nombre para el índice de vectores local y vincula el servidor de contenido de Calibre al puerto 8080.

Puede personalizar las variables de ejecución copiando el archivo de entorno de ejemplo:

cp .env.example .env

Luego edite .env con su URL y credenciales locales de Calibre. El archivo Compose también puede apuntarse a http://calibre:8080 si desea usar el nombre del servicio contenedorizado en lugar de una URL vinculada al host.

Comandos comunes

Use el Makefile incluido para las tareas principales del proyecto:

make install
make test
make run
make docker-up
make docker-down

Ejecución manual

Claude Desktop se comunica con el servidor a través de stdio. Para ejecutarlo directamente con fines de diagnóstico:

CALIBRE_SERVER_URL=http://127.0.0.1:8080 .venv/bin/pergamos

No imprima mensajes de diagnóstico en stdout porque stdout está reservado para el tráfico del protocolo MCP.

Seguridad

Prefiera un servidor Calibre local vinculado a 127.0.0.1. Si el servidor es accesible a través de una red, habilite la autenticación de Calibre y HTTPS. Mantenga las credenciales en la configuración de entorno de Claude Desktop y no confirme ese archivo.

Lista de verificación de seguridad para confirmaciones

Antes de crear una confirmación inicial o enviar un PR, confirme que:

  • .env, .env.local y cualquier archivo de credenciales estén excluidos de git
  • los datos generados como .pergamos_index/ y las cachés locales estén ignorados
  • la documentación use ejemplos neutrales como /path/to/pergamos en lugar de rutas específicas de la máquina
  • las URL, nombres de usuario y contraseñas reales de Calibre nunca estén codificados en el repositorio
  • los archivos de configuración de ejemplo sean marcadores de posición seguros, no configuración local activa

Un comando de revisión rápida es:

git status --short
git ls-files .env .pergamos_index .venv .pytest_cache

Desarrollo

.venv/bin/python -m pip install pytest
.venv/bin/python -m pytest -q