# Utility MCP Server

A fully featured Model Context Protocol (MCP) server providing utility tools, resources, and prompts. Built with TypeScript and the modern MCP SDK.

## 📁 Project Structure

The project is organized for scalability and readability:

```text
.
├── index.ts              # Entry point: Initializes server and registers modules
├── src/
│   ├── tools.ts          # Tool handlers (Arithmetic, Randomness, Sampling)
│   ├── prompts.ts        # Prompt templates (Math Tutoring)
│   └── resources.ts      # Resource definitions (System Status)
├── tests/
│   └── utility.test.ts   # Comprehensive unit tests
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── jest.config.js        # Testing configuration
```

---

## 🚀 Features

### 1. Tools
- **`random_number`**: Generates a random integer within a specified range.
- **`calculator`**: Performs basic arithmetic (`add`, `subtract`, `multiply`, `divide`).
- **`suggest_arithmetic_task`**: Demonstrates **LLM Sampling** by requesting the client/LLM to generate a creative math problem.

### 2. Resources
- **`system_status`** (`utility://system/status`): Provides a real-time status update of the server's health and feature count.

### 3. Prompts
- **`math_tutor`**: A template that guides the LLM to act as a math teacher, optionally focusing on a specific topic.

---

## 📡 Calling the API (Postman / JSON-RPC)

Model Context Protocol uses **JSON-RPC 2.0**. While this server currently runs over **stdio** (standard input/output), you can interact with it using these message formats if you expose it via an HTTP/SSE bridge or use a debugger.

### 🛠 Tools

#### List Tools
**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

#### Call `calculator`
**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "arguments": {
      "operation": "multiply",
      "a": 5,
      "b": 10
    }
  }
}
```

---

### 📖 Resources

#### List Resources
**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/list"
}
```

#### Read `system_status`
**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": {
    "uri": "utility://system/status"
  }
}
```

---

### 📝 Prompts

#### List Prompts
**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "prompts/list"
}
```

#### Get `math_tutor` Prompt
**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "prompts/get",
  "params": {
    "name": "math_tutor",
    "arguments": {
      "topic": "algebra"
    }
  }
}
```

---

## 🛠 Development

### Setup
```bash
npm install
```

### Running the Server
```bash
npm start
```

### Running Tests
```bash
npm test
```

### 🤖 Using the Custom Client
We've included a built-in client example so you can see how to connect programmatically:
```bash
npm run client
```
This script will:
1. Spawn the server as a child process.
2. Connect via Stdio.
3. Automatically demonstrate listing tools, calling the calculator, and reading resources.

### 🔍 Testing with MCP Inspector
To interact with the server visually:
```bash
npx @modelcontextprotocol/inspector npx tsx index.ts
```

> [!IMPORTANT]
> This server uses the **Stdio Transport**. It communicates via `stdin` and `stdout`. For Postman to work via HTTP, an SSE (Server-Sent Events) transport layer would need to be added to the server configuration.