@otskit/mcp 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+<p align="center">
+  <img src="docs/header.png" alt="OTSkit.ts MCP" width="480" />
+</p>
+
+# @otskit/mcp
+
+OpenTimestamps MCP server — stamp, upgrade, and verify timestamps via AI agents (Claude).
+
+## Installation
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Usage
+
+```bash
+ots-mcp
+```
+
+## Dependencies
+
+- [`@otskit/core`](../otskit-core) — OpenTimestamps core logic
+- [`@otskit/client`](../otskit-client) — OTS client
+- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) — MCP SDK
+- `better-sqlite3` — local database
+- `archiver` — ZIP support
+
+## Development
+
+```bash
+pnpm dev       # watch mode
+pnpm test      # run tests
+pnpm build     # production build
+```

package/dist/chunk-XG7E5YXZ.js

@@ -0,0 +1,367 @@
+import {
+  writeAtomic
+} from "./chunk-YFSUDT24.js";
+
+// src/config.ts
+import { readFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function getDataDir() {
+  return process.env.OTS_MCP_DATA_DIR ?? join(homedir(), ".ots-mcp");
+}
+var DEFAULTS = {
+  stamp_enabled: true,
+  preserve_enabled: true,
+  preserve_whitelist: [],
+  preserve_max_bytes: 104857600,
+  preserve_max_files: 1e4,
+  scheduler_interval_minutes: 30,
+  calendar_timeout_ms: 1e4,
+  calendar_max_response_bytes: 1048576,
+  retry_max_attempts: 20,
+  log_file: join(getDataDir(), "ots-mcp.log"),
+  calendars: [
+    "https://alice.btc.calendar.opentimestamps.org",
+    "https://bob.btc.calendar.opentimestamps.org",
+    "https://finney.calendar.eternitywall.com",
+    "https://btc.calendar.catallaxy.com"
+  ],
+  esplora_url: "https://blockstream.info/api"
+};
+function loadConfig() {
+  const dir = getDataDir();
+  mkdirSync(dir, { recursive: true });
+  const configPath = join(dir, "config.json");
+  if (!existsSync(configPath)) return { ...DEFAULTS };
+  const raw = JSON.parse(readFileSync(configPath, "utf8"));
+  return { ...DEFAULTS, ...raw };
+}
+
+// src/db/index.ts
+import DatabaseConstructor from "better-sqlite3";
+import { join as join2 } from "path";
+import { mkdirSync as mkdirSync2, statSync } from "fs";
+
+// src/db/schema.ts
+function initDb(db) {
+  db.pragma("journal_mode = WAL");
+  db.pragma("busy_timeout = 5000");
+  db.pragma("foreign_keys = ON");
+  runMigrations(db);
+}
+function runMigrations(db) {
+  const version = db.pragma("user_version", { simple: true });
+  if (version < 1) migrateTo1(db);
+}
+function migrateTo1(db) {
+  db.transaction(() => {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS stamps (
+        id              TEXT PRIMARY KEY,
+        hash            TEXT NOT NULL,
+        status          TEXT NOT NULL,
+        created_at      TEXT NOT NULL,
+        confirmed_at    TEXT,
+        bitcoin_block   INTEGER,
+        bitcoin_time    TEXT,
+        proof_path      TEXT,
+        archive_path    TEXT,
+        last_attempt_at TEXT,
+        attempt_count   INTEGER NOT NULL DEFAULT 0,
+        last_error      TEXT,
+        next_retry_at   TEXT,
+        metadata        TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_stamps_hash   ON stamps(hash);
+      CREATE INDEX IF NOT EXISTS idx_stamps_status ON stamps(status);
+
+      CREATE TABLE IF NOT EXISTS operations_log (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        stamp_id         TEXT NOT NULL REFERENCES stamps(id),
+        action           TEXT NOT NULL,
+        result           TEXT NOT NULL,
+        error_msg        TEXT,
+        calendar_uri     TEXT,
+        response_time_ms INTEGER,
+        created_at       TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_oplog_stamp_id ON operations_log(stamp_id);
+      CREATE INDEX IF NOT EXISTS idx_oplog_created  ON operations_log(created_at);
+    `);
+    db.pragma("user_version = 1");
+  })();
+}
+
+// src/db/index.ts
+var _db = null;
+function getDb() {
+  if (_db) return _db;
+  const dir = getDataDir();
+  mkdirSync2(dir, { recursive: true });
+  _db = new DatabaseConstructor(join2(dir, "db.sqlite"));
+  initDb(_db);
+  reconcileOrphans(_db);
+  return _db;
+}
+function backupDb(destPath) {
+  getDb().backup(destPath);
+}
+function reconcileOrphans(db) {
+  const pending = db.prepare(
+    `SELECT id, proof_path FROM stamps WHERE status = 'pending' AND proof_path IS NOT NULL`
+  ).all();
+  for (const row of pending) {
+    try {
+      statSync(row.proof_path);
+    } catch {
+      db.prepare(`UPDATE stamps SET status = 'failed', last_error = ? WHERE id = ?`).run("proof file missing on disk", row.id);
+    }
+  }
+}
+
+// src/tools/create-timestamp.ts
+import { mkdirSync as mkdirSync3 } from "fs";
+import { join as join3 } from "path";
+import { randomUUID } from "crypto";
+import { OpenTimestampsClient } from "@otskit/client";
+
+// src/db/stamps.ts
+function insertStamp(db, params) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  db.prepare(`
+    INSERT INTO stamps (id, hash, status, created_at, proof_path, archive_path, attempt_count, metadata)
+    VALUES (?, ?, 'pending', ?, ?, ?, 0, ?)
+  `).run(params.id, params.hash, now, params.proof_path, params.archive_path ?? null, params.metadata ?? null);
+  return getStamp(db, params.id);
+}
+function getStamp(db, id) {
+  return db.prepare("SELECT * FROM stamps WHERE id = ?").get(id) ?? null;
+}
+function updateStampStatus(db, id, params) {
+  const fields = [];
+  const values = [];
+  const add = (col, val) => {
+    fields.push(`${col} = ?`);
+    values.push(val);
+  };
+  if (params.status !== void 0) add("status", params.status);
+  if (params.bitcoin_block !== void 0) add("bitcoin_block", params.bitcoin_block);
+  if (params.bitcoin_time !== void 0) add("bitcoin_time", params.bitcoin_time);
+  if (params.confirmed_at !== void 0) add("confirmed_at", params.confirmed_at);
+  if (params.last_error !== void 0) add("last_error", params.last_error);
+  if (params.attempt_count !== void 0) add("attempt_count", params.attempt_count);
+  if (params.last_attempt_at !== void 0) add("last_attempt_at", params.last_attempt_at);
+  if (params.next_retry_at !== void 0) add("next_retry_at", params.next_retry_at);
+  if (fields.length === 0) return;
+  values.push(id);
+  db.prepare(`UPDATE stamps SET ${fields.join(", ")} WHERE id = ?`).run(...values);
+}
+function listStamps(db, params) {
+  const conds = [];
+  const vals = [];
+  if (params.status) {
+    conds.push("status = ?");
+    vals.push(params.status);
+  }
+  if (params.older_than_hours) {
+    const cutoff = new Date(Date.now() - params.older_than_hours * 36e5).toISOString();
+    conds.push("created_at < ?");
+    vals.push(cutoff);
+  }
+  const where = conds.length ? `WHERE ${conds.join(" AND ")}` : "";
+  const total = db.prepare(`SELECT COUNT(*) as n FROM stamps ${where}`).get(...vals).n;
+  const items = db.prepare(
+    `SELECT * FROM stamps ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`
+  ).all(...vals, params.limit, params.offset);
+  return { items, total };
+}
+
+// src/db/operations-log.ts
+function logOperation(db, params) {
+  db.prepare(`
+    INSERT INTO operations_log (stamp_id, action, result, error_msg, calendar_uri, response_time_ms, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    params.stamp_id,
+    params.action,
+    params.result,
+    params.error_msg ?? null,
+    params.calendar_uri ?? null,
+    params.response_time_ms ?? null,
+    (/* @__PURE__ */ new Date()).toISOString()
+  );
+}
+
+// src/tools/create-timestamp.ts
+var HEX64 = /^[0-9a-f]{64}$/i;
+async function createTimestamp(input, db, config) {
+  if (!HEX64.test(input.hash)) {
+    return { error: "invalid_hash", details: "hash must be 64 hex characters (SHA-256)" };
+  }
+  const normalizedHash = input.hash.toLowerCase();
+  const client = new OpenTimestampsClient({
+    calendars: config.calendars,
+    resilience: { timeout: config.calendar_timeout_ms }
+  });
+  const t0 = Date.now();
+  let proofBuffer;
+  try {
+    proofBuffer = await client.stamp(normalizedHash);
+  } catch (e) {
+    return { error: "calendar_error", details: String(e) };
+  }
+  const responseTimeMs = Date.now() - t0;
+  const id = randomUUID();
+  const proofDir = join3(getDataDir(), "proofs");
+  mkdirSync3(proofDir, { recursive: true });
+  const proofPath = join3(proofDir, `${id}.ots`);
+  try {
+    writeAtomic(proofPath, proofBuffer);
+  } catch (e) {
+    return { error: "storage_error", details: String(e) };
+  }
+  const record = insertStamp(db, { id, hash: normalizedHash, proof_path: proofPath });
+  logOperation(db, { stamp_id: id, action: "stamp", result: "success", response_time_ms: responseTimeMs });
+  return {
+    id: record.id,
+    hash: record.hash,
+    status: "pending",
+    calendars: config.calendars,
+    created_at: record.created_at,
+    proof_path: proofPath
+  };
+}
+
+// src/tools/upgrade-timestamp.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { OpenTimestampsClient as OpenTimestampsClient2, UpgradeError } from "@otskit/client";
+import { deserializeOTS, hasConfirmedAttestation, getEarliestBitcoinBlock } from "@otskit/core";
+function checkBitcoinConfirmation(bytes) {
+  try {
+    const proof = deserializeOTS(new Uint8Array(bytes));
+    const confirmed = hasConfirmedAttestation(proof.attestations);
+    if (confirmed) {
+      const block = getEarliestBitcoinBlock(proof.attestations);
+      return { confirmed: true, block };
+    }
+    return { confirmed: false };
+  } catch {
+    return { confirmed: false };
+  }
+}
+function nextRetryAt(attemptCount) {
+  const base = Math.min(3e4 * Math.pow(2, attemptCount), 36e5);
+  const jitter = Math.random() * 0.2 * base;
+  return new Date(Date.now() + base + jitter).toISOString();
+}
+async function upgradeTimestamp(input, db, config) {
+  const record = getStamp(db, input.id);
+  if (!record) return { error: "not_found", details: `No stamp with id ${input.id}` };
+  if (!record.proof_path) return { error: "storage_error", details: "No proof_path on record" };
+  const proofBefore = readFileSync2(record.proof_path);
+  const client = new OpenTimestampsClient2({
+    calendars: config.calendars,
+    resilience: { timeout: config.calendar_timeout_ms }
+  });
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const newAttemptCount = record.attempt_count + 1;
+  const next = nextRetryAt(newAttemptCount);
+  let upgraded;
+  try {
+    upgraded = await client.upgrade(proofBefore);
+  } catch (e) {
+    if (e instanceof UpgradeError) {
+      updateStampStatus(db, input.id, { last_attempt_at: now, attempt_count: newAttemptCount, next_retry_at: next });
+      logOperation(db, { stamp_id: input.id, action: "upgrade", result: "pending" });
+      return { id: input.id, status: "pending", attempt_count: newAttemptCount, last_attempt_at: now, next_retry_at: next };
+    }
+    updateStampStatus(db, input.id, { last_attempt_at: now, attempt_count: newAttemptCount, last_error: String(e), next_retry_at: next });
+    logOperation(db, { stamp_id: input.id, action: "upgrade", result: "failed", error_msg: String(e) });
+    return { error: "calendar_error", details: String(e) };
+  }
+  writeAtomic(record.proof_path, upgraded);
+  const { confirmed, block } = checkBitcoinConfirmation(upgraded);
+  if (confirmed && block !== void 0) {
+    const bitcoinTime = now;
+    updateStampStatus(db, input.id, {
+      status: "confirmed",
+      bitcoin_block: block,
+      bitcoin_time: bitcoinTime,
+      confirmed_at: now,
+      last_attempt_at: now,
+      attempt_count: newAttemptCount
+    });
+    logOperation(db, { stamp_id: input.id, action: "upgrade", result: "success" });
+    return { id: input.id, status: "confirmed", bitcoin_block: block, bitcoin_time: bitcoinTime, proof_path: record.proof_path };
+  }
+  updateStampStatus(db, input.id, { last_attempt_at: now, attempt_count: newAttemptCount, next_retry_at: next });
+  logOperation(db, { stamp_id: input.id, action: "upgrade", result: "pending" });
+  return { id: input.id, status: "pending", attempt_count: newAttemptCount, last_attempt_at: now, next_retry_at: next };
+}
+
+// src/tools/verify-timestamp.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { OpenTimestampsClient as OpenTimestampsClient3 } from "@otskit/client";
+async function verifyTimestamp(input, db, config) {
+  const record = getStamp(db, input.id);
+  if (!record) return { error: "not_found", details: `No stamp with id ${input.id}` };
+  if (!record.proof_path) return { error: "storage_error", details: "No proof_path on record" };
+  let proofBytes;
+  try {
+    proofBytes = readFileSync3(record.proof_path);
+  } catch (e) {
+    return { error: "storage_error", details: String(e) };
+  }
+  const client = new OpenTimestampsClient3({
+    calendars: config.calendars,
+    resilience: { timeout: config.calendar_timeout_ms }
+  });
+  let result;
+  try {
+    result = await client.verify(proofBytes, record.hash);
+  } catch (e) {
+    logOperation(db, { stamp_id: input.id, action: "verify", result: "failed", error_msg: String(e) });
+    return { status: "network_error", hash: record.hash, details: String(e) };
+  }
+  if (!result.valid) {
+    if (result.error?.includes("No Bitcoin attestation")) {
+      logOperation(db, { stamp_id: input.id, action: "verify", result: "pending" });
+      return { status: "pending", hash: record.hash, calendars: config.calendars };
+    }
+    if (result.error?.toLowerCase().includes("invalid") || result.error?.toLowerCase().includes("corrupt")) {
+      logOperation(db, { stamp_id: input.id, action: "verify", result: "failed", error_msg: result.error });
+      return { status: "invalid", hash: record.hash, reason: result.error ?? "unknown" };
+    }
+    logOperation(db, { stamp_id: input.id, action: "verify", result: "failed", error_msg: result.error });
+    return { status: "unknown", hash: record.hash };
+  }
+  logOperation(db, { stamp_id: input.id, action: "verify", result: "success" });
+  return {
+    status: "confirmed",
+    hash: record.hash,
+    bitcoin_block: result.blockHeight,
+    bitcoin_time: new Date(result.timestamp * 1e3).toISOString()
+  };
+}
+
+// src/tools/list-pending.ts
+function listPending(input, db, _config) {
+  return listStamps(db, {
+    status: input.status ?? "pending",
+    limit: Math.min(input.limit ?? 50, 200),
+    offset: input.offset ?? 0,
+    older_than_hours: input.older_than_hours
+  });
+}
+
+export {
+  getDataDir,
+  loadConfig,
+  getDb,
+  backupDb,
+  getStamp,
+  createTimestamp,
+  upgradeTimestamp,
+  verifyTimestamp,
+  listPending
+};

package/dist/chunk-YFSUDT24.js

@@ -0,0 +1,24 @@
+// src/utils.ts
+import { execFileSync } from "child_process";
+import { writeFileSync, renameSync } from "fs";
+function which(cmd) {
+  try {
+    const out = execFileSync(
+      process.platform === "win32" ? "where" : "which",
+      [cmd]
+    ).toString().trim();
+    return out.split("\n")[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function writeAtomic(dest, data) {
+  const tmp = dest + ".tmp";
+  writeFileSync(tmp, data);
+  renameSync(tmp, dest);
+}
+
+export {
+  which,
+  writeAtomic
+};

package/dist/cli-KXB6JLHY.js

@@ -0,0 +1,96 @@
+import {
+  backupDb,
+  createTimestamp,
+  getDb,
+  listPending,
+  loadConfig,
+  upgradeTimestamp,
+  verifyTimestamp
+} from "./chunk-XG7E5YXZ.js";
+import "./chunk-YFSUDT24.js";
+
+// src/cli.ts
+async function runCli(command, args) {
+  const config = loadConfig();
+  const db = getDb();
+  switch (command) {
+    case "stamp": {
+      const hash = args[0];
+      if (!hash) {
+        process.stderr.write("Usage: ots-mcp stamp <sha256-hash>\n");
+        process.exit(1);
+      }
+      const result = await createTimestamp({ hash }, db, config);
+      if ("error" in result) {
+        process.stderr.write(`Error: ${result.error} \u2014 ${result.details}
+`);
+        process.exit(1);
+      }
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      break;
+    }
+    case "upgrade": {
+      const id = args[0];
+      if (!id) {
+        process.stderr.write("Usage: ots-mcp upgrade <id>\n");
+        process.exit(1);
+      }
+      const result = await upgradeTimestamp({ id }, db, config);
+      if ("error" in result) {
+        process.stderr.write(`Error: ${result.error} \u2014 ${result.details}
+`);
+        process.exit(1);
+      }
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      break;
+    }
+    case "verify": {
+      const id = args[0];
+      if (!id) {
+        process.stderr.write("Usage: ots-mcp verify <id>\n");
+        process.exit(1);
+      }
+      const result = await verifyTimestamp({ id }, db, config);
+      if ("error" in result) {
+        process.stderr.write(`Error: ${result.error} \u2014 ${result.details}
+`);
+        process.exit(1);
+      }
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      break;
+    }
+    case "list": {
+      const status = args[0] ?? "pending";
+      const result = listPending({ status }, db, config);
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      break;
+    }
+    case "check-pending": {
+      const { items } = listPending({ status: "pending", limit: 200 }, db, config);
+      process.stderr.write(`Processing ${items.length} pending stamps...
+`);
+      for (const record of items) {
+        const result = await upgradeTimestamp({ id: record.id }, db, config);
+        const statusStr = "status" in result ? result.status : `error:${result.error}`;
+        process.stderr.write(`${record.id.slice(0, 8)}: ${statusStr}
+`);
+      }
+      break;
+    }
+    case "backup": {
+      const dest = args[0] ?? `ots-mcp-backup-${Date.now()}.sqlite`;
+      backupDb(dest);
+      process.stdout.write(`Backup saved to ${dest}
+`);
+      break;
+    }
+    case "scheduler": {
+      const { runScheduler } = await import("./scheduler-VVSCSTMC.js");
+      await runScheduler(args);
+      break;
+    }
+  }
+}
+export {
+  runCli
+};

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+// src/index.ts
+var [, , command, ...args] = process.argv;
+if (!command || command === "--help" || command === "help") {
+  process.stderr.write(`Usage: ots-mcp <command>
+Commands:
+  serve           Start MCP server (stdio transport)
+  stamp <hash>    Stamp a SHA-256 hash
+  upgrade <id>    Upgrade a pending stamp
+  verify <id>     Verify a stamp
+  list [status]   List stamps (default: pending)
+  check-pending   Run pending upgrades (for scheduler)
+  backup [dest]   Backup the SQLite database
+  scheduler       Manage OS scheduler (install|remove|status)
+`);
+  process.exit(command ? 0 : 1);
+}
+switch (command) {
+  case "serve": {
+    const { runServer } = await import("./server-KWTBEIKF.js");
+    await runServer();
+    break;
+  }
+  case "stamp":
+  case "upgrade":
+  case "verify":
+  case "list":
+  case "check-pending":
+  case "backup":
+  case "scheduler": {
+    const { runCli } = await import("./cli-KXB6JLHY.js");
+    await runCli(command, args);
+    break;
+  }
+  default: {
+    process.stderr.write(`Unknown command: ${command}. Run 'ots-mcp help' for usage.
+`);
+    process.exit(1);
+  }
+}

package/dist/install-BUSOMBB2.js

@@ -0,0 +1,37 @@
+import {
+  which
+} from "./chunk-YFSUDT24.js";
+
+// src/scheduler/install.ts
+import { execFileSync } from "child_process";
+import { writeFileSync } from "fs";
+async function installScheduler(args) {
+  const intervalIdx = args.indexOf("--interval");
+  const interval = intervalIdx !== -1 ? parseInt(args[intervalIdx + 1] ?? "30") : 30;
+  const bin = which("ots-mcp") ?? process.argv[1];
+  if (process.platform === "win32") {
+    const xmlPath = `${process.env.TEMP}\\ots-mcp-task.xml`;
+    writeFileSync(xmlPath, `<?xml version="1.0"?>
+<Task xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <Triggers><TimeTrigger>
+    <Repetition><Interval>PT${interval}M</Interval><StopAtDurationEnd>false</StopAtDurationEnd></Repetition>
+    <StartBoundary>2020-01-01T00:00:00</StartBoundary><Enabled>true</Enabled>
+  </TimeTrigger></Triggers>
+  <Actions><Exec>
+    <Command>${bin}</Command>
+    <Arguments>check-pending</Arguments>
+  </Exec></Actions>
+</Task>`);
+    execFileSync("schtasks", ["/create", "/tn", "ots-mcp-check-pending", "/xml", xmlPath, "/f"]);
+    process.stdout.write(`Scheduler installed: runs every ${interval} minutes
+`);
+  } else {
+    process.stdout.write(`Add to crontab (run: crontab -e):
+`);
+    process.stdout.write(`*/${interval} * * * * "${bin}" check-pending
+`);
+  }
+}
+export {
+  installScheduler
+};

package/dist/remove-BGFQRDX3.js

@@ -0,0 +1,17 @@
+// src/scheduler/remove.ts
+import { execFileSync } from "child_process";
+async function removeScheduler() {
+  if (process.platform === "win32") {
+    try {
+      execFileSync("schtasks", ["/delete", "/tn", "ots-mcp-check-pending", "/f"]);
+      process.stdout.write("Scheduler task removed\n");
+    } catch {
+      process.stderr.write("Task not found or could not be removed\n");
+    }
+  } else {
+    process.stdout.write("Remove the ots-mcp entry from crontab: crontab -e\n");
+  }
+}
+export {
+  removeScheduler
+};

package/dist/scheduler-VVSCSTMC.js

@@ -0,0 +1,27 @@
+// src/scheduler/index.ts
+async function runScheduler(args) {
+  const [sub, ...rest] = args;
+  switch (sub) {
+    case "install": {
+      const { installScheduler } = await import("./install-BUSOMBB2.js");
+      await installScheduler(rest);
+      break;
+    }
+    case "remove": {
+      const { removeScheduler } = await import("./remove-BGFQRDX3.js");
+      await removeScheduler();
+      break;
+    }
+    case "status": {
+      const { statusScheduler } = await import("./status-M6A2RG7G.js");
+      await statusScheduler();
+      break;
+    }
+    default:
+      process.stderr.write("Usage: ots-mcp scheduler install [--interval N] | remove | status\n");
+      process.exit(1);
+  }
+}
+export {
+  runScheduler
+};

package/dist/server-KWTBEIKF.js

@@ -0,0 +1,295 @@
+import {
+  createTimestamp,
+  getDataDir,
+  getDb,
+  getStamp,
+  listPending,
+  loadConfig,
+  upgradeTimestamp,
+  verifyTimestamp
+} from "./chunk-XG7E5YXZ.js";
+import "./chunk-YFSUDT24.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+// src/tools/inspect-timestamp.ts
+import { readFileSync, statSync } from "fs";
+import { deserializeOTS, hasConfirmedAttestation, getEarliestBitcoinBlock } from "@otskit/core";
+function inspectTimestamp(input, db, _config) {
+  const record = getStamp(db, input.id);
+  if (!record) return { error: "not_found", details: `No stamp with id ${input.id}` };
+  if (!record.proof_path) return { error: "proof_missing", details: "No proof file on record" };
+  let proofBytes;
+  let proofSize;
+  try {
+    proofSize = statSync(record.proof_path).size;
+    proofBytes = readFileSync(record.proof_path);
+  } catch {
+    return { error: "proof_missing", details: `Cannot read proof: ${record.proof_path}` };
+  }
+  let attestationCount = 0;
+  let hasBitcoin = false;
+  let bitcoinBlock = null;
+  try {
+    const proof = deserializeOTS(new Uint8Array(proofBytes));
+    attestationCount = proof.attestations.length;
+    hasBitcoin = hasConfirmedAttestation(proof.attestations);
+    if (hasBitcoin) bitcoinBlock = getEarliestBitcoinBlock(proof.attestations) ?? null;
+  } catch {
+  }
+  return {
+    id: record.id,
+    hash: record.hash,
+    status: record.status,
+    created_at: record.created_at,
+    proof_path: record.proof_path,
+    proof_size_bytes: proofSize,
+    attestation_count: attestationCount,
+    has_bitcoin_confirmation: hasBitcoin,
+    bitcoin_block: bitcoinBlock
+  };
+}
+
+// src/tools/preserve.ts
+import { createReadStream, createWriteStream, realpathSync, statSync as statSync2, mkdirSync } from "fs";
+import { join, resolve, sep } from "path";
+import { createHash, randomUUID } from "crypto";
+import archiver from "archiver";
+function isPathInWhitelist(resolvedPath, whitelist) {
+  const parts = resolvedPath.split(sep);
+  return whitelist.some((entry) => {
+    const entryParts = resolve(entry).split(sep);
+    return entryParts.length <= parts.length && entryParts.every((part, i) => parts[i] === part);
+  });
+}
+async function preserve(input, db, config) {
+  if (!config.preserve_enabled || config.preserve_whitelist.length === 0) {
+    return { error: "whitelist_not_configured", details: "Set preserve_whitelist in ~/.ots-mcp/config.json" };
+  }
+  let resolvedInput;
+  try {
+    resolvedInput = realpathSync(resolve(input.dir_path));
+  } catch (e) {
+    return { error: "path_not_in_whitelist", details: `Cannot resolve path: ${e}` };
+  }
+  const resolvedWhitelist = config.preserve_whitelist.map((p) => {
+    try {
+      return realpathSync(resolve(p));
+    } catch {
+      return resolve(p);
+    }
+  });
+  if (!isPathInWhitelist(resolvedInput, resolvedWhitelist)) {
+    return { error: "path_not_in_whitelist", details: `${resolvedInput} is not in the configured whitelist` };
+  }
+  let st;
+  try {
+    st = statSync2(resolvedInput);
+  } catch (e) {
+    return { error: "path_not_in_whitelist", details: String(e) };
+  }
+  if (!st.isDirectory()) {
+    return { error: "path_not_in_whitelist", details: "Path must be a directory" };
+  }
+  const archiveDir = join(getDataDir(), "archives");
+  mkdirSync(archiveDir, { recursive: true });
+  const label = input.label ? `-${input.label.replace(/[^a-z0-9-]/gi, "_")}` : "";
+  const archivePath = join(archiveDir, `${randomUUID()}${label}.zip`);
+  const warnings = [];
+  let filesCount = 0;
+  await new Promise((res, rej) => {
+    const output = createWriteStream(archivePath);
+    const arc = archiver("zip", { zlib: { level: 6 } });
+    arc.on("warning", (e) => {
+      if (e.code === "ENOENT") warnings.push(e.message);
+      else rej(e);
+    });
+    arc.on("error", rej);
+    arc.on("entry", () => {
+      filesCount++;
+    });
+    output.on("close", res);
+    arc.pipe(output);
+    arc.directory(resolvedInput, false);
+    arc.finalize();
+  });
+  const archiveSize = statSync2(archivePath).size;
+  if (archiveSize > config.preserve_max_bytes) {
+    return { error: "resource_limit_exceeded", details: `Archive ${archiveSize} bytes exceeds limit ${config.preserve_max_bytes}` };
+  }
+  const hash = await new Promise((res, rej) => {
+    const h = createHash("sha256");
+    createReadStream(archivePath).on("data", (d) => h.update(d)).on("end", () => res(h.digest("hex"))).on("error", rej);
+  });
+  const stampResult = await createTimestamp({ hash }, db, config);
+  if ("error" in stampResult) return { error: "stamp_error", details: stampResult.details };
+  db.prepare("UPDATE stamps SET archive_path = ?, metadata = ? WHERE id = ?").run(
+    archivePath,
+    JSON.stringify({ source_path: resolvedInput, files_count: filesCount, total_bytes: archiveSize }),
+    stampResult.id
+  );
+  return {
+    id: stampResult.id,
+    hash,
+    archive_path: archivePath,
+    proof_path: stampResult.proof_path,
+    status: "pending",
+    files_count: filesCount,
+    archive_size_bytes: archiveSize,
+    warnings
+  };
+}
+
+// src/tool-definitions.ts
+var TOOL_DEFINITIONS = [
+  {
+    name: "create_timestamp",
+    description: "Stamps a SHA-256 hash against public OpenTimestamps calendars. IMPORTANT: the digest is sent to external calendar servers (alice.btc, bob.btc, finney, catallaxy).",
+    inputSchema: {
+      type: "object",
+      properties: { hash: { type: "string", description: "SHA-256 hex digest (64 chars)" } },
+      required: ["hash"]
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  {
+    name: "upgrade_timestamp",
+    description: "Checks if a pending stamp has been confirmed in Bitcoin. Use the id returned by create_timestamp.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "UUID from the stamp record" } },
+      required: ["id"]
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  {
+    name: "verify_timestamp",
+    description: "Verifies a stamp against Bitcoin. Does NOT affirm document authorship or truth \u2014 only proves the hash existed before a given Bitcoin block.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "UUID from the stamp record" } },
+      required: ["id"]
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  {
+    name: "inspect_timestamp",
+    description: "Shows the contents of a stored proof file without making any network calls. Useful for debugging: returns size, parsed attestations, and confirmation status from the proof itself.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "UUID from the stamp record" } },
+      required: ["id"]
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  },
+  {
+    name: "list_pending",
+    description: "Lists stamp records with status and retry info.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", enum: ["pending", "confirmed", "failed", "timeout"] },
+        limit: { type: "number", maximum: 200 },
+        offset: { type: "number" },
+        older_than_hours: { type: "number" }
+      }
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  },
+  {
+    name: "preserve",
+    description: "FILESYSTEM-SENSITIVE: Compresses a directory to ZIP, stamps its SHA-256 hash, stores archive in whitelist directory. Requires preserve_whitelist config.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        dir_path: { type: "string", description: "Absolute path to directory (must be in preserve_whitelist)" },
+        label: { type: "string", description: "Optional label for the archive filename" }
+      },
+      required: ["dir_path"]
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  }
+];
+
+// src/server.ts
+async function runServer() {
+  const config = loadConfig();
+  const db = getDb();
+  const server = new Server(
+    { name: "ots-mcp", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOL_DEFINITIONS
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      let result;
+      switch (name) {
+        case "create_timestamp":
+          result = await createTimestamp(args, db, config);
+          break;
+        case "upgrade_timestamp":
+          result = await upgradeTimestamp(args, db, config);
+          break;
+        case "verify_timestamp":
+          result = await verifyTimestamp(args, db, config);
+          break;
+        case "inspect_timestamp":
+          result = inspectTimestamp(args, db, config);
+          break;
+        case "list_pending":
+          result = listPending(args, db, config);
+          break;
+        case "preserve":
+          result = await preserve(args, db, config);
+          break;
+        default:
+          return { content: [{ type: "text", text: JSON.stringify({ error: "unknown_tool", tool: name }) }], isError: true };
+      }
+      const isError = Boolean(result && typeof result === "object" && "error" in result);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], isError };
+    } catch (e) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: "internal_error", details: String(e) }) }], isError: true };
+    }
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+export {
+  runServer
+};

package/dist/status-M6A2RG7G.js

@@ -0,0 +1,17 @@
+// src/scheduler/status.ts
+import { execFileSync } from "child_process";
+async function statusScheduler() {
+  if (process.platform === "win32") {
+    try {
+      const out = execFileSync("schtasks", ["/query", "/tn", "ots-mcp-check-pending", "/fo", "LIST"]).toString();
+      process.stdout.write(out + "\n");
+    } catch {
+      process.stdout.write("Scheduler task not found\n");
+    }
+  } else {
+    process.stdout.write("Check with: crontab -l | grep ots-mcp\n");
+  }
+}
+export {
+  statusScheduler
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@otskit/mcp",
+  "version": "0.1.0",
+  "description": "OpenTimestamps MCP server — stamp, upgrade, verify via AI agents",
+  "type": "module",
+  "engines": { "node": ">=18" },
+  "bin": { "ots-mcp": "dist/index.js" },
+  "exports": "./dist/index.js",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "dev":   "tsup src/index.ts --format esm --watch",
+    "test":  "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@otskit/core": "file:../otskit-core",
+    "@otskit/client": "file:../otskit-client",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "archiver": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/archiver": "^6.0.3",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}