Skip to main content
Glama
enesjakozh
cds-id

MCP Server Boilerplate

by cds-id
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

MCP Server Boilerplate

MCP TypeScript SDK NPM Version MIT License

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

Table of Contents

Related MCP server: MCP Server Scaffold

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

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

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

Available Tools

2 tools
calculateD
ParametersJSON Schema
NameRequiredDescriptionDefault
operationYes
aYes
bYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

timestampD
ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoiso

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observedcalculate
    • First observedtimestamp
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

D1.7/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: 'calculate' suggests mathematical or computational operations, while 'timestamp' implies time-related functions. With no overlapping descriptions, there is no ambiguity between them.

Naming Consistency5/5

Both tool names follow a consistent pattern of using single, descriptive nouns in lowercase. There are no deviations in style or convention across the set.

Tool Count2/5

With only 2 tools, the server feels thin and under-scoped for a 'boilerplate' purpose, which typically implies a foundational or example set. This minimal count limits functionality and utility.

Completeness1/5

The server lacks descriptions, making it impossible to infer a clear domain or assess coverage. Without context, it appears severely incomplete, with no indication of what operations are supported or how they fit together.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Server Scaffold

    vjouenne76
    F
    license
    B
    quality
    D
    maintenance
    A basic starter project for building Model Context Protocol (MCP) servers that enables standardized interactions between AI systems and various data sources through secure, controlled tool implementations.
    2
    -

  • TypeScript MCP Server

    chuljung
    F
    license
    Not graded
    quality
    D
    maintenance
    A starter project designed to quickly build and deploy Model Context Protocol (MCP) servers using the TypeScript SDK and Zod for schema validation. It features example implementations for tools and resources, providing a solid foundation for custom MCP development and integration.
    -

  • Basic MCP Server

    Habib0x0
    F
    license
    Not graded
    quality
    D
    maintenance
    A minimal Model Context Protocol (MCP) server demonstrating the implementation of tools, resources, and prompts. It serves as a starter template built with the Smithery SDK for developing custom integrations.
    -