# MCP Server Boilerplate
**A TypeScript template for building Model Context Protocol (MCP) servers.**
This boilerplate provides a solid foundation for creating MCP servers that can integrate with Cursor, Claude, and other AI assistants. It includes best practices, example tools, proper error handling, and a well-structured TypeScript codebase.
## What This Template Provides
- **Complete MCP Server Setup**: Ready-to-use server with proper configuration
- **Example Tools**: Demonstrates common MCP tool patterns and best practices
- **TypeScript Integration**: Full type safety with Zod validation
- **Error Handling**: Robust error handling patterns throughout
- **Testing Setup**: Vitest configuration for unit testing
- **Development Workflow**: Build, watch, and inspection scripts
## Key Features
**Type-Safe Development**: Built with TypeScript and Zod for runtime validation and compile-time safety.
**Modular Architecture**: Well-organized code structure with separate modules for tools, utilities, and types.
**Example Patterns**: Demonstrates data retrieval, search, analytics, and system utilities.
**Development Ready**: Includes hot reload, testing, and MCP inspector integration.
## Quick Start
### 1. Clone and Setup
```bash
git clone https://github.com/vltansky/mcp-boilerplate.git
cd mcp-server-boilerplate
yarn install
yarn build
```
### 2. Configure MCP Client
Add to your `.cursor/mcp.json` or other MCP client configuration:
```json
{
"mcpServers": {
"my-custom-server": {
"command": "node",
"args": ["path/to/your/dist/server.js"]
}
}
}
```
### 3. Start Developing
```bash
yarn watch # Start development with hot reload
```
### 4. Test Your Tools
Use the MCP inspector to test your tools:
```bash
yarn inspector
```
## Task Master - Getting Started
Once you have your MCP server running, here's how to get the most out of the Task Master workflow:
### Next Steps for Project Success
1. **Configure AI models** (if needed) and add API keys to `.env`
- Models: Use `task-master models` commands
- Keys: Add provider API keys to .env (or inside the MCP config file i.e. .cursor/mcp.json)
2. **Discuss your idea with AI** and ask for a PRD using example_prd.txt, and save it to scripts/PRD.txt
3. **Ask Cursor Agent** (or run CLI) to parse your PRD and generate initial tasks:
- MCP Tool: parse_prd | CLI: task-master parse-prd scripts/prd.txt
4. **Ask Cursor to analyze the complexity** of the tasks in your PRD using research
- MCP Tool: analyze_project_complexity | CLI: task-master analyze-complexity
5. **Ask Cursor to expand all of your tasks** using the complexity analysis
6. **Ask Cursor to begin working** on the next task
7. **Add new tasks anytime** using the add-task command or MCP tool
8. **Ask Cursor to set the status** of one or many tasks/subtasks at a time. Use the task id from the task lists.
9. **Ask Cursor to update all tasks** from a specific task id based on new learnings or pivots in your project.
10. **Ship it!**
## Example Tools Included
### Core Tools
- **`get_data`** - Demonstrates data retrieval with filtering and pagination
- **`search_items`** - Shows search functionality with multiple search types (exact, fuzzy, regex)
- **`analyze_data`** - Example analytics tool with chart data generation
- **`get_system_info`** - System utilities for date, timezone, and version information
### Tool Patterns Demonstrated
- **Parameter Validation**: Using Zod schemas for type-safe input validation
- **Error Handling**: Consistent error handling and user-friendly error messages
- **Async Operations**: Proper async/await patterns with timeout simulation
- **Response Formatting**: JSON and compact-JSON output modes
- **Type Safety**: Full TypeScript integration with proper type inference
## Project Structure
```
src/
├── server.ts # Main MCP server setup and tool registration
├── tools/
│ └── example-tools.ts # Example tool implementations
└── utils/
└── formatter.ts # Response formatting utilities
docs/ # Documentation files
package.json # Dependencies and scripts
tsconfig.json # TypeScript configuration
vitest.config.ts # Testing configuration
```
## Customizing for Your Use Case
### 1. Replace Example Tools
Edit `src/tools/example-tools.ts` to implement your business logic:
```typescript
export async function yourCustomOperation(input: YourInputType): Promise<YourOutputType> {
// Your implementation here
return result;
}
```
### 2. Update Server Registration
Modify `src/server.ts` to register your tools:
```typescript
server.tool(
'your_tool_name',
'Description of what your tool does',
{
// Zod schema for parameters
param1: z.string().describe('Parameter description'),
param2: z.number().optional().default(10)
},
async (input) => {
// Tool implementation
const result = await yourCustomOperation(input);
return {
content: [{
type: 'text',
text: formatResponse(result, input.outputMode)
}]
};
}
);
```
### 3. Add Your Data Layer
Create modules for your specific data sources:
```
src/
├── database/ # Database connections and queries
├── external-apis/ # External API integrations
├── file-system/ # File system operations
└── your-domain/ # Your business logic
```
## Development Workflow
### Available Scripts
- `yarn build` - Compile TypeScript to JavaScript
- `yarn watch` - Watch mode for development
- `yarn start` - Run the compiled server
- `yarn test` - Run unit tests
- `yarn test:ui` - Run tests with UI
- `yarn inspector` - Start MCP inspector for testing tools
### Testing Your Tools
1. **Unit Tests**: Add tests alongside your tool files
2. **Integration Testing**: Use the MCP inspector to test tool behavior
3. **Manual Testing**: Test with actual MCP clients like Cursor
### Adding Dependencies
For data sources, add appropriate dependencies:
```bash
# Database
yarn add sqlite3 @types/sqlite3
# HTTP requests
yarn add axios
# File processing
yarn add fs-extra @types/fs-extra
# Date handling
yarn add date-fns
```
## MCP Best Practices
### Tool Design
- **Clear Descriptions**: Write detailed tool descriptions for AI assistants
- **Parameter Validation**: Use Zod for runtime validation
- **Error Handling**: Provide meaningful error messages
- **Output Consistency**: Use consistent response formats
### Performance
- **Async Operations**: Use async/await for all I/O operations
- **Resource Management**: Clean up resources properly
- **Caching**: Implement caching for expensive operations
- **Pagination**: Support pagination for large datasets
### Security
- **Input Validation**: Validate all inputs with Zod
- **Error Messages**: Don't expose sensitive information in errors
- **Resource Limits**: Implement appropriate limits and timeouts
- **Authentication**: Add authentication if accessing sensitive data
## Common Use Cases
### File System Tools
- File search and indexing
- Content analysis
- Code parsing and analysis
### Database Integration
- Query interfaces
- Data analysis and reporting
- Schema exploration
### External API Integration
- API wrapping and simplification
- Data aggregation from multiple sources
- Rate limiting and caching
### Development Tools
- Code generation
- Testing utilities
- Build and deployment helpers
## Contributing
1. Fork this repository
2. Create your feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
MIT License - feel free to use this template for your own projects.
## Resources
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Zod Documentation](https://zod.dev/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
---
**Ready to build your MCP server?** Start by customizing the example tools in `src/tools/example-tools.ts` and updating the server registration in `src/server.ts`.
