# 🚀 Simple MCP Demo

A comprehensive demonstration of a **Model Context Protocol (MCP)** server implemented in Python. This project showcases how to build a unified server that supports multiple transport mechanisms: **Standard I/O (stdio)**, **Server-Sent Events (SSE)**, and **Streamable HTTP**.

---

## 🛠️ Features

- **Multi-Transport Server**: One server, three ways to connect.
- **`add_numbers` Tool**: A functional example of a tool discovery and execution flow.
- **Reference Clients**: Dedicated Python scripts for each transport type.
- **Inspector Ready**: Fully compatible with the official MCP Inspector.

---

## 📂 Project Structure

- `server.py`: The core MCP server containing tool logic and transport routing.
- `client_stdio.py`: Client for local subprocess communication (pipes).
- `client_sse.py`: Client for web-based event streaming.
- `client_http.py`: Client for stateful session-based HTTP streaming.
- `DOCUMENTATION.md`: Detailed functional and technical specifications.
- `requirements.txt`: Project dependencies.

---

## 🚀 Getting Started

### 1. Installation
Clone the repo and install the required packages:
```bash
pip install -r requirements.txt
```

### 2. Run with MCP Inspector (Recommended)
The easiest way to test the server is using the official tool inspector:
```bash
npx @modelcontextprotocol/inspector python server.py
```

### 3. Run Reference Clients

#### Standard I/O (stdio)
```bash
python client_stdio.py
```

#### Server-Sent Events (SSE)
Terminal 1 (Start Server):
```bash
python server.py --transport sse
```
Terminal 2 (Run Client):
```bash
python client_sse.py
```

#### Streamable HTTP
Terminal 1 (Start Server):
```bash
python server.py --transport http
```
Terminal 2 (Run Client):
```bash
python client_http.py
```

---

## 📈 Protocol Flow

1. **Initialize**: Client and Server exchange capabilities.
2. **List Tools**: Client discovers the `add_numbers` tool.
3. **Call Tool**: Client sends parameters (`a`, `b`) and receives the sum.

---

## 📝 Technical Details
For a deeper dive into the architecture, flow diagrams, and transport implementation details, see [DOCUMENTATION.md](./DOCUMENTATION.md).

---

Built with ❤️ using the [Model Context Protocol](https://modelcontextprotocol.io/)