MCP Server Template

A template for creating Model Context Protocol (MCP) servers in TypeScript. This template provides a solid foundation for building MCP-compatible servers with proper tooling, type safety, and best practices.

Features

• 🚀 Full TypeScript support

• 🏗️ Container-based dependency injection

• 📦 Service-based architecture with DataProcessor interface

• 🛠️ Example tool implementation with tests

• 🧪 Vitest testing framework

• 📝 Type definitions

• 🔌 MCP SDK integration

Getting Started

Development

1. Install dependencies:

   npm install

2. Start the development server with hot reload:

   npm run dev

3. Build the project:

   npm run build

4. Run tests:

   npm test

5. Start the production server:

   npm start

Project Structure

Creating Tools

1. Export your tool and handlers following the example in src/tools/example.ts:

   // In your-tool.ts export const YOUR_TOOLS = [ { name: "your-tool-name", description: "Your tool description", parameters: { // Your tool parameters schema }, }, ]; export const YOUR_HANDLERS = { "your-tool-name": async (request) => { // Your tool handler implementation return { toolResult: { content: [{ type: "text", text: "Result" }], }, }; }, };

2. Register your tool in the ALL_TOOLS and ALL_HANDLERS constants in src/index.ts:

   // In src/index.ts import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js"; // Combine all tools const ALL_TOOLS = [...EXAMPLE_TOOLS, ...YOUR_TOOLS]; const ALL_HANDLERS = { ...EXAMPLE_HANDLERS, ...YOUR_HANDLERS };

The server will automatically:

• List your tool in the available tools

• Handle input validation

• Process requests to your tool

• Format responses according to the MCP protocol

Testing

The template includes a built-in TestClient for local testing and the MCP Inspector for visual debugging.

Using TestClient

The TestClient provides a simple way to test your tools:

Using MCP Inspector

The template includes the MCP Inspector for visual debugging of your tools:

1. Start the inspector:

   npx @modelcontextprotocol/inspector node dist/index.js

2. Open the inspector UI at http://localhost:5173

The inspector provides:

• Visual interface for testing tools

• Real-time request/response monitoring

• Tool metadata inspection

• Interactive testing environment

Local Testing with Cursor

To test your MCP server locally with Cursor:

1. Build and link the package:

   npm run build npm run link

2. Verify the binary works:

   npx example-mcp-tool

3. Add the server to Cursor:

   • Open Cursor settings

   • Navigate to the Features tab

   • Scroll down to MCP Servers section

   • Click "Add Server"

   • Select "Command" type

   • Give it a name (e.g., "Local Example Tool")

   • Enter the command: npx example-mcp-tool

   • Click Confirm

4. Verify the server starts correctly in Cursor by checking the MCP Servers section shows your server as running.

Note: If you make changes to your code, remember to rebuild and relink:

When you're done testing, you can unlink the package:

This will remove the global symlink created during development.