pergamos

Servidor MCP do Calibre

GitHubExperimente este MCPPatrocinado

Documentação

Pergamos

Tests

Pergamos é um servidor MCP somente leitura que permite ao Claude Desktop pesquisar e inspecionar uma biblioteca Calibre através do Calibre Content Server.

Requisitos

  • macOS com Python 3.10 ou mais recente
  • Calibre com o Content Server em execução
  • O SDK oficial do MCP Python, instalado pela configuração do projeto abaixo

Inicie o Calibre Content Server em Compartilhar/conectar > Iniciar servidor de conteúdo. O endereço padrão é http://127.0.0.1:8080.

Instalação

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

Configurar o Claude Desktop

Adicione uma entrada de servidor ao arquivo de configuração do Claude Desktop, geralmente ~/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 um Content Server com autenticação, adicione CALIBRE_USERNAME e CALIBRE_PASSWORD ao mesmo objeto env. CALIBRE_REQUEST_TIMEOUT pode ser definido como um número positivo de segundos. Um prefixo de URL como http://127.0.0.1:8080/calibre é suportado.

Reinicie o Claude Desktop após alterar sua configuração.

Para as ferramentas RAG opcionais, adicione a variável de ambiente PERGAMOS_RAG_DIR se quiser que o armazenamento de vetores fique em outro lugar que não o diretório padrão .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"
      }
    }
  }
}

Ferramentas

  • list_libraries: verifica o servidor e retorna o feed OPDS raiz.
  • search_books: realiza uma pesquisa em toda a biblioteca Calibre nos campos de metadados indexados pelo Calibre, incluindo títulos, autores, tags, comentários e identificadores. Aceita query, limit (1-100) e offset, e segue a paginação OPDS até o limite solicitado.
  • get_book_details: retorna metadados e links de formatos disponíveis para um identificador de livro do Calibre.
  • index_book_content: baixa um arquivo de livro selecionado, extrai o texto, divide-o em partes e armazena os embeddings para recuperação semântica.
  • search_book_content: pesquisa as partes de texto indexadas para um ou mais IDs de livro usando uma consulta semântica.

O servidor não altera a biblioteca nem baixa arquivos. As URLs de formato são retornadas como metadados para que o Claude possa identificar as edições disponíveis.

A pesquisa do Content Server do Calibre é uma pesquisa de metadados. Ela não pesquisa o texto completo de arquivos EPUB, PDF ou outros arquivos de livro.

Exemplo de fluxo de trabalho

Este é o padrão recomendado para fazer RAG com uma biblioteca 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,
)

Na prática, o Claude Desktop pode chamar as ferramentas nessa ordem:

  1. search_books para encontrar livros candidatos
  2. get_book_details para buscar os metadados exatos e URLs de formato
  3. index_book_content para adicionar o conteúdo do livro ao índice RAG
  4. search_book_content para responder consultas no estilo de perguntas sobre o texto indexado

Isso oferece recuperação de metadados mais recuperação de conteúdo semântico sem substituir a camada de pesquisa do Calibre.

Padrão RAG de camada dupla

Para RAG verdadeiro, mantenha o Pergamos como a camada de metadados/descoberta e adicione um indexador de conteúdo separado para os arquivos de livro reais. O servidor de metadados deve responder perguntas como "quais livros correspondem a este tópico?" enquanto a camada de conteúdo baixa o EPUB/PDF selecionado, extrai o texto, divide em partes, gera embeddings e armazena os vetores para pesquisa semântica.

Uma implementação inicial mínima está incluída em src/pergamos/rag/:

  • extractors.py lida com extração e divisão de texto
  • indexer.py baixa um livro, extrai texto e indexa embeddings
  • search.py expõe um wrapper simples de pesquisa semântica

Instale os extras RAG opcionais com:

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

Isso mantém a camada de navegação da biblioteca somente leitura enquanto permite um pipeline de recuperação de texto completo sobre os mesmos metadados de livros.

Exemplos executáveis

O repositório inclui alguns exemplos prontos para execução em examples/:

  • examples/rag_example.py: exemplo completo de orquestração usando as ferramentas de metadados + conteúdo em sequência.
  • examples/one_book_index.py: indexa um único livro no armazenamento de vetores local.

Execute-os com:

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

Docker Compose

Uma pilha mínima pode ser iniciada com Docker Compose para desenvolvimento local:

docker compose up --build

Isso inicia:

  • pergamos: o servidor MCP
  • calibre: o servidor de conteúdo web do Calibre

A pilha usa um volume nomeado para o índice de vetores local e vincula o servidor de conteúdo do Calibre à porta 8080.

Você pode personalizar as variáveis de execução copiando o arquivo de ambiente de exemplo:

cp .env.example .env

Em seguida, edite .env com sua URL e credenciais locais do Calibre. O arquivo Compose também pode ser apontado para http://calibre:8080 se você quiser o nome do serviço conteinerizado em vez de uma URL vinculada ao host.

Comandos comuns

Use o Makefile incluído para as principais tarefas do projeto:

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

Execução manual

O Claude Desktop se comunica com o servidor via stdio. Para executá-lo diretamente para diagnósticos:

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

Não imprima mensagens de diagnóstico no stdout porque o stdout é reservado para o tráfego do protocolo MCP.

Segurança

Prefira um servidor Calibre local vinculado a 127.0.0.1. Se o servidor estiver acessível por uma rede, habilite a autenticação do Calibre e HTTPS. Mantenha as credenciais na configuração de ambiente do Claude Desktop e não faça commit desse arquivo.

Lista de verificação de segurança para commits

Antes de criar um commit inicial ou enviar um PR, confirme que:

  • .env, .env.local e qualquer arquivo de credenciais estão excluídos do git
  • dados gerados como .pergamos_index/ e caches locais são ignorados
  • a documentação usa exemplos neutros como /path/to/pergamos em vez de caminhos específicos de máquina
  • URLs, nomes de usuário e senhas reais do Calibre nunca são codificados no repositório
  • arquivos de configuração de exemplo são placeholders seguros, não configuração local ativa

Um comando rápido de revisão é:

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

Desenvolvimento

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