# Simple Calculator MCP Server

A simple **Model Context Protocol (MCP)** server built with **FastMCP** that demonstrates how to create MCP **Tools** and **Resources**. This project exposes basic arithmetic operations, random number generation, and server metadata over the HTTP transport.

---

## Features

- ➕ Add two integers
- 🎲 Generate a random number within a specified range
- 📄 Expose server information as an MCP Resource
- 🌐 HTTP transport support

---

## Project Structure

```text
SimpleCalculatorMCPServer/
│
├── main.py
├── pyproject.toml
├── README.md
└── .venv/
```

---

## Requirements

- Python 3.10+
- uv
- FastMCP

---

## Installation

### 1. Clone the repository

```bash
git clone <repository-url>
cd SimpleCalculatorMCPServer
```

### 2. Create a virtual environment

```bash
uv venv
```

### 3. Activate the environment

Linux/macOS

```bash
source .venv/bin/activate
```

Windows

```powershell
.venv\Scripts\activate
```

### 4. Install FastMCP

```bash
uv add fastmcp
```

---

## Running the Server

Start the MCP server:

```bash
python main.py
```

or

```bash
uv run python main.py
```

The server will start on:

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

---

# Available Tools

## 1. add

Adds two integers.

### Parameters

| Name | Type | Description |
|------|------|-------------|
| a | int | First integer |
| b | int | Second integer |

### Example

Input

```json
{
  "a": 15,
  "b": 25
}
```

Output

```json
40
```

---

## 2. random_number

Generates a random integer within a given range.

### Parameters

| Name | Type | Default |
|------|------|---------|
| min_val | int | 1 |
| max_val | int | 100 |

### Example

Input

```json
{
  "min_val": 10,
  "max_val": 50
}
```

Output

```json
27
```

---

# Available Resource

## info://server

Returns metadata about the MCP server.

Example Response

```json
{
  "name": "Simple Calculator Server",
  "Version": "1.0.0",
  "Description": "A basic MCP server with math tools and random number generation.",
  "tools": [
    "add",
    "random_number"
  ],
  "authors": "BinishaChapagain"
}
```

---

## Transport

The server runs using the **HTTP transport**.

Configuration:

```python
mcp.run(
    transport="http",
    host="0.0.0.0",
    port=8000
)
```

---

## Testing

You can test the server using:

- FastMCP Inspector
- OpenCode
- Any MCP-compatible client

Available endpoints:

- Tool: `add`
- Tool: `random_number`
- Resource: `info://server`

---

## Technologies Used

- Python
- FastMCP
- Model Context Protocol (MCP)

---

## Learning Objectives

This project demonstrates how to:

- Create an MCP server using FastMCP.
- Register MCP tools.
- Register MCP resources.
- Expose an MCP server over HTTP.
- Interact with the server using an MCP client.