MCP Server Template

🚀 MCP Server Template

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

✨ Features

• 🚀 Comprehensive TypeScript support
• 🏗️ Container-based dependency injection
• 📦 Service-oriented architecture with DataProcessor interface
• 🛠️ Example tool implementation and testing
• 🧪 Vitest testing framework
• 📝 Type definitions
• 🔌 MCP SDK integration

📦 Installation

Start Development

1. Install dependencies:

npm install

2. Start the development server with hot reloading:

npm run dev

3. Build the project:

npm run build

4. Run tests:

npm test

5. Start the production server:

npm start

📚 Documentation

Project Structure

src/
├── index.ts          # Entry point
├── interfaces/       # Interface definitions
│   └── tool.ts      # DataProcessor interface
└── tools/           # Tool implementations
    └── example.ts   # Example tool

Create Tools

1. Export your tools 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 parameter schema
    },
  },
];

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

2. Register your tools in src/index.ts:

// In src/index.ts
import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js";

// Merge all tools
const ALL_TOOLS = [...EXAMPLE_TOOLS, ...YOUR_TOOLS];
const ALL_HANDLERS = { ...EXAMPLE_HANDLERS, ...YOUR_HANDLERS };

The server will automatically:

• List your tools as available tools
• Handle input validation
• Handle requests for your tools
• Format responses according to the MCP protocol

Testing

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

Use TestClient

The TestClient provides an easy way to test your tools:

import { TestClient } from "./utils/TestClient";

describe("YourTool", () => {
  const client = new TestClient();

  it("should process data correctly", async () => {
    await client.assertToolCall(
      "your-tool-name",
      { input: "test" },
      (result) => {
        expect(result.toolResult.content).toBeDefined();
      }
    );
  });
});

Use MCP Inspector

This template includes an MCP Inspector for debugging tools:

1. Start the inspector:

npx @modelcontextprotocol/inspector node dist/index.js

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

The Inspector provides:

• A visual interface for testing tools
• Real-time request/response monitoring
• Tool metadata inspection
• An interactive testing environment

Local Testing with Cursor

To test your MCP server in Cursor:

1. Build and link the package:

npm run build
npm run link

2. Verify that the binary works:

npx example-mcp-tool

3. Add the server in Cursor:

• Open Cursor settings
• Navigate to the Features tab
• Scroll to the MCP Servers section at the bottom
• Click "Add Server"
• Select the "Command" type
• Enter a name (e.g., "Local Example Tool")
• Enter the command: npx example-mcp-tool
• Click Confirm

4. Check the MCP Servers section in Cursor to ensure your server is shown as running.

Note: If you change the code, remember to rebuild and relink:

npm run build
npm run link

When you no longer need it, you can uninstall the package:

npm uninstall example-mcp-tool
rm -rf ~/.node_modules_bins/example-mcp-link

Changelog

v1.0.0

• Initial version released