# Film Equipment Rental MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with tools to interact with the Film Equipment Rental WordPress plugin API.

## Overview

This MCP server exposes comprehensive tools for managing film equipment inventory, clients, rental sessions, and statistics through the Film Equipment Rental WordPress plugin's REST API.

## Features

### Equipment Management
- `list_equipment` - List all equipment with optional filtering
- `get_equipment` - Get detailed equipment info including rental history
- `create_equipment` - Add new equipment to inventory
- `update_equipment` - Update equipment details
- `delete_equipment` - Remove equipment from inventory

### Client Management
- `list_clients` - List all clients with rental statistics
- `get_client` - Get detailed client info with rental history
- `create_client` - Add new client
- `update_client` - Update client information
- `delete_client` - Remove client

### Rental Management
- `list_rentals` - List rental sessions with pagination
- `get_rental` - Get detailed rental information
- `create_rental` - Create new rental session
- `update_rental` - Update rental session
- `delete_rental` - Delete rental session

### Statistics
- `get_statistics` - Get comprehensive rental statistics, ROI, and trends

## Prerequisites

- Node.js 18+ or compatible runtime
- Film Equipment Rental WordPress plugin installed and activated
- API key generated in plugin settings

## Installation

### 1. Install Dependencies

```bash
cd mcp-server
npm install
```

### 2. Build the Server

```bash
npm run build
```

