Books API MCP Server

A Model Context Protocol (MCP) server that exposes book management tools for AI assistants. This server provides a bridge between AI applications and a .NET Books API, enabling seamless book collection management through standardized MCP tool calls.

The .NET Book API backend that this MCP server interacts with is available at: https://github.com/0x1D-1983/book-api.

Features

MCP Protocol Support: Implements Model Context Protocol for tool discovery and execution
RESTful API Integration: Connects to a .NET Books API backend
Comprehensive CRUD Operations: Full Create, Read, Update, and Delete functionality for books
FastAPI Framework: Modern, fast, and easy-to-maintain Python web framework
Type-Safe Models: Uses Pydantic for robust data validation
Error Handling: Comprehensive error handling with clear error messages

Available Tools

The MCP server exposes the following tools:

1. `list_books`

Retrieve all books from the database.

Parameters:

None

Returns:

Array of book objects with the following fields:
id (integer): Unique book identifier
title (string): Book title
author (string): Book author
isbn (string): International Standard Book Number
publishedDate (string): Publication date in ISO 8601 format
createdAt (string): Record creation timestamp

Example Usage: ```python result = BookService.list_books()

Returns: List of all books in the database


---

### 2. `get_book`

Retrieve a specific book by its ID.

**Parameters:**
- `book_id` (integer, required): The unique identifier of the book to retrieve

**Returns:**
- Book object with full details, or error if book not found

**Example Usage:**

result = BookService.get_book(1)

Returns: Book with ID 1


---

### 3. `create_book`

Create a new book in the database.

**Parameters:**
- `book_data` (object, required): Book information object containing:
  - `id` (integer, optional): Unique identifier for the book
  - `title` (string, required): Title of the book
  - `author` (string, required): Author of the book
  - `isbn` (string, optional): ISBN of the book
  - `publishedDate` (string, optional): Publication date in **ISO 8601 UTC format** (must end with 'Z', e.g., `2024-04-11T00:00:00Z`)

**Returns:**
- Created book object with all fields including generated `createdAt` timestamp

**Example Usage:**

book_data = { "title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "isbn": "978-0743273565", "publishedDate": "1925-04-10T00:00:00Z" } result = BookService.create_book(book_data) ```

Important: The publishedDate field must be in ISO 8601 UTC format ending with 'Z' to ensure PostgreSQL compatibility.

---

4. `update_book`

Update an existing book's information.

Parameters:

book_id (integer, required): The unique identifier of the book to update
book_data (object, required): Updated book information object containing:
id (integer): ID of the book (must match book_id)
title (string, optional): New title
author (string, optional): New author
isbn (string, optional): New ISBN
publishedDate (string, optional): New publication date in ISO 8601 UTC format (must end with 'Z')

Returns:

Success message if update was successful, or error if book not found

Example Usage: ``python book_data = { "id": 1, "title": "Updated Title", "author": "Updated Author", "isbn": "978-1234567890", "publishedDate": "2023-01-01T00:00:00Z" } result = BookService.update_book(1, book_data) ``

---

5. `delete_book`

Delete a book from the database.

Parameters:

book_id (integer, required): The unique identifier of the book to delete

Returns:

Success message if deletion was successful, or error if book not found

Example Usage: ```python result = BookService.delete_book(1)

Returns: Success message confirming deletion


---

## Setup Instructions

### Prerequisites

- Python 3.8 or higher
- Access to a running Books API instance (default: `http://localhost:5288`)
- Virtual environment (recommended)

### Installation

1. **Clone or navigate to the project directory:**

