Skip to main content
Glama

MCP Boilerplate

by jakreymyers

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

  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:

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

πŸ”„ 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

-
security - not tested
A
license - permissive license
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A minimal, production-ready MCP server with a simple addition calculator tool that demonstrates integration with the Model Context Protocol.

  1. ✨ Features
    1. πŸš€ Quick Start
      1. πŸ“‹ Requirements
        1. πŸ—οΈ Project Structure
          1. πŸ› οΈ Available Scripts
            1. πŸ”§ Claude Desktop Integration
              1. πŸ§ͺ Testing
                1. βœ… Successful Operations
                2. βœ… Error Handling
              2. πŸ›‘οΈ Security Features
                1. πŸ“Š Tool Reference
                  1. calculator_add
                2. πŸ”„ Extending the Boilerplate
                  1. Adding a New Tool
                3. πŸ› Troubleshooting
                  1. Server Won't Start
                  2. Tool Not Found
                  3. Validation Errors
                4. πŸ“ License
                  1. 🀝 Contributing

                    Related MCP Servers

                    • A
                      security
                      F
                      license
                      A
                      quality
                      A simple Model Context Protocol server that provides standardized tool functionality, currently implementing a basic calculator for adding two numbers together.
                    • A
                      security
                      F
                      license
                      A
                      quality
                      A simple and extendable MCP server that currently provides basic addition functionality and can be easily extended by defining new tools with docstrings.
                      Last updated -
                      4
                    • A
                      security
                      F
                      license
                      A
                      quality
                      A comprehensive learning project providing hands-on experience with Model Context Protocol (MCP) server development, featuring calculator and text utility tools for integration with Claude Desktop.
                      Last updated -
                      1
                      • Apple
                      • Linux
                    • -
                      security
                      F
                      license
                      -
                      quality
                      A containerized MCP (Model Context Protocol) server that provides a simple calculator tool for adding two numbers, deployable to Kubernetes/EKS environments.
                      Last updated -
                      6

                    View all related MCP servers

                    MCP directory API

                    We provide all the information about MCP servers via our MCP API.

                    curl -X GET 'https://glama.ai/api/mcp/v1/servers/jakreymyers/mcp-boilerplate'

                    If you have feedback or need assistance with the MCP directory API, please join our Discord server