# MCP Server

A lightweight Model Context Protocol (MCP) server built from scratch in Python, implementing Streamable HTTP, JSON-RPC 2.0, and Server-Sent Events (SSE).

The server allows MCP-compatible clients to discover and execute tools through a standardized interface without relying on an MCP SDK.

## Features

- MCP protocol version `2026-07-28`
- Streamable HTTP transport
- JSON-RPC 2.0 request and response handling
- Tool discovery and execution
- Real-time timer notifications using SSE
- Input validation and error handling
- Automated unit and HTTP integration tests

## Available Tools

| Tool | Description |
|------|-------------|
| `today` | Returns the current date in a specified format. |
| `weekday` | Returns the weekday for a given date. |
| `timer` | Runs a timer with progress updates every 10 seconds. |
| `calculator` | Evaluates mathematical expressions using `bc`. |

## Project Structure

```text
src/
├── __init__.py
├── server.py
├── protocol.py
└── tools.py

tests/
├── test_protocol.py
├── test_server.py
└── test_tools.py
```

- **server.py** — Handles HTTP requests, responses, and SSE streaming.
- **protocol.py** — Implements MCP discovery, JSON-RPC, and tool validation.
- **tools.py** — Contains the implementations of the four tools.
- **tests/** — Contains unit and HTTP integration tests.

## Getting Started

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- [just](https://just.systems/)
- Node.js (for MCP Inspector)
- `bc` calculator

### Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/EfazAhmed/CSEE-4119-Project-1-MCP-Server.git
cd CSEE-4119-Project-1-MCP-Server
uv sync
```

### Running the Server

Start the MCP server:

```bash
just run
```

The server runs locally at:

```text
http://localhost:8000/mcp
```

### Testing with MCP Inspector

In a separate terminal, launch MCP Inspector:

```bash
just inspector
```

Connect using:

- **Transport:** Streamable HTTP
- **Protocol Era:** Modern (`2026-07-28`)
- **Server URL:** `http://localhost:8000/mcp`

Use the **Tools** tab to discover and execute the available tools.

## Testing

Run the automated test suite:

```bash
just test
```

The project includes 20 automated tests covering:

- Tool functionality and input validation
- MCP discovery and JSON-RPC handling
- HTTP requests and responses
- SSE timer notifications

## Development

| Command | Description |
|---------|-------------|
| `just run` | Start the MCP server |
| `just inspector` | Launch MCP Inspector |
| `just test` | Run automated tests |
| `just lint` | Check code with Ruff |
| `just lint --fix` | Automatically fix supported lint errors |
| `just format` | Format Python code |

## License

This project is licensed under the [MIT License](LICENSE).