AI导哈

Calibre MCP 服务器与搜索插件

一个实验性的 Model Context Protocol (MCP) 服务器，提供对本地 Calibre 电子书库的研究 API，包括全文搜索和结构化摘录功能。

  • by Miguel0888
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Miguel0888/mcp-server

使用说明

Calibre MCP服务器和搜索插件

一个实验 模型上下文协议（MCP） 服务器位于本地 卡利伯 图书馆进入。其目的是为 AI 代理（如 ChatGPT、Copilot、Claude Desktop）提供一个研究 API，以便为您的电子书收藏提供全文搜索和结构化摘录。

此外，还有一个Calibre GUI插件。

  • den MCP-服务器 WebSocket-Dienst开始了。ws://127.0.0.1:8765）和
  • 一 搜索代理 提供，该
    • 使用 MCP 服务器的全文工具，
    • 通过LLM衍生的关键词和
    • 在 Calibre 对话框中显示包括来源在内的答案（标题 + ISBN）。

特点（现状）

MCP‑服务器

  • 实施于 fastmcp
  • 目前提供两个工具：
    • calibre_fulltext_search
      • 输入 ： query: str, limit: int
      • 发送结果（book_id, title, isbn, snippet)
      • 搜索 metadata.db 关于 books + comments （标题，ISBN，评论）
    • calibre_get_excerpt
      • 输入 ： isbn: str, max_chars: int
      • 提供短的文本片段加元数据（book_id, title)
  • 域层 LibraryResearchService 作为中央API
  • 访问 Calibremetadata.db 通过SQLite（只读）
    • ISBN 查找 identifiers +回退auf books.isbn

Calibre插件 mcp_server_recherche

  • 通过 WebSocket 启动/停止 MCP 服务器 （ws://host:port)
  • 设置一个 检索对话框 准备好了，
    • 向已配置的LLM提供商发送问题，
    • 自动使用 MCP 工具进行全文搜索和摘录
    • 显示搜索结果和摘录
    • 生成包含来源（包括ISBN）的结构化响应。
  • 支持 后续问题:
    • 短询将与上一个问题相结合 （例如，“告诉我更多关于 LIN 的信息（以：有哪些车辆总线系统？”）。
    • 代理再次在库中搜索，但使用以前的上下文。
  • 对话框中的调试输出（可选），例如：
    • Suchrunde 1 (Kernbegriffe): ['hacking', 'Sicherheit', ...]
    • Toolcall calibre_fulltext_search: query='hacking', limit=6
    • MCP -> list_tools, MCP <- call_tool 美国。

仓库结构（简介）

重要目录/文件：

  • pyproject.toml 项目和依赖定义
  • src/calibre_mcp_server/ MCP 服务器和域代码
    • core/models.py 简单域模型（FulltextHit, Excerpt, ...)
    • core/service.py – LibraryResearchService，zentrale Research‑API
    • infra/metadata_sqlite.py – 访问 metadata.db 关于SQLite
    • tools/ft_search_tool.py –MCP工具 calibre_fulltext_search
    • tools/excerpt_tool.py –MCP工具 calibre_get_excerpt
    • websocket_server.py – 用于 MCP 调用的小型 WebSocket RPC 服务器
    • mcp_protocol.py 简单的 MCP 请求/响应结构
    • main.py 服务器的入口点
  • calibre_plugin/ –Calibre-GUI插件
    • __init__.py – Calibre 插件元数据
    • config.py – 插件设置 / UI
    • main.py – 对话框， 搜索代理， 启动/停止 WebSocket 服务器
    • providers.py – 配置LLM提供程序（OpenAI兼容等）
    • recherche_agent.py LLM + MCP-Tools的编排
    • ui.py Qt Dialog 和 UI 逻辑
  • tests/
    • inspect_metadata_isbn.py 调试脚本，显示ISBN映射 metadata.db
    • manual_test_websocket_connectivity.py – 使用简单的客户端测试 WS-Server

安装（开发设置）

先决条件：

  • Python 3.10+（测试使用 3.12）
  • 本地 Calibre 库 metadata.db)

