InventoryApplication MCP Server

A Python Model Context Protocol (MCP) 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.

Related MCP server: MCP Inventory Manager

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:

   cd InventoryApplication-MCP

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt
   pip install -r requirements-dev.txt  # Optional: for development and testing

4. Configure environment variables:

   cp .env.example .env

   Edit .env with your API configuration:

   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

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)

Customer Tools (6)

Order Tools (4)

Sales Tools (6)

User Tools (6)

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:

pytest tests/ -v

Run with coverage:

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

Configuration

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

Error Handling

Tools return structured error messages that include:

• HTTP status codes

• API error details

• Descriptive error messages

Example error response:

{
  "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