cd book-api-mcp-server ```

Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:

   pip install fastapi uvicorn requests pydantic

Or if you have a requirements.txt file: ``bash pip install -r requirements.txt ``

Configure the Books API URL:

Edit services.py and update the BOOKS_API_URL constant if your Books API is running on a different host/port: ``python BOOKS_API_URL = "http://localhost:5288" # Update as needed ``

Run the server:

   python run.py

The server will start on http://0.0.0.0:8080 by default.

You can customize the host and port using environment variables: ``bash export MCP_SERVER_HOST=localhost export MCP_SERVER_PORT=8080 python run.py ``

Testing the Server

Check server health:

   curl http://localhost:8080/health

List available tools:

   curl http://localhost:8080/tools

Run the test suite:

   python test_tools.py

---

Configuration

Environment Variables

MCP_SERVER_HOST: Server host address (default: 0.0.0.0)
MCP_SERVER_PORT: Server port number (default: 8080)
BOOKS_API_URL: Base URL of the Books API (configured in services.py, default: http://localhost:5288)

Cursor Integration

To use this MCP server with Cursor, add the following to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "books-api": {
      "command": "python3",
      "args": ["/path/to/book-api-mcp-server/run.py"]
    }
  }
}

Note: Restart Cursor after updating the MCP configuration for changes to take effect.

---

API Endpoints

The MCP server exposes the following HTTP endpoints:

GET /: Root endpoint with server information
GET /tools: List all available MCP tools
POST /tool-calls: Execute one or more tool calls
GET /health: Health check endpoint
GET /docs: Interactive API documentation (FastAPI Swagger UI)

---

Usage Examples

Using Python Client

from services import BookService
import json

# List all books
books = BookService.list_books()
print(json.dumps(books.result, indent=2))

# Get a specific book
book = BookService.get_book(1)
print(json.dumps(book.result, indent=2))

# Create a new book
new_book = {
    "title": "1984",
    "author": "George Orwell",
    "isbn": "978-0451524935",
    "publishedDate": "1949-06-08T00:00:00Z"
}
result = BookService.create_book(new_book)
print(json.dumps(result.result, indent=2))

# Update a book
updated_data = {
    "id": 1,
    "title": "Nineteen Eighty-Four",
    "author": "George Orwell"
}
result = BookService.update_book(1, updated_data)

# Delete a book
result = BookService.delete_book(1)

Using HTTP API

# List all tools
curl http://localhost:8080/tools

# Call a tool
curl -X POST http://localhost:8080/tool-calls \
  -H "Content-Type: application/json" \
  -d '{
    "tool_calls": [
      {
        "name": "list_books",
        "parameters": {}
      }
    ]
  }'

---

Project Structure

book-api-mcp-server/
├── main.py              # FastAPI application and server setup
├── routes.py            # API route handlers for MCP endpoints
├── tools.py             # Tool definitions and schemas
├── services.py          # Business logic and Books API integration
├── models.py            # Pydantic models for data validation
├── config.py            # Configuration settings
├── run.py               # Server entry point
├── test_tools.py        # Test suite for validating tools
├── requirements.txt     # Python dependencies
└── README.md           # This file

---

Date Format Requirements

Important: All date fields (publishedDate) must be provided in ISO 8601 UTC format ending with 'Z'. This is required for PostgreSQL compatibility.

Correct Format:

2024-04-11T00:00:00Z
2023-05-11T12:30:45Z

Incorrect Formats (will cause errors):

2024-04-11T00:00:00 (missing 'Z')
2024-04-11 (not full ISO 8601)
04/11/2024 (not ISO 8601)

---

Technologies

Python 3.8+: Programming language
FastAPI: Modern web framework for building APIs
Uvicorn: ASGI server for running FastAPI
Pydantic: Data validation using Python type annotations
Requests: HTTP library for making API calls to the Books API

---

Error Handling

All tools return a ToolCallResult object with the following structure:

{
    "result": <data> | None,  # Result data if successful
    "error": <string> | None  # Error message if operation failed
}

Common error scenarios:

404 Not Found: Book with specified ID does not exist
400 Bad Request: Invalid input data (e.g., missing required fields, invalid date format)
500 Server Error: Database or API connection issues
Connection Error: Books API is not accessible

---

Troubleshooting

Server won't start

Check if port 8080 is already in use
Verify Python version (3.8+)
Ensure all dependencies are installed

Tools return connection errors

Verify the Books API is running and accessible
Check the BOOKS_API_URL in services.py
Test the Books API directly: curl http://localhost:5288/books

Date format errors

Ensure all dates end with 'Z' for UTC timezone
Use full ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

---

License

This project is part of a book management system demonstration.

Books API MCP Server