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:

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:

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:

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
   

2. Create and activate a virtual environment:

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

3. Install dependencies:

   pip install fastapi uvicorn requests pydantic
   

   Or if you have a requirements.txt file:

   pip install -r requirements.txt
   

4. 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:

   BOOKS_API_URL = "http://localhost:5288"  # Update as needed
   

5. 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:

   export MCP_SERVER_HOST=localhost
   export MCP_SERVER_PORT=8080
   python run.py
   

Testing the Server

1. Check server health:

   curl http://localhost:8080/health
   

2. List available tools:

   curl http://localhost:8080/tools
   

3. 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.