Your First Test

Let's walk through creating and running your very first MCP server test step by step.

Step 1: Create a Test Server

First, let's create a simple "Hello World" MCP server to test. Save this as hello-server.js:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'hello-world-server',
  version: '1.0.0',
}, {
  capabilities: {
    tools: {},
    resources: {},
  },
});

// Add a simple greeting tool
server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'greet',
    description: 'Generate a personalized greeting',
    inputSchema: {
      type: 'object',
      properties: {
        name: { 
          type: 'string',
          description: 'Name of the person to greet'
        },
      },
      required: ['name'],
    },
  }],
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'greet') {
    const { name } = request.params.arguments;
    return {
      content: [{
        type: 'text',
        text: `Hello, ${name}! Welcome to MCP Jest! 🎉`,
      }],
    };
  }
  
  throw new Error(`Unknown tool: ${request.params.name}`);
});

// Add a simple resource
server.setRequestHandler('resources/list', async () => ({
  resources: [{
    uri: 'info://server',
    name: 'Server Information',
    description: 'Basic information about this server',
    mimeType: 'application/json',
  }],
}));

server.setRequestHandler('resources/read', async (request) => {
  if (request.params.uri === 'info://server') {
    return {
      contents: [{
        uri: 'info://server',
        mimeType: 'application/json',
        text: JSON.stringify({
          name: 'Hello World Server',
          version: '1.0.0',
          description: 'A simple MCP server for testing',
          author: 'MCP Jest Tutorial'
        }, null, 2)
      }]
    };
  }
  
  throw new Error(`Unknown resource: ${request.params.uri}`);
});

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

console.error('Hello World MCP Server started!');

Step 2: Create Your Test Configuration

Now create a test file called hello-test.json:

{
  "name": "🌟 Hello World Server Tests",
  "description": "My first MCP Jest test suite!",
  "server": {
    "command": "node",
    "args": ["hello-server.js"],
    "env": {
      "NODE_ENV": "test"
    },
    "timeout": 10000
  },
  "tests": [
    {
      "name": "Should have correct server metadata",
      "description": "Verify the server identifies itself correctly",
      "type": "capabilities",
      "expect": {
        "name": "hello-world-server",
        "version": "1.0.0"
      }
    },
    {
      "name": "Should list available tools",
      "description": "Check that our greeting tool is available",
      "type": "tools",
      "expect": {
        "tools": [
          {
            "name": "greet",
            "description": "Generate a personalized greeting"
          }
        ]
      }
    },
    {
      "name": "Should greet Alice correctly",
      "description": "Test the greeting functionality with a specific name",
      "type": "tool",
      "tool": "greet",
      "arguments": {
        "name": "Alice"
      },
      "expect": {
        "content": [
          {
            "type": "text",
            "text": "Hello, Alice! Welcome to MCP Jest! 🎉"
          }
        ]
      }
    },
    {
      "name": "Should greet Bob correctly",
      "description": "Test with a different name to ensure dynamic behavior",
      "type": "tool",
      "tool": "greet",
      "arguments": {
        "name": "Bob"
      },
      "expect": {
        "content": [
          {
            "type": "text",
            "text": "Hello, Bob! Welcome to MCP Jest! 🎉"
          }
        ]
      }
    },
    {
      "name": "Should list server resources",
      "description": "Verify that resources are properly exposed",
      "type": "resources",
      "expect": {
        "resources": [
          {
            "uri": "info://server",
            "name": "Server Information"
          }
        ]
      }
    },
    {
      "name": "Should read server info resource",
      "description": "Test reading the server information resource",
      "type": "resource",
      "resource": "info://server",
      "expect": {
        "contents": [
          {
            "uri": "info://server",
            "mimeType": "application/json"
          }
        ]
      }
    }
  ]
}

Step 3: Install Dependencies

First, make sure you have the MCP SDK installed:

npm install @modelcontextprotocol/sdk

Step 4: Run Your First Test

Now for the exciting part! Run your test:

mcp-jest hello-test.json

You should see output like this:

🚀 MCP Jest v1.0.9
📋 Running: Hello World Server Tests

✅ Should have correct server metadata (45ms)
✅ Should list available tools (12ms) 
✅ Should greet Alice correctly (18ms)
✅ Should greet Bob correctly (15ms)
✅ Should list server resources (8ms)
✅ Should read server info resource (22ms)

╭────────────────────────────╮
│ Tests:     6 passed ✨     │
│ Time:      0.645s ⚡       │
│ Status:    All good! 🎉    │
╰────────────────────────────╯

🎊 Congratulations! Your server is working perfectly!

Understanding the Test Structure

Let's break down what each part of the test does:

🔧 Server Configuration

The server section tells MCP Jest how to start your server. It runsnode hello-server.js and waits for it to be ready.

🎯 Test Types

We use different test types: capabilities checks server metadata,tools lists available tools, tool calls specific tools, and resources tests resource access.

✨ Expectations

The expect sections define what responses we expect. MCP Jest compares actual responses with these expectations and reports any differences.

What If Something Fails?

Let's see what happens when a test fails. Edit your server to change the greeting message, then run the test again:

✗ Should greet Alice correctly (25ms)
  Expected: "Hello, Alice! Welcome to MCP Jest! 🎉"
  Received: "Hi there, Alice!"
  
  Difference:
  - Expected
  + Received
  
  - Hello, Alice! Welcome to MCP Jest! 🎉
  + Hi there, Alice!

MCP Jest shows you exactly what went wrong with clear diff output!

Adding More Tests

Try adding a test for error handling:

{
  "name": "Should handle missing name parameter",
  "description": "Test error handling when required parameter is missing",
  "type": "tool",
  "tool": "greet",
  "arguments": {},
  "expectError": true,
  "expect": {
    "error": {
      "message": { "type": "string" }
    }
  }
}

Watch Mode

For development, use watch mode to automatically re-run tests when files change:

mcp-jest hello-test.json --watch

🎉 You did it!

You've successfully created and run your first MCP Jest test! You now understand the basics of testing MCP servers.

Next steps: