# moolre-mcp (Node.js)

MCP server exposing Moolre's API — accounts, transfers, payments, SMS, WhatsApp — as 24 tools an AI agent can call. This is the Node.js port of the original PHP implementation (`mcp_php/mcp.php`); behavior is a 1:1 match, verified against it directly.

Built on the official `@modelcontextprotocol/sdk` for protocol handling (JSON-RPC validation, session management, SSE framing) — Moolre-specific logic (the REST client and 24 tool definitions) is the only custom code.

## Requirements

- Node.js 18 or later (uses the built-in `fetch`; developed and tested on Node 22).
- `npm install` (pulls in `@modelcontextprotocol/sdk`).

## Running locally (stdio — for MCP clients like Claude Code, Cursor)

```bash
node mcp.js
```

When run with a plain `node mcp.js` and no `PORT` env var, this reads/writes newline-delimited JSON-RPC over stdin/stdout — the shape an MCP client expects when it spawns the server as a subprocess, e.g. `"command": "node", "args": ["/path/to/mcp.js"]` in the client's MCP config. See `CURSOR_SETUP.md` / `AGENT_SETUP.md` for full config examples.

## Running as a hosted HTTP server

```bash
PORT=3000 node mcp.js
```

Setting `PORT` (which most Node hosts — Render, Railway, Fly.io, etc. — inject automatically) switches this to the **Streamable HTTP** transport: a single endpoint handling

- `POST` — JSON-RPC messages (responds as plain JSON, or as an SSE-framed event if the client sends `Accept: text/event-stream`)
- `GET` — optional standalone SSE stream (used for server-initiated messages; this server has none to push, so it opens and immediately closes the stream — enough to satisfy clients that check for SSE support)
- `DELETE` — explicit session termination

Session IDs are issued on `initialize` via the `Mcp-Session-Id` response header (handled by the SDK's `StreamableHTTPServerTransport`), and required on every subsequent request via the same header. We keep one transport (and one connected MCP `Server` instance) per session in an in-memory `Map` — **if you ever run multiple instances behind a load balancer without sticky sessions, session lookups will fail against the wrong instance.** For a single hosted instance this isn't a concern.

To force HTTP mode without a `PORT` (rare), set `MCP_TRANSPORT=http` instead (defaults to port 3000).

## Environment variables

| Variable | Purpose | Used by |
|---|---|---|
| `X-API-USER` | Your Moolre username | every endpoint |
| `X-API-KEY` | Private API key | account/transfer/payment/list_transactions endpoints |
| `X-API-PUBKEY` | Public API key | `create_payment_id`, `create_bank_account_number`, `generate_payment_link`, `payment_status` |
| `X-API-VASKEY-SMS` | VASKEY for SMS endpoints | `send_sms`, `send_sms_get`, `sms_status`, `create_sender_id`, `sender_id_status`, `list_sender_ids`, `approve_sender_id`, `sms_account_status` |
| `X-API-VASKEY-WHATSAPP` | VASKEY for WhatsApp endpoints | `get_whatsapp_templates`, `send_whatsapp_message`, `whatsapp_message_status` |
| `accountnumber` | Your Moolre wallet account number | most endpoints (not `create_account`, and not SMS/WhatsApp endpoints) |

All of these are **fallbacks only** — if a tool call explicitly supplies `headers` or `accountnumber` in its arguments, that always takes precedence over the environment.

The single header Moolre actually receives is always `X-API-VASKEY` — the two env vars just let the server pick the right value automatically depending on which service (SMS vs WhatsApp) the tool being called talks to.

## Project structure

- `mcp.js` — REST client (`callRest`), the MCP `Server` wiring (`tools/list` / `tools/call` handlers), and both transports (stdio via `StdioServerTransport`, HTTP via `StreamableHTTPServerTransport` + a thin session-routing layer)
- `tools.js` — the 24 tool schemas and their REST-call configuration (method, path, default `type`, credential group)

## Testing

```bash
# stdio
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node mcp.js

# HTTP
PORT=3000 node mcp.js &
curl -s -i -X POST http://127.0.0.1:3000/ \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

Note: the SDK validates requests against the real MCP schema, so `initialize` needs a proper `clientInfo`/`capabilities` payload (real MCP clients already send this) — unlike the earlier hand-rolled version, bare `{"params":{}}` won't pass validation.