bookbind

bookbind

bookbind is a small local bridge to Epublys, a hosted service that works on EPUB and PDF ebooks: merging and splitting books, compressing them, converting between formats, editing metadata, checking a file for spec problems, and generating cover art. This package does none of that work itself. It stands in front of the service's remote MCP endpoint, presents the upstream tool list locally exactly as captured, and passes each call through, returning whatever the upstream returns.

That split matters in practice. The conversions, metadata edits and validation verdicts all come from Epublys' own machinery, so a result you get through bookbind is the service's result, not a local approximation. The bridge adds no processing of its own and rewrites nothing on the way back. Most tools take base64-encoded file content (file, or files for the multi-file tools) and return base64-encoded output; the upstream's own free-tier and Pro limits, as described in each tool's description, apply upstream.

Tools

This build serves a labelled subset of the captured surface: 12 of the 13 tools seen in the live capture. The omitted tool is upgrade_to_pro, which returns a checkout link so the user can upgrade their account to a paid tier; a payment funnel is out of scope for this program, so the tool is deliberately absent, and a test asserts that absence. The remaining tools are document operations, served verbatim — including epub_to_pdf, whose captured description carries the upstream's own Pro-tier language. This rebuild adds no payment or gating machinery of its own.

• merge_epub — merge two or more EPUB files (files, required) into one ebook with a table of contents and chapter dividers; optional names, title, author and dividers.
• split_epub — split one EPUB (file, required). With a chapter range (chapterStart / chapterEnd) the result is a single EPUB of exactly those chapters; without one it is a ZIP holding one EPUB per chapter.
• compress_epub — shrink an EPUB (file, required), with a compression level from 1 to 9 and an option to strip unused assets.
• read_epub_metadata — read an EPUB's metadata (file, required): title, author, language, publisher, description, series, cover status and more, returned as JSON.
• edit_epub_metadata — edit metadata fields in an EPUB (file, required): title, author(s), language, publisher, description, series, subjects, ISBN, date, even a new cover image; returns the modified EPUB.
• epub_to_pdf — convert an EPUB (file, required) to PDF, with page size, margins, font and page number options.
• pdf_to_epub — convert a PDF (file, required) to an EPUB, with automatic chapter detection, chapter grouping modes and optional image extraction.
• markdown_to_epub — build an EPUB3 ebook from Markdown files (files, required), one file per chapter in array order; understands YAML frontmatter and Obsidian wikilinks.
• docx_to_epub — convert a Word document (file, required) to an EPUB3 ebook, splitting chapters on headings or page breaks and keeping formatting, lists, tables, images and footnotes.
• epub_to_markdown — convert an EPUB (file, required) to Markdown: a ZIP with one file per chapter, an index, and the referenced images.
• validate_epub — validate an EPUB (file, required) for errors, compatibility issues and spec compliance; returns JSON check results, with an optional deep scan and auto-fix.
• generate_cover — generate an AI book cover image from a creative description and a genre, with optional title, author and seed. No argument is required by the captured schema, though the upstream expects a description or a title.

Configuration

• EPUBLYS_MCP_URL (optional) — override the upstream endpoint. Defaults to https://epublys.com/mcp. (The override hook is this rebuild's own labelled reconstruction.)
• EPUBLYS_API_KEY (optional) — when set, every upstream request carries Authorization: Bearer <key>. When it is not set, no auth header is sent, matching the keyless capture this rebuild is based on. (The header behaviour is a labelled reconstruction; the registry record declares an optional Authorization header for the remote, but the capture was taken without one.) Account-scoped behaviour is served upstream under the caller's own credential.

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name bookbind), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request, and the session is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read, and the message with the matching id wins.

Successful upstream results pass through verbatim, including any isError flag the upstream sets and any extra fields it adds. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with bookbind error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string (omit it for tools that take none):

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

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/bookbind mcp

MCP client config:

{
  "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

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.