开发环境（Development Environment）：

# Repository klonen
git clone https://github.com/Miguel0888/mcp-server.git
cd mcp-server

# Optional: virtuelles Environment anlegen
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS

# Paket im Editable‑Mode installieren (inkl. Dependencies)
python -m pip install --upgrade pip
python -m pip install -e .

之后，包裹 calibre_mcp_server 在活动的 Python 解释器中可用。

手动启动 MCP 服务器（WebSocket 模式）

Calibre 插件工作流会自动启动服务器。对于手动测试，您也可以直接运行它。

1. 通过环境变量进行配置

服务器读取库配置 src/calibre_mcp_server/config.py默认：当前 Calibre 库或配置的路径。

对于手动测试，您可以 CALIBRE_LIBRARY_PATH 设置：

set CALIBRE_LIBRARY_PATH=X:\E-Books
python -m calibre_mcp_server.main

然后，服务器启动一个 WebSocket 端点，例如： ws://127.0.0.1:8765接受类似 MCP 的请求（list_tools, call_tool).

测试工具（例如通过 WebSocket 客户端或测试脚本）

查看 tests/manual_test_websocket_connectivity.py 一个最小的例子：

  • 连接到 ws://127.0.0.1:8765 制造，
  • list_tools 发送和
  • 随后 call_tool 为 calibre_fulltext_search 执行 。

Calibre‑Plugin：安装和配置

创建插件-ZIP（如果不是通过 GitHub 发布）

在 Project Root 中：

mkdir dist
cd calibre_plugin
zip -r ..\dist\calibre-mcp-plugin.zip .

ZIP文件 dist/calibre-mcp-plugin.zip 然后按照 Calibre 的预期，将插件文件包含在 root 中。

在 Calibre 中安装插件

  1. 打开Calibre
  2. 设置 → 插件 → 从文件加载插件
  3. dist/calibre-mcp-plugin.zip 选择
  4. 校准或启动

之后，插件（例如“MCP搜索”）将出现在菜单/工具栏中。

插件的重要设置

Im插件对话框(Einstellungen → Plugins → MCP Server Recherche → Konfigurieren):

  • MCP 服务器设置
    • Server-Host （默认值： 127.0.0.1)
    • Server-Port （默认值： 8765)
    • Calibre-Bibliothek （可选固定路径；否则使用活动库）
    • 可选：用于 MCP 服务器的 Python 解释器（如果不使用全局解释器）
  • 重新研究-Feintuning
    • max_query_variants – 每轮搜索查询最多使用多少变体。
    • max_hits_per_query 每个查询的命中次数限制。
    • max_hits_total – 在上下文中采用的命中次数的全球限制。
    • target_sources – 代理人至少应该找到多少不同的来源（书籍）。
    • max_excerpts / max_excerpt_chars 摘录的数量和长度。
    • min_hits_required – 搜索结束前的最小匹配次数。
    • max_search_rounds – 代理最大化搜索次数（例如2：简单关键字+精简）。
    • context_influence 以前的问题对新需求的影响程度（0-100）。
  • 提示提示
    • Hinweis für Query-Planer-Prompt (query_planner_hint)
      • 您可以提供给 AI 以控制搜索查询类型的额外文本 （例如“优先使用德国汽车工程专业术语”）。
    • Hinweis für Schlagwort-Prompt (keyword_extraction_hint)
      • 优化关键字提取，例如“首先使用没有AND的广义术语，而不是长的UND字符串”。
    • Hinweis für Antwort-Prompt (answer_style_hint)
      • 补充如何表达答案（例如“解释学士学位”）。
  • 搜索模式
    • LLM für Query-Planung verwenden 启用/关闭 LLM 支持的关键字/查询规划。
    • Max. Schlagwörter pro Suche (max_search_keywords)
    • Verknüpfung (AND/OR) (keyword_boolean_operator主要用于经典启发式查询。

搜索代理如何工作（高级）

逻辑的核心在于 calibre_plugin/recherche_agent.py:

  1. 问题正常化

    • 空的输入将被忽略。
    • 简短的查询将与上一个问题相结合，以获得上下文。

  2. 执行搜索

    • 第一轮：
      • _extract_keywords （LLM） 生成单词列表/简单短语。
      • 如果它只是一个列表（例如“黑客网络攻击安全……”）， 单词被分割和 单个 作为查询（hacking, Sicherheit, ...). → 对单个术语进行有效的OR-搜索。
      • 如果返回多个短语，则每个短语将被用作自己的查询。
    • 轮2+（可选，最多） max_search_rounds):
      • _refine_search_queries 利用LLM基于以往的结果 创建替代或复杂的搜索查询。
      • 结果将与之前的结果合并并并重复。

  3. 用摘录丰富结果

    • 对于有限数量的ISBN匹配，请调用代理 calibre_get_excerpt auf， 加载短文本片段（例如评论）。

  4. 快速构建和获取LLM答案

    • 代理构建一个由三个部分组成的Markdown提示符：
      1. 简要摘要
      2. 相关书籍，带有简要注释和ISBN
      3. 详细回答问题
    • LLM提供商将通过 ChatProviderClient 被提及。

  5. 在对话框中显示答案

    • 对话框显示响应（Markdown）和可选的工具使用调试日志。

