MCP Template
Build Status
Release Status
A TypeScript template for building MCP (Model Context Protocol) servers with automated template synchronization to downstream repositories.
Features
- 🚀 TypeScript with ES Modules - Modern JavaScript with full type safety
- 🧪 Comprehensive Testing - Vitest with coverage reporting
- 🔧 Code Quality - Biome for linting and formatting
- 📦 Automated Publishing - Semantic versioning and NPM publishing
- 🔄 Template Synchronization - Automatic updates to derived repositories
- 🛠️ Development Tools - Hot reload, watch mode, and CLI support
- 📋 Git Hooks - Automated linting and commit message validation
Quick Start
Using as Template
- Use this template on GitHub to create your new MCP server repository
- Clone your new repository:
git clone https://github.com/yourusername/your-mcp-server.git cd your-mcp-server - Install dependencies:
yarn install - Update configuration:
- Edit
package.jsonwith your server name and details - Update
src/index.tsserver name and version - Replace example tools in
src/tools/with your implementations
- Edit
Development
# Start development server with hot reload
yarn dev
# Run tests
yarn test
# Run tests in watch mode
yarn test:watch
# Build the project
yarn build
# Run linting
yarn lint
# Auto-fix linting issues
yarn lint:fix
Template Structure
mcp-template/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── cli.ts # CLI entry point (optional)
│ ├── tools/
│ │ ├── example.ts # Example tool implementation
│ │ ├── example.test.ts # Example tool tests
│ │ └── fetch-example.ts # HTTP fetch example tool
│ └── utils/
│ ├── validation.ts # Common validation schemas
│ └── fetch.ts # HTTP utilities with caching
├── .github/
│ └── workflows/
│ ├── ci.yml # Continuous Integration
│ ├── semantic-release.yml # Automated versioning
│ └── template-sync-*.yml # Template synchronization
├── .template-marker # Template tracking file
├── .template-version # Template version tracking
└── shared/ # Shared utilities for template sync
Writing MCP Tools
Basic Tool Example
import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';
// Define input schema
export const MyToolSchema = z.object({
input: z.string().describe('Input parameter'),
count: z.number().optional().default(1).describe('Number of iterations'),
});
export type MyToolInput = z.infer<typeof MyToolSchema>;
// Export tool schema for MCP registration
export const myToolSchema = {
name: 'my_tool',
description: 'Description of what this tool does',
inputSchema: zodToJsonSchema(MyToolSchema),
};
// Tool implementation
export async function myTool(input: unknown) {
const validated = MyToolSchema.parse(input);
// Your tool logic here
const result = `Processed: ${validated.input}`;
return {
content: [
{
type: 'text',
text: result,
},
],
};
}
Register Tools in MCP Server
// In src/index.ts
import { myToolSchema, myTool } from './tools/my-tool.js';
// Register in ListToolsRequestSchema handler
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
myToolSchema,
// ... other tools
],
}));
// Register in CallToolRequestSchema handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
switch (name) {
case 'my_tool':
return await myTool(args);
// ... other tools
default:
throw new Error(`Unknown tool: ${name}`);
}
});
Template Synchronization
This template includes an automated synchronization system that keeps derived repositories up to date:
How It Works
- Template Changes: When you update the template repository
- Automatic Discovery: GitHub Actions discovers all repositories created from this template
- Sync Dispatch: Template changes are automatically synchronized to derived repos
- Pull Request Creation: Changes are proposed via pull requests for review
Template Marker
The .template-marker file identifies repositories created from this template:
template_repository: mcp-template
template_version: 1.0.0
created_from_template: true
sync_enabled: true
Customizing Sync Behavior
Edit .github/template-sync-config.yml to control what gets synchronized:
sync_patterns:
- "tsconfig.json"
- "biome.json"
- "vitest.config.ts"
- ".github/workflows/**"
- "src/utils/validation*"
# Add patterns for files to sync
ignore_patterns:
- "src/tools/**" # Don't sync tool implementations
- "README.md" # Keep custom README
# Add patterns for files to ignore
CI/CD Pipeline
Continuous Integration
- Code Quality: Linting, formatting, and type checking
- Testing: Unit tests with coverage reporting
- Build Verification: Ensures TypeScript compiles successfully
- Multi-Node Testing: Tests on Node.js 18, 20, and 22
Automated Release
- Semantic Versioning: Automatic version bumping based on commit messages
- Changelog Generation: Automatically generated from commit history
- NPM Publishing: Automatic package publishing on release
- GitHub Releases: Automatic GitHub release creation
Commit Message Format
Follow Conventional Commits:
feat: add new tool for data processing
fix: resolve validation error in example tool
docs: update README with usage examples
chore: update dependencies
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'feat: add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
License
This project is licensed under the CC BY-NC-SA 4.0 license.