book-api-mcp-server by 0x1D-1983 - MCP Server

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

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:

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

0x1D-1983/book-api-mcp-server

Books API MCP Server

Features

Available Tools

1. list_books

2. get_book

3. create_book

4. update_book

5. delete_book

Setup Instructions

Prerequisites

Installation

Testing the Server

Configuration

Environment Variables

Cursor Integration

API Endpoints

Usage Examples

Using Python Client

Using HTTP API

Project Structure

Date Format Requirements

Technologies

Error Handling

Troubleshooting

Server won't start

Tools return connection errors

Date format errors

License

1. `list_books`

2. `get_book`

3. `create_book`

4. `update_book`

5. `delete_book`