All About MCP: A Human + AI Coursebook

December 4, 2025 · View on GitHub

alt text

All About MCP is a personal learning resource that demonstrates a true AI approach to creating long-form educational content—where the human defines what to learn and AI agents handle the research and writing.

The key distinction: you define the curriculum, then the multi-agent pipeline researches, writes, formats, and produces the final outputs (PDF, audiobook).

What Makes This "True AI"?

This isn't AI writing whatever it wants—it's AI executing your learning agenda:

  1. Human-Authored Curriculum: You write the outline of what you want to learn
  2. AI Research & Writing: Agents research current information and write chapters following your structure
  3. Consistent Output: A style guide ensures the stitched document reads cohesively
  4. Multiple Formats: Automated PDF generation and audiobook synthesis

The human remains in control of what is learned; AI handles how it's produced.

Philosophy: On AI-Generated Educational Content

I create this material under the expectation that it may not be entirely accurate. When developing it for my own use, I haven't felt the need to encumber the natural flow of text with disclaimers. But so far I have been generally pleasantly surprised by the accuracy of the information contained.

As retrieval and grounding systems become more mature and reliable, the assumption that everything generated by AI is inherently untrustworthy will (I predict and already see) become untenable.

At a certain point, we humans may be forced to accept, with humility, that AI is "good enough" at synthesising information accurately—and maybe even better at the task than we are.

None of this is to suggest that human authorship is any less valuable than it was at any prior point in time. Merely to suggest that LLMs can be leveraged as highly effective information-synthesising tools for humans wishing to explore a complex subject in depth. And that doing so is a net positive for streamlining self-directed learning.

The Core Mechanism: Chunked Generation and Stitching

The recipe I have used for generating long-form content is stitching-based: LLMs degrade in accuracy as context accumulates. So asking a large language model to write an entire book, or even a swathe of it, in one shot will tend to yield poor results. Even if the model is capable of completing enough tokens to generate large chunks of text in one output, results may be dramatically inferior to when that same model is asked to generate text in shorter bursts.

For that reason, the methodology I have found success with—and share in this template—is approximately this:

Step 1: Curriculum Development (Human)

The human develops a "curriculum" functioning as an outline of the topics to be covered in the long-form coursebook. This is effectively a table of contents. This is a fun process! The human can map out a personalised curriculum defining precisely what they wish to learn within this (large) topic.

Step 2: Style Guide Generation (Agent)

Critical for consistency. Before any content is written, a style guide agent analyzes the curriculum and generates a comprehensive style guide that defines:

  • Voice and tone: Authoritative yet accessible, conversational but professional
  • Person and perspective: Consistent use of first/second/third person
  • Terminology: Glossary of key terms, acronym handling, capitalization rules
  • Document structure: Heading hierarchy, section patterns, transition approaches
  • Formatting standards: Code blocks, lists, emphasis, callouts
  • Content patterns: How to introduce concepts, provide examples, conclude sections

This style guide is then provided to every chapter-writer agent, ensuring the final stitched document reads as if written by a single author.

Step 3: Prompt Chunking (Agent)

