# MCP Server with FastAPI (Python)

A hands-on implementation of a **Model Context Protocol (MCP)** server built with Python using the official MCP SDK and FastAPI/Starlette.

## What is MCP?

**Model Context Protocol (MCP)** is an open standard that enables AI assistants (like Claude, Kiro, Cursor) to connect with external tools, data sources, and APIs through a unified interface — similar to how USB-C standardized device connectivity.

```
┌─────────────┐         ┌─────────────┐         ┌──────────────┐
│  AI Client  │  ←───→  │  MCP Server │  ←───→  │  Your Tools/ │
│(Claude/Kiro)│  JSON   │  (This Repo)│         │  Data/APIs   │
└─────────────┘         └─────────────┘         └──────────────┘
```

## Features

- **Tools**: Functions that AI clients can discover and call
  - `greet` — Returns a greeting for a given name
  - `add_numbers` — Adds two numbers and returns the result
  - `get_current_time` — Returns the current date and time
- **SSE Transport**: Server-Sent Events based communication (HTTP)
- **Test Client**: A Python client that connects to the server and calls all tools

## Tech Stack

- Python 3.13+
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (v1.9)
- FastAPI / Starlette
- Uvicorn (ASGI server)
- SSE (Server-Sent Events) transport

## Getting Started

### Prerequisites

- Python 3.10+
- pip

### Installation

```bash
git clone https://github.com/MuhammadIshaqSkd/mcp-fastapi-tutorial.git
cd mcp-fastapi-tutorial

# Create virtual environment
python -m venv venv

# Activate (Windows)
.\venv\Scripts\activate

# Activate (macOS/Linux)
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### Running the Server

```bash
python server.py
```

Server starts on `http://127.0.0.1:8080` with SSE endpoint at `/sse`.

### Testing with the Client

Open a second terminal (keep the server running):

```bash
python test_client.py
```

**Expected output:**
```
==================================================
MCP Client - Connecting to server...
==================================================

✅ Connection successful!

📋 Available Tools:
------------------------------
  🔧 greet: Greet someone by name and return a greeting message.
  🔧 add_numbers: Return the sum of two numbers.
  🔧 get_current_time: Return the current date and time.

🎯 Calling 'greet' tool...
  Result: Assalam-o-Alaikum, Mishaq! MCP Server se aapko salam!

🎯 Calling 'add_numbers' tool...
  Result: 15 + 27 = 42

🎯 Calling 'get_current_time' tool...
  Result: Current time: 2026-06-22 18:15:09

==================================================
🎉 All tools called successfully!
==================================================
```

## Project Structure

```
mcp-fastapi-tutorial/
├── server.py           # MCP Server — registers and exposes tools via SSE
├── test_client.py      # MCP Client — connects to server, lists & calls tools
├── requirements.txt    # Python dependencies
└── README.md
```

## How It Works

1. **Server** registers tools using `@mcp.tool()` decorator
2. **Client** connects via SSE to `/sse` endpoint
3. Client calls `list_tools()` to discover available tools
4. Client calls `call_tool("tool_name", {args})` to execute a tool
5. Server executes the function and returns the result

## Key Concepts Demonstrated

| Concept | Description |
|---------|-------------|
| Tool Registration | Using `@mcp.tool()` to expose Python functions as MCP tools |
| SSE Transport | HTTP-based bidirectional communication via Server-Sent Events |
| Client Session | Initializing and managing MCP client-server sessions |
| Tool Discovery | Clients dynamically discover available tools at runtime |
| Tool Execution | Remote procedure call pattern over the MCP protocol |

## Roadmap

- [x] Basic MCP server with tools
- [ ] Add Resources (context/data providers for AI)
- [ ] Add Prompts (reusable prompt templates)
- [ ] Streamable HTTP transport
- [ ] Authentication & authorization
- [ ] Deploy to cloud

## Resources

- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [FastMCP Documentation](https://gofastmcp.com/)

## License

MIT