# 🚚 ShipSmart MCP Server

ShipSmart is a sample **Logistics AI Backend** that demonstrates how to expose an existing FastAPI application as an **MCP (Model Context Protocol) Server**.

The project simulates a logistics company that manages customer orders, shipments, warehouses, and package tracking. A FastAPI backend exposes REST APIs, while an MCP server wraps those APIs so AI assistants (such as Claude Desktop, Cursor, or MCP Inspector) can interact with the logistics system using standardized MCP tools.

This project demonstrates how to build AI-ready applications without modifying existing business logic.


# 🏗️ Architecture

![Architecture diagram](docs/architecture.png)

The MCP server does **not** access the database directly. Instead, it communicates with the FastAPI backend over HTTP, demonstrating how existing applications can be made AI-accessible without changing their internal architecture.


# ✨ Features

- FastAPI REST backend
- SQLite database using SQLAlchemy ORM
- MCP Server built using FastMCP
- AI-accessible logistics operations
- Sample logistics dataset
- Layered architecture (API → Services → Database)
- MCP Tools
- MCP Resources
- MCP Prompt


# 📁 Project Structure

```text
logistics-mcp-server/
│
├── app/
│ ├── api/                      # FastAPI routes
│ ├── database/                 # Database connection, models and seed script
│ ├── mcp_server/
│ │ ├── api_client.py           # Calls FastAPI endpoints
│ │ ├── server_v1.py            # MCP Server using official MCP SDK
│ │ └── server_v2.py            # MCP Server using FastMCP package
│ ├── schemas/                  # Pydantic models
│ └── services/                 # Business logic
│
├── client/
│ └── streamlit_app.py          # Streamlit client application connecting to MCP Server
│
├── requirements.txt
├── .env
└── README.md

```


# 🛠 MCP Tools

The following tools are exposed through the MCP Server.

| Tool | Description |
|------|-------------|
| get_order_details | Retrieve complete order information |
| search_orders | Search orders by customer, city or status |
| track_package | Retrieve shipment tracking details |
| cancel_order | Cancel an order |
| reschedule_delivery | Update the estimated delivery date |
| find_warehouse | Find warehouse serving a city |


# 📄 MCP Resources

The project also exposes static resources.

| Resource | Description |
|----------|-------------|
| company://shipping-policy | Company shipping policy |
| company://supported-couriers | Supported courier partners |
| company://warehouse-locations | Warehouse locations |


# 💬 MCP Prompt

| Prompt | Description |
|---------|-------------|
| summarize_tracking | Generates a professional customer-friendly shipment update from tracking information |


# 🗄 Database

The project uses **SQLite** for simplicity.

Main entities:

- Customer
- Order
- OrderItem
- Shipment
- TrackingHistory
- Warehouse


# 🚀 Running the Project

## 1. Clone the repository

```bash
git clone <repository-url>
cd logistics-mcp-server
```


## 2. Create a virtual environment

Windows

```bash
python -m venv .venv
.venv\Scripts\activate
```

Linux / macOS

```bash
python3 -m venv .venv
source .venv/bin/activate
```

---

## 3. Install dependencies

```bash
pip install -r requirements.txt
```


## 4. Create the database

```bash
python -m app.database.create_db
```


## 5. Seed sample data

```bash
python -m app.database.seed
```

This populates the database with sample:

- Customers
- Orders
- Shipments
- Tracking history
- Warehouses


## 6. Start the FastAPI server

```bash
uvicorn app.api.main:app --reload
```

Swagger UI

```
http://localhost:8000/docs
```

## 7. Start the MCP Server

ShipSmart MCP Server contains two implementations:

### MCP Server Implementations

| File | Implementation | Import Used | Usage |
|---|---|---|---|
| `server_v1.py` | Official MCP SDK FastMCP | `from mcp.server.fastmcp import FastMCP` | Basic MCP server implementation |
| `server_v2.py` | FastMCP package | `from fastmcp import FastMCP` | Used with the Streamlit + Gemini client |

The Streamlit application connects to **`server_v2.py`**.


## Running servers

To start the MCP server:

```bash
python -m app.mcp_server.server_v1
#OR
python -m app.mcp_server.server_v2
```

## Testing MCP Tools

You can test the MCP servers independently using the MCP Inspector:

```bash
mcp dev app/mcp_server/sever_v1.py
#OR
fastmcp dev inspector app/mcp_server/server_v2.py
```
<img width="1881" height="907" alt="mcp_inspector" src="https://github.com/user-attachments/assets/4f171960-c399-4cea-8f2e-b60566f4c18f" />


The MCP Inspector allows you to test the available tools and verify that the server is exposing the expected MCP functionality.


## 8. Start the Streamlit Client

The Streamlit application acts as an MCP client and connects to `server_v2.py`.

Run:

```bash
streamlit run client/streamlit_app.py
```
<img width="1256" height="816" alt="streamlit_app" src="https://github.com/user-attachments/assets/2b5fda46-9b26-4fa9-ade5-73bbbd12d94c" />

# 💡 Example Questions for an AI Assistant

Once connected to the MCP Server, an AI assistant can answer questions like:

- Where is my order ORD-1001?
- Show me the tracking history for ORD-1002.
- Cancel order ORD-1003.
- Reschedule delivery for ORD-1004 to next Monday.
- Find the warehouse responsible for Pune.
- Search all delivered orders for Alice.

# 🧠 Why MCP?

Without MCP, every AI application would need custom integration code for each backend service.

MCP provides a standard interface that allows AI assistants to discover and invoke application capabilities through Tools, Resources, and Prompts.

This enables existing business applications to become AI-accessible with minimal changes.

# 🛠 Tech Stack

- Python
- FastAPI
- SQLAlchemy
- SQLite
- Pydantic
- HTTPX
- FastMCP (Model Context Protocol)
- Faker