LibraryMCP

Demo project — Intended for local development and learning purposes only. Do not expose it to the public internet or use it to store real data.

LibraryMCP is a FastAPI-based backend server designed to serve as a Model Context Protocol (MCP) tool invocation source for library management. It provides a set of API endpoints to manage books, members, and loans in a library system.

Features

• Books Management: Full CRUD with filtering by title, author, genre, and availability.
• Members Management: Register, list (with filters), view details with loan history and fines, update, and delete with business rules.
• Loans Management: Borrow/return workflows, active loans listing, and fine calculations.
• JWT Authentication: All API endpoints (except /auth/token) require a Bearer token. Credentials are configurable via environment variables.
• SQLite Database: Lightweight storage using SQLAlchemy ORM.
• FastAPI: High-performance web framework for building APIs with Python.
• CORS Enabled: Open CORS for easy local development and browser demos.
• Simple Frontend Demo: Minimal HTML page to add/list books and members.
• Seeding Tool: Built-in script to populate the database with initial sample data.

Project Structure

libraryMCP/
├── backend/                # Application source code
│   ├── routers/            # API route handlers
│   │   ├── auth.py         # Authentication endpoint (token issuance)
│   │   ├── books.py        # Book-related endpoints
│   │   ├── loans.py        # Loan-related endpoints
│   │   └── members.py      # Member-related endpoints
│   ├── auth.py             # JWT creation, verification, and get_current_user dependency
│   ├── crud.py             # CRUD operations
│   ├── database.py         # Database configuration and session management
│   ├── main.py             # FastAPI application entry point (CORS + routers)
│   ├── models.py           # SQLAlchemy database models
│   ├── schemas.py          # Pydantic models for request/response validation
│   └── seed.py             # Database seeding script
├── frontend/
│   └── index.html          # Simple browser demo (books/members)
├── library.db              # SQLite database file
├── openapi.json            # Generated OpenAPI schema snapshot
├── pyproject.toml          # Project dependencies and configuration
├── uv.lock                 # Lock file for dependencies
└── README.md               # Project documentation

Prerequisites

• Python >= 3.13
• uv (recommended for dependency management)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd libraryMCP
   

2. Install dependencies:

   uv sync
   

3. Configure credentials in .env (copy from .env and fill in your values):

   ADMIN_USERNAME="admin"
   ADMIN_PASSWORD="your-password"
   SECRET_KEY="your-secret-key"
   BACKEND_URL=http://localhost:8000
   

Usage

Running the Server

Start the FastAPI server using uvicorn:

uv run uvicorn backend.main:app --reload

The API will be available at http://127.0.0.1:8000.

Authentication

All endpoints except POST /auth/token require a JWT Bearer token.

Obtain a token:

curl -X POST http://127.0.0.1:8000/auth/token \
  -d "username=admin&password=your-password"

Response:

{ "access_token": "<token>", "token_type": "bearer" }

Use the token:

curl http://127.0.0.1:8000/books/ \
  -H "Authorization: Bearer <token>"

Tokens expire after 30 minutes. Configure credentials via ADMIN_USERNAME, ADMIN_PASSWORD, and SECRET_KEY environment variables (or in .env).

API Documentation

Once the server is running, you can access the interactive API documentation:

• Swagger UI: http://127.0.0.1:8000/docs — click Authorize, call POST /auth/token first to get a token, then paste it in the Bearer field
• ReDoc: http://127.0.0.1:8000/redoc
• OpenAPI JSON: http://127.0.0.1:8000/openapi.json (a snapshot also lives at openapi.json)

Seeding the Database

To populate the database with sample data, run the seed script:

uv run python backend/seed.py

Simple Frontend Demo (optional)

You can interact with the API using a tiny frontend:

• Open frontend/index.html in your browser
• Ensure the backend runs at http://localhost:8000 (CORS is enabled)
• Use the UI to add/list books and members

MCP Server

The MCP server exposes the library's functionality as tools that AI assistants (Claude, etc.) can call directly.

Running the MCP Server

The MCP server communicates over stdio. Start the FastAPI backend first, then run:

uv run python mcp_server/main_stdio.py

The server reads BACKEND_URL, ADMIN_USERNAME, and ADMIN_PASSWORD from the environment (or .env). It obtains a JWT token automatically on first use and refreshes it when it expires.

Connecting to Claude Desktop

Add the following to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "library": {
      "command": "uv",
      "args": ["run", "python", "mcp_server/main_stdio.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/libraryMCP"
      }
    }
  }
}

Available MCP Tools

Tool	Description
search_books	Search books by title, author, or genre
get_book	Get full details of a book by ID
add_book	Add a new book to the catalog
update_book	Update book metadata or copy count
delete_book	Remove a book (blocked if active loans exist)
list_members	List members with optional filters
register_member	Register a new library member
get_member	Get member profile, loan history, and fines
delete_member	Delete a member (blocked if active loans or unpaid fines)
borrow_book	Borrow a book for a member
return_book	Return a borrowed book, calculating any overdue fine
get_loans	List all active loans for a member
check_fines	Get total outstanding fines for a member

API Endpoints Overview

Authentication

• POST /auth/token — Obtain a JWT Bearer token (form fields: username, password).

Books

• GET /books/ — List books with optional filters.
  • Query: title, author, genre, available_only
• GET /books/{id} — Get a single book by ID.
• POST /books/ — Create a book (initial available_copies = total_copies).
• PUT /books/{id} — Update a book.
• DELETE /books/{id} — Delete a book (blocked if there are active loans).

Members

• GET /members/ — List members with filters and pagination.
  • Query: skip, limit, name, email, is_active
• GET /members/{id} — Get member details with loan history, active loans count, and total fines.
• POST /members/ — Register a new member (unique email required).
• PUT /members/{id} — Update member (cannot deactivate with active loans; email must be unique/valid).
• DELETE /members/{id} — Delete member (blocked if active loans or unpaid fines).

Loans

• POST /loans/borrow — Borrow a book (member must be active; book must have available copies; no duplicate active loan).
• POST /loans/return — Return a book (increments availability; computes fine if overdue: $0.50/day).
• GET /loans/{member_id} — List active loans for a member.
• GET /loans/{member_id}/fines — Calculate and return fine breakdown for a member.