sutton-barto-mcp

An MCP server that exposes the full text of Reinforcement Learning: An Introduction (2nd edition) by Richard S. Sutton and Andrew G. Barto, so an LLM can search it, pull a specific page, or read a whole chapter instead of guessing from memory.

Built with FastMCP. Runs locally over stdio, or as a remote HTTP server with OAuth for clients like claude.ai.

Licensing: the code is MIT. The book text under pages_corrected/ and ocr_raw/ is not — it belongs to the authors and MIT Press. Read NOTICE.md before you reuse anything from those directories.

Tools

Tool	What it does
search(query, max_results=5)	Case-insensitive term search across all 548 pages. Returns the best-scoring pages with a surrounding excerpt and the chapter each one falls in.
get_page(page_number)	One page verbatim, 1–548. Page numbers are PDF page numbers, not the printed body numbering.
get_chapter(chapter_number)	A whole chapter, 0–24. Index 0 is the second-edition preface; 3 is Chapter 1. Call list_chapters for the mapping.
list_chapters()	All 25 sections with their page ranges.

Math is returned as LaTeX, as it appears in the source text.

Install

Python 3.10 or newer.

git clone https://github.com/BNJ02/sutton-barto-mcp.git
cd sutton-barto-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Run

Local (stdio)

This is the default and needs no configuration:

python server.py

To register it with Claude Code:

claude mcp add rlbook -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

Or, for any client that reads a JSON config:

{
  "mcpServers": {
    "rlbook": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Remote (HTTP + OAuth)

For clients that connect over the network. Copy .env.example to .env and fill it in first — the server exits if MCP_CLIENT_SECRET is missing:

cp .env.example .env
# generate a secret and a PIN, then edit .env
openssl rand -hex 32

set -a && source .env && set +a
python server.py --http --port=8003

MCP_BASE_URL must be the public HTTPS URL the client will reach, since it is used to build the OAuth redirect URIs. Put the server behind a reverse proxy or a tunnel that terminates TLS.

Authorization flow: the client is redirected to a page served by this app, you enter MCP_ACCESS_PIN, and the authorization code is issued. Registered clients and issued tokens are persisted in oauth_state.db, which is gitignored — it holds live credentials, so keep it out of version control and off backups you share.

Repository layout

server.py             MCP server: tools, chapter map, page loader
persistent_oauth.py   SQLite-backed OAuth provider + PIN approval routes
pages_corrected/      Extracted book text, 10 pages per file (see NOTICE.md)
ocr_raw/              Raw OCR output, kept for diffing corrections
  nougat/             Nougat output — good at math, occasionally hallucinates
  pymupdf/            PyMuPDF text layer — literal, poor at math

pages_corrected/ is what the server actually reads. Each file holds --- Page N --- delimiters that _load_all_pages() splits on, so any new page file has to keep that marker format.

ocr_raw/ is not used at runtime. It's there because the two extractors fail in different ways — Nougat reconstructs equations well but drifts on dense pages, PyMuPDF is faithful but flattens math — and having both makes it possible to check a suspicious passage in pages_corrected/ against them.

The source PDF

Not included: it's ~70 MB and copyrighted. Get it from the authors: http://incompleteideas.net/book/the-book.html

You only need it if you want to re-extract or fix pages. The server runs from pages_corrected/ alone.

Known limitations

• Page numbers are PDF-relative. Page 23 of the PDF is the first page of Chapter 1. Printed page numbers in the book differ.
• Search is literal. It counts term occurrences; no stemming, no synonyms, no semantic ranking. "eligibility traces" scores pages containing either word, not the phrase.
• All pages are held in memory. Roughly 1.6 MB of text is loaded at import. Fine, but it means startup does real work.
• OCR is imperfect. Complex equations, figures, and tables are the weak spots. Check anything surprising against the PDF.

Credits

The book is by Richard S. Sutton and Andrew G. Barto, published by The MIT Press. This repository only wraps its text in an MCP interface. See NOTICE.md.