TestMcpServer

Introduction

This example MCP Server implementation uses Anthropic's open source Model Context Protocol.

I found the existing examples to be unbearable to look at, mostly very long one-filers and very hard to read through.

With this more manageable approach I want users to find examples that are easier to understand and get into than what is currently out there.

Let this be the foundation for your next MCP Server project.

Requires Node, npm, typescript

Features

The MCP server currently provides the following tools:

Mathematical Tools

• Addition: Add two numbers together
• Subtraction: Subtract one number from another
• Multiplication: Multiply two numbers together
• Division: Divide one number by another (with division by zero protection)
• Square Root: Calculate the square root of a number
• Power: Raise a number to the power of another number
• Modulo: Calculate the remainder when dividing one number by another
• Logarithm: Calculate the logarithm of a number with a specified base
• Average: Calculate the arithmetic mean of two numbers

Image Processing Tools

• Image Conversion: Convert images between formats (PNG/JPG to WebP/AVIF) with compression
• Image Resize: Resize images while optionally converting formats

Filesystem Tools

• Tree: Get the directory tree structure of a specified path

Git Tools

• Commit History: Show recent git commits
• Diff: Show diffs between revisions

Text Utilities

• Word Count: Count lines, words and characters
• Search Replace: Perform search and replace on files

Network Tools

• HTTP Request: Perform a simple HTTP request
• Ping: Check connectivity to a host

Date/Time Utilities

• Timestamp Convert: Convert between timestamps and dates
• Schedule: Run a command after a short delay

Security Tools

• Hash: Generate hashes for text or files
• Checksum: Verify file checksums

Browser Tools

• Console Capture: Captures browser console logs (errors, warnings, info, logs) from a specified URL

All tools include comprehensive error handling and input validation to ensure robust operation.

Installation

run `npm install` upon cloning the repository.

Check package.json for scripts to use.

Run `npm run build` to build the server.

Run `node build/index.js` to run the server.

I suggest the following however:

Run `npm run dev` to watch changes on save and then rebuild and re-run inspector so you can test it in `localhost:5173`

Before being able to run the MCP server in Cursor it must be built first.

Testing MCP Tools

This project includes a comprehensive testing framework for MCP tools using Jest. The tests ensure that all tools work correctly and handle edge cases properly.

Running Tests

To run all tests:

npm test

To run tests with coverage report:

npm run test:coverage

To run specific tests:

npm test -- --testPathPattern=tests/maths/

Test Structure

• Controller Tests: Test controller handler methods directly (`tests/maths/`, `tests/browser/`, etc.)
• Filesystem Tests: Use fixture directories for consistent testing
• Browser Tests: Test browser interactions with test HTML pages
• MCP Simulation Tests: Test tools through the MCP request/response flow
• Edge Case Tests: Specialized tests for validation and error handling (`tests/maths/validation-edge-cases.test.ts`)

Testing Approach

The test suite follows a comprehensive approach:

1. Basic functionality tests - Verify that tools work correctly with valid inputs

2. Edge case tests - Test boundary conditions like zero values, negative numbers, etc.

3. Error handling tests - Verify proper error responses for invalid inputs

4. Validation tests - Test input validation with null/undefined values, non-numeric inputs, etc.

5. Overflow tests - Test behavior with extremely large values

Adding New Tests

1. Create test files in the appropriate category folder under `tests/`

2. Use the utility in `tests/utils/mcpTestHelper.ts` to simulate MCP tool calls

3. For filesystem tests, use the fixtures in `tests/fixtures/`

4. For browser tests, use or create test HTML files

5. For validation edge cases, add tests to specialized validation test files

MCP Server - Adding New Tools

This guide explains how to add new tools to the MCP server. The process involves four main components:

1. Tool Definition (`/src/definitions/`)

First, create your tool definition in the appropriate category folder (e.g., `maths/`):

// Example: src/definitions/maths/addition.ts
import { Tool } from "@modelcontextprotocol/sdk/types.js";

export const ADDITION: Tool = {
  name: "addition",
  description: "Add two numbers together",
  inputSchema: {
    type: "object",
    properties: {
      a: {
        type: "number",
        description: "First number to add",
      },
      b: {
        type: "number",
        description: "Second number to add",
      },
    },
    required: ["a", "b"],
  },
};

Then add it to the category's main file:

// src/definitions/maths/main.ts
import { ADDITION } from "./addition.js";
import { MULTIPLICATION } from "./multiplication.js";

const MATHS_TOOLS = [ADDITION, MULTIPLICATION] as const;

export default MATHS_TOOLS;

2. Controller Implementation (`/src/controllers/`)

Add the handler method to the appropriate controller:

// src/controllers/MathsController.ts
class MathsController {
  async handleAddition(a: number, b: number) {
    try {
      const result = a + b;
      return {
        content: [
          {
            type: "text",
            text: `Sum: ${result}`,
          },
        ],
        isError: false,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error calculating sum: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
        isError: true,
      };
    }
  }
}

3. Tool Registry (`/src/utils/toolRegistry.ts`)

Register your tool in the `controllerMap`:

const controllerMap: ControllerMap = {
  // Math tools
  addition: {
    controller: MathsController,
    handlerMethod: "handleAddition",
  },
  multiplication: {
    controller: MathsController,
    handlerMethod: "handleMultiplication",
  },
};

The registry exports two main functions:

// Get tool definitions for server registration
export function getToolDefinitions() {
  return {
    MATHS_TOOLS,
  };
}

// Get handler for tool execution
export function getToolHandler(toolName: string) {
  const mapping = controllerMap[toolName];
  if (!mapping) {
    return null;
  }

  const controllerInstance = new mapping.controller();
  return async (args: any) => {
    return await controllerInstance[mapping.handlerMethod](
      ...Object.values(args)
    );
  };
}

4. Server Configuration (`/src/index.ts`)

The server is configured to use the tool registry:

const tools = getToolDefinitions();

const server = new Server(
  {
    name: "mcp-server",
    version: "0.1.0",
  },
  {
    capabilities: {
      tools: getToolDefinitions(), // Register tools array
    },
  }
);

// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: tools,
}));

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  try {
    const handler = getToolHandler(request.params.name);
    if (!handler) {
      return toolController.getUnknownToolResponse(request.params.name);
    }
    return await handler(request.params.arguments);
  } catch (error) {
    return toolController.getErrorResponse(error);
  }
});

Conventions

1. Tool Names: Use lowercase (e.g., `addition`, `multiplication`)

2. Handler Methods: Name them as `handle` + PascalCase of the tool name (e.g., `handleAddition`, `handleMultiplication`)

3. Tool Categories: Group related tools in their own directory under `definitions/`

4. Controllers: Group related handlers in a controller class named after the category (e.g., `MathsController`)

Example Flow

1. Create tool definition in `src/definitions/category/toolname.ts`

2. Add tool to category's `main.ts`

3. Add handler method to appropriate controller

4. Register tool in `toolRegistry.ts`'s `controllerMap`

5. Test the new tool

Add MCP Server to Cursor

1. Open settings

2. Go to Features

3. Scroll to MCP Servers

4. Click Add new MCP server

5. Give MCP Server a name of your preference

6. For type use `command`

7. Server URL for local use should be `node \build\index.js>`

It should light up green and list the registered tools.