# MCP Orders Server — Practice Project

A small **practice project** to learn how the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) works. It exposes an in-memory “orders” API as MCP tools so an MCP client (e.g. Cursor) can create and list orders via the protocol.

## What’s in this repo

- **`app/`** — Core domain: Pydantic models (`Order`, `CreateOrderRequest`) and service functions (`create_order`, `list_orders`) that keep orders in memory.
- **`mcp_server/`** — MCP server built with [FastMCP](https://github.com/jlowin/fastmcp): exposes two tools that call into `app`.
- **`mcp.json`** — Example MCP config for Cursor (or copy into `.cursor/mcp.json` or `~/.cursor/mcp.json`).

## How MCP fits in

1. **MCP server** = process that exposes **tools** (and optionally resources, prompts). Here it’s `mcp_server/server.py`, which runs over **stdio** and talks JSON-RPC.
2. **MCP client** = app that discovers and calls those tools. Cursor is an MCP client; when you add this server in Cursor’s MCP settings, Cursor spawns the server and sends tool calls to it.
3. **Tools** = named functions with typed arguments. This server exposes:
   - **`create_order_tool(product_id, quantity)`** — creates an order and returns it.
   - **`list_orders_tool()`** — returns all orders.

So “how MCP works” here: Cursor sends a tool call (e.g. create order with product_id 1, quantity 255) → MCP server receives it → server calls `create_order` → returns the new order as the tool result → Cursor shows it to you.

## Setup

```bash
cd /path/to/MCP
python -m venv venv
source venv/bin/activate   # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt
```

## Run the MCP server locally (stdio)

From the project root:

```bash
python mcp_server/server.py
```

The server runs over stdio and waits for JSON-RPC messages. It will exit quickly if nothing is connected; that’s expected. To use it, run it via an MCP client (e.g. Cursor).

## Use with Cursor

1. **Config** — Cursor reads MCP config from:
   - **Project:** `.cursor/mcp.json`
   - **User:** `~/.cursor/mcp.json`

2. **Example config** (adjust paths if needed):

   ```json
   {
     "mcpServers": {
       "orders-server": {
         "command": "/path/to/MCP/venv/bin/python",
         "args": ["mcp_server/server.py"],
         "cwd": "/path/to/MCP"
       }
     }
   }
   ```

   `cwd` must be the project root so the `app` package can be imported.

3. Restart Cursor (or reload MCP) so it picks up the config and starts the server.

4. In Cursor you can then call the **create order** and **list orders** tools (e.g. from the MCP / Composer tools UI).

## Project layout

```
MCP/
├── app/
│   ├── schema.py      # Order, CreateOrderRequest (Pydantic)
│   ├── service.py     # create_order(), list_orders() — in-memory store
│   └── main.py        # optional FastAPI app (not required for MCP)
├── mcp_server/
│   └── server.py      # FastMCP server, create_order_tool, list_orders_tool
├── mcp.json           # example MCP config for Cursor
├── requirements.txt
└── README.md
```

## Tech used

- **Python 3**
- **[MCP](https://pypi.org/project/mcp/)** — Model Context Protocol SDK
- **FastMCP** — from the MCP package, for defining tools and running the stdio server
- **Pydantic** — request/response models

This repo is for learning: minimal persistence (in-memory only), no database, no auth — just enough to see how an MCP server exposes tools and how a client calls them.