# BlackLotus MCP Server (Node.js + StreamableHTTPServerTransport)
[![smithery badge](https://smithery.ai/badge/@BadRooBot/blacklotus_mcp)](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.