调试与测试

  • 直接测试FT搜索
    • src/calibre_mcp_server/tools/ft_search_tool.py 使用 LibraryResearchService.fulltext_search.
    • 您可以使用简单的 WebSocket 客户端或测试脚本进行手动测试。
  • 检查 ISBN 映射
    • tests/inspect_metadata_isbn.py 有助于了解Calibre ISBNs如何在 books 和 identifiers 放置 。

示例调用：

python tests\inspect_metadata_isbn.py 9783658024192

路线图/Ieden

  • 其他 MCP 工具，例如
    • 关键字搜索（标签、系列）
    • 作者搜索
    • 实际书籍内容的全文搜索（如有索引）
  • 更好地支持 Calibre 对话框中的流响应
  • 可配置的工具跟踪显示（调试面板可打开/隐藏）
  • 针对搜索代理的高级多阶段策略（例如，超过 2 轮搜索、加权匹配）

这个项目是实验性的 - 欢迎反馈，问题和拉请求。

ChatGPT:每个隧道的HTTPS加密协议（Cloudflare/ngrok）

ChatGPT kann 没有本地 localhost/127.0.0.1到达服务器。所以你需要一个 公开访问的 HTTPS URL重定向到您的本地 HTTP MCP 端点。

1） mcp-http本地启动器

首先在本地启动 HTTP MCP 服务器（例如端口 8000）：

set CALIBRE_LIBRARY_PATH=X:\E-Books
set MCP_HTTP_HOST=127.0.0.1
set MCP_HTTP_PORT=8000
python -m calibre_mcp_server.http_server

之后，终端点应该可以在本地访问：

  • http://127.0.0.1:8000/mcp

注： 路径 (/mcp它必须与您的服务器相匹配。

2） Cloudflare隧道（快速隧道）

安装（例子）：

  • 窗户： winget install Cloudflare.cloudflared
  • macOS： brew install cloudflare/cloudflare/cloudflared

开始隧道 ：

cloudflared tunnel --url http://127.0.0.1:8000

你会得到一个像这样的URL。 https://<irgendwas>.trycloudflare.com.

ChatGPT连接器URL:

  • https://<irgendwas>.trycloudflare.com/mcp

3） 替代品：ngrok

开始隧道 ：

ngrok http 8000

你会得到一个像这样的URL。 https://<irgendwas>.ngrok-free.app.

ChatGPT连接器URL:

  • https://<irgendwas>.ngrok-free.app/mcp

安全说明

在ChatGPT中时 “混合” 或 没有OAuth 如果工作的话，隧道链接是你的“钥匙”。 将URL视为秘密（不发布，不写入公共日志）。对于真正的安全性，OAuth流是更强大的解决方案。

相关 MCP