┌─────────────────────────────────────────────────────────────────┐
│                        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                    │
└─────────────────────────────────────────────────────────────────┘

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

# 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

# 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

# Install test deps
pip install -r requirements.txt

# Run all tests
pytest tests/ -v

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

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..."}]}