raidcom-mcp 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.1.3 — 2026-10-28
+
+### Added
+
+- **`RAIDCOM_HTTP_CLIENT_IP_HEADER`** reads the client's address from a header a trusted proxy sets, such as `cf-connecting-ip` behind Cloudflare. On Render, which sits behind Cloudflare, counting `X-Forwarded-For` entries gave a Cloudflare address, so every user shared the rate limit and the in-progress cap of their Cloudflare edge.
+- **`RAIDCOM_HTTP_DEBUG_CLIENT=true`** makes `/healthz` show the forwarding headers it received, to choose the proxy settings.
+
 ## 0.1.2 — 2026-10-27
 
 0.1.0 and 0.1.1 were withdrawn from npm and can't be published again there; this is the first version on npm since. 0.1.1's GitHub release and Docker image stay available.

package/INSTALL.md

@@ -145,7 +145,7 @@ Which settings are required depends on where it listens:
 - **Loopback only** (the default `127.0.0.1`): a token, or `RAIDCOM_HTTP_OPEN=true`.
 - **Reachable by other machines**: also TLS. Either give the server a certificate (`RAIDCOM_HTTP_TLS_CERT`, `RAIDCOM_HTTP_TLS_KEY`) or put it behind a reverse proxy or load balancer that ends TLS and set `RAIDCOM_HTTP_BEHIND_TLS_PROXY=true`.
 - **A public name**: list it in `RAIDCOM_HTTP_ALLOWED_HOSTS` (for example `raidcom.example.com`), or requests are refused with 403 to defend against DNS rebinding.
-- **Behind a proxy**: set `RAIDCOM_HTTP_TRUST_PROXY` to the number of proxies in front of the server (`true` means one), so the rate limits apply per user. Each proxy adds an entry to `X-Forwarded-For`; the server takes the entry that many places from the right, and ignores entries further left, which the client could have written. Too low a number makes every user look like the same proxy (they then share one rate limit); too high lets a client choose its own address. To check the number, open `/healthz`: behind proxies it shows `client`, which should be your own public address (compare with `curl https://ifconfig.me`). Hosting platforms often have more than one proxy; on Render, try `3` and check `/healthz`.
+- **Behind a proxy**: set `RAIDCOM_HTTP_TRUST_PROXY` to the number of proxies in front of the server (`true` means one), so the rate limits apply per user. Each proxy adds an entry to `X-Forwarded-For`; the server takes the entry that many places from the right, and ignores entries further left, which the client could have written. Too low a number makes every user look like the same proxy (they then share one rate limit); too high lets a client choose its own address. To check the number, open `/healthz`: behind proxies it shows `client`, which should be your own public address (compare with `curl https://ifconfig.me`). Hosting platforms often have more than one proxy, and some put a CDN in front whose own proxies vary in number. If the address `/healthz` shows never matches yours, set `RAIDCOM_HTTP_DEBUG_CLIENT=true` and open `/healthz` again: it lists the forwarding headers it received. Behind Cloudflare (Render, for example) use `RAIDCOM_HTTP_CLIENT_IP_HEADER=cf-connecting-ip` instead of counting proxies; Cloudflare overwrites that header on every request, so a client can't set it. Turn the debug setting off again afterwards.
 
 A public service that anyone may use can run with `RAIDCOM_HTTP_OPEN=true`: the server holds no secrets and cannot reach any array, so the risk is limited to load, which the rate limit and the 256 KB body limit bound.
 

package/README.md

@@ -98,6 +98,8 @@ The endpoint is `/mcp` (stateless Streamable HTTP); `/healthz` reports liveness.
 | `RAIDCOM_HTTP_ALLOWED_HOSTS` | none | Extra `Host` values to accept (`*` for any) |
 | `RAIDCOM_HTTP_ALLOWED_ORIGINS` | none | `Origin` values to accept (`*` for any) |
 | `RAIDCOM_HTTP_RATE_LIMIT` | `120` | Requests per minute per client (`0` for none) |
