MD Book Tools
A markdown book reader and writer with DI/SOA architecture and MCP server support for Claude Code integration.
Features
- Multi-Format Support: mdBook, GitBook, Leanpub, Bookdown, and auto-detection
- YAML Frontmatter: Extract metadata (title, author, date, draft status)
- Interactive Reader: Terminal navigation with chapter jumping
- Book Writing: Initialize projects, add chapters, generate TOC
- MCP Server: Expose book operations as tools for AI assistants
Architecture
mdbook/
├── domain/ # Core entities (Book, Chapter, ChapterMetadata)
├── services/ # Business logic with interface protocols
│ ├── interfaces.py # IBookService, IReaderService, IWriterService, IStructureService
│ ├── book_service.py
│ ├── reader_service.py
│ ├── writer_service.py
│ └── structure_service.py
├── repositories/ # Data access layer
│ ├── interfaces.py # IFileRepository, IConfigRepository
│ ├── file_repository.py
│ └── config_repository.py
├── infrastructure/ # DI container and composition root
│ └── container.py # ServiceContainer with lazy singleton resolution
├── mcp/ # Model Context Protocol server
│ └── server.py # Exposes book operations as MCP tools
└── cli.py # Unified Click-based CLI
Installation
Using uv (recommended)
cd book-reader
uv pip install -e .
Using pip
cd book-reader
pip install -e .
This installs the single mdbook command with all subcommands.
Quick Start
# Read a book (pass book path as argument)
mdbook read /path/to/book
# Or use --book/-b global option
mdbook --book /path/to/book read
# Show book info
mdbook info /path/to/book
# Create a new book
mdbook init ./my-book -t "My Book Title" -a "Author Name"
# Add a chapter
mdbook new-chapter ./my-book -t "Introduction"
# Regenerate table of contents
mdbook toc ./my-book
# Start MCP server for a specific book
mdbook serve-mcp /path/to/book
# Auto-configure Claude Code MCP integration
mdbook setup /path/to/book
Command Reference
mdbook [OPTIONS] COMMAND [ARGS]
Commands:
read Read a markdown book interactively
info Show book information
init Initialize a new book project
new-chapter Add a new chapter to a book
toc Regenerate table of contents
serve-mcp Start MCP server for Claude Code
setup Auto-configure Claude Code MCP integration
Global Options:
-b, --book PATH Book directory (used by all commands)
--version Show version and exit
--help Show help message and exit
read
mdbook read [BOOK] [OPTIONS]
Arguments:
BOOK Book directory (or use global --book option)
Options:
-c, --chapter NUM Start at specific chapter
init
mdbook init PATH [OPTIONS]
Arguments:
PATH Directory to create book in
Options:
-t, --title TEXT Book title (required)
-a, --author TEXT Author name (required)
new-chapter
mdbook new-chapter [BOOK] [OPTIONS]
Arguments:
BOOK Book directory (or use global --book option)
Options:
-t, --title TEXT Chapter title (required)
-d, --draft Mark as draft
setup
mdbook setup [BOOK]
Arguments:
BOOK Book directory (or use global --book option)
Auto-configures Claude Code MCP integration by updating .mcp.json
in the project directory. Creates the file if it doesn't exist or
adds/updates the mdbook server configuration.
MCP Server Integration
The MCP server exposes book operations as tools for Claude Code and other AI assistants.
Available MCP Tools
| Tool | Description |
|---|---|
book_info |
Get book metadata and chapter list |
read_chapter |
Read chapter content by number |
list_chapters |
List all chapters with metadata |
create_book |
Create a new book project |
add_chapter |
Add a chapter to a book |
update_toc |
Regenerate SUMMARY.md |
Claude Code Configuration
Add to your .mcp.json:
{
"mcpServers": {
"mdbook": {
"command": "mdbook",
"args": ["serve-mcp"]
}
}
}
Or with uv:
{
"mcpServers": {
"mdbook": {
"command": "uv",
"args": ["run", "--directory", "/path/to/book-reader", "mdbook", "serve-mcp"]
}
}
}
Supported Book Formats
| Format | Detection File |
|---|---|
| mdBook/GitBook | SUMMARY.md |
| mdBook | book.toml |
| Leanpub | Book.txt |
| Bookdown | _bookdown.yml |
| Auto | Directory scan |
Requirements
- Python 3.10+
- click, rich, markdown, pyyaml, mcp
License
MIT License
Version History
- v1.0.0 - Initial public release with DI/SOA architecture, unified
mdbookCLI, MCP server integration, multi-book support with BOOK argument and--book/-bglobal option,setupcommand for Claude Code MCP auto-configuration, multi-format support (mdBook, GitBook, Leanpub, Bookdown), and YAML frontmatter parsing
Metadata
Release files for md-book 1.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| md_book-1.0.4.tar.gz | 780.9 kB | Without provenance | Details for md_book-1.0.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| md_book-1.0.4-py3-none-any.whl | Python 3 | none | any | Details for md_book-1.0.4-py3-none-any.whl |
Total release size: 821.0 kB
Release files / md_book-1.0.4.tar.gz
| Download URL | md_book-1.0.4.tar.gz |
|---|---|
| Size | 780.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e63dcd92a614f52875997778dc96270c4ca61c24cef21d12225c8a6a9ddafffe
|
|
BLAKE2b-256 checksum How to use checksums |
4f69f748e2dedf9bebff9b0b26e8985342bca2a2414dfeeef3811ffd374391d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / md_book-1.0.4-py3-none-any.whl
| Download URL | md_book-1.0.4-py3-none-any.whl |
|---|---|
| Size | 40.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e66caa52adea0d995b147bb5e98b573e3c7d1e8e420782722eff42284cc346ad
|
|
BLAKE2b-256 checksum How to use checksums |
b0b56a510341b772dee7755dda515c942a232f4131591c70a0e78eee950a1b08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for md-book 1.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.