@rel-time/mcp-server 1.2.2 → 1.2.4

package/README.md

@@ -10,25 +10,26 @@ Official Model Context Protocol (MCP) server for **[Rel-Time](https://rel-time.c
 
 ---
 
-## Quick Setup (Claude Desktop / Cursor / Windsurf / Antigravity)
+## Quick Setup (Claude Desktop / Claude Code / Cursor / Windsurf / Antigravity)
 
-Add the following to your `claude_desktop_config.json` or `.cursor/mcp.json`:
+Add the following to your `.mcp.json`, `claude_desktop_config.json`, or `.cursor/mcp.json` (no API key or `.zshrc` environment variables needed to start!):
 
 ```json
 {
   "mcpServers": {
     "rel-time": {
       "command": "npx",
-      "args": ["-y", "@rel-time/mcp-server"],
-      "env": {
-        "RELTIME_API_KEY": "YOUR_RELTIME_API_KEY"
-      }
+      "args": ["-y", "@rel-time/mcp-server@latest"]
     }
   }
 }
 ```
 
-*(Note: `reltime_link_passkey`, `reltime_get_sun_stamp`, `reltime_check_proof`, and `reltime_provision_agent_key` work immediately even without an API key configured!)*
+When you start a fresh chat and ask to anchor a file or provision a key, `@rel-time/mcp-server` automatically prompts your agent to ask which pack you want first:
+1. **Agent Launch Pack (`pack: "launch"`, `$5 / 50 Hashes`):** Priority 10-Minute Bitcoin Queue · Standard Mode only (Data Integrity + Biometric or Anonymous) · Includes 64-Ray Sun-Stamp, 1-Click Stamped Copy (`.PDF`/`.PNG`), and `.JSON` Doomsday Proof.
+2. **Autonomous Agents (`pack: "standard"`, `$50 / 500 Hashes`):** Dynamic 6-Hour Batch Queue · Supports both Temporal Mode (`T_index` sub-second VDF sequencing) and Standard Mode · Reloadable anytime (`+500` credits / `$50`).
+
+Once paid via Lightning (or if you pass an existing `rel_key_...` key), the MCP server automatically saves your API key to `~/.reltime/api_key.json` (`0600` permissions) — no app restart or `.zshrc` edits required.
 
 ---
 

package/index.js

@@ -18,11 +18,36 @@ const path = require("path");
 const readline = require("readline");
 const { exec } = require("child_process");
 const { PDFDocument } = require("pdf-lib");
+const QRCode = require("qrcode");
 const sharp = require("sharp");
 
-const API_BASE = (process.env.RELTIME_API_URL || "https://rel-time.com/api/v1").replace(/\/+$/, "");
+function normalizeApiBase(rawUrl) {
+  const cleaned = (rawUrl || "https://rel-time.com/api/v1").trim().replace(/\/+$/, "");
+  if (
+    cleaned === "https://rel-time.com/v1" ||
+    cleaned === "https://rel-time.com" ||
+    cleaned.includes("api.rel-time.com")
+  ) {
+    return "https://rel-time.com/api/v1";
+  }
+  return cleaned;
+}
+
+function isValidApiKeyCandidate(k) {
+  if (!k || typeof k !== "string") return false;
+  const trimmed = k.trim();
+  if (!trimmed || trimmed.length < 16) return false;
+  if (trimmed.includes("${") || trimmed.includes("...") || trimmed.includes("YOUR_") || trimmed.includes("<")) {
+    return false;
+  }
+  return trimmed.startsWith("rel_");
+}
+
+const API_BASE = normalizeApiBase(process.env.RELTIME_API_URL);
 const WEB_BASE = (process.env.RELTIME_WEB_URL || "https://rel-time.com").replace(/\/+$/, "");
-let CURRENT_API_KEY = process.env.RELTIME_API_KEY || "";
+let CURRENT_API_KEY = isValidApiKeyCandidate(process.env.RELTIME_API_KEY)
+  ? process.env.RELTIME_API_KEY.trim()
+  : "";
 
 const PASSKEY_CONFIG_DIR = path.join(os.homedir(), ".reltime");
 const PASSKEY_CONFIG_PATH = path.join(PASSKEY_CONFIG_DIR, "passkey.json");
@@ -31,23 +56,53 @@ let LAST_INVOICE_PACK = null;
 
 const SERVER_INFO = {
   name: "rel-time-mcp-server",
-  version: "1.2.2",
+  version: "1.2.4",
 };
 
+/**
+ * Resolves a local file path, automatically matching macOS screenshot filenames
+ * that contain Narrow No-Break Spaces (U+202F) or Non-Breaking Spaces (U+00A0)
+ * when the caller passes normal ASCII spaces.
+ */
+function resolveLocalFilePath(rawPath) {
+  const resolved = path.resolve(rawPath);
+  if (fs.existsSync(resolved)) {
+    return resolved;
+  }
+  const dir = path.dirname(resolved);
+  const targetBase = path.basename(resolved);
+  const normalizeSpaces = (s) => s.normalize("NFC").replace(/[\u00A0\u202F\u2007\u2009\s]+/g, " ");
+  const normalizedTarget = normalizeSpaces(targetBase);
+  try {
+    if (fs.existsSync(dir)) {
+      const entries = fs.readdirSync(dir);
+      for (const entry of entries) {
+        if (normalizeSpaces(entry) === normalizedTarget) {
+          return path.join(dir, entry);
+        }
+      }
+    }
+  } catch (e) {
+    // Ignore directory read error
+  }
+  return resolved;
+}
+
 /**
  * Loads saved API key from ~/.reltime/api_key.json if not provided via env/args.
  */
 function loadSavedApiKey() {
-  if (CURRENT_API_KEY && CURRENT_API_KEY.trim()) {
+  if (isValidApiKeyCandidate(CURRENT_API_KEY)) {
     return CURRENT_API_KEY.trim();
   }
-  if (process.env.RELTIME_API_KEY && process.env.RELTIME_API_KEY.trim()) {
-    return process.env.RELTIME_API_KEY.trim();
+  if (isValidApiKeyCandidate(process.env.RELTIME_API_KEY)) {
+    CURRENT_API_KEY = process.env.RELTIME_API_KEY.trim();
+    return CURRENT_API_KEY;
   }
   try {
     if (fs.existsSync(API_KEY_CONFIG_PATH)) {
       const parsed = JSON.parse(fs.readFileSync(API_KEY_CONFIG_PATH, "utf8"));
-      if (parsed.api_key && parsed.api_key.trim()) {
+      if (isValidApiKeyCandidate(parsed.api_key)) {
         CURRENT_API_KEY = parsed.api_key.trim();
         return CURRENT_API_KEY;
       }
@@ -58,6 +113,41 @@ function loadSavedApiKey() {
   return "";
 }
 
+function buildPackSelectionPrompt(contextMessage) {
+  return {
+    status: "pack_selection_required",
+    api_endpoint: API_BASE,
+    important_instruction_for_ai_agent:
+      "DO NOT tell the user to edit ~/.zshrc, .mcp.json, or restart Claude/Cursor! The MCP server manages and persists API keys automatically in ~/.reltime/api_key.json. Simply ask the user right here in chat which of the two Agent API Key packs below they want to provision (or if they already have a `rel_key_...` key to paste), then call `reltime_provision_agent_key` with `action: 'create_invoice'` and `pack: 'launch'` or `pack: 'standard'`.",
+    message:
+      contextMessage ||
+      "No Rel-Time API key is active yet. Ask the user which key pack they want to provision first:",
+    available_packs: [
+      {
+        pack: "launch",
+        name: "1. Agent Launch Pack ($5 / 50 Hashes)",
+        price_usd: "$5.00",
+        credits: 50,
+        settlement_queue: "Priority 10-Minute Bitcoin Queue",
+        hashing_modes: "Standard Mode only (Data Integrity + Biometric or Anonymous)",
+        outputs: "64-Ray Sun-Stamp SVG + 1-Click Stamped Copy (.PDF/.PNG) + .JSON Doomsday Proof",
+      },
+      {
+        pack: "standard",
+        name: "2. Autonomous Agents ($50 / 500 Hashes)",
+        price_usd: "$50.00",
+        credits: 500,
+        settlement_queue: "Dynamic 6-Hour Batch Queue",
+        hashing_modes: "Temporal Mode (T_index sub-second VDF sequencing) + Standard Mode (Biometric or Anonymous)",
+        outputs:
+          "64-Ray Sun-Stamp SVG + 1-Click Stamped Copy (.PDF/.PNG) + .JSON Doomsday Proof + Reloadable anytime (+500 credits / $50)",
+      },
+    ],
+    next_step:
+      "Ask the user: 'Would you like to start with the **Agent Launch Pack ($5 / 50 Hashes · 10-Min Queue · Standard Mode)** or the **Autonomous Agents Pack ($50 / 500 Hashes · 6-Hr Queue · Standard + Temporal Mode)**?' Once they answer, call `reltime_provision_agent_key({ action: 'create_invoice', pack: 'launch' | 'standard' })`.",
+  };
+}
+
 /**
  * Saves provisioned API key to ~/.reltime/api_key.json with 0600 permissions.
  */
@@ -143,7 +233,7 @@ function openSystemBrowser(url) {
  * Rel-Time WebAuthn Passkey Bridge in the user's browser so they can touch
  * TouchID / FaceID / YubiKey.
  */
-function launchBrowserPasskeyBridge(timeoutMs = 120000) {
+function launchBrowserPasskeyBridge(timeoutMs = 300000) {
   return new Promise((resolve, reject) => {
     const server = http.createServer((req, res) => {
       res.setHeader("Access-Control-Allow-Origin", "*");
@@ -428,13 +518,14 @@ const TOOLS = [
   {
     name: "reltime_account_status",
     description:
-      "Checks the remaining Hash Credits, tier, and lifetime usage of the configured Rel-Time API key (`GET /v1/account`).",
+      "Checks the remaining Hash Credits, tier, and lifetime usage of the configured Rel-Time API key (`GET /api/v1/account`). If no API key is configured yet, returns the two available Agent API Key packs (`launch` $5/50 hashes vs `standard` $50/500 hashes) so you can ask the user which pack they want to provision in chat (without needing any .zshrc or config edits).",
     inputSchema: {
       type: "object",
       properties: {
         api_key: {
           type: "string",
-          description: "Optional override for RELTIME_API_KEY.",
+          description:
+            "Optional: pass a `rel_key_...` API key to check its balance AND automatically save it to ~/.reltime/api_key.json for all future calls.",
         },
       },
     },
@@ -442,7 +533,7 @@ const TOOLS = [
   {
     name: "reltime_provision_agent_key",
     description:
-      "Self-onboarding & Top-Up for Autonomous AI Agents via Bitcoin Lightning (`POST /v1/agent/invoice` & `POST /v1/agent/claim`). IMPORTANT: Before calling `create_invoice` for a new key, ALWAYS ask the user which pack they want first:\n1. **Agent Launch Pack (`pack: 'launch'`, $5 / 50 Hashes):** Priority 10-Minute Bitcoin Queue · Standard Mode only (Data Integrity + Biometric or Anonymous) · Includes Sun-Stamp, 1-Click Stamped Copy (.PDF/.PNG), and .JSON Doomsday Proof.\n2. **Autonomous Agents (`pack: 'standard'`, $50 / 500 Hashes):** Dynamic 6-Hour Batch Queue · Supports both Temporal Mode (`T_index` sub-second sequencing) and Standard Mode · Reloadable anytime (+500 credits / $50) with zero key rotation.",
+      "Self-onboarding & Top-Up for Autonomous AI Agents via Bitcoin Lightning (`POST /v1/agent/invoice` & `POST /v1/agent/claim`). IMPORTANT:\n1. Before calling `create_invoice` for a new key, ALWAYS ask the user which pack they want first:\n   - **Agent Launch Pack (`pack: 'launch'`, $5 / 50 Hashes):** Priority 10-Minute Bitcoin Queue · Standard Mode only (Data Integrity + Biometric or Anonymous) · Includes Sun-Stamp, 1-Click Stamped Copy (.PDF/.PNG), and .JSON Doomsday Proof.\n   - **Autonomous Agents (`pack: 'standard'`, $50 / 500 Hashes):** Dynamic 6-Hour Batch Queue · Supports both Temporal Mode (`T_index` sub-second sequencing) and Standard Mode · Reloadable anytime (+500 credits / $50) with zero key rotation.\n2. When `create_invoice` returns, ALWAYS present BOTH the scannable QR code image (by calling Read on `qr_code_png_path` so the image renders inline in chat!) AND the full, un-truncated `ln_invoice` (`bolt11`) string in a copyable code block on the VERY FIRST try!",
     inputSchema: {
       type: "object",
       properties: {
@@ -479,7 +570,11 @@ const TOOLS = [
 ];
 
 async function executeTool(name, args = {}) {
-  const key = (args.api_key || loadSavedApiKey() || "").trim();
+  if (args.api_key && isValidApiKeyCandidate(args.api_key)) {
+    CURRENT_API_KEY = args.api_key.trim();
+    saveApiKeyConfig(CURRENT_API_KEY, "custom");
+  }
+  const key = (isValidApiKeyCandidate(args.api_key) ? args.api_key.trim() : loadSavedApiKey()) || "";
 
   if (name === "reltime_link_passkey") {
     if (args.public_key_hex && args.passkey_signature) {
@@ -506,15 +601,15 @@ async function executeTool(name, args = {}) {
   }
 
   if (name === "reltime_anchor_file") {
-    const filePath = path.resolve(args.file_path);
-    if (!fs.existsSync(filePath)) {
-      throw new Error(`File not found at path: ${filePath}`);
-    }
     if (!key) {
-      throw new Error(
-        "Missing RELTIME_API_KEY. Please ask the user which API key pack they would like to provision first before calling `reltime_provision_agent_key`:\n1. **Agent Launch Pack (`pack: \"launch\"`, $5 / 50 Hashes):** Priority 10-Min Bitcoin Queue · Standard Mode only (Data Integrity + Biometric or Anonymous)\n2. **Autonomous Agents (`pack: \"standard\"`, $50 / 500 Hashes):** Dynamic 6-Hr Batch Queue · Temporal Mode (T_index sequencing) + Standard Mode · Reloadable anytime"
+      return buildPackSelectionPrompt(
+        "Before anchoring files, a Rel-Time API key is required. Ask the user which pack they want to provision first:"
       );
     }
+    const filePath = resolveLocalFilePath(args.file_path);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`File not found at path: ${filePath}`);
+    }
 
     // 1. Compute SHA-256 locally (Zero-Knowledge: raw file never leaves the device)
     const fileBuffer = fs.readFileSync(filePath);
@@ -631,7 +726,7 @@ async function executeTool(name, args = {}) {
   }
 
   if (name === "reltime_stamp_file") {
-    const filePath = path.resolve(args.file_path);
+    const filePath = resolveLocalFilePath(args.file_path);
     if (!fs.existsSync(filePath)) {
       throw new Error(`File not found at path: ${filePath}`);
     }
@@ -659,8 +754,8 @@ async function executeTool(name, args = {}) {
 
   if (name === "reltime_anchor_hash") {
     if (!key) {
-      throw new Error(
-        "Missing RELTIME_API_KEY. Please ask the user which API key pack they would like to provision first before calling `reltime_provision_agent_key`: 1) Agent Launch Pack (`pack: \"launch\"`, $5 / 50 Hashes · 10-Min Queue · Standard Mode only) or 2) Autonomous Agents (`pack: \"standard\"`, $50 / 500 Hashes · 6-Hr Queue · Temporal & Standard Modes)."
+      return buildPackSelectionPrompt(
+        "Before anchoring hashes, a Rel-Time API key is required. Ask the user which pack they want to provision first:"
       );
     }
     const clientHash = (args.client_hash || "").trim().toLowerCase();
@@ -746,13 +841,26 @@ async function executeTool(name, args = {}) {
 
   if (name === "reltime_account_status") {
     if (!key) {
-      throw new Error("Missing RELTIME_API_KEY.");
+      return buildPackSelectionPrompt(
+        "Rel-Time MCP is connected! No API key is saved yet. Ask the user which pack they would like to provision first:"
+      );
     }
     const res = await fetch(`${API_BASE}/account`, {
       headers: { Authorization: `Bearer ${key}` },
     });
-    const data = await res.json();
+    const text = await res.text();
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch (e) {
+      throw new Error(`Rel-Time Account error (${res.status}) from ${API_BASE}/account: ${text.slice(0, 200)}`);
+    }
     if (!res.ok) {
+      if (res.status === 401 || res.status === 403) {
+        return buildPackSelectionPrompt(
+          "The configured API key was not recognized. Ask the user which pack they would like to provision:"
+        );
+      }
       throw new Error(`Rel-Time Account error (${res.status}): ${JSON.stringify(data)}`);
     }
     return data;
@@ -761,33 +869,9 @@ async function executeTool(name, args = {}) {
   if (name === "reltime_provision_agent_key") {
     if (args.action === "create_invoice") {
       if (args.pack !== "launch" && args.pack !== "standard") {
-        return {
-          status: "pack_selection_required",
-          message:
-            "Please ask the user which Rel-Time Agent API Key pack they would like to provision before generating the Lightning invoice:",
-          available_packs: [
-            {
-              pack: "launch",
-              name: "Agent Launch Pack",
-              price_usd: "$5.00",
-              credits: 50,
-              settlement_queue: "Priority 10-Minute Bitcoin Queue",
-              hashing_modes: "Standard Mode only (Data Integrity + Biometric or Anonymous)",
-              outputs: "64-Ray Sun-Stamp SVG + 1-Click Stamped Copy (.PDF/.PNG) + .JSON Doomsday Proof",
-            },
-            {
-              pack: "standard",
-              name: "Autonomous Agents",
-              price_usd: "$50.00",
-              credits: 500,
-              settlement_queue: "Dynamic 6-Hour Batch Queue",
-              hashing_modes: "Temporal Mode (T_index sub-second VDF sequencing) + Standard Mode (Biometric or Anonymous)",
-              outputs: "64-Ray Sun-Stamp SVG + 1-Click Stamped Copy (.PDF/.PNG) + .JSON Doomsday Proof + Reloadable anytime (+500 credits / $50)",
-            },
-          ],
-          next_step:
-            "Once the user chooses, call `reltime_provision_agent_key` with `action: 'create_invoice'` and `pack: 'launch'` or `pack: 'standard'`.",
-        };
+        return buildPackSelectionPrompt(
+          "Please ask the user which Rel-Time Agent API Key pack they would like to provision before generating the Lightning invoice:"
+        );
       }
 
       LAST_INVOICE_PACK = args.pack;
@@ -799,7 +883,40 @@ async function executeTool(name, args = {}) {
           pack: args.pack,
         }),
       });
-      return await res.json();
+      const data = await res.json();
+      const bolt11 = data.ln_invoice || data.bolt11 || "";
+      if (bolt11) {
+        try {
+          if (!fs.existsSync(PASSKEY_CONFIG_DIR)) {
+            fs.mkdirSync(PASSKEY_CONFIG_DIR, { recursive: true, mode: 0o700 });
+          }
+          const qrPngBuffer = await QRCode.toBuffer(bolt11.toUpperCase(), {
+            type: "png",
+            width: 560,
+            margin: 2,
+            errorCorrectionLevel: "M",
+          });
+          const homeQrPath = path.join(PASSKEY_CONFIG_DIR, "lightning-invoice-qr.png");
+          const tmpQrPath = "/tmp/reltime-lightning-qr.png";
+          fs.writeFileSync(homeQrPath, qrPngBuffer);
+          try {
+            fs.writeFileSync(tmpQrPath, qrPngBuffer);
+          } catch (e) {
+            // Ignore /tmp write error
+          }
+          data.bolt11 = bolt11;
+          data.ln_invoice = bolt11;
+          data.qr_code_png_path = homeQrPath;
+          data.qr_code_tmp_png_path = tmpQrPath;
+          data.invoice_expiration = "60 minutes (3,600 seconds)";
+          data.mandatory_first_reply_instructions =
+            "CRITICAL INSTRUCTION FOR AI AGENT: On this very first reply, you MUST show the user BOTH: (1) the scannable QR code image (immediately call your Read tool on `qr_code_png_path` BEFORE sending your message so the QR code PNG renders inline in the chat window right now!) AND (2) the full, un-truncated `bolt11` (`lnbc...`) Lightning invoice string inside a copyable code block so the user can either scan with their phone or copy-paste on the first try without asking!";
+          data._mcp_image_base64 = qrPngBuffer.toString("base64");
+        } catch (qrErr) {
+          data.qr_error = qrErr.message;
+        }
+      }
+      return data;
     } else if (args.action === "claim_invoice") {
       if (!args.invoice_id) throw new Error("invoice_id is required when action is 'claim_invoice'.");
       const resolvedPack = args.pack || LAST_INVOICE_PACK || undefined;
@@ -879,16 +996,25 @@ rl.on("line", async (line) => {
       const toolArgs = params?.arguments || {};
       try {
         const resultObj = await executeTool(toolName, toolArgs);
+        const contentItems = [];
+        if (resultObj && resultObj._mcp_image_base64) {
+          const b64 = resultObj._mcp_image_base64;
+          delete resultObj._mcp_image_base64;
+          contentItems.push({
+            type: "image",
+            data: b64,
+            mimeType: "image/png",
+          });
+        }
+        contentItems.push({
+          type: "text",
+          text: JSON.stringify(resultObj, null, 2),
+        });
         sendJsonRpc({
           jsonrpc: "2.0",
           id,
           result: {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(resultObj, null, 2),
-              },
-            ],
+            content: contentItems,
           },
         });
       } catch (toolErr) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rel-time/mcp-server",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Official Model Context Protocol (MCP) server for Rel-Time (rel-time.com) — Zero-Knowledge Bitcoin & VDF Provenance, Local File Hashing, and Sun-Stamp Generation for Claude, Cursor, Windsurf, and Antigravity.",
   "main": "index.js",
   "bin": {
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "pdf-lib": "^1.17.1",
+    "qrcode": "^1.5.4",
     "sharp": "^0.35.5"
   }
 }