+| `RAIDCOM_HTTP_CLIENT_IP_HEADER` | none | A header your proxy sets to the client's address, e.g. `cf-connecting-ip` behind Cloudflare (Render uses Cloudflare). Takes precedence over `X-Forwarded-For` |
+| `RAIDCOM_HTTP_DEBUG_CLIENT` | `false` | `/healthz` also shows the forwarding headers it received, to choose the two settings above |
 | `RAIDCOM_HTTP_TRUST_PROXY` | `false` | Take the client address from `X-Forwarded-For`: `true` for one proxy in front, or the number of proxies (see [INSTALL.md](INSTALL.md#run-over-http)) |
 | `RAIDCOM_CATALOG`, `RAIDCOM_LIMITS`, `RAIDCOM_RECIPES`, `RAIDCOM_EXAMPLES` | bundled | Use another spec file (an empty `RAIDCOM_EXAMPLES` turns the example questions off) |
 

package/dist/config.js

@@ -30,6 +30,14 @@ export function loadServerConfig(env = process.env) {
     };
 }
 const MIN_TOKEN_LENGTH = 32;
+/** RAIDCOM_HTTP_CLIENT_IP_HEADER: a header name, lower-cased. */
+function clientHeader(v) {
+    if (!v)
+        return undefined;
+    if (!/^[A-Za-z0-9-]{1,64}$/.test(v))
+        throw new Error(`[raidcom-mcp] RAIDCOM_HTTP_CLIENT_IP_HEADER must be a header name such as cf-connecting-ip, not "${v}"`);
+    return v.toLowerCase();
+}
 /** RAIDCOM_HTTP_TRUST_PROXY: unset or false → 0, true → 1, or a number of proxies from 1 to 10. */
 function proxyHops(v) {
     if (v === undefined || v === "" || v === "false" || v === "0")
@@ -114,5 +122,7 @@ export function loadHttpConfig(env = process.env) {
         behindTlsProxy,
         rateLimitPerMinute: Math.floor(rate),
         trustProxy: proxyHops(env.RAIDCOM_HTTP_TRUST_PROXY),
+        clientIpHeader: clientHeader(env.RAIDCOM_HTTP_CLIENT_IP_HEADER),
+        debugClient: env.RAIDCOM_HTTP_DEBUG_CLIENT === "true",
     };
 }

package/dist/http.js

@@ -96,7 +96,14 @@ export class RateLimiter {
  * proxy added. Entries further left come from the client and can say anything. (Same rule as Express's
  * `trust proxy` set to a number.)
  */
-export function clientAddress(req, hops) {
+export function clientAddress(req, hops, header) {
+    // a header the proxy sets to the client's address, such as cf-connecting-ip; used only if it holds an IP address
+    if (header) {
+        const raw = req.headers[header];
+        const v = (Array.isArray(raw) ? raw[0] : raw)?.trim();
+        if (v && /^[0-9A-Fa-f:.]{2,45}$/.test(v))
+            return v;
+    }
     if (hops > 0) {
         const xff = req.headers["x-forwarded-for"];
         const entries = (Array.isArray(xff) ? xff.join(",") : (xff ?? "")).split(",").map((s) => s.trim()).filter(Boolean);
@@ -116,7 +123,7 @@ export async function startHttp(cfg, createServer) {
     let active = 0;
     const perClient = new Map();
     const refuse = (req, res, status, message, headers) => {
-        console.error(`[raidcom-mcp] refused ${req.method} ${req.url} from ${clientAddress(req, cfg.trustProxy)}: ${status} ${message}`);
+        console.error(`[raidcom-mcp] refused ${req.method} ${req.url} from ${clientAddress(req, cfg.trustProxy, cfg.clientIpHeader)}: ${status} ${message}`);
         reject(res, status, message, headers);
     };
     const handler = async (req, res) => {
@@ -125,7 +132,17 @@ export async function startHttp(cfg, createServer) {
             res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
             // Behind proxies, the health check also shows the address the server takes as the caller's, so the number of
             // proxies (RAIDCOM_HTTP_TRUST_PROXY) can be checked: it should be your own public address.
-            const body = { status: "ok", version: VERSION, ...(cfg.trustProxy ? { client: clientAddress(req, cfg.trustProxy) } : {}) };
+            const proxied = cfg.trustProxy > 0 || !!cfg.clientIpHeader;
+            const seen = (h) => (Array.isArray(req.headers[h]) ? req.headers[h].join(", ") : req.headers[h]);
+            const body = {
+                status: "ok",
+                version: VERSION,
+                ...(proxied ? { client: clientAddress(req, cfg.trustProxy, cfg.clientIpHeader) } : {}),
+                // RAIDCOM_HTTP_DEBUG_CLIENT=true: what the proxies sent, to choose RAIDCOM_HTTP_TRUST_PROXY or _CLIENT_IP_HEADER
+                ...(cfg.debugClient
+                    ? { forwarding: { socket: req.socket.remoteAddress, "x-forwarded-for": seen("x-forwarded-for"), "cf-connecting-ip": seen("cf-connecting-ip"), "true-client-ip": seen("true-client-ip"), "x-real-ip": seen("x-real-ip") } }
+                    : {}),
+            };
             return res.end(req.method === "HEAD" ? undefined : JSON.stringify(body));
         }
         if (path !== MCP_PATH)
@@ -135,7 +152,7 @@ export async function startHttp(cfg, createServer) {
         const origin = req.headers.origin;
         if (origin !== undefined && !anyOrigin && !origins.has(origin.toLowerCase()))
             return refuse(req, res, 403, "Origin not allowed. Add it to RAIDCOM_HTTP_ALLOWED_ORIGINS if this page should reach the server.");
-        const client = clientAddress(req, cfg.trustProxy);
+        const client = clientAddress(req, cfg.trustProxy, cfg.clientIpHeader);
         if (!limiter.allow(client))
             return refuse(req, res, 429, "Too many requests. Try again in a minute.", { "retry-after": "60" });
         if (token && !authorized(req.headers.authorization, token))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raidcom-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "mcpName": "io.github.visubramaniam/raidcom-mcp",
   "description": "MCP server that builds and checks Hitachi raidcom commands from structured requests. Build-only: it never connects to a storage system. Not an official Hitachi Vantara product.",
   "license": "MIT",
@@ -29,10 +29,10 @@
     "node": ">=22.19.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.1"
+    "@modelcontextprotocol/sdk": "1.32.2"
   },
   "devDependencies": {
-    "@types/node": "22.18.8",
+    "@types/node": "22.20.5",
     "typescript": "7.0.2"
   },
   "author": "Vinod Subramaniam",