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

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

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 mdbook CLI, MCP server integration, multi-book support with BOOK argument and --book/-b global option, setup command for Claude Code MCP auto-configuration, multi-format support (mdBook, GitBook, Leanpub, Bookdown), and YAML frontmatter parsing