@reaatech/mcp-server-engine

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

MCP server framework built on Express 5 with a composable middleware pipeline, tool orchestration, and dual-transport support. This is the top-level package that ties together the @reaatech/mcp-server-* ecosystem.

Installation

npm install @reaatech/mcp-server-engine
# or
pnpm add @reaatech/mcp-server-engine

Feature Overview

• Express 5 server — Helmet security headers, CORS with configurable origins, 10 MB JSON body parsing
• Middleware pipeline — Auth → Rate limit → Idempotency → Sanitization, in order
• Dual transports — Streamable HTTP (primary) + SSE (legacy), mounted automatically
• Tool orchestration — Auto-discovers .tool.ts files, registers them, traces execution
• Health endpoints — /health (full diagnostics), /ready (readiness), /live (liveness)
• Observability — OpenTelemetry tracing on every tool call, Pino structured logging
• Graceful shutdown — SIGTERM/SIGINT handlers drain connections within a configurable timeout
• Environment-validated — All configuration validated at startup via Zod; fails fast on misconfiguration

Quick Start

Start a Server (30 seconds)

import { startServer } from '@reaatech/mcp-server-engine';
 
// Built-in echo and health-check tools are available
// Transport, auth, rate limiting, idempotency, and sanitization are all configured
startServer();

PORT=8080 pnpm dev

✅ GET  /health        → { status: "healthy", version: "1.0.0", ... }
✅ POST /mcp           → MCP messages (Streamable HTTP)
✅ GET  /mcp/sse       → SSE stream
✅ POST /mcp/messages  → SSE message handling

Customize the App

import { createApp } from '@reaatech/mcp-server-engine';
 
const app = await createApp();
 
// Add custom routes, middleware, or error handlers
app.get('/custom', (req, res) => {
  res.json({ custom: true });
});
 
app.listen(8080);

API Reference

createApp(): Promise<Express>

Builds and returns a fully configured Express application.

const app = await createApp();
app.listen(8080);

Steps performed:

1. Initializes OpenTelemetry (tracing + metrics)
2. Discovers and registers tools via @reaatech/mcp-server-tools
3. Mounts security middleware (Helmet, CORS, JSON body parsing)
4. Registers request ID generation
5. Adds health/readiness/liveness endpoints
6. Applies the middleware pipeline (auth → rate-limit → idempotency → sanitization)
7. Mounts Streamable HTTP and SSE transports
8. Adds 404 handler and centralized error handler

startServer(): Promise<void>

Creates the app, listens on the configured PORT, and registers SIGTERM/SIGINT graceful shutdown handlers.

startServer();
// Server listens on envConfig.PORT (default 8080)
// Graceful shutdown: drains connections within 30 seconds

createMcpServer(tools: ToolDefinition[]): McpServer

Creates an MCP server instance with the given tools. Each tool is registered with the MCP SDK’s server.tool() method. Tool execution is wrapped in OpenTelemetry spans and emits metrics.

import { createMcpServer } from '@reaatech/mcp-server-engine';
import { getTools } from '@reaatech/mcp-server-tools';
 
const server = createMcpServer(getTools());

Middleware Components

Each middleware function returns an Express middleware:

import {
  rateLimitMiddleware,
  idempotencyMiddleware,
  sanitizationMiddleware,
} from '@reaatech/mcp-server-engine';
 
app.use(rateLimitMiddleware());
app.use(idempotencyMiddleware());
app.use(sanitizationMiddleware());

Utility Functions

Middleware Pipeline

Configuration

All configuration is read from @reaatech/mcp-server-core’s validated environment:

Health Endpoints

Error Handling

The server includes a centralized error handler:

• 404 responses: { error: "Not Found", message: "Endpoint not found" }
• Unhandled errors: { error: "Internal Server Error", message } — error details are hidden in production

Related Packages

• @reaatech/mcp-server-core — Core types and configuration
• @reaatech/mcp-server-auth — Authentication middleware
• @reaatech/mcp-server-observability — Logging, tracing, metrics
• @reaatech/mcp-server-transport — Transport layer
• @reaatech/mcp-server-tools — Tool registry and built-in tools

License

MIT