Skip to main content
Glama

MCP Template

by Mearman
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
1

MCP Template

npm version License: CC BY-NC-SA 4.0

Build Status

CI Build Tests

Related MCP server: MCP Server Template

Release Status

Release Template Sync

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

  1. Use this template on GitHub to create your new MCP server repository

  2. Clone your new repository:

    git clone https://github.com/yourusername/your-mcp-server.git cd your-mcp-server

  3. Install dependencies:

    yarn install

  4. 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

  1. Template Changes: When you update the template repository

  2. Automatic Discovery: GitHub Actions discovers all repositories created from this template

  3. Sync Dispatch: Template changes are automatically synchronized to derived repos

  4. 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

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/amazing-feature

  3. Commit changes: git commit -m 'feat: add amazing feature'

  4. Push to branch: git push origin feature/amazing-feature

  5. Open a Pull Request

License

This project is licensed under the CC BY-NC-SA 4.0 license.

Related Projects

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Mearman/mcp-ai'

If you have feedback or need assistance with the MCP directory API, please join our Discord server