2. A first server¶
In this chapter we write the smallest useful version of Shelf: search the catalog, and get one book.
The library¶
The library's data lives in library.py: 60 books split across two branches, north and south, plus the loans and a slow "reviews" service we will meet in chapter 4. It is plain Python with no OunceMCP in it, so we will not look at it here. All you need to know is that make_catalog() returns a dictionary of Book objects keyed by id (b-001 to b-060).
Step 1: the catalog¶
Here is the whole server:
"""Shelf, step 1: a read-only catalog (the book, chapter 2).
Two tools: search the catalog, and get one book. Run it with
``ouncemcp dev examples/book/shelf/step1_catalog.py``.
"""
from __future__ import annotations
from library import make_catalog
from pydantic import BaseModel, Field
from ouncemcp import Effect, NotFound, OunceServer
CATALOG = make_catalog()
server = OunceServer(
"shelf",
instructions="A library catalog. Search for books, then get one book by its id.",
)
class BookSummary(BaseModel):
id: str
title: str
author: str
class SearchResult(BaseModel):
books: list[BookSummary] = Field(max_length=10)
total: int
class BookDetail(BaseModel):
id: str
title: str
author: str
subject: str
year: int
branch: str
@server.tool(name="books.search", effect=Effect.READ)
def search(
query: str = Field(description="Words from the title or the author's name"),
limit: int = Field(5, ge=1, le=10),
) -> SearchResult:
"""Find books whose title or author contains every word of the query.
Use books.get for the details of one book."""
words = query.lower().split()
found = [
b for b in CATALOG.values() if all(w in f"{b.title} {b.author}".lower() for w in words)
]
return SearchResult(
books=[BookSummary(id=b.id, title=b.title, author=b.author) for b in found[:limit]],
total=len(found),
)
@server.tool(name="books.get", effect=Effect.READ)
def get(id: str = Field(description="Book id from books.search, for example b-007")) -> BookDetail:
"""Get one book: title, author, subject, year and branch. Use books.search to find ids."""
book = CATALOG.get(id)
if book is None:
raise NotFound(f"No book with id '{id}'.", hint="Use books.search to find ids.")
return BookDetail(
id=book.id,
title=book.title,
author=book.author,
subject=book.subject,
year=book.year,
branch=book.branch,
)
if __name__ == "__main__":
server.run()
Let's go through it.
The server¶
OunceServer wraps a FastMCP server. The name identifies it to hosts; the instructions are a sentence or two the host may show the model about the server as a whole. Keep them short: they are context too.
Tools have names, effects and types¶
@server.tool(name="books.search", effect=Effect.READ)
def search(query: str = Field(description=...), limit: int = Field(5, ge=1, le=10)) -> SearchResult:
Three things are required on every tool, and OunceMCP refuses to start without them:
- A name. Use
noun.verbnames (books.search,books.get) so related tools sort together and the model can tell them apart. - An effect.
Effect.READsays the tool changes nothing. Writes areEffect.WRITEorEffect.DESTRUCTIVE(chapter 6). The effect decides retries, approvals and lints, so it is never guessed. - A typed result. The return annotation must be a Pydantic model. That model becomes the tool's output schema, and OunceMCP uses it to shape results that are too large without ever breaking the schema.
Note
Try removing the return annotation. The server fails at import with "Tool 'books.search' must be annotated to return a Pydantic model". Mistakes like this surface when you write them, not when a model trips over them.
Descriptions are for the model¶
The docstring is the tool's description, and each Field(description=...) documents a parameter. The model reads these to decide which tool to call and what to pass, so write them for it:
- Say what the tool does and what it returns.
- Say where argument values come from ("Book id from books.search").
- Point to the next tool ("Use books.get for the details of one book").
Bounds matter as much as words. limit: int = Field(5, ge=1, le=10) stops the model asking for 10,000 rows, and Field(max_length=10) on the result list says the result can never hold more.
Errors are values the model can act on¶
When a book does not exist we raise NotFound with a hint. The model receives the message, the hint and a machine-readable category. Chapter 5 covers errors in full.
Running it¶
Run the server with hot reload:
dev serves on http://127.0.0.1:8000/mcp, restarts when you save, and prints one line per call with the tokens the result used. Point any MCP host or the MCP Inspector at that URL and call books.search with {"query": "ada"}.
To use it from Claude Desktop over stdio instead, add it to claude_desktop_config.json:
{
"mcpServers": {
"shelf": {"command": "uv", "args": ["run", "--directory", "/path/to/ouncemcp", "python", "examples/book/shelf/step1_catalog.py"]}
}
}
Seeing what the model sees¶
ouncemcp context prints the exact definition a client receives:
{
"name": "books.get",
"description": "Get one book: title, author, subject, year and branch. Use books.search to find ids.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {"description": "Book id from books.search, for example b-007", "type": "string"}
},
"required": ["id"]
},
"outputSchema": { ... }
}
Every one of those characters is in the model's context for the whole session. The next chapter puts a number on it.
Summary¶
- A tool needs a
noun.verbname, anEffectand a Pydantic return type. - Descriptions and field descriptions are written for the model: what, returns, where values come from, what to call next.
- Bound every input and every list.
ouncemcp devruns the server;ouncemcp contextshows what the model receives.