# InventoryApplication MCP Server

A Python [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes the InventoryApplication REST API as tools for AI agents. This server acts as the bridge between AI assistants and the inventory management system.

## Overview

Enable AI agents (Claude, GPT, etc.) to interact with the inventory management system through natural language. The MCP server exposes 33 tools that allow AI assistants to query and modify inventory data without needing to understand SQL, connection strings, or the internal database schema.

## Architecture

```
User / AI Agent
 │
 ▼
MCP Client (LangGraph, custom client, etc.)
 │
 │ MCP Protocol (HTTP/SSE)
 ▼
InventoryApplication MCP Server (Python)
 │
 │ HTTP/REST
 ▼
InventoryApplication.API (ASP.NET Core 8)
 │
 ▼
SQL Server (InventoryDatabase)
```

### Key Design Principles

1. **MCP talks to the API, not the database directly** — The C# API layer provides business logic, validation, and authorization. The MCP server never connects to SQL Server.

2. **Structured JSON responses** — Tools return structured data that the LLM can reason over, not free-text descriptions.

3. **Separate query tools from action tools** — Read-only tools have different security implications than write tools, enabling clear permission boundaries.

4. **Use the existing API** — No changes to the C# application are required. The MCP server consumes the REST API the same way any HTTP client would.

## Installation

### Prerequisites

- Python 3.11 or higher

### Setup

1. Clone the repository and navigate to the MCP directory:
   ```bash
   cd InventoryApplication-MCP
   ```

2. Create and activate a virtual environment:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   pip install -r requirements-dev.txt  # Optional: for development and testing
   ```

4. Configure environment variables:
   ```bash
   cp .env.example .env
   ```
   
   Edit `.env` with your API configuration:
   ```env
   API_BASE_URL=http://localhost:5000
   API_TIMEOUT=30
   API_KEY=  # Optional: if JWT auth is enabled in the future
   MCP_SERVER_PORT=8080
   ```

## Running the Server

```bash
python3 -m src.server
```

The server starts an HTTP endpoint at `http://localhost:8080/sse`. Clients connect via SSE for real-time communication. Multiple clients can connect to the same server instance.

## Available Tools

The server exposes **33 tools** across 5 categories:

### Inventory Tools (11)

| Tool | Description | Method |
|------|-------------|--------|
| `get_product` | Retrieve a product by ID | GET `/api/inventory/{id}` |
| `get_inventory` | List all products | GET `/api/inventory` |
| `search_inventory` | Search products by name | GET `/api/inventory/search?q=` |
| `create_product` | Create a new product | POST `/api/inventory` |
| `update_product` | Update an existing product | PUT `/api/inventory/{id}` |
| `delete_product` | Delete a product | DELETE `/api/inventory/{id}` |
| `get_categories` | List all categories | GET `/api/categories` |
| `get_category` | Retrieve a category by ID | GET `/api/categories/{id}` |
| `create_category` | Create a new category | POST `/api/categories` |
| `update_category` | Update a category | PUT `/api/categories/{id}` |
| `delete_category` | Delete a category | DELETE `/api/categories/{id}` |

### Customer Tools (6)

| Tool | Description | Method |
|------|-------------|--------|
| `get_customers` | List all customers | GET `/api/customers` |
| `search_customers` | Search customers by name | GET `/api/customers/search?q=` |
| `get_customer` | Retrieve a customer by ID | GET `/api/customers/{id}` |
| `create_customer` | Create a new customer | POST `/api/customers` |
| `update_customer` | Update a customer | PUT `/api/customers/{id}` |
| `delete_customer` | Delete a customer | DELETE `/api/customers/{id}` |

### Order Tools (4)

| Tool | Description | Method |
|------|-------------|--------|
| `get_orders` | List all orders | GET `/api/orders` |
| `get_order` | Retrieve an order by ID | GET `/api/orders/{id}` |
| `get_order_details` | Get order with line items | GET `/api/orders/{id}/details` |
| `create_order` | Create a new order | POST `/api/orders` |

### Sales Tools (6)

| Tool | Description | Method |
|------|-------------|--------|
| `get_sales` | List all sales | GET `/api/sales` |
| `get_sales_by_order` | Get sales for an order | GET `/api/sales/order/{orderId}` |
| `get_sales_by_product` | Get sales for a product | GET `/api/sales/product/{productName}` |
| `get_sales_history` | Get sales history for a product | GET `/api/sales/history?productId=&days=` |
| `create_sales` | Create sales records from an order | POST `/api/sales` |
| `update_product_quantity` | Update product inventory quantity | POST `/api/sales/update-quantity` |

### User Tools (6)

| Tool | Description | Method |
|------|-------------|--------|
| `get_users` | List all application users | GET `/api/users` |
| `login` | Authenticate a user | POST `/api/users/login` |
| `create_user` | Create a new user | POST `/api/users` |
| `update_user` | Update user information | PUT `/api/users/{id}` |
| `update_user_password` | Update a user's password | PUT `/api/users/{id}/password` |
| `delete_user` | Delete a user | DELETE `/api/users/{id}` |

## Project Structure

```
InventoryApplication-MCP/
├── src/
│   ├── server.py              # MCP server entry point
│   ├── config.py              # Configuration loading (env vars, .env)
│   ├── http_client.py         # Async HTTP client wrapper for API calls
│   └── tools/
│       ├── __init__.py        # Package initialization
│       ├── shared.py          # Shared utilities (error formatting, result wrappers)
│       ├── inventory_tools.py # Product and category tools (11 tools)
│       ├── customer_tools.py  # Customer tools (6 tools)
│       ├── order_tools.py     # Order tools (4 tools)
│       ├── sales_tools.py     # Sales tools (6 tools)
│       └── user_tools.py      # User tools (6 tools)
├── tests/
│   ├── conftest.py            # Shared test fixtures and mock data
│   ├── test_http_client.py    # HTTP client unit tests
│   ├── test_inventory_tools.py
│   ├── test_customer_tools.py
│   ├── test_order_tools.py
│   ├── test_sales_tools.py
│   └── test_user_tools.py
├── docs/
│   ├── project_prompt.md      # Architecture and design documentation
│   └── checklist.md           # Implementation checklist
├── requirements.txt           # Production dependencies
├── requirements-dev.txt       # Development dependencies (pytest, etc.)
├── .env.example               # Example environment configuration
└── .gitignore                 # Git ignore rules
```

## Testing

Run the test suite:

```bash
pytest tests/ -v
```

Run with coverage:

```bash
pytest tests/ -v --cov=src --cov-report=html
```

## Configuration

The MCP server is configured via environment variables or a `.env` file:

| Variable | Description | Default |
|----------|-------------|---------|
| `API_BASE_URL` | Base URL of the InventoryApplication.API | `http://localhost:5000` |
| `API_TIMEOUT` | HTTP request timeout in seconds | `30` |
| `API_KEY` | Optional API key for JWT auth | `None` |
| `MCP_SERVER_PORT` | HTTP port | `8080` |

## Error Handling

Tools return structured error messages that include:
- HTTP status codes
- API error details
- Descriptive error messages

Example error response:
```json
{
  "status": "error",
  "message": "API error (HTTP 404): Product not found"
}
```

## Future Considerations

- Add ANALYSIS tools: `calculate_sales_velocity`, `calculate_reorder_quantity`, `forecast_demand`
- Add authentication/authorization for MCP tools (API key or JWT)
- Add rate limiting to protect the API from excessive MCP calls
- Integrate with LangGraph for multi-step agent workflows

## License

MIT