@flarewatch/mcp 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# @flarewatch/mcp
+
+stdio→HTTPS bridge for the FlareWatch MCP server.
+
+Lets stdio-only MCP clients (Claude Desktop, Cursor, Continue) reach
+the remote endpoint at `https://mcp.flarewatch.io/api/mcp` without
+each client having to implement the Streamable HTTP transport.
+
+## Install / use
+
+No install needed — `npx` will fetch on demand:
+
+```bash
+npx -y @flarewatch/mcp
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "flarewatch": {
+      "command": "npx",
+      "args": ["-y", "@flarewatch/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 13 FlareWatch tools (validators, FTSO
+providers, scoring methodology, agent transparency, etc.) become
+available in every conversation.
+
+### Cursor
+
+Cursor supports Streamable HTTP natively — you don't need this bridge.
+Configure directly:
+
+```json
+{
+  "url": "https://mcp.flarewatch.io/api/mcp"
+}
+```
+
+### Continue.dev
+
+```json
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@flarewatch/mcp"] }
+      }
+    ]
+  }
+}
+```
+
+## Environment overrides
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `FLAREWATCH_MCP_URL` | `https://mcp.flarewatch.io/api/mcp` | Endpoint to forward to. Useful for preview deploys or local dev. |
+| `FLAREWATCH_MCP_TIMEOUT_MS` | `30000` | Per-request HTTP timeout in ms. |
+
+## What this bridge does NOT do
+
+It's intentionally dumb. ~150 LoC. The server is the single source of
+truth for:
+
+- Tool definitions
+- Resource content
+- Rate limiting
+- Quarantine / honeypot / classifier walls
+- Response signing
+
+The bridge just forwards JSON-RPC frames between stdio and HTTPS. No
+caching, no retries, no fallback. If the remote endpoint is down, the
+bridge surfaces the upstream error rather than attempting recovery.
+
+## Verification
+
+Every tool response carries a `verification_signature` HMAC. To verify
+a citation came from this server, call the `verify_response` tool with
+the cited payload + signature.

package/dist/bridge.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * @flarewatch/mcp — stdio↔HTTPS bridge for the FlareWatch MCP server.
+ *
+ * Speaks MCP-over-stdio on its standard input/output and forwards
+ * every JSON-RPC request to the remote endpoint at
+ * https://mcp.flarewatch.io/api/mcp. Lets stdio-only MCP clients
+ * (Claude Desktop, Cursor's filesystem-MCP integration, Continue's
+ * stdio transport, etc.) reach the remote server without each client
+ * having to implement Streamable HTTP.
+ *
+ * ~150 LoC of dumb forwarding. NOT a re-implementation of tools or
+ * resources — the server is the single source of truth.
+ *
+ * Environment overrides:
+ *   FLAREWATCH_MCP_URL — point at a non-default endpoint (preview /
+ *                        local dev). Defaults to https://mcp.flarewatch.io/api/mcp.
+ *   FLAREWATCH_MCP_TIMEOUT_MS — per-request HTTP timeout (default 30000).
+ *
+ * Usage:
+ *   npx @flarewatch/mcp
+ *
+ * Claude Desktop config:
+ *   {
+ *     "mcpServers": {
+ *       "flarewatch": {
+ *         "command": "npx",
+ *         "args": ["-y", "@flarewatch/mcp"]
+ *       }
+ *     }
+ *   }
+ */
+import { createInterface } from "node:readline";
+import { stdin, stdout, stderr } from "node:process";
+const DEFAULT_URL = "https://mcp.flarewatch.io/api/mcp";
+const URL = process.env.FLAREWATCH_MCP_URL ?? DEFAULT_URL;
+const TIMEOUT_MS = Number(process.env.FLAREWATCH_MCP_TIMEOUT_MS ?? "30000");
+const VERSION = "0.1.0";
+function write(obj) {
+    stdout.write(JSON.stringify(obj) + "\n");
+}
+function logStderr(msg, extra) {
+    // Stderr only — the MCP client reads JSON from stdout, so any
+    // diagnostic we emit must go to stderr to avoid corrupting the
+    // wire protocol.
+    const line = extra
+        ? `[flarewatch-mcp] ${msg} ${JSON.stringify(extra)}`
+        : `[flarewatch-mcp] ${msg}`;
+    stderr.write(line + "\n");
+}
+async function forward(req) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": `flarewatch-mcp-bridge/${VERSION}`,
+                "MCP-Protocol-Version": "2025-06-18",
+            },
+            body: JSON.stringify(req),
+            signal: controller.signal,
+        });
+        if (res.status === 204) {
+            // Notification reply — no body.
+            return null;
+        }
+        if (!res.ok) {
+            return {
+                jsonrpc: "2.0",
+                id: req.id ?? null,
+                error: {
+                    code: -32603,
+                    message: `bridge: upstream HTTP ${res.status}`,
+                },
+            };
+        }
+        const parsed = (await res.json());
+        if (Array.isArray(parsed)) {
+            // Batch — return only the first response that matches the id.
+            // stdio doesn't support batches well; the bridge accepts only
+            // single requests at a time, so this branch shouldn't fire in
+            // practice. Defensive return so we don't crash.
+            const match = parsed.find((r) => r.id === req.id);
+            return match ?? null;
+        }
+        return parsed;
+    }
+    catch (e) {
+        return {
+            jsonrpc: "2.0",
+            id: req.id ?? null,
+            error: {
+                code: -32603,
+                message: `bridge: forward failed — ${e instanceof Error ? e.message : String(e)}`,
+            },
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function main() {
+    logStderr(`starting; forwarding to ${URL}`);
+    const rl = createInterface({
+        input: stdin,
+        crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        let req;
+        try {
+            req = JSON.parse(line);
+        }
+        catch (e) {
+            write({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32700,
+                    message: `bridge: parse error — ${e instanceof Error ? e.message : String(e)}`,
+                },
+            });
+            continue;
+        }
+        const isNotification = req.id === undefined || req.id === null;
+        const response = await forward(req);
+        if (response === null) {
+            // Notification or 204 — no stdio output.
+            if (!isNotification) {
+                // Server returned 204 to a request that had an id — synthesize
+                // an empty success so the client doesn't hang forever.
+                write({ jsonrpc: "2.0", id: req.id ?? null, result: {} });
+            }
+            continue;
+        }
+        write(response);
+    }
+}
+main().catch((e) => {
+    logStderr("fatal", { error: e instanceof Error ? e.message : String(e) });
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@flarewatch/mcp",
+  "version": "0.1.0",
+  "description": "stdio→HTTPS bridge for the FlareWatch MCP server. Lets stdio-only MCP clients (Claude Desktop, Cursor, etc.) attach via `npx @flarewatch/mcp`.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "flarewatch-mcp": "dist/bridge.js"
+  },
+  "main": "dist/bridge.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/bridge.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "tsc"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nbridges333/flarewatch.git",
+    "directory": "packages/mcp-bridge"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "flare",
+    "flarewatch",
+    "ftso",
+    "validator"
+  ]
+}