How to Build a Multi‑Protocol MCP Server Framework with TypeScript

Overview

The MCP‑Server framework (TypeScript) unifies three MCP transport protocols—stdio, streamableHttp (named streamableHttpless), and Server‑Sent Events (SSE)—into a single code base. This eliminates duplicated implementations, reduces platform‑specific boilerplate, and lowers the learning curve for new developers.

Key Features

Simultaneous support for stdio, streamableHttp, and SSE modes.

Modular architecture: business logic resides in a dedicated file without touching core modules.

Configuration via environment variables ( MCP_HOST, MCP_PORT, MCP_DOMAIN, MCP_BASE_PATH) for production deployment.

Mode switching through npm scripts; no code changes required.

Built‑in logging module for runtime inspection.

Deployment scripts for the JD “Xingyun” platform (adaptable to other platforms).

Directory Structure

- build                # compiled output
- src
  ├─ router            # HTTP and SSE route definitions
  │   ├─ index.ts      # entry for streamableHttp routes
  │   ├─ mcp.ts        # default path <code>/mcp</code> (configurable via MCP_BASE_PATH)
  │   └─ sse.ts        # SSE path configuration (default <code>/mcp</code>)
  ├─ tools             # utility modules
  │   ├─ index.ts      # tool registration
  │   └─ mockFunc.ts   # example mock implementation
  ├─ cli.ts            # command‑line parser
  ├─ index.ts          # main entry point (selects transport)
  ├─ server.ts         # creates MCP service and registers shared tools
  ├─ sse.ts            # runs SSE mode
  ├─ stdio.ts          # runs stdio mode
  └─ streamableHttp.ts # runs streamableHttp mode
- xingyun/bin          # deployment scripts for Xingyun platform
- build_xingyun.sh    # auxiliary build script

Startup Commands (npm scripts)

{
  "scripts": {
    "build": "tsc && chmod 755 build/src/index.js build/src/cli.js",
    "start": "node ./build/src/cli.js",
    "start:http": "node ./build/src/cli.js --transport http",
    "start:sse": "node ./build/src/cli.js --transport sse",
    "dev:http": "node ./build/src/cli.js --transport http --port 3002",
    "stop": "pkill -f \"demo\" || true",
    "restart": "npm run stop && npm run start:http",
    "inspector": "npx @modelcontextprotocol/inspector"
  }
}

Typical usage: npm run start – default stdio mode. npm run start:http – streamableHttp on port 3001. npm run dev:http – streamableHttp on a custom port (e.g., 3002). npm run start:sse – SSE mode.

Production Configuration via Environment Variables

# Example settings
export MCP_HOST=192.168.1.100
export MCP_PORT=3001
export MCP_DOMAIN=mcp-server.internal.com
export MCP_BASE_PATH=/api/mcp

Resolution priority:

Port: MCP_PORT (env) → --port argument → default 3001.

Address: MCP_DOMAIN (env) → MCP_HOST (env) → default localhost.

Core Modules

index.ts parses the --transport flag and delegates to the corresponding mode module (stdio, http, sse).

server.ts creates the MCP service instance and registers shared tools used by all modes.

tools/index.ts acts as a registry; each utility is exported and registered individually.

router folder defines HTTP routes for streamableHttp and SSE, mapping them to the base path configured by MCP_BASE_PATH.

Deployment Script Example (Xingyun)

start(){
  npm run start:http
  sleep 3
  status
}

To switch to SSE, replace the command inside the script with npm run start:sse.

Open‑Source References

Source code: https://github.com/XingtongCai/mcp-server-ts

Related projects:

JoyAgent‑Genie: https://github.com/jd-opensource/joyagent-jdgenie

JoyCode Agent: https://github.com/jd-opensource/joycode-agent

Published npm package (JD internal registry): https://npm.m.jd.com/package/@jd/demo-mcp-server