Problem
Most agent demos are impressive until you inspect the seams: vague tool contracts, implicit mutation, environment-specific paths, and safety claims that live only in prose.
Executable book · Working repository · Production thesis
An executable book for building spec-driven MCP agents.
MCP with DSPy Theory and Application is both a book and the system that proves the book's claims. Ideas originate in a PKM vault, specs define tool contracts, policy fences govern side effects, tests enforce guarantees, and the result is published as a professional multi-format edition.
- Contract-first MCP tooling with JSON-schema validation
- Policy-enforced PKM writes with vault-relative path semantics
- Published in PDF, HTML, EPUB, and manuscript form from the same repo pipeline
Edition
First working edition
Built directly from the repository pipeline
Why this project is different
The repository does not accompany the book. It enforces it.
Design
This project separates reasoning, contracts, execution, and policy. MCP specs are authoritative, PKM writes are fenced, and the vault remains the canonical authoring surface.
Outcome
The result is a publication-grade book plus a working system where specs, code, walkthroughs, and tests reinforce the same architecture instead of drifting apart.
Recursive architecture
The same loop teaches the system and builds the book.
Canonical vault
Zettels and MoCs in the Obsidian vault remain the source of truth for ideas, structure, and chapter intent.
Executable repository
Specs, MCP servers, DSPy orchestration, constitutional policy checks, and tests turn the ideas into deterministic software.
Derived documentation
Walkthroughs and reference docs are regenerated from canonical notes rather than written freehand, preserving provenance and scope.
Published artifact
The repo assembles and publishes the book in reader-facing formats, then feeds the next round of refinement back into the system.
A book that builds itself
This primer is its own proof of concept.
Self-generating
The MCP tooling described in this book generated the book itself. The same agents, specs, and pipelines that teach MCP server development were used to write, structure, and publish this very primer. It is not a book about a system—it is the output of that system.
Reusable pattern
This repository can be forked and adapted to create new MCP servers with their own Human-Focused Books—an Obsidian vault + markdown approach that explains both concepts and implementation. Each new project inherits the same loop: vault as source of truth, specs as contracts, publication as artifact.
Human-Focused Books
The pattern produces documentation that humans actually want to read: zettels for atomic ideas, MoCs for navigation, walkthroughs for practical understanding, and published editions for professional presentation. The book teaches by showing the working system it describes.
Proof, not promises
What visitors can verify immediately
Authoritative specs
Tool declarations live in modules/pkm_tools/tools.yml, and startup fails if
an advertised tool lacks a real implementation.
Safe side effects
PKM mutations require explicit consent, stay inside allowed roots, reject path escape, and return vault-relative POSIX paths.
Test-backed guarantees
The repo's behavior is enforced by the test suite, including validation, overwrite semantics, write fences, and mutation edge cases.
Publication pipeline
The same repository builds the book in PDF, HTML, EPUB, and manuscript form while cleaning generated-doc residue out of the reader-facing edition.
Read it now
Publication artifacts and engineering entry points
Professional PDF
The first working edition, built from the repository's publication pipeline and styled for a real book reading experience.
HTML edition
Browse the complete book in the browser without leaving the site showcase.
Open HTML editionManuscript markdown
Inspect the assembled publication manuscript that feeds the final build formats.
Open manuscriptImplementation proof
Read the code, decisions, tests, and build pipeline behind the publication.
Visit GitHubPositioning
A world-class agent systems case study should feel inevitable at every layer.
This project aims for that standard: conceptual rigor in the vault, deterministic behavior in the repo, enforceable safety in the policy layer, and publication-quality output in the book.