MCP Template

TypeScript template for building MCP (Model Context Protocol) servers with automated template synchronization.

MCP Server Ecosystem

Repository	CI	Release	NPM	Coverage
mcp-template Base template repository			Template
mcp-wayback-machine Internet Archive integration
mcp-openalex Academic knowledge graph
mcp-mcp Template with examples
mcp-ollama Ollama model integration

Quick Start

# Use this template on GitHub, then:
git clone https://github.com/yourusername/your-mcp-server.git
cd your-mcp-server
yarn install
yarn dev

Core Features

• TypeScript + ES Modules - Modern development with full type safety
• Automated Testing - Vitest with coverage reporting and CI integration
• Code Quality - Biome linting/formatting with pre-commit hooks
• Template Sync - Automatic updates to all derived repositories
• Semantic Releases - Automated versioning and NPM publishing
• Repository Management - Scripts for managing the entire ecosystem

Development Commands

yarn dev          # Hot reload development server
yarn test         # Run tests with coverage
yarn test:watch   # Watch mode for development
yarn build        # Compile TypeScript
yarn lint         # Check code quality
yarn lint:fix     # Auto-fix linting issues

Creating MCP Tools

import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';

// Define tool schema
export const MyToolSchema = z.object({
  input: z.string().describe('Input parameter'),
});

// Create tool definition
export const myToolSchema = {
  name: 'my_tool',
  description: 'Tool description',
  inputSchema: zodToJsonSchema(MyToolSchema),
};

// Implement tool
export async function myTool(input: unknown) {
  const { input: userInput } = MyToolSchema.parse(input);
  return {
    content: [{ type: 'text', text: `Processed: ${userInput}` }],
  };
}

Register in src/index.ts:

// List tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [myToolSchema],
}));

// Handle execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  switch (request.params.name) {
    case 'my_tool': return await myTool(request.params.arguments);
    default: throw new Error(`Unknown tool: ${request.params.name}`);
  }
});

Template Synchronization

Automatically syncs template updates to all derived repositories:

• Auto-discovery of repositories created from this template
• Selective sync of configuration files and shared utilities
• Pull request workflow for reviewing changes
• Version tracking across the ecosystem

Configure in .github/template-sync-config.yml:

sync_patterns:
  - "tsconfig.json"
  - ".github/workflows/**"
  - "src/utils/**"

ignore_patterns:
  - "src/tools/**"
  - "README.md"

Repository Management

./mcp-manager.sh                      # Interactive management menu
./scripts/check-ci-status.sh          # Check CI across all repos
./scripts/trigger-template-sync.sh    # Force template sync
./scripts/run-all-tests.sh           # Test all repositories

CI/CD

• Quality Gates: Linting, type checking, testing on multiple Node.js versions
• Semantic Releases: Automatic versioning from conventional commits
• NPM Publishing: Automated package publishing with provenance
• GitHub Releases: Generated releases with changelogs

Project Structure

mcp-template/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/                # Tool implementations
│   └── utils/                # Shared utilities
├── .github/workflows/        # CI/CD pipelines
├── scripts/                  # Management tools
└── .template-marker          # Template identification

License

CC BY-NC-SA 4.0

Resources

• MCP TypeScript SDK
• MCP Specification
• MCP Servers