@rel-time/mcp-server 1.2.1 → 1.2.3

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

@@ -20,18 +20,123 @@ const { exec } = require("child_process");
 const { PDFDocument } = require("pdf-lib");
 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");
+const API_KEY_CONFIG_PATH = path.join(PASSKEY_CONFIG_DIR, "api_key.json");
+let LAST_INVOICE_PACK = null;
 
 const SERVER_INFO = {
   name: "rel-time-mcp-server",
-  version: "1.2.1",
+  version: "1.2.3",
 };
 
+/**
+ * Loads saved API key from ~/.reltime/api_key.json if not provided via env/args.
+ */
+function loadSavedApiKey() {
+  if (isValidApiKeyCandidate(CURRENT_API_KEY)) {
+    return CURRENT_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 (isValidApiKeyCandidate(parsed.api_key)) {
+        CURRENT_API_KEY = parsed.api_key.trim();
+        return CURRENT_API_KEY;
+      }
+    }
+  } catch (e) {
+    // Ignore corrupted file
+  }
+  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.
+ */
+function saveApiKeyConfig(apiKey, pack) {
+  if (!fs.existsSync(PASSKEY_CONFIG_DIR)) {
+    fs.mkdirSync(PASSKEY_CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  const payload = {
+    api_key: apiKey.trim(),
+    pack: pack || "standard",
+    saved_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(API_KEY_CONFIG_PATH, JSON.stringify(payload, null, 2), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  return payload;
+}
+
 /**
  * Loads linked Passkey credentials from env vars or ~/.reltime/passkey.json.
  */
@@ -383,13 +488,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.",
         },
       },
     },
@@ -397,7 +503,7 @@ const TOOLS = [
   {
     name: "reltime_provision_agent_key",
     description:
-      "Self-onboarding & Top-Up for Autonomous AI Agents: Requests a Bitcoin Lightning invoice (`POST /v1/agent/invoice`, $5 for 50 Hash Credits Launch Pack or $50 for 500 Hash Credits) or claims a paid invoice (`POST /v1/agent/claim`) to either provision a brand-new Tier 4 Autonomous Agent API key OR reload an existing key without changing the key.",
+      "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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -411,7 +517,7 @@ const TOOLS = [
           type: "string",
           enum: ["launch", "standard"],
           description:
-            "Optional: 'launch' ($5 for 50 Hash Credits) or 'standard' (default, $50 for 500 Hash Credits).",
+            "Which key pack the user selected: 'launch' (Agent Launch Pack — $5 for 50 Hash Credits, 10-Min Queue, Standard Mode only) or 'standard' (Autonomous Agents — $50 for 500 Hash Credits, 6-Hr Queue, Temporal & Standard Modes, reloadable). If omitted on 'create_invoice', the tool returns the two options so you can ask the user which pack they prefer.",
         },
         invoice_id: {
           type: "string",
@@ -434,7 +540,11 @@ const TOOLS = [
 ];
 
 async function executeTool(name, args = {}) {
-  const key = (args.api_key || CURRENT_API_KEY || "").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) {
@@ -461,15 +571,15 @@ async function executeTool(name, args = {}) {
   }
 
   if (name === "reltime_anchor_file") {
+    if (!key) {
+      return buildPackSelectionPrompt(
+        "Before anchoring files, a Rel-Time API key is required. Ask the user which pack they want to provision first:"
+      );
+    }
     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. Set RELTIME_API_KEY in your MCP config, pass `api_key`, or call `reltime_provision_agent_key` to get an Autonomous Agent key."
-      );
-    }
 
     // 1. Compute SHA-256 locally (Zero-Knowledge: raw file never leaves the device)
     const fileBuffer = fs.readFileSync(filePath);
@@ -614,7 +724,9 @@ async function executeTool(name, args = {}) {
 
   if (name === "reltime_anchor_hash") {
     if (!key) {
-      throw new Error("Missing RELTIME_API_KEY. Set RELTIME_API_KEY in your MCP config or pass `api_key`.");
+      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();
     if (!/^[0-9a-f]{64}$/.test(clientHash)) {
@@ -699,13 +811,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;
@@ -713,22 +838,30 @@ async function executeTool(name, args = {}) {
 
   if (name === "reltime_provision_agent_key") {
     if (args.action === "create_invoice") {
+      if (args.pack !== "launch" && args.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;
       const res = await fetch(`${API_BASE}/agent/invoice`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           accept_terms: true,
-          pack: args.pack === "launch" ? "launch" : "standard",
+          pack: args.pack,
         }),
       });
       return await res.json();
     } 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;
       const claimPayload = {
         invoice_id: args.invoice_id,
-        pack: args.pack === "launch" ? "launch" : undefined,
+        pack: resolvedPack === "launch" ? "launch" : undefined,
       };
-      const targetReloadKey = args.api_key || (args.reload_existing ? CURRENT_API_KEY : "");
+      const targetReloadKey = args.api_key || (args.reload_existing ? loadSavedApiKey() : "");
       if (targetReloadKey && targetReloadKey.trim()) {
         claimPayload.api_key = targetReloadKey.trim();
       }
@@ -740,6 +873,8 @@ async function executeTool(name, args = {}) {
       const data = await res.json();
       if (data.api_key) {
         CURRENT_API_KEY = data.api_key;
+        saveApiKeyConfig(data.api_key, resolvedPack || "standard");
+        data.saved_to_config = API_KEY_CONFIG_PATH;
       }
       return data;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rel-time/mcp-server",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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": {