@rel-time/mcp-server 0.0.0-stage → 1.2.0

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# `@rel-time/mcp-server` — Official Rel-Time MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official Model Context Protocol (MCP) server for **[Rel-Time](https://rel-time.com)** — enabling Claude Desktop, Cursor, Windsurf, and Google Antigravity agents to:
+1. **Hash local files with 100% Zero-Knowledge** (your file bytes never leave your computer).
+2. **Execute both Anonymous & Biometric (Passkey) Anchors** (`SHA256(File_Hash + Passkey_PubKey)`) using TouchID, FaceID, or YubiKey via `https://rel-time.com/mcp-passkey`.
+3. **Anchor SHA-256 hashes to the Bitcoin Timechain & Rel-Time VDF** (`POST /v1/anchor`).
+4. **Generate & overlay 64-ray Sun-Stamps onto PDFs and Images** (`reltime-stamped-<name>.pdf` / `.png`).
+5. **Verify Bitcoin block settlement & Merkle proofs** (`GET /v1/proof/{hash}`).
+6. **Self-provision or Reload (+500 Hash Credits / $50) an Autonomous Agent API key via Lightning** (`POST /v1/agent/invoice` & `POST /v1/agent/claim`).
+
+---
+
+## Quick Setup (Claude Desktop / Cursor / Windsurf / Antigravity)
+
+Add the following to your `claude_desktop_config.json` or `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "rel-time": {
+      "command": "npx",
+      "args": ["-y", "@rel-time/mcp-server"],
+      "env": {
+        "RELTIME_API_KEY": "YOUR_RELTIME_API_KEY"
+      }
+    }
+  }
+}
+```
+
+*(Note: `reltime_link_passkey`, `reltime_get_sun_stamp`, `reltime_check_proof`, and `reltime_provision_agent_key` work immediately even without an API key configured!)*
+
+---
+
+## Available MCP Tools
+
+| Tool Name | Requires Key? | What It Does |
+| :--- | :---: | :--- |
+| `reltime_anchor_file` | Yes | Computes the SHA-256 hash of a local file **on your machine** (0 bytes uploaded), supports `biometric: true` for **Biometric Anchors** (TouchID/FaceID/YubiKey), anchors via `POST /v1/anchor`, saves `reltime-stamp-<filename>.svg` and `reltime-doomsday-proof-<filename>.json`, and automatically outputs a **Stamped Copy** (`reltime-stamped-<name>.pdf` or `.png`). |
+| `reltime_link_passkey` | **No** | Opens `https://rel-time.com/mcp-passkey` in the system browser so the user can touch TouchID / FaceID / YubiKey once, saving `{ public_key_hex, passkey_signature }` to `~/.reltime/passkey.json` for seamless Biometric Anchors. |
+| `reltime_stamp_file` | **No** | Overlays the authentic 64-ray Sun-Stamp onto the bottom-right corner of any local PDF or Image (`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`) 100% locally. |
+| `reltime_anchor_hash` | Yes | Anchors any 64-char hex SHA-256 hash in `standard` (10-min Express / Integrity) or `temporal` (VDF sequence ordering) mode. |
+| `reltime_get_sun_stamp` | **No** | Fetches the deterministic 64-ray SVG Sun-Stamp (`GET /v1/stamp/{hash}`) and returns ready-to-paste Markdown/HTML badge snippets. |
+| `reltime_check_proof` | **No** | Queries `GET /v1/proof/{hash}` for Bitcoin TXID, Block Height, UTC Timestamp, and Merkle inclusion path, and optionally saves/updates the `.json` Doomsday Proof receipt on disk. |
+| `reltime_account_status` | Yes | Checks remaining Hash Credits and tier status (`GET /v1/account`). |
+| `reltime_provision_agent_key` | **No** | Generates a Lightning invoice (`$50` for 500 Hash Credits) and claims either a brand-new Tier 4 Autonomous Agent API key or **reloads `+500` Hash Credits into an existing key** (`reload_existing: true` or `api_key`). |

package/index.js

