BlackLotus MCP Server (Node.js + StreamableHTTPServerTransport)

An MCP server that responds with plain text content for AI tools, built with Node.js/TypeScript and the Model Context Protocol SDK. It uses the Streamable HTTP transport with session management over Express.

• Server name: context7-mcp-server

• Transport: StreamableHTTPServerTransport

• Tools: create_plan, create_tasks, create_role

Prerequisites

• Node.js >= 18.18

Related MCP server: Spec Workflow MCP

Install & Run

From the blacklotus_mcp/ directory:

npm install
npm run dev

The server starts on http://localhost:3000 by default.

Endpoints

• POST /mcp – JSON-RPC over HTTP for client->server messages. Used for initialization and tool calls.

• GET /mcp – Server-Sent Events for server->client notifications (requires mcp-session-id header).

• DELETE /mcp – Terminates a session (requires mcp-session-id header).

• GET /health – Basic readiness probe.

CORS is enabled for demo purposes with origin: "*", and exposes the Mcp-Session-Id response header. Adjust for production.

JSON-RPC Examples (curl)

1) Initialize a session

curl -i \
  -H "Content-Type: application/json" \
  -X POST http://localhost:3000/mcp \
  --data '{
    "jsonrpc":"2.0",
    "id":"1",
    "method":"initialize",
    "params":{
      "protocolVersion":"2024-11-05",
      "capabilities":{},
      "clientInfo":{"name":"curl","version":"0.0.1"}
    }
  }'

• On success, the response will include a Mcp-Session-Id header. Copy its value for subsequent calls.

2) Call create_plan tool

curl -i \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <PASTE_SESSION_ID>" \
  -X POST http://localhost:3000/mcp \
  --data '{
    "jsonrpc":"2.0",
    "id":"2",
    "method":"tools/call",
    "params":{
      "name":"create_plan",
      "arguments":{"text":"Build an e-commerce app with payments and order tracking"}
    }
  }'

3) Call create_tasks tool

curl -i \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <PASTE_SESSION_ID>" \
  -X POST http://localhost:3000/mcp \
  --data '{
    "jsonrpc":"2.0",
    "id":"3",
    "method":"tools/call",
    "params":{
      "name":"create_tasks",
      "arguments":{"text":"<PASTE_THE_PLAN_TEXT_HERE>"}
    }
  }'

4) Call create_role tool

curl -i \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <PASTE_SESSION_ID>" \
  -X POST http://localhost:3000/mcp \
  --data '{
    "jsonrpc":"2.0",
    "id":"4",
    "method":"tools/call",
    "params":{
      "name":"create_role",
      "arguments":{"text":"<PROJECT_CONTEXT_AND_GOALS>"}
    }
  }'

5) Subscribe to notifications (SSE)

curl -N \
  -H "mcp-session-id: <PASTE_SESSION_ID>" \
  http://localhost:3000/mcp

6) End the session

curl -i \
  -X DELETE \
  -H "mcp-session-id: <PASTE_SESSION_ID>" \
  http://localhost:3000/mcp

Code Overview

• src/index.ts

  • Creates an Express app with CORS and JSON body parsing.

  • Manages MCP sessions with StreamableHTTPServerTransport and a session map.

  • Defines three tools via McpServer:

    • create_plan(text: string) – returns a comprehensive technical design document as plain text (intended for plan.md).

    • create_tasks(text: string) – returns a phase-based checklist as plain text (intended for tasks.md).

    • create_role(text: string) – returns a detailed role definition as plain text (intended for role.md).

• tsconfig.json – TypeScript config using NodeNext modules.

• package.json – Scripts for dev, build, start.

Security Notes

• For local-only usage, you can enable DNS rebinding protection:

const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: () => randomUUID(),
  enableDnsRebindingProtection: true,
  allowedHosts: ["127.0.0.1"],
});

Adjust CORS origin, allowedHeaders, and exposed headers for your deployment environment.

Production

• Run npm run build to compile to dist/, then npm start.

• Place behind a reverse proxy and configure TLS and CORS appropriately.