mcp-quickstart — a books-catalog MCP server

A clean, well-documented Model Context Protocol (MCP) server, built with FastMCP, that exposes a local SQLite catalog of public-domain books as a set of well-designed tools. It is meant as a reference for how to design MCP tools an LLM can use reliably: clear names, schema-generating type hints, docstrings-as-contracts, validated inputs, and actionable error messages.

The data is a small set of public-domain classics (Austen, Verne, Doyle, Dostoevsky, ...) authored as seed data for this repo — nothing proprietary, and deliberately a generic domain.

---

What it exposes

Five tools over a 30-book catalog:

Tool	Signature	Purpose
search_books	(query: str, limit: int = 10)	Substring search over title + author.
get_book	(book_id: int)	Fetch one book by id; clear error if missing.
find_books_by_genre	(genre, year_from?, year_to?, limit=20)	Filter by genre + optional year range.
top_rated_books	(limit=5, genre?)	Highest-rated, optionally within a genre.
catalog_stats	()	Totals, per-genre counts, year range, averages.

---

Quickstart

git clone <this-repo> && cd mcp-quickstart
python -m pip install -r requirements.txt   # installs `mcp` and `pytest`

# Smoke test — list the tools and schemas without a live client:
python -m books_mcp list-tools

# Run the test suite (offline, in-memory catalog):
python -m pytest

# Run the server (stdio transport — this is what an MCP client launches):
python -m books_mcp

The smoke test output:

books-catalog MCP server exposes 5 tools (catalog: 30 books):

  - search_books(query, limit)
      Search the catalog by a keyword in the title or author.
  - get_book(book_id)
      Fetch a single book by its numeric id.
  - find_books_by_genre(genre, year_from, year_to, limit)
      List books in a genre, optionally filtered by publication-year range.
  - top_rated_books(limit, genre)
      Return the highest-rated books, optionally within a single genre.
  - catalog_stats()
      Summarize the whole catalog.

Example tool result (catalog_stats()):

{
  "total_books": 30,
  "total_authors": 19,
  "genres": { "Adventure": 7, "Fiction": 7, "Gothic": 6, "ScienceFiction": 3,
              "Historical": 2, "Mystery": 2, "Romance": 2, "Fantasy": 1 },
  "year_range": [1811, 1902],
  "avg_pages": 468.4,
  "avg_rating": 4.17
}

---

MCP tool-design patterns demonstrated

These are the choices that make tools usable by a model, not just callable:

1. One job per tool, named as a verb-phrase. search_books, find_books_by_genre, get_book. A model picks the right tool from the name alone.
2. The docstring is the contract. FastMCP turns each function's signature into the tool's JSON input schema and its docstring into the description the model sees. Both are written for a model reader: what it does, every argument, the return shape, and what raises.
3. Type hints drive the schema. book_id: int, genre: str, year_from: int | None = None become a validated input schema with the right types and optionality — no hand-written JSON schema.
4. Validate and bound every input. Limits are clamped to a hard MAX_LIMIT so a tool call can never trigger an unbounded scan; empty queries and bad ids are rejected up front.
5. Errors are actionable. An unknown genre returns Unknown genre 'Cyberpunk'. Available genres: Adventure, Fiction, ...; a bad id returns the valid range. The model can correct itself from the message.
6. Outputs are plain JSON-serializable dicts, never database row objects — stable, predictable, and easy for the model to consume.
7. The data layer is separate from the protocol. db.py is a typed, independently testable SQLite layer; server.py only does validation + wiring. You can unit-test all the logic without standing up a server.

---

Connect it to an MCP client

Claude Desktop

Add the server to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "books-catalog": {
      "command": "python",
      "args": ["-m", "books_mcp"],
      "cwd": "/absolute/path/to/mcp-quickstart"
    }
  }
}

Restart Claude Desktop; the five tools appear under the server. Then ask natural-language questions like "What are the top-rated adventure books before 1880?" and the model will call find_books_by_genre / top_rated_books.

Any MCP client

The server speaks the standard MCP stdio transport, so any compliant client (the MCP Inspector, a custom client using the mcp SDK, etc.) can launch python -m books_mcp and discover the tools via the normal list_tools / call_tool handshake.

---

Storage

By default the server builds an in-memory SQLite catalog from the bundled seed data at startup — zero setup, always fresh, no files left behind. To materialize a file-backed catalog (e.g. to inspect it with the sqlite3 CLI or share it across processes):

python -m books_mcp seed --db catalog.db
BOOKS_DB_PATH=catalog.db python -m books_mcp        # serve from the file

---

Project layout

mcp-quickstart/
├── books_mcp/
│   ├── __init__.py
│   ├── __main__.py      # serve | list-tools | seed
│   ├── server.py        # FastMCP server + the five tools
│   ├── db.py            # typed SQLite data-access layer (no MCP)
│   ├── seed.py          # build/seed a file-backed catalog
│   └── data/
│       └── books.json   # public-domain seed catalog
└── tests/               # pytest suite, all offline
    ├── test_db.py       # data-layer behavior
    └── test_tools.py    # tool behavior, validation, and registration

License

MIT — see LICENSE.