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.json with your server name and details
- Update src/index.ts server name and version
- Replace example tools in src/tools/ with your implementations

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.

Mearman/mcp-ai