Stevennevins 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, featuring comprehensive tool support, type safety, and best practices.

✨ Features

• 🚀 Full TypeScript support
• 🏗️ Container-based dependency injection
• 📦 Service-oriented architecture with DataProcessor interface
• 🛠️ Tool implementation examples and tests
• 🧪 Integration with Vitest testing framework
• 📝 Type definition files
• 🔌 Integration with MCP SDK

🚀 Quick Start

Development Steps

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 file
├── interfaces/       # Interface definitions
│   └── tool.ts      # DataProcessor interface
└── tools/           # Tool implementations
    └── example.ts   # Example tool

Creating Tools

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

// In your-tool.ts file
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 file
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 to your tools
• Format responses according to the MCP protocol

Testing

The template includes a TestClient for local testing and an MCP Inspector for visual debugging.

Using TestClient

The TestClient provides a simple 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();
      }
    );
  });
});

Using MCP Inspector

The template includes an MCP Inspector for visual debugging your tools:

1. Start the inspector:

npx @modelcontextprotocol/inspector node dist/index.js

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

The Inspector provides:

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

Using Cursor for Local Testing

To test your MCP server locally using 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 bottom to the MCP Servers section
• Click "Add Server"
• Select "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 the server is shown as running.

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

npm run build
npm run link

⚠️ Important Note

• Ensure that all dependencies are correctly installed.
• Conduct thorough testing before using in a production environment.
• Refer to the MCP documentation for more information.