### 3. Configure Environment Variables

Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```

Edit `.env` with your WordPress site details:

```env
FER_API_BASE_URL=https://yoursite.com/wp-json/film-equipment-rental/v1
FER_API_KEY=your_api_key_here
```

**To get your API key:**
1. Log in to WordPress admin
2. Go to **Settings → Equipment Rental Settings**
3. Navigate to the **REST API Access** tab
4. Copy the API key displayed

## Usage

### Running Standalone

For testing or development:

```bash
npm start
```

### Using with Claude Desktop

Add this server to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "film-equipment-rental": {
      "command": "node",
      "args": [
        "/absolute/path/to/Film-Equipment-Rental/mcp-server/dist/index.js"
      ],
      "env": {
        "FER_API_BASE_URL": "https://yoursite.com/wp-json/film-equipment-rental/v1",
        "FER_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**Important:** Replace `/absolute/path/to/` with the actual absolute path to your installation.

After adding the configuration:
1. Restart Claude Desktop
2. The Film Equipment Rental tools will be available in conversations

### Using with Other MCP Clients

Any MCP-compatible client can use this server via stdio transport. Configure according to your client's documentation, using:

- **Command:** `node`
- **Args:** `["path/to/mcp-server/dist/index.js"]`
- **Environment variables:** `FER_API_BASE_URL` and `FER_API_KEY`

## Tool Reference

### Equipment Tools

#### `list_equipment`

List all equipment items with optional filtering.

**Parameters:**
- `category` (optional): Filter by category slug (e.g., "cameras", "lenses")
- `status` (optional): Filter by status

**Example:**
```json
{
  "category": "cameras",
  "status": "active"
}
```

#### `get_equipment`

Get detailed information about a specific equipment item.

**Parameters:**
- `id` (required): Equipment ID

**Example:**
```json
{
  "id": 1
}
```

#### `create_equipment`

Create a new equipment item.

**Parameters:**
- `name` (required): Equipment name
- `brand`: Equipment brand
- `serial_number`: Serial number
- `description`: Full description
- `short_description`: Short description
- `category`: Category slug
- `daily_rate`: Daily rental rate
- `purchase_price`: Purchase price
- `purchase_date`: Purchase date (YYYY-MM-DD)
- `current_value`: Current estimated value
- `status`: Status (default: "active")
- `images`: Array of image URLs

**Example:**
```json
{
  "name": "ARRI Alexa Mini",
  "brand": "ARRI",
  "category": "cameras",
  "daily_rate": 500,
  "purchase_price": 40000,
  "purchase_date": "2024-01-15",
  "current_value": 35000
}
```

#### `update_equipment`

Update an existing equipment item (only provided fields will be updated).

**Parameters:**
- `id` (required): Equipment ID
- All other parameters are optional (same as create_equipment)

**Example:**
```json
{
  "id": 1,
  "daily_rate": 550,
  "current_value": 34000
}
```

#### `delete_equipment`

Delete an equipment item and its associated images.

**Parameters:**
- `id` (required): Equipment ID

**Example:**
```json
{
  "id": 1
}
```

### Client Tools

#### `list_clients`

List all clients with their rental statistics.

**Parameters:** None

#### `get_client`

Get detailed information about a specific client including rental history.

**Parameters:**
- `id` (required): Client ID

**Example:**
```json
{
  "id": 1
}
```

#### `create_client`

Create a new client.

**Parameters:**
- `name` (required): Client name

**Example:**
```json
{
  "name": "Production Company XYZ"
}
```

#### `update_client`

Update an existing client.

**Parameters:**
- `id` (required): Client ID
- `name` (required): Client name

**Example:**
```json
{
  "id": 1,
  "name": "Updated Production Company Name"
}
```

#### `delete_client`

Delete a client.

**Parameters:**
- `id` (required): Client ID

**Example:**
```json
{
  "id": 1
}
```

### Rental Tools

#### `list_rentals`

List all rental sessions with pagination.

**Parameters:**
- `limit` (optional): Number of rentals to return (default: 50)
- `offset` (optional): Offset for pagination (default: 0)

**Example:**
```json
{
  "limit": 10,
  "offset": 0
}
```

#### `get_rental`

Get detailed information about a specific rental session.

**Parameters:**
- `id` (required): Rental session ID

**Example:**
```json
{
  "id": 10
}
```

#### `create_rental`

Create a new rental session with equipment.

**Parameters:**
- `rental_date` (required): Rental date (YYYY-MM-DD)
- `rental_days` (required): Number of rental days (minimum 1)
- `equipment` (required): Array of equipment items with earnings
- `client_id` (optional): Client ID
- `notes` (optional): Project name or notes

**Example:**
```json
{
  "client_id": 1,
  "rental_date": "2024-03-20",
  "rental_days": 3,
  "notes": "Downtown film shoot",
  "equipment": [
    {
      "equipment_id": 1,
      "earnings": 1500
    },
    {
      "equipment_id": 2,
      "earnings": 300
    }
  ]
}
```

#### `update_rental`

Update an existing rental session.

**Parameters:**
- `id` (required): Rental session ID
- All other parameters are optional (same as create_rental)

**Example:**
```json
{
  "id": 10,
  "rental_days": 4,
  "notes": "Extended shoot"
}
```

#### `delete_rental`

Delete a rental session and its associated equipment earnings.

**Parameters:**
- `id` (required): Rental session ID

**Example:**
```json
{
  "id": 10
}
```

### Statistics Tool

#### `get_statistics`

Get comprehensive rental statistics including revenue, ROI, top clients, and monthly trends.

**Parameters:**
- `year` (optional): Year (e.g., 2024) or "all" for all-time statistics

**Example:**
```json
{
  "year": 2024
}
```

or

```json
{
  "year": "all"
}
```

## Development

### Project Structure

```
mcp-server/
├── src/
│   ├── index.ts        # Main MCP server implementation
│   └── api-client.ts   # WordPress REST API client
├── dist/               # Compiled JavaScript (generated)
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── .env.example        # Environment variables template
└── README.md          # This file
```

### Development Mode

Run TypeScript compiler in watch mode:

```bash
npm run dev
```

### Building

Compile TypeScript to JavaScript:

```bash
npm run build
```

## Troubleshooting

### API Connection Issues

**Error: "Invalid API key"**
- Verify your API key is correct in `.env`
- Check that the API key hasn't been regenerated in WordPress
- Ensure you're using the header authentication method

**Error: "API access is not configured"**
- Generate an API key in WordPress plugin settings
- Go to: Settings → Equipment Rental Settings → REST API Access

### Server Not Showing in Claude Desktop

1. Verify the path in `claude_desktop_config.json` is absolute
2. Ensure the server was built (`npm run build`)
3. Check that `dist/index.js` exists
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors

### Permission Errors

If you get permission errors when running the server:

```bash
chmod +x dist/index.js
```

## Security Notes

- Keep your API key confidential
- Use HTTPS in production environments
- The API key provides full access to your equipment data
- Regenerate the API key if it's compromised (in WordPress settings)
- Consider using environment-specific API keys for development/production

## API Documentation

For complete API documentation, see [API.md](../API.md) in the parent directory.

## Support

For issues or questions:
1. Check the [WordPress plugin documentation](../README.md)
2. Review the [API documentation](../API.md)
3. File an issue on the [GitHub repository](https://github.com/JensS/Film-Equipment-Rental)

## License

MIT

## Version

1.0.0