MCP Boilerplate

A minimal, production-ready MCP (Model Context Protocol) server boilerplate with a simple addition calculator tool. Built with TypeScript, Zod validation, and comprehensive error handling.

✨ Features

• Simple Calculator Tool: Addition tool demonstrating MCP integration

• Type Safety: Full TypeScript support with strict type checking

• Input Validation: Zod schemas with security-first validation

• Error Handling: Comprehensive error handling with McpError

• Production Ready: Proper process management and graceful shutdown

• Extensible: Clean architecture for adding more tools

🚀 Quick Start

📋 Requirements

• Node.js 18.x or higher

• npm or yarn package manager

🏗️ Project Structure

🛠️ Available Scripts

• npm run build - Compile TypeScript to JavaScript

• npm run dev - Watch mode compilation

• npm start - Start the MCP server

• npm run lint - Run ESLint

• npm run lint:fix - Fix linting issues

• npm run format - Format code with Prettier

• npm run clean - Remove compiled files

🔧 Claude Desktop Integration

1. Build the project:

   npm run build

2. Add to your Claude Desktop configuration (claude_desktop_config.json):

   { "mcpServers": { "mcp-boilerplate": { "command": "node", "args": ["/absolute/path/to/mcp-boilerplate/dist/index.js"], "env": { "NODE_ENV": "production" } } } }

3. Restart Claude Desktop

4. Test the calculator tool:

   • "Add 5 and 3"

   • "What is 1.5 + 2.7?"

   • "Calculate -2 plus 7"

🧪 Testing

The server has been tested with the following scenarios:

✅ Successful Operations

• Basic Addition: 5 + 3 = 8

• Negative Numbers: -2 + 7 = 5

• Decimal Numbers: 1.5 + 2.7 = 4.2

• Zero Values: 0 + 5 = 5

✅ Error Handling

• Invalid Input: String inputs return validation errors

• Missing Parameters: Missing 'a' or 'b' parameters return required field errors

• Out of Bounds: Numbers outside safe range are rejected

🛡️ Security Features

• Input Validation: Comprehensive Zod schemas prevent malicious input

• Number Safety: Finite number validation prevents NaN/Infinity injection

• Bounds Checking: Reasonable limits prevent DoS attacks

• Error Sanitization: Production errors don't expose internal details

📊 Tool Reference

calculator_add

Adds two numbers together with comprehensive validation.

Parameters:

• a (number): First number to add (-10,000,000,000 to 10,000,000,000)

• b (number): Second number to add (-10,000,000,000 to 10,000,000,000)

Returns:

• Success: { content: [{ type: 'text', text: 'a + b = result' }] }

• Error: MCP error with validation details

Example:

🔄 Extending the Boilerplate

Adding a New Tool

1. Create the schema in src/schemas/:

   export const MyToolSchema = z.object({ param1: z.string().min(1), }).strict(); export type MyToolInput = z.infer<typeof MyToolSchema>;

2. Implement the tool in src/tools/:

   export const myTool: ToolDefinition<MyToolInput> = { name: 'my_tool', description: 'Description of what the tool does', inputSchema: MyToolSchema, execute: async (params) => { // Tool implementation return { content: [{ type: 'text', text: 'Result' }] }; }, };

3. Register the tool in src/tools/index.ts:

   export const tools = { calculator_add: calculatorTool, my_tool: myTool, // Add your tool here } as const;

4. Rebuild and test:

   npm run build npm start

🐛 Troubleshooting

Server Won't Start

• Check Node.js version (requires 18.x+)

• Run npm run build to compile TypeScript

• Check for port conflicts

Tool Not Found

• Verify tool is registered in src/tools/index.ts

• Rebuild with npm run build

• Check tool name matches exactly

Validation Errors

• Check input parameter types match schema

• Verify required fields are provided

• Check number bounds (-1e10 to 1e10)

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

Built with TypeScript, MCP SDK v1.17.0, and Zod validation