Boilerplate MCP Server

A foundation for developing custom Model Context Protocol (MCP) servers in TypeScript. Provides a complete layered architecture pattern, working example tools, and developer infrastructure to connect AI assistants with external APIs and data sources.

Features

• Multiple Transport Support: STDIO and Streamable HTTP transports
• Production-Ready Architecture: Clean separation between CLI, tools, controllers, and services
• Type Safety: Built with TypeScript for improved developer experience
• Working Example: Fully implemented IP address lookup tools
• Testing Framework: Ready-to-use testing infrastructure with coverage reporting
• Complete Developer Tooling: Pre-configured ESLint, Prettier, TypeScript

What is MCP?

Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This boilerplate implements the MCP specification with a clean, layered architecture that can be extended to build custom MCP servers for any API or data source.

Prerequisites

• Node.js (>=18.x): Download
• Git: For version control

Quick Start

1# Clone the repository
2git clone https://github.com/aashari/boilerplate-mcp-server.git
3cd boilerplate-mcp-server
4
5# Install dependencies
6npm install
7
8# Run in different modes:
9
10# 1. CLI Mode - Execute commands directly
11npm run cli -- get-ip-details 8.8.8.8
12
13# 2. STDIO Transport - For direct AI assistant integration
14npm run mcp:stdio
15
16# 3. HTTP Transport - For web-based integrations (default)
17npm run mcp:http
18
19# 4. Development with MCP Inspector
20npm run mcp:inspect

Transport Modes

STDIO Transport

• Traditional subprocess communication via stdin/stdout
• Ideal for local AI assistant integrations
• Run with: TRANSPORT_MODE=stdio npm run build && node dist/index.js

Streamable HTTP Transport (Default)

• Modern HTTP-based transport with Server-Sent Events (SSE)
• Supports multiple concurrent connections
• Runs on port 3000 by default (configurable via PORT env var)
• Endpoint: http://localhost:3000/mcp
• Health check: http://localhost:3000/
• Run with: TRANSPORT_MODE=http npm run build && node dist/index.js

Architecture Overview

src/
├── cli/              # Command-line interfaces
│   ├── index.ts      # CLI entry point
│   └── *.cli.ts      # Feature-specific CLI modules
├── controllers/      # Business logic
│   └── *.controller.ts  # Feature controllers
├── services/         # External API interactions
│   └── *.service.ts  # Service modules
├── tools/            # MCP tool definitions
│   ├── *.tool.ts     # Tool implementations
│   └── *.types.ts    # Tool argument schemas
├── resources/        # MCP resource definitions
│   └── *.resource.ts # Resource implementations
├── types/            # Type definitions
│   └── common.types.ts # Shared type definitions
├── utils/            # Shared utilities
│   ├── logger.util.ts  # Structured logging
│   ├── error.util.ts   # Error handling
│   └── ...           # Other utility modules
└── index.ts          # Server entry point

Layered Architecture

The boilerplate follows a clean, layered architecture that promotes maintainability and clear separation of concerns:

