bookbind

bookbind

bookbind 是一个小型本地桥接程序，可连接到托管服务 Epublys。该服务可处理 EPUB 和 PDF 电子书：合并和拆分图书、压缩、格式转换、编辑元数据、检查文件是否存在规范问题，以及生成封面图。本软件包本身不执行任何这些操作。它接入该服务的远程 MCP 端点，在本地原样呈现上游捕获的工具列表，并转发每次调用，返回上游提供的任何内容。

这种分工在实际使用中很重要。转换、元数据编辑和验证结论都由 Epublys 自己的机制提供，因此通过 bookbind 获得的结果就是该服务的结果，而不是本地近似结果。桥接程序不会自行进行任何处理，也不会改写返回内容。大多数工具接收 Base64 编码的文件内容（多文件工具使用 files，其他工具使用 file），并返回 Base64 编码的结果；每种工具的说明中所述的上游免费套餐和 Pro 限制同样适用。

工具

此版本提供捕获到的工具集合中的指定子集：在实时捕获中看到的 13 个工具里有 12 个。省略的工具是 upgrade_to_pro，它会返回结账链接，供用户将账户升级到付费套餐；付款流程不在此程序的范围内，因此特意不提供该工具，并且有测试会断言该工具不存在。其余工具均为文档操作，原样提供——其中包括 epub_to_pdf，其捕获的说明保留了上游关于 Pro 套餐的表述。此重建版本不添加任何自行实现的付款或访问限制机制。

• merge_epub — 将两个或更多 EPUB 文件（必需参数 files）合并为一本带目录和章节分隔符的电子书；可选参数包括 names、title、author 和 dividers。
• split_epub — 拆分一个 EPUB（必需参数 file）。指定章节范围（chapterStart / chapterEnd）时，结果是一本仅包含这些章节的 EPUB；不指定时，结果是一个 ZIP 文件，其中每章各包含一个 EPUB。
• compress_epub — 压缩一个 EPUB（必需参数 file），压缩 level 为 1 到 9，并可选择移除未使用的资源。
• read_epub_metadata — 读取 EPUB 的元数据（必需参数 file）：标题、作者、语言、出版商、描述、丛书、封面状态等，并以 JSON 格式返回。
• edit_epub_metadata — 编辑 EPUB 的元数据字段（必需参数 file）：标题、作者、语言、出版商、描述、丛书、主题、ISBN、日期，甚至可以替换封面图；返回修改后的 EPUB。
• epub_to_pdf — 将 EPUB（必需参数 file）转换为 PDF，可设置页面大小、页边距、字体和页码选项。
• pdf_to_epub — 将 PDF（必需参数 file）转换为 EPUB，支持自动检测章节、章节分组模式以及可选的图像提取。
• markdown_to_epub — 根据 Markdown 文件（必需参数 files）构建 EPUB3 电子书，数组中的每个文件对应一章；支持 YAML frontmatter 和 Obsidian wikilinks。
• docx_to_epub — 将 Word 文档（必需参数 file）转换为 EPUB3 电子书，按标题或分页符拆分章节，并保留格式、列表、表格、图像和脚注。
• epub_to_markdown — 将 EPUB（必需参数 file）转换为 Markdown：生成一个 ZIP，其中包含每章对应的一个文件、索引以及引用的图像。
• validate_epub — 检查 EPUB（必需参数 file）是否存在错误、兼容性问题并符合规范；以 JSON 格式返回检查结果，可选择深度扫描和自动修复。
• generate_cover — 根据创意 description 和 genre 生成 AI 书籍封面图；可选参数包括 title、author 和 seed。捕获的架构中没有必需参数，但上游要求提供描述或标题。

配置

• EPUBLYS_MCP_URL（可选）— 覆盖上游端点。默认值为 https://epublys.com/mcp。（此覆盖入口是本次重建自行标注的还原内容。）
• EPUBLYS_API_KEY（可选）— 设置后，每个上游请求都会携带 Authorization: Bearer <key>。未设置时， 不会发送身份验证标头，与本次重建所依据的无密钥捕获记录一致。（标头 行为是自行标注的还原内容；注册表记录声明远程服务的 Authorization 标头为可选，但捕获记录是在未携带该标头的情况下取得的。）账户范围的行为由上游使用 调用者自己的凭据提供。

转发机制

首次调用工具时，客户端会在上游打开一个 可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26， clientInfo name bookbind），然后发送 notifications/initialized 通知，接着发送携带调用者 原样参数的 tools/call 请求。上游通过 initialize 响应返回 Mcp-Session-Id 标头时，该值会随之后的每个请求发送， 并且会话会在进程运行期间重复使用。响应可能以纯 JSON 或服务器发送事件的形式到达；两种形式都会被读取，并以 ID 匹配的消息为准。

成功的上游结果会原样传递，包括上游设置的任何 isError 标志以及添加的任何额外字段。失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或无法完成的请求——会以 isError 结果返回，其文本以 bookbind error: 开头（此呈现方式是本次重建自行标注的还原内容）。

命令行

每个工具也都是一个子命令，接受一个 JSON 参数字符串（不需要参数的工具可省略）：

npx @reneturcios/bookbind read_epub_metadata '{"file":"<base64-epub>"}'
npx @reneturcios/bookbind generate_cover '{"description":"a lighthouse at dusk","genre":"literary"}'
npx @reneturcios/bookbind validate_epub '{"file":"<base64-epub>","deepScan":true}'
npx @reneturcios/bookbind --version

退出代码：成功时为 0，结果为 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/bookbind mcp

MCP 客户端配置：

{
  "mcpServers": {
    "bookbind": {
      "command": "npx",
      "args": ["-y", "@reneturcios/bookbind", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/bookbind
docker run --rm ghcr.io/cloudcorprecords/bookbind --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数会照常传递给命令行。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全通过桩接的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。