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:

.
├── 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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Call calculator

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "arguments": {
      "operation": "multiply",
      "a": 5,
      "b": 10
    }
  }
}

📖 Resources

List Resources

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/list"
}

Read system_status

Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": {
    "uri": "utility://system/status"
  }
}

📝 Prompts

List Prompts

Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "prompts/list"
}

Get math_tutor Prompt

Request:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "prompts/get",
  "params": {
    "name": "math_tutor",
    "arguments": {
      "topic": "algebra"
    }
  }
}

🛠 Development

Setup

npm install

Running the Server

npm start

Running Tests

npm test

🤖 Using the Custom Client

We've included a built-in client example so you can see how to connect programmatically:

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:

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.