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
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 (requiresmcp-session-idheader).DELETE /mcp– Terminates a session (requiresmcp-session-idheader).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-Idheader. 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
StreamableHTTPServerTransportand a session map. - Defines three tools via
McpServer:create_plan(text: string)– returns a comprehensive technical design document as plain text (intended forplan.md).create_tasks(text: string)– returns a phase-based checklist as plain text (intended fortasks.md).create_role(text: string)– returns a detailed role definition as plain text (intended forrole.md).
-
tsconfig.json– TypeScript config usingNodeNextmodules. -
package.json– Scripts fordev,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 buildto compile todist/, thennpm start. - Place behind a reverse proxy and configure TLS and CORS appropriately.