A curriculum-prompt-generator agent transforms the curriculum into structured chapter prompts. Each prompt includes:

  • Chapter metadata (number, title, position in curriculum)
  • Context and continuity (what came before, reader's knowledge state)
  • Content requirements (topic, learning objectives, key concepts)
  • Structural guidelines (opening, core sections, closing)
  • Style directives (reference to the style guide)

Step 4: Chapter Generation (Agent - Parallel)

Chapter-writer agents generate content from the structured prompts. Each writer receives:

  1. Their specific chapter prompt
  2. The style guide (for consistency)
  3. Optionally: research context (for up-to-date information)

Parallel execution is supported—multiple chapters can be written simultaneously since each agent has the style guide ensuring consistency.

Step 5: Stitching (Agent)

The output-stitcher agent concatenates chapters into a single document:

  • Determines correct ordering from file naming
  • Preserves formatting and structure
  • Adds section breaks as needed
  • Reports any inconsistencies found

Step 6: PDF Conversion (Agent)

The markdown-pdf-converter agent produces the final PDF:

  • Adds title page, table of contents, page numbers
  • Ensures chapters start on new pages
  • Applies consistent typography and styling

Optional: Audiobook Generation

See the Audiobook Conversion section below for generating audio output using Chatterbox TTS.

Optional Enhancements

  • The authoring agent could be instructed to use Mermaid in order to create flowcharts for explanations that benefit from diagrammatic representation.
  • Authoring agents can also leverage image generation tooling in order to create engaging images to break up the monotony of pure text.
  • Research integration: For rapidly evolving topics, a research agent (using Tavily, Perplexity, or Context7) can gather current information to inject into chapter prompts.

Text Formatting and Output Creation

My workloads have targeted Markdown as the initial concatenation format for its versatility.

From Markdown, I tend to target PDF.

For best results, an agent is best used for this process. The best mechanism for converting a very lengthy Markdown document into a PDF is difficult to define programmatically (in advance) owing to the inherent variability of the text that the large language model will generate. An agent is highly useful for its ability to think: "Which of the 10 ways I can create a PDF from this will yield the best result?"

Formatting Requirements

A little bit of instructing is usually necessary in my experience in order to define requirements like that every new chapter begin on a new page. These requirements might seem obvious, but it's frequently necessary to state them rather than hope or expect that they will be inferred.

To make the end document presentable and readable, I usually also ask for:

  • A title page
  • A table of contents
  • Page numbers in the footer
  • Other basic formatting elements

Finally, a PDF is stitched together.

Audiobook Conversion

I enjoy consuming long-form content through audio.

TTS Service: Resemble AI Chatterbox

This project uses Chatterbox by Resemble AI for text-to-speech synthesis:

  • Model: resemble-ai/chatterbox via Replicate API
  • Quality: Production-grade, benchmarked against ElevenLabs
  • License: MIT (open source)
  • Key Features:
    • Emotion exaggeration control (unique to Chatterbox)
    • Zero-shot voice cloning from short audio samples
    • Built-in watermarking for responsible AI
    • 0.5B Llama backbone, trained on 500K hours of data

Audio Pipeline

  1. Text Conversion (tts-formatter agent): Convert Markdown into TTS-friendly text optimized for Chatterbox:

    • Sentence length: 15-25 words optimal
    • Strip markup, expand abbreviations
    • Convert technical content to spoken descriptions

  2. Audio Generation (audiobook-generator agent): Orchestrate Chatterbox via Replicate:

    • Chunk text to API limits
    • Generate audio segments with consistent voice
    • Concatenate into final audiobook
    • Output to outputs/audio/

Configuration

API key stored in .env as REPLICATE_API_TOKEN. See api-ref/chatterbox.txt for full API documentation.

Use Cases

I found this to be a brilliant way to get a quick "bring me up to speed" style guide on a subject.

Given that the concatenation is scripted and therefore doesn't impose a direct impediment to context, I don't believe there is an inherent limit as to the length of the ultimate document generated. I've created documents that are hundreds of pages long.

Coherence and Task Retention

One aspect of this task that is challenging is how to maintain coherence throughout the text.

The stitched document should not read like a stitched composite of short outputs. Ensuring fluency and consistency between the chapters is challenging.

Solutions

Style Guide (Primary Solution): The most effective mechanism for consistency. The style-guide-generator agent creates a comprehensive style guide before any content generation begins. This guide covers:

  • Voice, tone, and perspective
  • Terminology and vocabulary standards
  • Structural patterns and formatting rules
  • Content patterns (introductions, examples, conclusions)

Every chapter-writer agent receives this style guide, ensuring unified output regardless of whether chapters are generated sequentially or in parallel.

Previous Chapter Context (Secondary): One potential solution at the prompting level is to instruct the chapter generation agent to read (only) the previous chapter. By asking it to parse only one previous output, this limits the context, preventing the generation context and the previous context from overwhelming context windows.

Structured Prompts: The curriculum-prompt-generator ensures each chapter prompt includes explicit style directives and continuity information, referencing what came before and what comes after.

Generation Process

All starting from the user-defined curriculum!

Slash command initiation:

alt text

Pipeline stage 1: style guide definition

alt text

Pipelie stage 2: curricum -> prompt splitting

alt text

alt text

While this pattern was initially developed using Claude Code's agent system, it's designed for implementation with dedicated multi-agent frameworks:

For projects requiring current information (like MCP, which evolves rapidly):

  • GPT-Researcher: Handles web research with automatic citations
  • LangGraph: Orchestrates the pipeline with state management and parallel execution
Human Curriculum → Style Guide → Research Phase → Parallel Chapter Writing → Stitch → PDF → Audio

Alternative Frameworks

  • CrewAI: Role-based agents, excellent for content pipelines with defined stages
  • STORM (Stanford): Wikipedia-style article generation with multi-perspective research
  • AutoGen: Enterprise-focused with robust error handling

Key Integration Points

  1. Research Agent: Use Tavily, Perplexity, or Context7 to gather current information
  2. Style Guide Distribution: Ensure all chapter writers receive the same style guide
  3. Parallel Execution: LangGraph/CrewAI can run chapter writers concurrently
  4. TTS Integration: Chatterbox via Replicate for audiobook generation

See CLAUDE.md for specific implementation details.

Repository Structure

This repository serves a dual purpose:

  1. Demonstrating the pattern: Showing how this chunked generation and stitching process works in practice
  2. Generating deliverables: Creating the actual MCP coursebook for personal reading and listening

The CLAUDE.md file contains the specific generation task context for the MCP coursebook.

Directory Layout

All-About-MCP/
├── CLAUDE.md                    # Project instructions for AI agents
├── README.md                    # This file
├── pyproject.toml               # Python dependencies
├── .env                         # API keys (GOOGLE_API_KEY, REPLICATE_API_TOKEN)
│
├── inputs/
│   ├── curriculum-transcript-formatted.md   # ⭐ HUMAN-AUTHORED CURRICULUM
│   ├── curriculum-transcript-raw.md         # Original transcript (reference)
│   └── voices/
│       └── corn-1min.mp3                    # Voice reference for TTS cloning
│
├── outputs/
│   ├── style-guide/             # Generated style guide for consistency
│   ├── chapter-prompts/         # Structured prompts (JSON) for each chapter
│   ├── chapters/                # Individual chapter markdown files
│   ├── images/                  # AI-generated images for chapters
│   ├── full-text/               # Stitched document (MD + HTML)
│   ├── pdf/                     # Final PDF with TOC and formatting
│   └── audio/                   # Audiobook (chapter WAVs + final MP3)
│
├── src/                         # Python implementation
│   ├── main.py                  # CLI entry point (--all, --book, --pdf, --audio)
│   ├── config.py                # Configuration and paths
│   ├── gemini_client.py         # Gemini with Google Search grounding
│   ├── pipeline.py              # Pipeline orchestration
│   ├── chapter_writer.py        # Chapter generation logic
│   ├── pdf_converter.py         # Markdown to PDF (WeasyPrint)
│   ├── pdf_generator.py         # Alternative PDF generation
│   ├── audiobook.py             # Chatterbox TTS (integrated)
│   ├── audiobook_generator.py   # Standalone audiobook generator
│   ├── agents.py                # CrewAI agent definitions
│   ├── tasks.py                 # CrewAI task definitions
│   └── schemas.py               # Pydantic schemas
│
├── agents/                      # Agent prompt documentation
│   ├── style-guide-generator.md
│   ├── curriculum-prompt-generator.md
│   ├── chapter-writer.md
│   ├── output-stitcher.md
│   ├── markdown-pdf-converter.md
│   ├── tts-formatter.md
│   └── audiobook-generator.md
│
└── api-ref/
    └── chatterbox.txt           # Chatterbox TTS API reference

Quick Start

Prerequisites

  • Python 3.11+
  • uv (recommended) or pip
  • Google Gemini API key
  • Replicate API token (for audiobook generation)

Installation

# Clone the repository
git clone https://github.com/danielrosehill/All-About-MCP.git
cd All-About-MCP

# Create virtual environment and install dependencies
uv venv .venv
source .venv/bin/activate
uv pip install -e .

Configuration

  1. Edit .env with your API keys:
GOOGLE_API_KEY="your-gemini-api-key"
REPLICATE_API_TOKEN="your-replicate-token"

  1. Write your curriculum in inputs/curriculum-transcript-formatted.md:

    • This is the human-authored outline defining what the AI will write about
    • Structure it as chapters/sections you want covered
    • Be specific about topics, depth, and any special focus areas

  2. Optionally add a voice reference for audiobook cloning in inputs/voices/

Usage

# Generate everything (book + PDF + audiobook)
python -m src.main --all

# Generate just the book (markdown)
python -m src.main --book

# Generate PDF from existing markdown
python -m src.main --pdf

# Generate audiobook from existing markdown
python -m src.main --audio

# Generate only the style guide
python -m src.main --style-guide

# Use custom voice for audiobook (voice cloning)
python -m src.main --audio --voice-reference "https://example.com/voice-sample.mp3"

# Or run the standalone audiobook generator with local voice file
python -m src.audiobook_generator

How It Works

  1. You Write the Curriculum: Define what you want to learn in inputs/curriculum-transcript-formatted.md
  2. Style Guide Generation: Agent analyzes your curriculum, creates style guide for consistency
  3. Curriculum → Prompts: Agent transforms your outline into structured chapter prompts (JSON)
  4. Chapter Writing: Gemini with Google Search grounding researches and writes each chapter
  5. Document Stitching: Chapters combined into cohesive document
  6. PDF Conversion: WeasyPrint generates styled PDF with TOC and page numbers
  7. Audiobook Generation: Chatterbox TTS via Replicate creates voice-cloned MP3