1. CLI Layer (src/cli/*.cli.ts)

• Purpose: Command-line interfaces that parse arguments and call controllers
• Pattern: Use commander for argument parsing, call controllers, handle errors with handleCliError
• Naming: <feature>.cli.ts

2. Tools Layer (src/tools/*.tool.ts)

• Purpose: MCP tool definitions exposed to AI assistants
• Pattern: Use zod for schema validation, call controllers, format responses for MCP
• Naming: <feature>.tool.ts with types in <feature>.types.ts

3. Controllers Layer (src/controllers/*.controller.ts)

• Purpose: Business logic orchestration, error handling, response formatting
• Pattern: Return standardized ControllerResponse objects, throw errors with context
• Naming: <feature>.controller.ts with optional <feature>.formatter.ts

4. Services Layer (src/services/*.service.ts)

• Purpose: External API interactions and data handling
• Pattern: Pure API calls with minimal logic, return raw data
• Naming: <feature>.service.ts or vendor.<vendor>.<feature>.service.ts

5. Utils Layer (src/utils/*.util.ts)

• Purpose: Shared functionality across the application
• Key Utils: Logging, error handling, formatting, configuration

Developer Guide

Development Scripts

1# Development
2npm run build               # Build TypeScript
3npm run clean               # Clean build artifacts
4
5# Running different modes
6npm run cli -- [command]    # Run CLI commands
7npm run mcp:stdio          # Run with STDIO transport
8npm run mcp:http           # Run with HTTP transport (default)
9npm run mcp:inspect        # Run with MCP Inspector
10
11# Development modes
12npm run dev:stdio          # STDIO with inspector
13npm run dev:http           # HTTP in development mode
14
15# Testing
16npm test                    # Run all tests
17npm run test:coverage       # Generate coverage report
18
19# Code Quality
20npm run lint                # Run ESLint
21npm run format              # Format with Prettier

Environment Variables

• TRANSPORT_MODE: Set to stdio or http (default: http)
• PORT: HTTP server port (default: 3000)
• DEBUG: Enable debug logging (default: false)
• IPAPI_API_TOKEN: API token for ip-api.com (optional)

Debugging Tools

• MCP Inspector: Visual tool for testing your MCP tools

  • Run server with npm run mcp:inspect
  • Open the URL shown in terminal
  • Test your tools interactively

• Debug Logging: Enable with DEBUG=true environment variable

1{
2  "boilerplate": {
3    "environments": {
4      "DEBUG": "true",
5      "TRANSPORT_MODE": "http",
6      "PORT": "3000"
7    }
8  }
9}

Building Custom Tools

1// src/services/example.service.ts
2import { Logger } from '../utils/logger.util.js';
3
4const logger = Logger.forContext('services/example.service.ts');
5
6export async function getData(param: string): Promise<any> {
7	logger.debug('Getting data', { param });
8	// API interaction code here
9	return { result: 'example data' };
10}

1// src/controllers/example.controller.ts
2import { Logger } from '../utils/logger.util.js';
3import * as exampleService from '../services/example.service.js';
4import { formatMarkdown } from '../utils/formatter.util.js';
5import { handleControllerError } from '../utils/error-handler.util.js';
6import { ControllerResponse } from '../types/common.types.js';
7
8const logger = Logger.forContext('controllers/example.controller.ts');
9
10export interface GetDataOptions {
11	param?: string;
12}
13
14export async function getData(
15	options: GetDataOptions = {},
16): Promise<ControllerResponse> {
17	try {
18		logger.debug('Getting data with options', options);
19
20		const data = await exampleService.getData(options.param || 'default');
21
22		const content = formatMarkdown(data);
23
24		return { content };
25	} catch (error) {
26		throw handleControllerError(error, {
27			entityType: 'ExampleData',
28			operation: 'getData',
29			source: 'controllers/example.controller.ts',
30		});
31	}
32}

1// src/tools/example.tool.ts
2import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3import { z } from 'zod';
4import { Logger } from '../utils/logger.util.js';
5import { formatErrorForMcpTool } from '../utils/error.util.js';
6import * as exampleController from '../controllers/example.controller.js';
7
8const logger = Logger.forContext('tools/example.tool.ts');
9
10const GetDataArgs = z.object({
11	param: z.string().optional().describe('Optional parameter'),
12});
13
14type GetDataArgsType = z.infer<typeof GetDataArgs>;
15
16async function handleGetData(args: GetDataArgsType) {
17	try {
18		logger.debug('Tool get_data called', args);
19
20		const result = await exampleController.getData({
21			param: args.param,
22		});
23
24		return {
25			content: [{ type: 'text' as const, text: result.content }],
26		};
27	} catch (error) {
28		logger.error('Tool get_data failed', error);
29		return formatErrorForMcpTool(error);
30	}
31}
32
33export function register(server: McpServer) {
34	server.tool(
35		'get_data',
36		`Gets data from the example API, optionally using \`param\`.
37Use this to fetch example data. Returns formatted data as Markdown.`,
38		GetDataArgs.shape,
39		handleGetData,
40	);
41}

1// src/cli/example.cli.ts
2import { program } from 'commander';
3import { Logger } from '../utils/logger.util.js';
4import * as exampleController from '../controllers/example.controller.js';
5import { handleCliError } from '../utils/error-handler.util.js';
6
7const logger = Logger.forContext('cli/example.cli.ts');
8
9program
10	.command('get-data')
11	.description('Get example data')
12	.option('--param <value>', 'Optional parameter')
13	.action(async (options) => {
14		try {
15			logger.debug('CLI get-data called', options);
16
17			const result = await exampleController.getData({
18				param: options.param,
19			});
20
21			console.log(result.content);
22		} catch (error) {
23			handleCliError(error);
24		}
25	});

1// In src/cli/index.ts
2import '../cli/example.cli.js';
3
4// In src/index.ts (for the tool)
5import exampleTool from './tools/example.tool.js';
6// Then in registerTools function:
7exampleTool.register(server);

Publishing Your MCP Server

1. Update package.json with your details:

   1{
   2  "name": "your-mcp-server-name",
   3  "version": "1.0.0",
   4  "description": "Your custom MCP server",
   5  "author": "Your Name",
   6  // Other fields...
   7}

2. Update README.md with your tool documentation

3. Build: npm run build

4. Test: npm run mcp:stdio and npm run mcp:http

5. Publish: npm publish

Testing Best Practices

• Unit Tests: Test utils and pure functions in isolation
• Controller Tests: Test business logic with mocked service calls
• Integration Tests: Test CLI with real dependencies
• Coverage Goal: Aim for >80% test coverage

License

ISC License

Resources

• MCP Specification
• Official MCP Documentation
• TypeScript Documentation