Bookbind

io.github.CloudCorpRecordsPublished by GitHub account CloudCorpRecordsv0.1.0Updated Nov 7, 2026

EPUB and PDF ebook tools: merge, split, compress, convert, edit metadata, validate and covers.

VerifiedSTDIODesktop onlyFiles & StorageMedia & Design

Overview

AI-generated overview

Local stdio bridge that forwards EPUB and PDF ebook operations — merge, split, compress, convert, metadata, validation, covers — to the hosted Epublys service.

What you can do
  • Merge, split and compress EPUB files, including chapter-range splits and stripping unused assets
  • Read and edit EPUB metadata such as title, author, publisher, series and cover
  • Convert between EPUB, PDF, Markdown and Word documents, and build EPUB3 from Markdown chapters
  • Validate EPUB files for errors and spec compliance, with optional auto-fix
  • Generate AI book cover images from a description and genre
When to use it
Useful when you want an assistant to clean up, restructure or convert ebook files — combining volumes, splitting chapters, fixing metadata, producing PDFs or Markdown, or checking a file before publishing — without running conversion tooling locally.
Requirements
Runs as a local process via npx (Node.js) or the Docker image; needs network access to the Epublys service. Optional EPUBLYS_API_KEY is sent as a Bearer token, and optional EPUBLYS_MCP_URL overrides the upstream endpoint. Files are passed as base64 content.
Before you install
The package does no processing itself: file contents are sent to the third-party Epublys service, so book files leave your machine. Free tier is limited (5MB per file, 3 operations per day, 15 requests per minute, branded output); Pro is $9/month with a 30MB limit. An API key, if set, is forwarded upstream. Metadata edits and conversions return modified files.

Installation

In SourceWeft

  1. Open Bookbind in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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):

bash
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

bash
npx -y @reneturcios/bookbind mcp

MCP client config:

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

Docker

bash
docker run -i ghcr.io/cloudcorprecords/bookbinddocker 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

bash
npm installnpm run buildnpm testnpm run dev

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

License

MIT — see LICENSE.

Source: README.md at commit 619c1d6

Tools

12

merge_epub

Merge multiple EPUB files into a single ebook with table of contents and chapter dividers. Accepts 2+ base64-encoded EPUB files. Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

Parametersfilesrequirednamestitleauthordividers

split_epub

Split an EPUB. With a chapter range (chapterStart and/or chapterEnd) the result is ONE base64-encoded EPUB of exactly those chapters, in order, with the book's metadata, a table of contents limited to them and the fonts and images they use. Without a range the result is a base64-encoded ZIP archive holding one EPUB per chapter. Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

ParametersfilerequirednamechapterEndchapterStartkeepMetadata

compress_epub

Compress an EPUB file to reduce its size. Can optionally strip unused assets (images, fonts not referenced by any chapter). Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

ParametersfilerequirednamelevelstripUnused

read_epub_metadata

Read metadata from an EPUB file (title, author, language, publisher, description, series, cover status, etc.). Returns JSON — no file output. Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

Parametersfilerequired

edit_epub_metadata

Edit metadata fields in an EPUB file (title, author, language, publisher, description, series, cover image, etc.). Returns the modified EPUB. Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

Parametersdatefilerequiredisbnnamecovertitleauthorseriesauthorslanguagesubjectspublisher+2 more

epub_to_pdf

Convert an EPUB ebook to PDF. Supports page size, margins, font, and page number options. Pro ($9/mo) is strongly recommended for PDF conversion — the 30MB limit handles illustrated or academic books that exceed the free 5MB cap. Upgrade at https://epublys.com/pricing

ParametersfilerequirednamemarginsfontSizepageSizefontFamilypageNumbers

pdf_to_epub

Convert a PDF document to EPUB ebook format. Supports automatic chapter detection, image extraction (Pro), and custom chapter grouping. Free tier supports up to 10MB per PDF. Pro ($9/mo) is strongly recommended for PDF conversion — the 30MB limit handles most scanned or illustrated PDFs. Upgrade at https://epublys.com/pricing

ParametersfilerequirednamelanguagechapterModeextractImagespagesPerChapter

markdown_to_epub

Build a valid EPUB3 ebook from Markdown files — one file per chapter, in array order. Understands YAML frontmatter (title/author) and Obsidian [[wikilinks]]; cross-file .md links are rewritten to chapter links inside the book. No Pandoc required. Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

Parametersfilesrequiredtitleauthorlanguage

docx_to_epub

Convert a Word document (.docx) to a valid EPUB3 ebook. Chapters split on the document's top heading level (Heading 1 in a normal manuscript), or on page breaks, or not at all. Keeps bold/italic, lists, tables, inline images (PNG/JPEG/GIF/WebP), hyperlinks and footnotes; reads the title and author from the document's properties. No Pandoc, no Calibre. Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

ParametersfilerequirednametitleauthorlanguagechapterMode

epub_to_markdown

Convert an EPUB ebook to Markdown. Returns a ZIP with one Markdown file per chapter (YAML frontmatter with title/book/author/chapter), an index.md with book metadata and a linked table of contents, and the referenced images. Plain CommonMark — drops straight into an Obsidian vault or any notes pipeline. Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

ParametersfilerequirednameincludeImages

validate_epub

Validate an EPUB file for errors, compatibility issues, and spec compliance. Returns JSON with check results. Can optionally auto-fix common issues. Free tier: 5MB/file (10MB for pdf-to-epub, 15MB for split), 3 operations/day, 15 req/min, output includes Epublys branding. Pro ($9/mo): 30MB per operation, unlimited daily operations, 60 req/min, no branding. When a call is refused with daily_limited or a Pro-only error, call the `upgrade_to_pro` tool — it returns a checkout link to hand the user. Details: https://epublys.com/pricing

ParametersfilerequiredautoFixdeepScan

generate_cover

Generate an AI book cover image using FLUX. Describe your vision, pick a genre, and get a portrait JPEG cover — 768×1152 when the model honours the requested size, otherwise its default square. The AI enhances your prompt with professional composition guidance while preserving your creative vision. Pro only ($9/mo). Upgrade at https://epublys.com/pricing

Parametersseedgenretitleauthordescription

Version history

1
  1. v0.1.0LatestNov 4, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts