Skip to main content
Glama
igun997

Boilerplate MCP Server

by igun997
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

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.

NPM Version Build Status TypeScript License: ISC

Why Use This Boilerplate?

  • Production-Ready Architecture: Follows the same pattern used in published MCP servers, with clean separation between CLI, tools, controllers, and services

  • Type Safety: Built with TypeScript for improved developer experience, code quality, and maintainability

  • Working Example: Includes fully implemented tools demonstrating the complete pattern from CLI to API integration

  • Testing Framework: Ready-to-use testing infrastructure for unit and CLI integration tests, with coverage reporting

  • Complete Developer Tooling: Pre-configured ESLint, Prettier, TypeScript, and CI/CD workflows

Related MCP server: WithSeismic MCP

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

# Clone the repository git clone https://github.com/aashari/boilerplate-mcp-server.git cd boilerplate-mcp-server # Install dependencies npm install # Start development server npm run dev:server # Try the example tool npm run dev:cli -- get-ip-details 8.8.8.8

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 ├── 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

# Start server in dev mode with hot-reload & inspector npm run dev:server # Run CLI commands in development npm run dev:cli -- [command] [args] # Build the project npm run build # Production server npm start npm run start:server # Production CLI npm run start:cli -- [command] [args] # Testing npm test # Run all tests npm test -- src/path/to/test.ts # Run specific tests npm run test:coverage # Generate coverage report # Code Quality npm run lint # Run ESLint npm run format # Format with Prettier npm run typecheck # Check TypeScript types

Debugging Tools

  • MCP Inspector: Visual tool for testing your MCP tools

    • Run server with npm run dev:server

    • Open http://localhost:5173 in your browser

  • Server Logs: Enable with DEBUG=true npm run dev:server or in config

Create ~/.mcp/configs.json:

{ "boilerplate": { "environments": { "DEBUG": "true", "ANY_OTHER_CONFIG": "value" } } }

Building Custom Tools

1. Define Service Layer

Create a new service in src/services/ to interact with your external API:

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

2. Create Controller

Add a controller in src/controllers/ to handle business logic:

// src/controllers/example.controller.ts import { Logger } from '../utils/logger.util.js'; import * as exampleService from '../services/example.service.js'; import { formatMarkdown } from '../utils/formatter.util.js'; import { handleControllerError } from '../utils/error-handler.util.js'; import { ControllerResponse } from '../types/common.types.js'; const logger = Logger.forContext('controllers/example.controller.ts'); export interface GetDataOptions { param?: string; } export async function getData( options: GetDataOptions = {}, ): Promise<ControllerResponse> { try { logger.debug('Getting data with options', options); const data = await exampleService.getData(options.param || 'default'); const content = formatMarkdown(data); return { content }; } catch (error) { throw handleControllerError(error, { entityType: 'ExampleData', operation: 'getData', source: 'controllers/example.controller.ts', }); } }

3. Implement MCP Tool

Create a tool definition in src/tools/:

// src/tools/example.tool.ts import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { z } from 'zod'; import { Logger } from '../utils/logger.util.js'; import { formatErrorForMcpTool } from '../utils/error.util.js'; import * as exampleController from '../controllers/example.controller.js'; const logger = Logger.forContext('tools/example.tool.ts'); const GetDataArgs = z.object({ param: z.string().optional().describe('Optional parameter'), }); type GetDataArgsType = z.infer<typeof GetDataArgs>; async function handleGetData(args: GetDataArgsType) { try { logger.debug('Tool get_data called', args); const result = await exampleController.getData({ param: args.param, }); return { content: [{ type: 'text' as const, text: result.content }], }; } catch (error) { logger.error('Tool get_data failed', error); return formatErrorForMcpTool(error); } } export function register(server: McpServer) { server.tool( 'get_data', `Gets data from the example API, optionally using \`param\`. Use this to fetch example data. Returns formatted data as Markdown.`, GetDataArgs.shape, handleGetData, ); }

4. Add CLI Support

Create a CLI command in src/cli/:

// src/cli/example.cli.ts import { program } from 'commander'; import { Logger } from '../utils/logger.util.js'; import * as exampleController from '../controllers/example.controller.js'; import { handleCliError } from '../utils/error-handler.util.js'; const logger = Logger.forContext('cli/example.cli.ts'); program .command('get-data') .description('Get example data') .option('--param <value>', 'Optional parameter') .action(async (options) => { try { logger.debug('CLI get-data called', options); const result = await exampleController.getData({ param: options.param, }); console.log(result.content); } catch (error) { handleCliError(error); } });

5. Register Components

Update the entry points to register your new components:

// In src/cli/index.ts import '../cli/example.cli.js'; // In src/index.ts (for the tool) import exampleTool from './tools/example.tool.js'; // Then in registerTools function: exampleTool.register(server);

Publishing Your MCP Server

  1. Update package.json with your details:

    { "name": "your-mcp-server-name", "version": "1.0.0", "description": "Your custom MCP server", "author": "Your Name", // Other fields... }

  2. Update README.md with your tool documentation

  3. Build: npm run build

  4. Test: npm run start:server

  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

This server cannot be installed

-
security - not tested
-
license - not tested
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/igun997/thuecat-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server