ylcnfrht/calculator-mcp-server

Calculator MCP Server

A tiny Model Context Protocol (MCP) server that exposes basic calculator tools. Built with TypeScript and Zod. Easy to extend.

Quick Start

npm install
npm run build && npm start

Server runs over stdio and logs:

Calculator MCP server is running...

Development

npm run dev

Inspector

Interactive testing with MCP Inspector:

npm run build
npm run inspector

This starts the server under the inspector so you can list tools and call them.

Tools

• add: adds two numbers
• subtract: subtracts two numbers
• multiply: multiplies two numbers
• divide: divides two numbers (throws on division by zero)

List tools request (MCP):

{
  "method": "tools/list",
  "params": {}
}

Call example:

{
  "method": "tools/call",
  "params": {
    "name": "add",
    "arguments": { "a": 3, "b": 5 }
  }
}

Response example:

{
  "content": [{ "type": "text", "text": "3 + 5 = 8" }]
}

Validation & Schemas

• Input validation is done with Zod directly in src/index.ts.
• inputSchema returned by tools/list is a JSON Schema object that MCP clients can use.

Two-number input schema (Zod):

const twoNumberInput = z.object({ a: z.number(), b: z.number() });

JSON Schema (for MCP):

const twoNumberJsonSchema = {
  type: 'object',
  properties: {
    a: { type: 'number', description: 'First number' },
    b: { type: 'number', description: 'Second number' },
  },
  required: ['a', 'b'],
} as const;

Project Structure

src/
  index.ts   # server setup, tool definitions, validation, and handlers
dist/
  index.js   # build output

Extending (add a new tool)

All tools are defined in src/index.ts under the tools map. To add one:

1. Add or reuse a Zod schema and corresponding JSON Schema.
2. Implement an execute function.
3. Register the tool in the tools map with description, inputSchema, validate, execute, and format.

Scripts

From package.json:

• build: compile TypeScript to dist/
• start: run node dist/index.js
• dev: tsc && node dist/index.js
• inspector: npx @modelcontextprotocol/inspector node dist/index.js

Troubleshooting

• "Cannot find module …/x.js": ensure ESM paths include .js extensions (tsconfig uses NodeNext).
• "Division by zero error!": divide throws when b === 0.
• "Invalid arguments …": Zod validation failed; ensure numeric a and b.

License

MIT