audiobook_mcp

Overview Schema Source Related Servers Discussions Admin

Start (or resume) an audiobook -> M4B conversion job

audiobook_start_conversion

Idempotent

Start a resumable audiobook-to-M4B conversion by parsing the EPUB and probing audio duration, then continue with chapter alignment tools.

Instructions

Create a resumable conversion job for one MP3/M4A audiobook + its EPUB, and run the fast first stage (EPUB parsing + audio duration probe). This does NOT do the slow chapter-alignment/encoding work -- call audiobook_continue_conversion or audiobook_run_until_done next, and loop until the response's "done" field is true.

Calling this again with the exact same mp3_path/epub_path/out_dir resumes the existing job (returning its current status) instead of creating a duplicate, unless force_restart=True.

Args: params (StartConversionInput): see field descriptions. Notably: - mp3_path/epub_path (str): source files, must both exist. - out_dir (str): where the finished .m4b will be written. - cover_image_path (Optional[str]): use this image instead of the EPUB's own cover. Typical flow: audiobook_lookup_book_metadata -> audiobook_fetch_cover_image -> pass the downloaded path here. - verify_first_chapter (bool): on by default. Confirms chapter 1's actual start via whisper.cpp transcription before any other chapter is aligned, since every later chapter is chained forward from it -- an unconfirmed guess there (typically a missed intro) otherwise throws off the whole book. Falls back to the old silence-only heuristic and logs a warning if whisper.cpp isn't configured; never fails the job. - detect_intro/detect_outro (bool): off by default; only turn on if the user has confirmed the book has an audible intro/outro segment (see tool description in code for why). detect_intro only takes effect as verify_first_chapter's fallback -- see its own field description.

Returns: str: JSON with schema: { "job_id": str, # pass this to every other job tool "stage": str, # "align" once extract succeeds "book": {"title", "author", "series", "series_index", "chapter_count", "cover_found"}, "next_step": str # what to call next } or {"error": str, "error_type": str} on failure.

Error Handling: - "ffmpeg_missing" if ffmpeg/ffprobe aren't on PATH. - Otherwise a PipelineError/EpubExtractError with a specific reason (file not found, wrong extension, unparseable EPUB, ...).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 18, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark idempotentHint=true and readOnlyHint=false, but the description adds substantial behavioral detail beyond that: it explains that re-calling with the same paths resumes instead of duplicating, that force_restart discards progress, that verify_first_chapter falls back to silence heuristics without failing, and that error responses include specific error types. This gives the agent an accurate model of side effects and failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but the tool is complex and the length is mostly justified. It is well-structured with clear Args, Returns, and Error Handling sections, and the core purpose and next-step guidance are front-loaded. Minor deductions for the slightly awkward 'see tool description in code' reference and some redundancy with the already-detailed schema field descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a multi-stage conversion pipeline, this description is complete: it specifies the exact output JSON shape, the required next actions, error types, resumption semantics, and the behavior of optional settings. An agent has enough context to invoke this tool correctly and decide what to do next.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the top-level schema coverage is 0%, the description compensates by highlighting the most decision-critical parameters: mp3_path/epub_path must exist, cover_image_path should come from the cover-fetch flow, verify_first_chapter is on by default and explains why, and detect_intro/detect_outro are off by default due to false-positive risk. It does not walk through every parameter, but it directs readers to field descriptions and adds meaningful behavioral context for the important ones.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb and resource: it creates/resumes a resumable conversion job for one MP3/M4A + EPUB, then runs only the fast first stage. It explicitly distinguishes itself from the slower alignment/encoding work by naming audiobook_continue_conversion and audiobook_run_until_done, so an agent can tell it apart from sibling tools immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit next-step routing: call audiobook_continue_conversion or audiobook_run_until_done and loop until 'done' is true. It also explains resumption behavior and the cover-image workflow (audiobook_lookup_book_metadata -> audiobook_fetch_cover_image -> cover_image_path), giving concrete guidance on when and how to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server