# 📚 Book Library — MCP Server Demo

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)

```bash
# 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

```bash
# 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

```bash
# 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 |