MCP Boilerplate

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