MCP-Server-CalculatorPOC by shreyasmurthy24 - MCP Server

MCP Hello World Server

A proof-of-concept Model Context Protocol (MCP) server that provides basic mathematical operations and a hello-world greeting. This server demonstrates how to build an MCP-compatible tool server that can be integrated with MCP clients.

Features

Dual Interface Support: Both MCP stdio protocol and HTTP REST API
Mathematical Tools: Add, subtract, multiply, and divide operations
Hello World Tool: Simple greeting functionality
Type-safe Implementation: Proper input validation and error handling
Comprehensive Testing: TypeScript test suite included

Available Tools

Tool	Description	Parameters
`hello-world`	Returns a simple greeting	None
`add`	Add two numbers	`a` (number), `b` (number)
`subtract`	Subtract second number from first	`a` (number), `b` (number)
`multiply`	Multiply two numbers	`a` (number), `b` (number)
`divide`	Divide first number by second	`a` (number), `b` (number)

Getting Started

Prerequisites

Node.js (v18 or higher)
npm or yarn

Installation

Clone or download this project
Install dependencies:
```
npm install
```

Running the Server

MCP Protocol (stdio)

npm run start:mcp
# or
node server.js --stdio

HTTP Server

npm start
# or
node server.js

The HTTP server will start on http://localhost:3000

Usage

HTTP API

List Available Tools

GET http://localhost:3000/tools

Execute a Tool

POST http://localhost:3000/tools/add
Content-Type: application/json

{
  "a": 5,
  "b": 3
}

Example Responses

// GET /tools
{
  "tools": ["hello-world", "add", "subtract", "multiply", "divide"]
}

// POST /tools/add with {"a": 5, "b": 3}
{
  "result": "5 + 3 = 8"
}

// POST /tools/hello-world
{
  "result": "Hello, world!"
}

MCP Protocol

The server also supports the standard MCP protocol over stdio for integration with MCP clients:

List Tools Request

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

Call Tool Request

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

Testing

Run the comprehensive test suite:

npm test

This will execute the TypeScript test client that:

✅ Tests tool listing functionality
✅ Tests tool execution
✅ Tests error handling for unknown tools
✅ Provides detailed logging and cleanup

Test Output Example

🧪 TypeScript MCP Hello-World Test Client

✅ Server started successfully!

=== 📋 Test 1: List Available Tools ===
📤 Sending tools/list request: {...}
📥 Server: {...}

=== 👋 Test 2: Call Hello-World Tool ===
📤 Sending tools/call request: {...}
📥 Server: {...}

=== ❌ Test 3: Call Unknown Tool (Error Test) ===
📤 Sending tools/call request: {...}
📥 Server: {...}

🎉 All tests completed successfully!

Error Handling

The server includes robust error handling:

Type Validation: Ensures numeric parameters are actually numbers
Division by Zero: Prevents division by zero operations
Unknown Tools: Returns proper error messages for non-existent tools
JSON-RPC Compliance: Follows JSON-RPC 2.0 specification for error responses

Project Structure

├── server.js              # Main server implementation
├── test-hello-world.ts     # Comprehensive test suite
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md             # This file

Development

Scripts

npm start - Start HTTP server
npm run start:mcp - Start MCP stdio server
npm test - Run test suite
npm run test:build - Build and run tests

Adding New Tools

Add tool definition to availableMCPTools array
Implement tool logic in executeMCPTool function
Update tests in test-hello-world.ts
Update this README

Contributing

Fork the project
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

ISC License