MCP Server TypeScript Boilerplate
A clean, reusable TypeScript boilerplate for building Model Context Protocol (MCP) servers.
Features
- Clean Architecture: Modular design with clear separation of concerns
- Type Safety: Full TypeScript support with strict type checking
- Easy Configuration: Simple configuration object for tools and resources
- Built-in Examples: Sample tools and resources to get you started
- Error Handling: Comprehensive error handling with meaningful messages
- Graceful Shutdown: Proper cleanup on process termination
- Development Ready: Hot reload and debugging support
Quick Start
Installation
npm install
Development
npm run dev
Build
npm run build
npm start
Usage
Adding Custom Tools
Tools are functions that can be called by MCP clients. Add them to the tools array in your server configuration:
const customTool: ToolHandler = {
name: "my_custom_tool",
description: "Description of what this tool does",
inputSchema: {
type: "object",
properties: {
param1: {
type: "string",
description: "Parameter description",
},
},
required: ["param1"],
},
handler: async (args: { param1: string }) => {
// Your tool logic here
return `Processed: ${args.param1}`;
},
};
Adding Custom Resources
Resources are static or dynamic content that can be read by MCP clients:
const customResource: ResourceHandler = {
uri: "custom://my-resource",
name: "My Custom Resource",
description: "Description of this resource",
mimeType: "application/json",
handler: async () => {
// Your resource logic here
return JSON.stringify({ data: "example" });
},
};
Configuration
Modify the serverConfig object to customize your server:
const serverConfig: ServerConfig = {
name: "my-mcp-server",
version: "1.0.0",
description: "My custom MCP server",
tools: [customTool, ...exampleTools],
resources: [customResource, ...exampleResources],
};
Project Structure
├── src/
│ └── index.ts # Main server implementation
├── dist/ # Compiled JavaScript (generated)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # This file
Example Tools
The boilerplate includes several example tools:
- echo: Echo back input messages
- add_numbers: Add two numbers together
- current_time: Get current time in various formats
Example Resources
- info://server/status: Server status and runtime information
- info://server/config: Server configuration details
Development
Scripts
npm run dev- Start development server with hot reloadnpm run build- Build for productionnpm start- Start production servernpm run clean- Clean build artifactsnpm run lint- Run ESLintnpm run lint:fix- Fix ESLint issues
Testing Your Server
You can test your MCP server using any MCP client. The server communicates via stdio, so you can also test it directly:
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node dist/index.js
Deployment
As a Standalone Application
npm run build
node dist/index.js
As a Library
You can also use this as a library in other projects:
import { MCPServer, ToolHandler, ResourceHandler } from './src/index.js';
const myTools: ToolHandler[] = [
// Your custom tools
];
const server = new MCPServer({
name: "my-server",
version: "1.0.0",
tools: myTools,
resources: [],
});
await server.start();
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - see LICENSE file for details
Support
For issues and questions:
- Create an issue on GitHub
- Check the MCP documentation
- Review the example implementations
Changelog
1.0.0
- Initial release
- Basic tool and resource support
- TypeScript boilerplate
- Example implementations