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

# Clone and install
git clone <your-repo-url>
cd mcp-boilerplate
npm install

# Build and run
npm run build
npm start

📋 Requirements

Node.js 18.x or higher
npm or yarn package manager

🏗️ Project Structure

mcp-boilerplate/
├── src/
│   ├── index.ts              # Server entry point
│   ├── server.ts             # MCP server setup
│   ├── tools/                # Tool implementations
│   │   ├── index.ts          # Tool registry
│   │   └── calculator.ts     # Addition tool
│   ├── schemas/              # Zod validation schemas
│   │   ├── index.ts          # Schema exports
│   │   └── calculator.ts     # Calculator schemas
│   ├── types/                # TypeScript definitions
│   │   ├── index.ts          # Type exports
│   │   └── tools.ts          # Tool interfaces
│   └── utils/                # Utility functions
│       ├── index.ts          # Utility exports
│       ├── errors.ts         # Error handling
│       └── validation.ts     # Validation helpers
├── dist/                     # Compiled JavaScript (generated)
├── docs/                     # Documentation and research
└── package.json              # Dependencies and scripts

🛠️ 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

Build the project:
```
npm run build
```

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"
      }
    }
  }
}

Restart Claude Desktop
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:

{
  "name": "calculator_add",
  "arguments": { "a": 5, "b": 3 }
}

🔄 Extending the Boilerplate

Adding a New Tool

Create the schema in src/schemas/:

export const MyToolSchema = z.object({
  param1: z.string().min(1),
}).strict();

export type MyToolInput = z.infer<typeof MyToolSchema>;

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' }] };
  },
};

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

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

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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

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