MCP Server Boilerplate

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

Overview
Project Structure
Getting Started
Running the Server
- HTTP Server
- Stdio Mode
Resources
Tools
Prompts
Extending the Server
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:

Static Info Resource: info://server
- Provides basic information about the server
Dynamic Greeting Resource: greeting://{name}
- 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:

Calculator: Performs basic arithmetic operations
- Parameters:
  - operation: Operation to perform (add, subtract, multiply, divide)
  - a: First number
  - b: Second number
Timestamp: Provides the current time in various formats
- Parameters:
  - format: Output format (iso, unix, readable)

Prompts

The boilerplate includes these example prompts:

Greeting: Creates a personalized greeting prompt
- Parameters:
  - name: Name to greet
  - formal: Whether to use formal greeting style (optional)
Analyze Data: Creates a prompt for data analysis
- 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:

Create a new file in src/resources/ (e.g., myResource.ts)
Implement your resource handler
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:

Create a new file in src/tools/ (e.g., myTool.ts)
Implement your tool handler
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:

Create a new file in src/prompts/ (e.g., myPrompt.ts)
Implement your prompt handler
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.

MCP Server Boilerplate

Integrations