Skip to main content
Glama

MCP Template

by Mearman
npmGitHub
TypeScript
5
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

  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.

This server cannot be installed

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

How are these scores calculated?

A TypeScript template for building Model Context Protocol servers that provides a structured foundation with automated tools, testing, and synchronization capabilities.

  1. Build Status
    1. Release Status
      1. Features
        1. Quick Start
          1. Using as Template
          2. Development
        2. Template Structure
          1. Writing MCP Tools
            1. Basic Tool Example
            2. Register Tools in MCP Server
          2. Template Synchronization
            1. How It Works
            2. Template Marker
            3. Customizing Sync Behavior
          3. CI/CD Pipeline
            1. Continuous Integration
            2. Automated Release
            3. Commit Message Format
          4. Contributing
            1. License
              1. Related Projects

                Related MCP Servers

                • MCP Server Starter

                  StevenStavrakis
                  A
                  security
                  A
                  license
                  A
                  quality
                  A production-ready template for creating Model Context Protocol servers with TypeScript, providing tools for efficient testing, development, and deployment.
                  Last updated -
                  1
                  16
                  12
                  JavaScript
                  MIT License

                • MCP Server Starter

                  coinselor
                  A
                  security
                  A
                  license
                  A
                  quality
                  A production-ready template for building Model Context Protocol servers in TypeScript, offering fast development with Bun, Biome linting, and automated version management.
                  Last updated -
                  1
                  16
                  JavaScript
                  MIT License

                • MCP Server Template

                  stevennevins
                  A
                  security
                  F
                  license
                  A
                  quality
                  A TypeScript-based template for developing Model Context Protocol servers with features like dependency injection and service-based architecture, facilitating the creation and integration of custom data processing tools.
                  Last updated -
                  1
                  2
                  TypeScript

                • MCP Server Starter

                  GreatAuk
                  A
                  security
                  A
                  license
                  A
                  quality
                  A TypeScript-based template for building Model Context Protocol servers, featuring fast testing, automated version management, and a clean structure for MCP tool implementations.
                  Last updated -
                  1
                  16
                  2
                  TypeScript
                  MIT License

                View all related MCP servers

                New MCP Servers

                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