@@ -0,0 +1,846 @@
+#!/usr/bin/env node
+
+/**
+ * @rel-time/mcp-server
+ * Official Model Context Protocol (MCP) Server for Rel-Time (https://rel-time.com)
+ *
+ * Zero-Knowledge Local File Hashing + Biometric Anchor (Passkey) +
+ * Bitcoin Timechain Anchoring + Deterministic Sun-Stamp SVG +
+ * 1-Click Option A Stamped Copy (.PDF / .PNG).
+ * Uses native Node.js (>=18) crypto, fs, http, and fetch over JSON-RPC 2.0 stdio transport.
+ */
+
+const crypto = require("crypto");
+const fs = require("fs");
+const http = require("http");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+const { exec } = require("child_process");
+const { PDFDocument } = require("pdf-lib");
+const sharp = require("sharp");
+
+const API_BASE = (process.env.RELTIME_API_URL || "https://api.rel-time.com/v1").replace(/\/+$/, "");
+const WEB_BASE = (process.env.RELTIME_WEB_URL || "https://rel-time.com").replace(/\/+$/, "");
+let CURRENT_API_KEY = process.env.RELTIME_API_KEY || "";
+
+const PASSKEY_CONFIG_DIR = path.join(os.homedir(), ".reltime");
+const PASSKEY_CONFIG_PATH = path.join(PASSKEY_CONFIG_DIR, "passkey.json");
+
+const SERVER_INFO = {
+  name: "rel-time-mcp-server",
+  version: "1.2.0",
+};
+
+/**
+ * Loads linked Passkey credentials from env vars or ~/.reltime/passkey.json.
+ */
+function loadSavedPasskey() {
+  if (process.env.RELTIME_PASSKEY_PUBKEY && process.env.RELTIME_PASSKEY_TOKEN) {
+    return {
+      public_key_hex: process.env.RELTIME_PASSKEY_PUBKEY.trim(),
+      passkey_signature: process.env.RELTIME_PASSKEY_TOKEN.trim(),
+      source: "env",
+    };
+  }
+  try {
+    if (fs.existsSync(PASSKEY_CONFIG_PATH)) {
+      const parsed = JSON.parse(fs.readFileSync(PASSKEY_CONFIG_PATH, "utf8"));
+      if (parsed.public_key_hex && parsed.passkey_signature) {
+        return {
+          public_key_hex: parsed.public_key_hex.trim(),
+          passkey_signature: parsed.passkey_signature.trim(),
+          source: PASSKEY_CONFIG_PATH,
+        };
+      }
+    }
+  } catch (e) {
+    // Ignore corrupted file
+  }
+  return null;
+}
+
+/**
+ * Saves Passkey credentials to ~/.reltime/passkey.json with 0600 permissions.
+ */
+function savePasskeyConfig(publicKeyHex, passkeySignature) {
+  if (!fs.existsSync(PASSKEY_CONFIG_DIR)) {
+    fs.mkdirSync(PASSKEY_CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  const payload = {
+    public_key_hex: publicKeyHex.trim(),
+    passkey_signature: passkeySignature.trim(),
+    linked_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(PASSKEY_CONFIG_PATH, JSON.stringify(payload, null, 2), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  return payload;
+}
+
+/**
+ * Opens a URL in the user's default system browser.
+ */
+function openSystemBrowser(url) {
+  const platform = process.platform;
+  const cmd =
+    platform === "darwin"
+      ? `open "${url}"`
+      : platform === "win32"
+      ? `start "" "${url}"`
+      : `xdg-open "${url}"`;
+  exec(cmd);
+}
+
+/**
+ * Launches a temporary 127.0.0.1 HTTP callback listener and opens the
+ * Rel-Time WebAuthn Passkey Bridge in the user's browser so they can touch
+ * TouchID / FaceID / YubiKey.
+ */
+function launchBrowserPasskeyBridge(timeoutMs = 120000) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      const parsedUrl = new URL(req.url, "http://127.0.0.1");
+      if (parsedUrl.pathname === "/callback") {
+        const pubKey = parsedUrl.searchParams.get("public_key_hex") || parsedUrl.searchParams.get("public_key");
+        const token = parsedUrl.searchParams.get("passkey_signature");
+        if (pubKey && token) {
+          const saved = savePasskeyConfig(pubKey, token);
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ status: "linked" }));
+          clearTimeout(timer);
+          server.close();
+          resolve(saved);
+          return;
+        }
+      }
+
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing public_key_hex or passkey_signature" }));
+    });
+
+    const timer = setTimeout(() => {
+      server.close();
+      reject(
+        new Error(
+          `Timed out waiting for hardware Passkey touch in browser. Please complete the prompt at ${WEB_BASE}/mcp-passkey or pass public_key_hex and passkey_signature directly to reltime_link_passkey.`
+        )
+      );
+    }, timeoutMs);
+
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = address.port;
+      const bridgeUrl = `${WEB_BASE}/mcp-passkey?port=${port}`;
+      openSystemBrowser(bridgeUrl);
+    });
+  });
+}
+
+/**
+ * Stamps the Option A (pure crisp 64-ray Sun-Stamp, 0% glare, no pill) onto a local Image or PDF.
+ * Returns { stamped: true, output_path, format } or { stamped: false, reason }.
+ */
+async function stampLocalFileOptionA(filePath, svgContent, customOutputPath = null) {
+  const ext = path.extname(filePath).toLowerCase().replace(/^\./, "");
+  const dir = path.dirname(filePath);
+  const baseName = path.basename(filePath, path.extname(filePath));
+
+  const isImage = ["png", "jpg", "jpeg", "webp", "gif"].includes(ext);
+  const isPdf = ext === "pdf";
+
+  if (!isImage && !isPdf) {
+    return {
+      stamped: false,
+      reason: "Feature unavailable for this file type (visual Sun-Stamp overlay is only available for Images and PDFs).",
+    };
+  }
+
+  if (isImage) {
+    const outPath = customOutputPath ? path.resolve(customOutputPath) : path.join(dir, `reltime-stamped-${baseName}.png`);
+    const img = sharp(filePath);
+    const meta = await img.metadata();
+    const w = meta.width || 1200;
+    const h = meta.height || 800;
+
+    const minDim = Math.min(w, h);
+    const badgeSize = Math.max(130, Math.min(420, Math.round(minDim * 0.22)));
+    const margin = Math.max(12, Math.round(minDim * 0.025));
+
+    const stampPngBuffer = await sharp(Buffer.from(svgContent, "utf8"))
+      .resize(badgeSize, badgeSize)
+      .png()
+      .toBuffer();
+
+    const left = Math.max(0, w - badgeSize - margin);
+    const top = Math.max(0, h - badgeSize - margin);
+
+    await img
+      .composite([{ input: stampPngBuffer, left, top }])
+      .png()
+      .toFile(outPath);
+
+    return {
+      stamped: true,
+      format: "PNG",
+      output_path: outPath,
+    };
+  }
+
+  if (isPdf) {
+    const outPath = customOutputPath ? path.resolve(customOutputPath) : path.join(dir, `reltime-stamped-${baseName}.pdf`);
+    const pdfBytes = fs.readFileSync(filePath);
+    const pdfDoc = await PDFDocument.load(pdfBytes, { ignoreEncryption: true });
+    const pages = pdfDoc.getPages();
+    if (pages.length === 0) {
+      throw new Error("PDF has no pages.");
+    }
+
+    const firstPage = pages[0];
+    const { width, height } = firstPage.getSize();
+
+    // Render high-DPI 480x480 Option A Sun-Stamp PNG (pure crisp SVG, 0% glare, no pill)
+    const stampPngBuffer = await sharp(Buffer.from(svgContent, "utf8"))
+      .resize(480, 480)
+      .png()
+      .toBuffer();
+
+    const pngImage = await pdfDoc.embedPng(stampPngBuffer);
+    const targetSize = Math.min(135, Math.max(85, Math.min(width, height) * 0.2));
+    const margin = 18;
+
+    firstPage.drawImage(pngImage, {
+      x: Math.max(margin, width - targetSize - margin),
+      y: margin,
+      width: targetSize,
+      height: targetSize,
+    });
+
+    const modifiedPdfBytes = await pdfDoc.save();
+    fs.writeFileSync(outPath, Buffer.from(modifiedPdfBytes));
+
+    return {
+      stamped: true,
+      format: "PDF",
+      output_path: outPath,
+    };
+  }
+}
+
+const TOOLS = [
+  {
+    name: "reltime_anchor_file",
+    description:
+      "Zero-knowledge file anchoring + 1-Click Stamped Copy: Computes the SHA-256 hash of a local file ENTIRELY ON THE LOCAL MACHINE (the file never leaves the user's computer), supports both Anonymous and Biometric (Passkey) Anchors, anchors the 64-char hash to the Bitcoin Timechain via Rel-Time, saves the 64-ray Sun-Stamp SVG and JSON Doomsday Proof, and automatically creates a Stamped Copy (`reltime-stamped-<name>.pdf` or `.png`) with the Sun-Stamp overlaid in the bottom-right corner for PDFs and Images.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: {
+          type: "string",
+          description: "Absolute path to the local file to hash and anchor.",
+        },
+        biometric: {
+          type: "boolean",
+          description:
+            "If true, performs a Biometric Anchor using your linked hardware Passkey (TouchID / FaceID / YubiKey) so the anchored hash (`SHA256(File_Hash + Passkey_PubKey)`) and Sun-Stamp mathematically prove your personal authorship. If no Passkey is linked yet, automatically opens the browser TouchID/FaceID prompt.",
+        },
+        anchor_mode: {
+          type: "string",
+          enum: ["standard", "temporal"],
+          description:
+            "Use 'standard' (default) to anchor the file/biometric SHA-256 hash into the Bitcoin Merkle tree for standalone file verification, or 'temporal' to anchor the VDF Thermodynamic Proof (T_index) for sub-second sequential ordering.",
+        },
+        save_sun_stamp_svg: {
+          type: "boolean",
+          description: "If true (default), saves `reltime-stamp-<filename>.svg` in the same folder as the file.",
+        },
+        save_stamped_copy: {
+          type: "boolean",
+          description:
+            "If true (default), automatically generates `reltime-stamped-<name>.pdf` or `.png` with the crisp 64-ray Sun-Stamp in the bottom-right corner when the file is a PDF or Image.",
+        },
+        api_key: {
+          type: "string",
+          description: "Optional override for RELTIME_API_KEY (Autonomous Agent, Universal Anchor, or Enterprise Superhighway key).",
+        },
+      },
+      required: ["file_path"],
+    },
+  },
+  {
+    name: "reltime_link_passkey",
+    description:
+      "Links the user's hardware Passkey (TouchID, FaceID, or YubiKey) to `@rel-time/mcp-server` for Biometric Anchors. Opens `https://rel-time.com/mcp-passkey` in the system browser, waits for the user's biometric touch, and saves `{ public_key_hex, passkey_signature }` to `~/.reltime/passkey.json`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        public_key_hex: {
+          type: "string",
+          description: "Optional: Directly provide the COSE public_key_hex from https://rel-time.com/mcp-passkey without opening a browser window.",
+        },
+        passkey_signature: {
+          type: "string",
+          description: "Optional: Directly provide the passkey_signature session token from https://rel-time.com/mcp-passkey.",
+        },
+      },
+    },
+  },
+  {
+    name: "reltime_stamp_file",
+    description:
+      "Overlays the authentic 64-ray Rel-Time Sun-Stamp (Option A: pure crisp Sun-Stamp, zero glare, no pill) onto the bottom-right corner of a local PDF or Image (.png, .jpg, .jpeg, .webp, .gif) 100% locally. Returns 'Feature unavailable for this file type' for other file formats.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: {
+          type: "string",
+          description: "Absolute path to the local PDF or Image file.",
+        },
+        hash: {
+          type: "string",
+          description:
+            "Optional 64-char hex hash to generate the Sun-Stamp from. If omitted, computes the SHA-256 hash of `file_path` locally.",
+        },
+        output_path: {
+          type: "string",
+          description: "Optional custom output file path for the stamped copy.",
+        },
+      },
+      required: ["file_path"],
+    },
+  },
+  {
+    name: "reltime_anchor_hash",
+    description:
+      "Anchors a 64-character hexadecimal SHA-256 hash directly into the Rel-Time VDF & Bitcoin Merkle Tree. Consumes 1 Hash Credit from the configured Rel-Time API key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        client_hash: {
+          type: "string",
+          description: "64-character hex SHA-256 hash of the payload/artifact.",
+        },
+        anchor_mode: {
+          type: "string",
+          enum: ["standard", "temporal"],
+          description: "'standard' (Data Integrity) or 'temporal' (VDF Sequence Ordering).",
+        },
+        api_key: {
+          type: "string",
+          description: "Optional override for RELTIME_API_KEY.",
+        },
+      },
+      required: ["client_hash"],
+    },
+  },
+  {
+    name: "reltime_get_sun_stamp",
+    description:
+      "Generates and downloads the official 64-ray Rel-Time Sun-Stamp SVG (`GET /v1/stamp/{hash}`) for any 64-char SHA-256 hash or T_index. Requires NO API key and works across all tiers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        hash: {
+          type: "string",
+          description: "64-character hex SHA-256 hash (client_hash or t_index).",
+        },
+        output_svg_path: {
+          type: "string",
+          description: "Optional local file path where the `.svg` Sun-Stamp should be saved.",
+        },
+      },
+      required: ["hash"],
+    },
+  },
+  {
+    name: "reltime_check_proof",
+    description:
+      "Queries `GET /v1/proof/{hash}` to check the Bitcoin settlement status (Block Height, Block UTC Time, Bitcoin TXID, Merkle Root, and Merkle Inclusion Path) of an anchored hash. Optionally saves or updates the finalized `.json` Doomsday Proof receipt on disk when settled.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        hash: {
+          type: "string",
+          description: "The 64-character client_hash or t_index to verify.",
+        },
+        output_json_path: {
+          type: "string",
+          description: "Optional local file path to save the settled JSON Doomsday Proof receipt.",
+        },
+      },
+      required: ["hash"],
+    },
+  },
+  {
+    name: "reltime_account_status",
+    description:
+      "Checks the remaining Hash Credits, tier, and lifetime usage of the configured Rel-Time API key (`GET /v1/account`).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        api_key: {
+          type: "string",
+          description: "Optional override for RELTIME_API_KEY.",
+        },
+      },
+    },
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["create_invoice", "claim_invoice"],
+          description:
+            "'create_invoice' generates a BOLT11 Lightning invoice; 'claim_invoice' exchanges a paid invoice_id for a new API key or reloads an existing API key.",
+        },
+        pack: {
+          type: "string",
+          enum: ["launch", "standard"],
+          description:
+            "Optional: 'launch' ($5 for 50 Hash Credits) or 'standard' (default, $50 for 500 Hash Credits).",
+        },
+        invoice_id: {
+          type: "string",
+          description: "Required when action is 'claim_invoice'.",
+        },
+        api_key: {
+          type: "string",
+          description:
+            "Optional when action is 'claim_invoice': pass an existing `rel_key_agent_...` key (or omit to use RELTIME_API_KEY if reload_existing is true) to reload Hash Credits into that key without rotating it.",
+        },
+        reload_existing: {
+          type: "boolean",
+          description:
+            "If true during 'claim_invoice', reloads Hash Credits into the currently configured RELTIME_API_KEY (or passed `api_key`) instead of generating a new key.",
+        },
+      },
+      required: ["action"],
+    },
+  },
+];
+
+async function executeTool(name, args = {}) {
+  const key = (args.api_key || CURRENT_API_KEY || "").trim();
+
+  if (name === "reltime_link_passkey") {
+    if (args.public_key_hex && args.passkey_signature) {
+      const saved = savePasskeyConfig(args.public_key_hex, args.passkey_signature);
+      return {
+        status: "linked",
+        mode: "direct",
+        config_path: PASSKEY_CONFIG_PATH,
+        public_key_hex: saved.public_key_hex,
+        linked_at: saved.linked_at,
+        message: "Hardware Passkey linked! You can now call reltime_anchor_file with biometric: true.",
+      };
+    }
+
+    const saved = await launchBrowserPasskeyBridge();
+    return {
+      status: "linked",
+      mode: "browser_webauthn_bridge",
+      config_path: PASSKEY_CONFIG_PATH,
+      public_key_hex: saved.public_key_hex,
+      linked_at: saved.linked_at,
+      message: "Hardware Passkey verified via TouchID/FaceID and saved to ~/.reltime/passkey.json! You can now call reltime_anchor_file with biometric: true.",
+    };
+  }
+
+  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. 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);
+    const originalFileHash = crypto.createHash("sha256").update(fileBuffer).digest("hex");
+    const anchorMode = args.anchor_mode || "standard";
+
+    let clientHash = originalFileHash;
+    let passkeyCreds = null;
+
+    if (args.biometric) {
+      passkeyCreds = loadSavedPasskey();
+      if (!passkeyCreds) {
+        // Automatically launch the browser TouchID / FaceID bridge if not linked yet
+        passkeyCreds = await launchBrowserPasskeyBridge();
+      }
+      clientHash = crypto
+        .createHash("sha256")
+        .update(`${originalFileHash}${passkeyCreds.public_key_hex}`, "utf8")
+        .digest("hex");
+    }
+
+    const requestBody = {
+      client_hash: clientHash,
+      anchor_mode: anchorMode,
+    };
+
+    if (args.biometric && passkeyCreds) {
+      requestBody.original_file_hash = originalFileHash;
+      requestBody.passkey_signature = passkeyCreds.passkey_signature;
+    }
+
+    // 2. Anchor the hash via POST /v1/anchor
+    const res = await fetch(`${API_BASE}/anchor`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      throw new Error(`Rel-Time API error (${res.status}): ${JSON.stringify(data)}`);
+    }
+
+    const tIndex = data.t_index || data.thermodynamic_proof;
+    const lookupHash = anchorMode === "temporal" ? tIndex : clientHash;
+    const verifyUrl = `https://rel-time.com/verify?t=${lookupHash}`;
+    const stampEndpointUrl = `${API_BASE}/stamp/${lookupHash}`;
+
+    const svgContent = data.visual_fingerprint || (await (await fetch(stampEndpointUrl)).text());
+
+    let savedSvgPath = null;
+    if (args.save_sun_stamp_svg !== false) {
+      savedSvgPath = path.join(path.dirname(filePath), `reltime-stamp-${path.basename(filePath)}.svg`);
+      fs.writeFileSync(savedSvgPath, svgContent, "utf8");
+    }
+
+    // Save initial Doomsday Proof JSON alongside the file
+    const savedProofJsonPath = path.join(
+      path.dirname(filePath),
+      `reltime-doomsday-proof-${path.basename(filePath)}.json`
+    );
+    fs.writeFileSync(
+      savedProofJsonPath,
+      JSON.stringify(
+        {
+          protocol: "Rel-Time Sovereign Provenance Protocol",
+          file_name: path.basename(filePath),
+          identity_mode: args.biometric ? "BIOMETRIC_PASSKEY" : "ANONYMOUS",
+          original_file_sha256_hash: originalFileHash,
+          anchored_client_hash: clientHash,
+          signer_public_key: passkeyCreds ? passkeyCreds.public_key_hex : null,
+          t_index: tIndex,
+          vdf_ticks: data.vdf_ticks || data.solar_ticks,
+          anchor_mode: data.anchor_mode || anchorMode,
+          status: data.status || "pending_finality",
+          verify_url: verifyUrl,
+          sun_stamp_svg_url: stampEndpointUrl,
+          settlement: data.settlement || null,
+        },
+        null,
+        2
+      ),
+      "utf8"
+    );
+
+    // 3. Automatically generate Stamped Copy (.PDF or .PNG) for PDFs and Images
+    let stampedCopyResult = null;
+    if (args.save_stamped_copy !== false) {
+      stampedCopyResult = await stampLocalFileOptionA(filePath, svgContent);
+    }
+
+    return {
+      status: data.status || "pending_finality",
+      file_name: path.basename(filePath),
+      identity_mode: args.biometric ? "Biometric Anchor (Passkey)" : "Anonymous Anchor",
+      original_file_sha256_hash: originalFileHash,
+      local_sha256_hash: clientHash,
+      signer_public_key: passkeyCreds ? passkeyCreds.public_key_hex : null,
+      t_index: tIndex,
+      vdf_ticks: data.vdf_ticks || data.solar_ticks,
+      anchor_mode: data.anchor_mode || anchorMode,
+      epoch_target: data.epoch_target,
+      verify_url: verifyUrl,
+      sun_stamp_svg_url: stampEndpointUrl,
+      saved_sun_stamp_svg_path: savedSvgPath,
+      saved_doomsday_proof_json_path: savedProofJsonPath,
+      stamped_copy: stampedCopyResult,
+      zero_knowledge_guarantee:
+        "File was hashed and stamped 100% locally on your machine; 0 bytes of file content were transmitted.",
+    };
+  }
+
+  if (name === "reltime_stamp_file") {
+    const filePath = path.resolve(args.file_path);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`File not found at path: ${filePath}`);
+    }
+    const targetHash = args.hash
+      ? args.hash.trim().toLowerCase()
+      : crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+
+    if (!/^[0-9a-f]{64}$/.test(targetHash)) {
+      throw new Error("hash must be a valid 64-character hexadecimal SHA-256 string.");
+    }
+
+    const stampRes = await fetch(`${API_BASE}/stamp/${targetHash}`);
+    if (!stampRes.ok) {
+      throw new Error(`Failed to fetch Sun-Stamp (${stampRes.status}): ${await stampRes.text()}`);
+    }
+    const svgContent = await stampRes.text();
+    const result = await stampLocalFileOptionA(filePath, svgContent, args.output_path || null);
+    return {
+      file_path: filePath,
+      hash: targetHash,
+      verify_url: `https://rel-time.com/verify?t=${targetHash}`,
+      ...result,
+    };
+  }
+
+  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`.");
+    }
+    const clientHash = (args.client_hash || "").trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(clientHash)) {
+      throw new Error("client_hash must be a valid 64-character hexadecimal SHA-256 string.");
+    }
+    const anchorMode = args.anchor_mode || "standard";
+
+    const res = await fetch(`${API_BASE}/anchor`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        client_hash: clientHash,
+        anchor_mode: anchorMode,
+      }),
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      throw new Error(`Rel-Time API error (${res.status}): ${JSON.stringify(data)}`);
+    }
+
+    const tIndex = data.t_index || data.thermodynamic_proof;
+    const lookupHash = anchorMode === "temporal" ? tIndex : clientHash;
+
+    return {
+      status: data.status,
+      client_hash: clientHash,
+      t_index: tIndex,
+      vdf_ticks: data.vdf_ticks || data.solar_ticks,
+      anchor_mode: data.anchor_mode || anchorMode,
+      epoch_target: data.epoch_target,
+      verify_url: `https://rel-time.com/verify?t=${lookupHash}`,
+      sun_stamp_svg_url: `${API_BASE}/stamp/${lookupHash}`,
+    };
+  }
+
+  if (name === "reltime_get_sun_stamp") {
+    const hash = (args.hash || "").trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(hash)) {
+      throw new Error("hash must be a 64-character hexadecimal SHA-256 string.");
+    }
+    const stampUrl = `${API_BASE}/stamp/${hash}`;
+    const res = await fetch(stampUrl);
+    if (!res.ok) {
+      throw new Error(`Failed to fetch Sun-Stamp (${res.status}): ${await res.text()}`);
+    }
+    const svg = await res.text();
+    let savedPath = null;
+    if (args.output_svg_path) {
+      savedPath = path.resolve(args.output_svg_path);
+      fs.writeFileSync(savedPath, svg, "utf8");
+    }
+    return {
+      hash,
+      sun_stamp_svg_url: stampUrl,
+      verify_url: `https://rel-time.com/verify?t=${hash}`,
+      saved_svg_path: savedPath,
+      embed_markdown: `[![Anchored on Bitcoin via Rel-Time](${stampUrl})](https://rel-time.com/verify?t=${hash})`,
+      embed_html: `<a href="https://rel-time.com/verify?t=${hash}" target="_blank" rel="noopener"><img src="${stampUrl}" alt="Rel-Time Sun-Stamp" width="160" height="160" /></a>`,
+    };
+  }
+
+  if (name === "reltime_check_proof") {
+    const hash = (args.hash || "").trim().toLowerCase();
+    const res = await fetch(`${API_BASE}/proof/${hash}`);
+    const data = await res.json();
+    const out = {
+      http_status: res.status,
+      verify_url: `https://rel-time.com/verify?t=${hash}`,
+      ...data,
+    };
+    if (args.output_json_path) {
+      const jsonPath = path.resolve(args.output_json_path);
+      fs.writeFileSync(jsonPath, JSON.stringify(out, null, 2), "utf8");
+      out.saved_json_path = jsonPath;
+    }
+    return out;
+  }
+
+  if (name === "reltime_account_status") {
+    if (!key) {
+      throw new Error("Missing RELTIME_API_KEY.");
+    }
+    const res = await fetch(`${API_BASE}/account`, {
+      headers: { Authorization: `Bearer ${key}` },
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      throw new Error(`Rel-Time Account error (${res.status}): ${JSON.stringify(data)}`);
+    }
+    return data;
+  }
+
+  if (name === "reltime_provision_agent_key") {
+    if (args.action === "create_invoice") {
+      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",
+        }),
+      });
+      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 claimPayload = {
+        invoice_id: args.invoice_id,
+        pack: args.pack === "launch" ? "launch" : undefined,
+      };
+      const targetReloadKey = args.api_key || (args.reload_existing ? CURRENT_API_KEY : "");
+      if (targetReloadKey && targetReloadKey.trim()) {
+        claimPayload.api_key = targetReloadKey.trim();
+      }
+      const res = await fetch(`${API_BASE}/agent/claim`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(claimPayload),
+      });
+      const data = await res.json();
+      if (data.api_key) {
+        CURRENT_API_KEY = data.api_key;
+      }
+      return data;
+    }
+    throw new Error(`Unknown action: ${args.action}`);
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+// Standard MCP JSON-RPC 2.0 over stdio
+const rl = readline.createInterface({
+  input: process.stdin,
+  terminal: false,
+});
+
+function sendJsonRpc(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+rl.on("line", async (line) => {
+  if (!line.trim()) return;
+  let req;
+  try {
+    req = JSON.parse(line);
+  } catch (e) {
+    return;
+  }
+
+  const { id, method, params } = req;
+
+  try {
+    if (method === "initialize") {
+      sendJsonRpc({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: (params && params.protocolVersion) || "2024-11-05",
+          capabilities: {
+            tools: {},
+          },
+          serverInfo: SERVER_INFO,
+        },
+      });
+    } else if (method === "notifications/initialized") {
+      // No response needed for notification
+    } else if (method === "tools/list") {
+      sendJsonRpc({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          tools: TOOLS,
+        },
+      });
+    } else if (method === "tools/call") {
+      const toolName = params?.name;
+      const toolArgs = params?.arguments || {};
+      try {
+        const resultObj = await executeTool(toolName, toolArgs);
+        sendJsonRpc({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(resultObj, null, 2),
+              },
+            ],
+          },
+        });
+      } catch (toolErr) {
+        sendJsonRpc({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Error: ${toolErr.message || String(toolErr)}`,
+              },
+            ],
+          },
+        });
+      }
+    } else if (method === "ping") {
+      sendJsonRpc({ jsonrpc: "2.0", id, result: {} });
+    } else if (id !== undefined) {
+      sendJsonRpc({
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32601, message: `Method not found: ${method}` },
+      });
+    }
+  } catch (err) {
+    if (id !== undefined) {
+      sendJsonRpc({
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32603, message: err.message || "Internal error" },
+      });
+    }
+  }
+});

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@rel-time/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "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": {
+    "mcp-server": "index.js",
+    "reltime-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "rel-time",
+    "bitcoin",
+    "provenance",
+    "timestamp",
+    "sun-stamp",
+    "vdf",
+    "passkey"
+  ],
+  "author": "Rel-Time Protocol (https://rel-time.com)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "pdf-lib": "^1.17.1",
+    "sharp": "^0.35.5"
+  }
+}