mcp server boilerplate

A boilerplate server implementation for the Model Context Protocol (MCP), built with TypeScript and Express.

Table of Contents

• Overview
• Project Structure
• Getting Started
• Prerequisites
• Installation
• Environment Variables
• Running the Server
• HTTP Server
• Stdio Mode
• Resources
• Tools
• Prompts
• Extending the Server
• Adding Resources
• Adding Tools
• Adding Prompts
• Testing and Debugging
• License

Overview

This project implements a server that follows the Model Context Protocol (MCP), which allows applications to provide context for LLMs in a standardized way. It includes:

• A fully configured MCP server with HTTP and stdio transport options
• Sample resources, tools, and prompts to demonstrate key functionality
• TypeScript support for type safety and better developer experience
• Express integration for the HTTP transport layer

Project Structure

mcp-server-boilerplate/
├── .env                  # Environment variables
├── .env.example          # Example environment variables
├── .gitignore            # Git ignore file
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── src/
│   ├── index.ts          # Main HTTP server entry point
│   ├── stdio.ts          # Stdio server entry point
│   ├── resources/        # MCP resources
│   │   ├── index.ts      # Resource registration
│   │   ├── infoResource.ts # Static info resource
│   │   └── greetingResource.ts # Dynamic greeting resource
│   ├── tools/            # MCP tools
│   │   ├── index.ts      # Tool registration
│   │   ├── calculatorTool.ts # Sample calculator tool
│   │   └── timestampTool.ts # Sample timestamp tool
│   └── prompts/          # MCP prompts
│       ├── index.ts      # Prompt registration
│       ├── greetingPrompt.ts # Sample greeting prompt
│       └── analyzeDataPrompt.ts # Sample data analysis prompt
└── dist/                 # Compiled JavaScript output

Getting Started

Prerequisites

• Node.js (v18 or later)
• npm or yarn

Installation

Clone the repository and install dependencies:

git clone https://github.com/yourusername/mcp-server-boilerplate.git
cd mcp-server-boilerplate
npm install

Environment Variables

Copy the example environment file and modify as needed:

cp .env.example .env

Available environment variables:

• PORT: The port for the HTTP server (default: 3000)
• NODE_ENV: Environment mode (development, production)
• OAuth settings (if needed)

Running the Server

HTTP Server

Build and start the HTTP server:

npm run build
npm start

For development with auto-restart:

npm run dev

The server will be available at http://localhost:3000/mcp (or the port specified in your .env file).

Stdio Mode

To run the server in stdio mode (for command-line tools):

npm run start:stdio

For development with auto-restart:

npm run dev:stdio

Resources

The boilerplate includes these example resources:

1. Static Info Resource: info://server

2. Provides basic information about the server

3. Dynamic Greeting Resource: greeting://{name}

4. Generates a personalized greeting with the provided name parameter

To access resources:

• Through the MCP protocol
• Using an MCP client library

Tools

The boilerplate includes these example tools:

1. Calculator: Performs basic arithmetic operations

2. Parameters:

   • operation: Operation to perform (add, subtract, multiply, divide)
   • a: First number
   • b: Second number

3. Timestamp: Provides the current time in various formats

4. Parameters:
   • format: Output format (iso, unix, readable)

Prompts

The boilerplate includes these example prompts:

1. Greeting: Creates a personalized greeting prompt

2. Parameters:

   • name: Name to greet
   • formal: Whether to use formal greeting style (optional)

3. Analyze Data: Creates a prompt for data analysis

4. Parameters:
   • data: The data to analyze
   • format: Data format (json, csv, text)
   • instructions: Additional analysis instructions (optional)

Extending the Server

Adding Resources

To add a new resource:

1. Create a new file in src/resources/ (e.g., myResource.ts)
2. Implement your resource handler
3. Register it in src/resources/index.ts

Example:

// myResource.ts
import { McpServer } from  @modelcontextprotocol/sdk/server/mcp.js ;

export function myResource(server: McpServer): void {
  server.resource( my-resource ,  my-resource://path , async uri => ({
    contents: [
      {
        uri: uri.href,
        text:  My resource content ,
      },
    ],
  }));
}

// Then add to resources/index.ts
import { myResource } from  ./myResource.js ;

export function registerResources(server: McpServer): void {
  // ...existing resources
  myResource(server);
}

Adding Tools

To add a new tool:

1. Create a new file in src/tools/ (e.g., myTool.ts)
2. Implement your tool handler
3. Register it in src/tools/index.ts

Example:

// myTool.ts
import { McpServer } from  @modelcontextprotocol/sdk/server/mcp.js ;
import { z } from  zod ;

export function myTool(server: McpServer): void {
  server.tool( my-tool , { param: z.string() }, async ({ param }) => ({
    content: [
      {
        type:  text ,
        text: `Processed: ${param}`,
      },
    ],
  }));
}

// Then add to tools/index.ts
import { myTool } from  ./myTool.js ;

export function registerTools(server: McpServer): void {
  // ...existing tools
  myTool(server);
}

Adding Prompts

To add a new prompt:

1. Create a new file in src/prompts/ (e.g., myPrompt.ts)
2. Implement your prompt handler
3. Register it in src/prompts/index.ts

Example:

// myPrompt.ts
import { McpServer } from  @modelcontextprotocol/sdk/server/mcp.js ;
import { z } from  zod ;

export function myPrompt(server: McpServer): void {
  server.prompt( my-prompt , { topic: z.string() }, ({ topic }) => ({
    messages: [
      {
        role:  user ,
        content: {
          type:  text ,
          text: `Please explain ${topic} in simple terms.`,
        },
      },
    ],
  }));
}

// Then add to prompts/index.ts
import { myPrompt } from  ./myPrompt.js ;

export function registerPrompts(server: McpServer): void {
  // ...existing prompts
  myPrompt(server);
}

Testing and Debugging

To test your MCP server, you can use:

• The MCP Inspector tool
• MCP client libraries
• Direct HTTP requests (for debugging)

License

This project is licensed under the MIT License - see the LICENSE file for details.