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

Getting Started

Prerequisites

• Node.js (v18 or later)

• npm or yarn

Installation

Clone the repository and install dependencies:

Environment Variables

Copy the example environment file and modify as needed:

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:

For development with auto-restart:

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):

For development with auto-restart:

Resources

The boilerplate includes these example resources:

1. Static Info Resource: info://server

   • Provides basic information about the server

2. 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:

1. Calculator: Performs basic arithmetic operations

   • Parameters:

     • operation: Operation to perform (add, subtract, multiply, divide)

     • a: First number

     • b: Second number

2. Timestamp: Provides the current time in various formats

   • Parameters:

     • format: Output format (iso, unix, readable)

Prompts

The boilerplate includes these example prompts:

1. Greeting: Creates a personalized greeting prompt

   • Parameters:

     • name: Name to greet

     • formal: Whether to use formal greeting style (optional)

2. 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:

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:

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:

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:

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.