Book Library Server

A production-ready reference implementation showing how Claude (or any LLM) connects to a real REST API through an MCP Server.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        YOU / CLAUDE                             │
│              (natural language: "find me Python books")         │
└───────────────────────────┬─────────────────────────────────────┘
                            │  MCP Protocol (JSON-RPC 2.0)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MCP SERVER  :9000                            │
│                   (book_mcp — FastMCP)                          │
│                                                                 │
│  Tools exposed:                                                 │
│   book_list   book_search   book_get                           │
│   book_create book_update   book_delete                        │
│                                                                 │
│  Responsibilities:                                              │
│   ✅ Translate MCP tool calls → HTTP requests                  │
│   ✅ Validate inputs with Pydantic                             │
│   ✅ Format API responses as Markdown or JSON                  │
│   ✅ Handle and surface errors cleanly                         │
└───────────────────────────┬─────────────────────────────────────┘
                            │  REST API (HTTP/JSON)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   BOOK LIBRARY API  :8000                       │
│                      (FastAPI)                                  │
│                                                                 │
│  Endpoints:                                                     │
│   GET    /api/v1/books/          List + filter + paginate      │
│   GET    /api/v1/books/search    Full-text search              │
│   GET    /api/v1/books/{id}      Get single book               │
│   POST   /api/v1/books/          Create book                   │
│   PATCH  /api/v1/books/{id}      Update book                   │
│   DELETE /api/v1/books/{id}      Delete book                   │
│   GET    /health                 Health probe                   │
│   GET    /docs                   Swagger UI                    │
└─────────────────────────────────────────────────────────────────┘

---

📁 Folder Structure

book-mcp-demo/
│
├── api/                          # FastAPI REST API
│   ├── core/
│   │   └── config.py             # Settings from env vars
│   ├── exceptions/
│   │   └── __init__.py           # Custom exception classes
│   ├── models/
│   │   └── book.py               # Domain model + in-memory store
│   ├── routers/
│   │   └── books.py              # All CRUD route handlers
│   ├── schemas/
│   │   └── book.py               # Pydantic request/response schemas
│   ├── main.py                   # FastAPI app entry point
│   └── requirements.txt
│
├── mcp_server/
│   ├── server.py                 # FastMCP server with 6 tools
│   └── requirements.txt
│
├── mcp_client/
│   ├── client.py                 # Demo client (shows MCP wire protocol)
│   └── requirements.txt
│
├── tests/
│   └── test_books_api.py         # API integration tests
│
├── Dockerfile.api                # Multi-stage Docker build for API
├── Dockerfile.mcp                # Multi-stage Docker build for MCP server
├── Dockerfile.client             # Docker build for demo client
├── docker-compose.yml            # Orchestrates all 3 services
├── requirements.txt              # Root deps for local dev
└── .env                          # Environment variables

---

🚀 Quick Start

Option 1 — Docker Compose (Recommended)

# Clone and enter the project
cd book-mcp-demo

# Start all 3 services (API + MCP Server + Client demo)
docker compose up --build

# You'll see:
# book_api    → ready on port 8000
# book_mcp    → ready on port 9000
# book_mcp_client → runs all demo scenarios, then exits

Option 2 — Local Development

# Install all dependencies
pip install -r requirements.txt

# Terminal 1: Start the API
uvicorn api.main:app --reload --port 8000

# Terminal 2: Start the MCP server
python mcp_server/server.py

# Terminal 3: Run the client demo
python mcp_client/client.py

---

🧪 Running Tests

# Install test deps
pip install -r requirements.txt

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=api

---

🌐 API Documentation

Once the API is running, open:

URL	Description
http://localhost:8000/docs	Swagger UI (interactive)
http://localhost:8000/redoc	ReDoc UI
http://localhost:8000/health	Health check

---

🔧 MCP Tools Reference

Tool	Description	Read-only
book_list	List all books with filters and pagination	✅ Yes
book_search	Search by title or author	✅ Yes
book_get	Get a single book by ID	✅ Yes
book_create	Add a new book (ISBN must be unique)	❌ No
book_update	Partially update a book	❌ No
book_delete	Permanently delete a book	❌ No

---

🔍 How MCP Works (Step by Step)

Step 1 — Handshake
  Client → Server: initialize (announce capabilities)
  Server → Client: serverInfo + available tools list

Step 2 — Tool Discovery
  Client → Server: tools/list
  Server → Client: [{name, description, inputSchema}, ...]

Step 3 — Tool Call
  Client → Server: tools/call {name: "book_search", arguments: {query: "python"}}
  Server:           validates input → calls Book API → formats response
  Server → Client: {content: [{type: "text", text: "### Search results..."}]}

---

🛡️ Error Handling Strategy

API Layer (FastAPI)

• Custom exceptions (BookNotFoundError, DuplicateISBNError) — raised in business logic
• Exception handlers in routers convert them to proper HTTP status codes
• Global handler catches anything unexpected → always returns clean JSON

MCP Layer (FastMCP)

• _handle_api_error() — single shared function maps all error types:
  • httpx.HTTPStatusError → maps HTTP codes to user-friendly messages
  • httpx.TimeoutException → timeout message
  • httpx.ConnectError → connectivity message
• Never exposes raw stack traces to the LLM client
• Structured logging to stderr (stdout is reserved for MCP protocol)

---

🐳 Container Design Decisions

Decision	Reason
Multi-stage builds	Smaller final images (no build tools in runtime)
Non-root user	Security best practice
Health checks	Docker and orchestrators (K8s) need these for readiness
depends_on: condition: service_healthy	MCP won't start until API is truly ready
PYTHONUNBUFFERED=1	Logs appear immediately in Docker
Per-service requirements.txt	Only installs what each container needs

---

⚙️ Environment Variables

Variable	Default	Description
BOOK_API_BASE_URL	http://localhost:8000/api/v1	API base URL seen by MCP server
BOOK_API_TIMEOUT	10.0	HTTP timeout in seconds
MCP_HOST	0.0.0.0	MCP server bind host
MCP_PORT	9000	MCP server port
MCP_SERVER_URL	http://localhost:9000	MCP URL seen by client
DEBUG	false	Enable debug logging