Model Context Protocol (MCP) Express & TypeScript Server

A highly robust, production-ready, and strictly typed Model Context Protocol (MCP) Server built with Node.js, Express.js, TypeScript, and WebSockets.

This server provides standard JSON-RPC 2.0 communication channels compliant with the MCP specifications, supporting dynamic tool execution, structured resource reading, and prompt template compiling. It also features a stunning, state-of-the-art Glassmorphism Admin Control Panel & Live API Playground served at the server root (http://localhost:3000).

---

🌟 Key Features

• Complete MCP Protocol Compliance: Implements the standardized JSON-RPC 2.0 message handshake and method routing structures over both WebSockets (/ws) and HTTP POST SSE Gateway (/api/mcp).
• Aesthetic Admin Dashboard & Playground: A premium dark-mode, glassmorphism-designed front-end interface featuring:
  • Live Metrics Grid: Tracking active connections, Cumulative requests count, allocated process heap memory, and simulated system CPU.
  • Interactive Sandbox Playground: Dynamically renders input parameter forms directly parsed from tools/prompts schemas, compiles standard JSON-RPC request objects, sends requests, and displays color-coded responses.
  • Real-time Log Stream Terminal: Watch system transactions, security check notifications, and tools validation events update in real-time.
• Sample Tools Out-of-the-Box:
  • weather: Generates realistic weather reports and forecasts based on location string hashes (consistent, stable results across Celsius and Fahrenheit).
  • calculator: Scientific mathematical calculator (addition, subtraction, multiplication, division, exponentiation, square roots) with advanced input validation (division by zero, negative square roots).
  • dbQuery: Analytics SELECT and STATS queries against a relational mock database containing users, products, and orders tables.
• Sample Resources Out-of-the-Box:
  • mcp://server/config: Exposes active server environments, capabilities, and registered module routing definitions.
  • mcp://server/logs: Serves the in-memory circular buffer (last 100 entries) as line-by-line formatted developer plain text logs.
• Sample Prompt Templates:
  • code_reviewer: Professional, Principal Engineer review prompt layout accepting raw code blocks and languages.
  • system_optimizer: Diagnostic optimization blueprint accepting architectures details and system bottleneck symptoms.
  • data_analyst: Dynamic tabular/JSON data analytics and statistical insights extractor.
• Token-Based Middleware Security: Comprehensive authorization checks (x-api-key headers, Bearer tokens, or query strings) supported natively across HTTP and WebSocket routes.

---

📁 Project Directory Structure

src/
├── server/
│   ├── index.ts        # Express bootstrapping, CORS, REST gateways, & HTTP Server
│   ├── mcp.ts          # Core MCP JSON-RPC protocol router & method controllers
│   └── websocket.ts    # WS server setup, authorization, and metrics log streams
├── tools/
│   ├── index.ts        # Tool registry coordinator & dispatcher mapping
│   ├── weather.ts      # weather tool execution and simulation handler
│   ├── calculator.ts   # calculator tool scientific operations handler
│   └── dbQuery.ts      # dbQuery tool relational select/stats analyzer
├── resources/
│   ├── index.ts        # Resource registry coordinator & dynamic loader
│   ├── config.ts       # mcp://server/config system configurations provider
│   └── systemLogs.ts   # mcp://server/logs live logs file stream provider
├── prompts/
│   ├── index.ts        # Prompt template registry coordinator
│   └── templates.ts    # code_reviewer, system_optimizer, & data_analyst prompts
├── middleware/
│   ├── auth.ts         # Secure API Key & Authorization Bearer validator
│   ├── error.ts        # Centralized Express boundary & JSON-RPC error builder
│   └── logging.ts      # Request latency tracking logger middleware
├── utils/
│   ├── logger.ts       # Custom ANSI colored printer with circular buffer & emitters
│   └── validator.ts    # Dependency-free JSON Schema compliance verification tool
├── types/
│   ├── index.ts        # Internal logs, registries, and metrics definitions
│   └── mcp.ts          # Standard MCP and JSON-RPC 2.0 protocol specifications
└── public/
    └── index.html      # Responsive visual dashboard and dynamic sandbox playground

---

🚀 Setup & Installation Instructions

1. Prerequisites

Make sure you have Node.js installed (v18+ recommended).

2. Install Dependencies

In the workspace directory, run:

npm install

3. Configure the Environment

Create a .env file in the root directory (one is pre-configured for you):

PORT=3000
API_KEY=mcp_secret_token_2026
NODE_ENV=development
SERVER_NAME=Antigravity MCP Server

Note: If API_KEY is commented out or left blank, authentication is fully disabled, allowing public access.

4. Running the Server

Development Mode (with hot-reloading)

Runs ts-node-dev to watch and hot-reload changes instantly:

npm run dev

Production Build & Start

Compiles TypeScript down to optimized JavaScript (/dist) and runs the production build:

npm run build
npm start

---

📡 REST API & Gateway Blueprints

All REST API routes are fully authenticated when API_KEY is configured in .env. Authenticate requests by adding either the x-api-key header, Authorization: Bearer <key> header, or appending ?token=<key> to the query string.

1. Health & Server Specifications Check

curl -X GET http://localhost:3000/api/health \
  -H "x-api-key: mcp_secret_token_2026"

2. Standard MCP Protocol POST Gateway

Send standard JSON-RPC 2.0 payloads directly to /api/mcp.

# Call Tools List
curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: mcp_secret_token_2026" \
  -d '{"jsonrpc":"2.0", "id": 1, "method": "tools/list", "params": {}}'

# Call Weather Tool
curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: mcp_secret_token_2026" \
  -d '{"jsonrpc":"2.0", "id": 2, "method": "tools/call", "params": {"name": "weather", "arguments": {"location": "San Francisco", "days": 3, "unit": "fahrenheit"}}}'

3. Relational Web Services Endpoints

List Tools

GET /api/tools

curl -X GET http://localhost:3000/api/tools -H "x-api-key: mcp_secret_token_2026"

Execute Tool

POST /api/tools/:name (Accepts arguments directly in body JSON)

curl -X POST http://localhost:3000/api/tools/calculator \
  -H "Content-Type: application/json" \
  -H "x-api-key: mcp_secret_token_2026" \
  -d '{"operation": "power", "a": 5, "b": 3}'

List Resources

GET /api/resources

curl -X GET http://localhost:3000/api/resources -H "x-api-key: mcp_secret_token_2026"

Read Specific Resource URI

GET /api/resources/read?uri=<resource_uri>

curl -X GET "http://localhost:3000/api/resources/read?uri=mcp://server/config" \
  -H "x-api-key: mcp_secret_token_2026"

List Prompt Templates

GET /api/prompts

curl -X GET http://localhost:3000/api/prompts -H "x-api-key: mcp_secret_token_2026"

Compile Prompt Template

POST /api/prompts/:name

curl -X POST http://localhost:3000/api/prompts/code_reviewer \
  -H "Content-Type: application/json" \
  -H "x-api-key: mcp_secret_token_2026" \
  -d '{"code": "const a = () => { return 42; };", "language": "JavaScript"}'

---

🔌 WebSocket JSON-RPC channel

Connect standard WebSocket clients (such as MCP client environments) to: ws://localhost:3000/ws?token=mcp_secret_token_2026

All messages exchanged over WebSocket must conform strictly to JSON-RPC 2.0 structures.

Example Exchange

1. Initialize Handshake

Client -> Server:

{
  "jsonrpc": "2.0",
  "id": 101,
  "method": "initialize",
  "params": {
    "protocolVersion": "1.0.0",
    "capabilities": {},
    "clientInfo": {
      "name": "Custom-Client",
      "version": "1.0"
    }
  }
}

Server -> Client:

{
  "jsonrpc": "2.0",
  "id": 101,
  "result": {
    "protocolVersion": "1.0.0",
    "capabilities": {
      "tools": { "listChanged": false },
      "resources": { "subscribe": false, "listChanged": false },
      "prompts": { "listChanged": false }
    },
    "serverInfo": {
      "name": "Antigravity MCP Server",
      "version": "1.0.0"
    }
  }
}

---

🛠️ Registering with LLM Clients (e.g. Claude Desktop)

To connect this custom MCP server to Claude Desktop, add the configuration into your claude_desktop_config.json file:

For macOS

File location: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following inside the "mcpServers" block (Note: Adjust absolute pathing to point to your compiled project location):

{
  "mcpServers": {
    "express-mcp-server": {
      "command": "node",
      "args": [
        "/Users/laptopheaven/mcp-skill/dist/server/index.js"
      ],
      "env": {
        "PORT": "3000",
        "API_KEY": "mcp_secret_token_2026",
        "NODE_ENV": "production",
        "SERVER_NAME": "Production Claude MCP Server"
      }
    }
  }
}

Restart Claude Desktop, and you will see the Weather, Calculator, and Mock Database querying tools appear in the attachments/tools toolbar!

---

☁️ Cloud Deployment Guides

The project is pre-configured for instant deployments to Render or Fly.io using the provided declarative manifest blueprints.

Option A: One-Click Blueprint Deploy on Render

The repository includes a declarative render.yaml blueprint.

1. Push your codebase to a personal GitHub or GitLab repository.
2. Go to the Render Dashboard and select Blueprints -> New Blueprint Instance.
3. Link your repository. Render will automatically read the render.yaml config and:
   • Provision a Node.js web service.
   • Install dependencies and build: npm install && npm run build.
   • Boot utilizing: npm start on port 10000.
   • Automatically generate a secure secret API key for your API_KEY environmental variable. Go to your Render service Environment settings to retrieve this secret!

Option B: Containerized Deploy on Fly.io

The repository includes both a two-stage Dockerfile and a fly.toml definition.

1. Install the Fly CLI and log in: fly auth login.
2. Initialize configuration: fly launch (select "Copy settings from fly.toml" if prompted).
3. Securely set your custom API authentication secret:

   fly secrets set API_KEY="your_secret_mcp_auth_token_value"
   

4. Deploy the application: fly deploy.
5. Your live admin control panel and JSON-RPC WebSocket will be hosted at: https://your-app-name.fly.dev