# Library MCP

A Model Context Protocol (MCP) server for college library management. This server provides AI-powered tools for managing library operations including book issuance, returns, inventory, and reporting.

## Features

### Tools
- **Issue Book**: Issue an available copy of a book to a student
- **Process Return**: Return a book and automatically assess late fines if overdue
- **Add Book**: Add new titles to the library catalog with multiple copies

### Resources
- **Book Info**: Retrieve full details for any book in the catalog
- **Book ID Lookup**: Resolve partial titles to matching book IDs
- **Availability**: Check available vs total copies of any book

### Prompts
- **Returns Due Today**: Generate reminder messages for books due back today
- **Top Performing Books**: Report the most-issued books
- **Under-Performing Books**: Identify underutilized titles for promotion or retirement

## Requirements

- Python 3.12+
- MySQL 8.0+
- FastMCP 3.4.7

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd library_mcp
```

2. Install dependencies:
```bash
uv sync
```

3. Set up MySQL database:
```bash
mysql -u root -p < data/library_schema.sql
mysql -u root -p < data/library_seed.sql
```

Or let the application auto-initialize on first run.

## Configuration

Set these environment variables in `.env`:

```env
MYSQL_HOST=localhost
MYSQL_USERNAME=root
MYSQL_PASSWORD=rootpassword
MYSQL_DATABASE=library
```

## Running the Server

```bash
uv run main.py
```

The MCP server will start on `http://127.0.0.1:19000/mcp`

### Database Auto-Initialization

The server automatically initializes the MySQL database on first run:
- Creates the `library` database and all tables
- Populates seed data with sample users, books, and transactions
- Subsequent runs skip initialization if tables already exist

## Project Structure

```
library_mcp/
├── main.py              # MCP server entry point with tools, resources, and prompts
├── db.py                # Database connection and initialization utilities
├── operations.py        # Business logic for library operations
├── datastore.py         # Data access layer
├── test.py              # Database connection test
├── pyproject.toml       # Project configuration and dependencies
├── README.md            # This file
├── .gitignore           # Git ignore rules
└── data/
    ├── library_schema.sql    # Database schema (tables and structure)
    └── library_seed.sql      # Sample data (users, books, transactions)
```

## Database Schema

The library system manages:
- **Users**: Librarians and students with authentication
- **Books**: Catalog with metadata (ISBN, title, subject, publisher)
- **Book Copies**: Individual copies with status tracking
- **Loan Transactions**: Issue and return records with dates
- **Fines**: Late fee assessment and payment tracking
- **Authors & Publishers**: Reference data for cataloging

## API Usage

### Issuing a Book
```python
issue_book(student_id="STU001", book_id=1, date="2026-08-13")
```

### Returning a Book
```python
process_return(student_id="STU001", book_id=1, date="2026-08-20", description="")
```

### Adding a New Book
```python
add_book(title="New Title", isbn13="978-0-123456-78-9", subject="CS", copies=5)
```

### Getting Book Info
```
GET /resources/book://{book_id}
```

### Checking Availability
```
GET /resources/availability://{book_id}
```

## Testing

Run the test script to verify database connectivity:
```bash
uv run test.py
```

## License

MIT