pr0methevs/mcp-template

MCP Express Server

A Model Context Protocol (MCP) server implementation using TypeScript, Express.js, and Server-Sent Events (SSE) for real-time communication.

Features

• MCP Protocol Support: Implements the Model Context Protocol specification
• SSE Transport: Real-time communication using Server-Sent Events
• TypeScript: Fully typed for better developer experience
• Express.js: Robust HTTP server framework
• Environment Configuration: Using dotenv for configuration management

Project Structure

src/
├── index.ts    # Main entry point and Express server setup
├── server.ts   # MCP protocol handling and SSE transport layer
├── tools.ts    # Tool implementations and business logic
└── types.ts    # TypeScript type definitions

Installation

npm install

Configuration

Create a .env file in the root directory:

cp .env.example .env

Edit .env with your configuration:

PORT=3000
HOST=0.0.0.0
SERVER_NAME=mcp-express-server
SERVER_VERSION=1.0.0

Development

Run in development mode with auto-reload:

npm run dev

Build

Compile TypeScript to JavaScript:

npm run build

Production

Run the compiled server:

npm start

API Endpoints

GET /

Server information and available endpoints

GET /health

Health check endpoint

• Returns server status and active connection count

GET /sse

Server-Sent Events endpoint

• Establishes a persistent connection for real-time notifications
• Clients should connect here to receive server updates

POST /message

MCP message endpoint

• Send JSON-RPC 2.0 formatted MCP requests
• Receives MCP responses

Available Tools

The server comes with three example tools:

1. echo: Echoes back a message
2. add: Adds two numbers together
3. get_time: Returns the current server time

MCP Protocol Usage

Initialize Connection

curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

List Available Tools

curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Call a Tool

curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "add",
      "arguments": {
        "a": 5,
        "b": 3
      }
    }
  }'

Adding New Tools

Edit src/tools.ts to add new tools:

export const availableTools: Tool[] = [
  // ... existing tools
  {
    name: 'your_tool',
    description: 'Description of your tool',
    inputSchema: {
      type: 'object',
      properties: {
        param1: {
          type: 'string',
          description: 'Parameter description'
        }
      },
      required: ['param1']
    }
  }
];

// Add implementation in executeTool function
case 'your_tool':
  return {
    content: [{
      type: 'text',
      text: `Result: ${args.param1}`
    }]
  };

License

MIT