# BlackLotus MCP Server (Node.js + StreamableHTTPServerTransport)
[](https://smithery.ai/server/@BadRooBot/blacklotus_mcp)
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:
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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)
```bash
curl -N \
-H "mcp-session-id: <PASTE_SESSION_ID>" \
http://localhost:3000/mcp
```
### 6) End the session
```bash
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:
```ts
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.
