@otskit/mcp 0.1.4 → 0.1.6

package/README.md

@@ -1,36 +1,98 @@
 <p align="center">
-  <img src="docs/header.png" alt="OTSkit.ts MCP" width="480" />
+  <img src="https://raw.githubusercontent.com/OTSkit/OTSkit-MCP/master/docs/header.png" alt="OTSkit.ts MCP" width="480" />
 </p>
 
 # @otskit/mcp
 
-OpenTimestamps MCP server — stamp, upgrade, and verify timestamps via AI agents (Claude).
+OpenTimestamps MCP server — stamp, upgrade, and verify Bitcoin timestamps via AI agents.
 
-## Installation
+Exposes a set of tools to any MCP-compatible agent so it can timestamp documents, monitor confirmation status, and verify proofs against the Bitcoin blockchain — all from a conversation.
+
+> **Note on confirmation times:** After stamping, a proof is `pending` until Bitcoin confirms it. This typically takes **10–60 minutes** but can take **several hours** during network congestion. Use `ots-mcp watch` or `upgrade_timestamp` to monitor. A pending status is not an error.
+
+## Install
 
 ```bash
-pnpm install
-pnpm build
+npm install -g @otskit/mcp
 ```
 
-## Usage
+## Agent setup
 
 ```bash
-ots-mcp
+ots-mcp setup claude   # Claude Desktop
+ots-mcp setup codex    # Codex CLI
 ```
 
-## Dependencies
+Each command writes the MCP entry into the agent's config file, makes a `.bak` backup if the file already exists, and skips if `ots-mcp` is already configured. Restart the agent afterwards to apply the changes.
 
-- [`@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
+## CLI commands
+
+| Command | Description |
+|---|---|
+| `ots-mcp serve` | Start the MCP server (stdio transport) |
+| `ots-mcp stamp <sha256>` | Stamp a SHA-256 hash against Bitcoin calendars |
+| `ots-mcp upgrade <id>` | Check if a pending stamp has been confirmed |
+| `ots-mcp verify <id>` | Verify a stamp against Bitcoin |
+| `ots-mcp list [status]` | List stamps (`pending` / `confirmed` / `failed`) |
+| `ots-mcp watch [minutes]` | Poll pending stamps in real-time (default: 5 min) |
+| `ots-mcp check-pending` | Run one upgrade pass over all pending stamps |
+| `ots-mcp scheduler install\|remove\|status` | Manage OS-level scheduler for auto-upgrades |
+| `ots-mcp backup [dest]` | Backup the SQLite database |
+| `ots-mcp setup <claude\|codex>` | Configure MCP for an agent |
+
+## MCP tools exposed to agents
+
+| Tool | Description |
+|---|---|
+| `create_timestamp` | Stamp a SHA-256 hash against 4 public OTS calendars |
+| `upgrade_timestamp` | Check if a pending stamp has been confirmed in Bitcoin |
+| `verify_timestamp` | Verify a stamp — proves hash existed before a given Bitcoin block |
+| `inspect_timestamp` | Inspect a stored proof file without network calls |
+| `list_pending` | List stamps with status, retry count, and filters |
+| `watch` | Open a terminal window monitoring pending stamps in real-time |
+
+## Data directory
+
+All data is stored in `~/.ots-mcp/`:
+
+```
+~/.ots-mcp/
+  ots-mcp.db       # SQLite database (stamps, proof files)
+  config.json      # Optional config overrides
+  ots-mcp.log      # Log file
+```
+
+## Configuration
+
+Create `~/.ots-mcp/config.json` to override defaults:
+
+```json
+{
+  "stamp_enabled": true,
+  "scheduler_interval_minutes": 30,
+  "retry_max_attempts": 20,
+  "calendar_timeout_ms": 10000,
+  "esplora_url": "https://blockstream.info/api",
+  "calendars": [
+    "https://alice.btc.calendar.opentimestamps.org",
+    "https://bob.btc.calendar.opentimestamps.org",
+    "https://finney.calendar.eternitywall.com",
+    "https://btc.calendar.catallaxy.com"
+  ]
+}
+```
 
 ## Development
 
 ```bash
-pnpm dev       # watch mode
-pnpm test      # run tests
-pnpm build     # production build
+npm run build    # production build
+npm run dev      # watch mode
+npm test         # run tests
 ```
+
+## Dependencies
+
+- [`@otskit/core`](https://github.com/AlexAlves87/otskit-core) — OpenTimestamps core logic
+- [`@otskit/client`](https://github.com/AlexAlves87/otskit-client) — OTS calendar client
+- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) — MCP SDK
+- `better-sqlite3` — local database

package/dist/chunk-4ZDPWS7C.js

@@ -0,0 +1,123 @@
+// 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);
+    }
+  }
+}
+
+export {
+  getDataDir,
+  loadConfig,
+  getDb,
+  backupDb
+};

package/dist/{chunk-ASPLCXMC.js → chunk-VHQD7HZD.js}

@@ -1,128 +1,15 @@
+import {
+  getDataDir
+} from "./chunk-4ZDPWS7C.js";
 import {
   writeAtomic
 } from "./chunk-YFSUDT24.js";
 
-// src/config.ts
-import { readFileSync, existsSync, mkdirSync } from "fs";
+// src/tools/create-timestamp.ts
+import { 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/upgrade-timestamp.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { OpenTimestampsClient, UpgradeError } from "@otskit/client";
-import { DetachedTimestampFile } from "@otskit/core";
+import { randomUUID } from "crypto";
+import { OpenTimestampsClient } from "@otskit/client";
 
 // src/db/stamps.ts
 function insertStamp(db, params) {
@@ -167,6 +54,10 @@ function listStamps(db, params) {
     conds.push("created_at < ?");
     vals.push(cutoff);
   }
+  if (params.due_now) {
+    conds.push("(next_retry_at IS NULL OR next_retry_at <= ?)");
+    vals.push((/* @__PURE__ */ new Date()).toISOString());
+  }
   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(
@@ -191,17 +82,66 @@ function logOperation(db, params) {
   );
 }
 
+// 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 = join(getDataDir(), "proofs");
+  mkdirSync(proofDir, { recursive: true });
+  const proofPath = join(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 } from "fs";
+import { OpenTimestampsClient as OpenTimestampsClient2, UpgradeError } from "@otskit/client";
+import { DetachedTimestampFile, StreamDeserializationContext } from "@otskit/core";
+function collectAttestations(ts) {
+  const atts = [...ts.attestations];
+  for (const branch of ts.branches) {
+    atts.push(...collectAttestations(branch.stamp));
+  }
+  return atts;
+}
 function checkBitcoinConfirmation(bytes) {
   try {
-    const proof = DetachedTimestampFile.deserialize(new Uint8Array(bytes));
-    const attestations = proof.timestamp.getAttestations();
-    const bitcoin = attestations.filter((a) => a.kind === "bitcoin");
-    if (bitcoin.length > 0) {
-      const block = Math.min(...bitcoin.map((a) => a.height));
-      return { confirmed: true, block };
-    }
-    return { confirmed: false };
+    const ctx = new StreamDeserializationContext(new Uint8Array(bytes));
+    const dtf = DetachedTimestampFile.deserialize(ctx);
+    const attestations = collectAttestations(dtf.timestamp);
+    const bitcoinAtts = attestations.filter((a) => a.kind === "bitcoin");
+    if (bitcoinAtts.length === 0) return { confirmed: false };
+    const block = Math.min(...bitcoinAtts.map((a) => a.height));
+    return { confirmed: true, block };
   } catch {
     return { confirmed: false };
   }
@@ -215,8 +155,8 @@ 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 OpenTimestampsClient({
+  const proofBefore = readFileSync(record.proof_path);
+  const client = new OpenTimestampsClient2({
     calendars: config.calendars,
     resilience: { timeout: config.calendar_timeout_ms }
   });
@@ -256,14 +196,66 @@ async function upgradeTimestamp(input, db, config) {
   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 readFileSync2 } 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 = readFileSync2(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,
+    due_now: input.due_now
+  });
+}
+
 export {
-  getDataDir,
-  loadConfig,
-  getDb,
-  backupDb,
-  insertStamp,
   getStamp,
-  listStamps,
-  logOperation,
-  upgradeTimestamp
+  createTimestamp,
+  upgradeTimestamp,
+  verifyTimestamp,
+  listPending
 };

package/dist/claude-QTEB3Z5V.js

@@ -0,0 +1,54 @@
+// src/setup/claude.ts
+import { readFileSync, writeFileSync, copyFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function getConfigPath() {
+  if (process.platform === "win32") {
+    return join(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json");
+  } else if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  } else {
+    return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+  }
+}
+function setupClaude() {
+  const configPath = getConfigPath();
+  const configDir = join(configPath, "..");
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      process.stderr.write(`  Aviso: no se pudo parsear la config existente, se crear\xE1 nueva.
+`);
+    }
+    const existing = config.mcpServers ?? {};
+    if ("otskit" in existing) {
+      process.stdout.write(`  ots-mcp ya est\xE1 configurado en ${configPath}
+`);
+      process.stdout.write(`  No se hizo ning\xFAn cambio.
+`);
+      return;
+    }
+    const backupPath = configPath + ".bak";
+    copyFileSync(configPath, backupPath);
+    process.stdout.write(`  Backup guardado en ${backupPath}
+`);
+  }
+  const mcpServers = config.mcpServers ?? {};
+  mcpServers["otskit"] = { command: "npx", args: ["-y", "@otskit/mcp", "serve"] };
+  config.mcpServers = mcpServers;
+  writeFileSync(configPath, JSON.stringify(config, null, 2), "utf8");
+  process.stdout.write(`OTSkit MCP configurado para Claude Desktop
+`);
+  process.stdout.write(`  Config: ${configPath}
+`);
+  process.stdout.write(`  Reinicia Claude Desktop para aplicar los cambios.
+`);
+}
+export {
+  setupClaude
+};

package/dist/{cli-67APZKT6.js → cli-TF5PYS3T.js}

@@ -1,14 +1,14 @@
 import {
   createTimestamp,
   listPending,
+  upgradeTimestamp,
   verifyTimestamp
-} from "./chunk-45GR42GV.js";
+} from "./chunk-VHQD7HZD.js";
 import {
   backupDb,
   getDb,
-  loadConfig,
-  upgradeTimestamp
-} from "./chunk-ASPLCXMC.js";
+  loadConfig
+} from "./chunk-4ZDPWS7C.js";
 import "./chunk-YFSUDT24.js";
 
 // src/cli.ts
@@ -68,7 +68,7 @@ async function runCli(command, args) {
       break;
     }
     case "check-pending": {
-      const { items } = listPending({ status: "pending", limit: 200 }, db, config);
+      const { items } = listPending({ status: "pending", limit: 200, due_now: true }, db, config);
       process.stderr.write(`Processing ${items.length} pending stamps...
 `);
       for (const record of items) {
@@ -77,7 +77,7 @@ async function runCli(command, args) {
         process.stderr.write(`${record.id.slice(0, 8)}: ${statusStr}
 `);
       }
-      break;
+      process.exit(0);
     }
     case "backup": {
       const dest = args[0] ?? `ots-mcp-backup-${Date.now()}.sqlite`;
@@ -87,7 +87,7 @@ async function runCli(command, args) {
       break;
     }
     case "scheduler": {
-      const { runScheduler } = await import("./scheduler-VVSCSTMC.js");
+      const { runScheduler } = await import("./scheduler-YF6WMSR4.js");
       await runScheduler(args);
       break;
     }

package/dist/codex-P7EDO5GY.js

@@ -0,0 +1,41 @@
+// src/setup/codex.ts
+import { readFileSync, writeFileSync, copyFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var BLOCK = `
+[mcp_servers.ots-mcp]
+command = "npx"
+args = ["-y", "@otskit/mcp", "serve"]
+`;
+function setupCodex() {
+  const configPath = join(homedir(), ".codex", "config.toml");
+  const configDir = join(configPath, "..");
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  let content = "";
+  if (existsSync(configPath)) {
+    content = readFileSync(configPath, "utf8");
+    if (content.includes("[mcp_servers.ots-mcp]")) {
+      process.stdout.write(`  ots-mcp ya est\xE1 configurado en ${configPath}
+`);
+      process.stdout.write(`  No se hizo ning\xFAn cambio.
+`);
+      return;
+    }
+    const backupPath = configPath + ".bak";
+    copyFileSync(configPath, backupPath);
+    process.stdout.write(`  Backup guardado en ${backupPath}
+`);
+  }
+  writeFileSync(configPath, content.trimEnd() + "\n" + BLOCK, "utf8");
+  process.stdout.write(`OTSkit MCP configurado para Codex
+`);
+  process.stdout.write(`  Config: ${configPath}
+`);
+  process.stdout.write(`  Reinicia Codex para aplicar los cambios.
+`);
+}
+export {
+  setupCodex
+};

package/dist/index.js

@@ -6,7 +6,7 @@ if (!command || command === "--help" || command === "help") {
   process.stderr.write(`Usage: ots-mcp <command>
 Commands:
   serve              Start MCP server (stdio transport)
-  install-claude     Install MCP in Claude Desktop config (auto-setup)
+  setup <target>     Configure MCP for an agent (claude | codex)
   watch [interval]   Watch pending stamps in real-time (default: 5 min)
   stamp <hash>       Stamp a SHA-256 hash
   upgrade <id>       Upgrade a pending stamp
@@ -20,18 +20,38 @@ Commands:
 }
 switch (command) {
   case "serve": {
-    const { runServer } = await import("./server-2YEI77IT.js");
+    const { runServer } = await import("./server-D5YXBC55.js");
     await runServer();
     break;
   }
+  case "setup": {
+    const target = args[0];
+    if (!target || target !== "claude" && target !== "codex") {
+      process.stderr.write(`Usage: ots-mcp setup <claude|codex>
+`);
+      process.exit(1);
+    }
+    if (target === "claude") {
+      const { setupClaude } = await import("./claude-QTEB3Z5V.js");
+      setupClaude();
+    } else {
+      const { setupCodex } = await import("./codex-P7EDO5GY.js");
+      setupCodex();
+    }
+    break;
+  }
   case "install-claude": {
     const { installClaude } = await import("./install-claude-UKSS65BW.js");
     installClaude();
     break;
   }
   case "watch": {
-    const { watchPending } = await import("./watch-JWDMAZWS.js");
-    const interval = args[0] ? parseInt(args[0]) : 5;
+    const { watchPending } = await import("./watch-7NPUWR6I.js");
+    const parsed = args[0] ? parseInt(args[0], 10) : NaN;
+    const interval = isNaN(parsed) || parsed < 1 ? 5 : parsed;
+    if (args[0] && (isNaN(parsed) || parsed < 1))
+      process.stderr.write(`Argumento inv\xE1lido "${args[0]}", usando intervalo por defecto: 5 min
+`);
     await watchPending(interval);
     break;
   }
@@ -42,7 +62,7 @@ switch (command) {
   case "check-pending":
   case "backup":
   case "scheduler": {
-    const { runCli } = await import("./cli-67APZKT6.js");
+    const { runCli } = await import("./cli-TF5PYS3T.js");
     await runCli(command, args);
     break;
   }

package/dist/{server-2YEI77IT.js → server-D5YXBC55.js}

@@ -1,15 +1,14 @@
 import {
   createTimestamp,
+  getStamp,
   listPending,
+  upgradeTimestamp,
   verifyTimestamp
-} from "./chunk-45GR42GV.js";
+} from "./chunk-VHQD7HZD.js";
 import {
-  getDataDir,
   getDb,
-  getStamp,
-  loadConfig,
-  upgradeTimestamp
-} from "./chunk-ASPLCXMC.js";
+  loadConfig
+} from "./chunk-4ZDPWS7C.js";
 import "./chunk-YFSUDT24.js";
 
 // src/server.ts
@@ -32,15 +31,15 @@ function inspectTimestamp(input, db, _config) {
   } catch {
     return { error: "proof_missing", details: `Cannot read proof: ${record.proof_path}` };
   }
-  let attestationCount = 0;
-  let hasBitcoin = false;
+  let calendarAttestations = 0;
+  let bitcoinAttestations = 0;
   let bitcoinBlock = null;
   try {
     const proof = DetachedTimestampFile.deserialize(new Uint8Array(proofBytes));
     const attestations = proof.timestamp.getAttestations();
-    attestationCount = attestations.length;
-    hasBitcoin = attestations.some((a) => a.kind === "bitcoin");
-    if (hasBitcoin) {
+    bitcoinAttestations = attestations.filter((a) => a.kind === "bitcoin").length;
+    calendarAttestations = attestations.filter((a) => a.kind !== "bitcoin").length;
+    if (bitcoinAttestations > 0) {
       const blocks = attestations.filter((a) => a.kind === "bitcoin").map((a) => a.height);
       bitcoinBlock = blocks.length > 0 ? Math.min(...blocks) : null;
     }
@@ -53,100 +52,23 @@ function inspectTimestamp(input, db, _config) {
     created_at: record.created_at,
     proof_path: record.proof_path,
     proof_size_bytes: proofSize,
-    attestation_count: attestationCount,
-    has_bitcoin_confirmation: hasBitcoin,
+    calendar_attestations: calendarAttestations,
+    bitcoin_attestations: bitcoinAttestations,
+    bitcoin_confirmed: bitcoinAttestations > 0,
     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);
+// src/tools/watch-window.ts
+import { exec } from "child_process";
+function openWatchWindow(intervalMinutes = 5) {
+  const minutes = Math.max(1, Math.floor(intervalMinutes));
+  const cmd = `start powershell.exe -NoExit -Command "ots-mcp watch ${minutes}"`;
+  let errorMsg;
+  exec(cmd, { shell: "cmd" }, (err) => {
+    if (err) errorMsg = err.message;
   });
-  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
-  };
+  return { opened: true, interval_minutes: minutes, ...errorMsg ? { error: errorMsg } : {} };
 }
 
 // src/tool-definitions.ts
@@ -198,7 +120,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     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.",
+    description: "Inspects a stored proof file without network calls. Returns calendar_attestations (promises from OTS servers, NOT Bitcoin confirmation) and bitcoin_attestations (actual Bitcoin blocks). A stamp is only truly confirmed when bitcoin_attestations > 0 and bitcoin_confirmed is true.",
     inputSchema: {
       type: "object",
       properties: { id: { type: "string", description: "UUID from the stamp record" } },
@@ -231,21 +153,19 @@ var TOOL_DEFINITIONS = [
     }
   },
   {
-    name: "preserve",
-    description: "FILESYSTEM-SENSITIVE: Compresses a directory to ZIP, stamps its SHA-256 hash, stores archive in whitelist directory. Requires preserve_whitelist config.",
+    name: "watch",
+    description: "Opens a new terminal window that monitors pending stamps in real-time, polling at the given interval. The window stays open so the user can watch progress.",
     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"]
+        interval_minutes: { type: "number", description: "Polling interval in minutes (default: 5, minimum: 1)" }
+      }
     },
     annotations: {
-      readOnlyHint: false,
+      readOnlyHint: true,
       destructiveHint: false,
       idempotentHint: false,
-      openWorldHint: true
+      openWorldHint: false
     }
   }
 ];
@@ -281,8 +201,8 @@ async function runServer() {
         case "list_pending":
           result = listPending(args, db, config);
           break;
-        case "preserve":
-          result = await preserve(args, db, config);
+        case "watch":
+          result = openWatchWindow(args?.interval_minutes);
           break;
         default:
           return { content: [{ type: "text", text: JSON.stringify({ error: "unknown_tool", tool: name }) }], isError: true };

package/dist/watch-7NPUWR6I.js

@@ -0,0 +1,41 @@
+import {
+  getDb,
+  loadConfig
+} from "./chunk-4ZDPWS7C.js";
+
+// src/tools/watch.ts
+async function watchPending(intervalMinutes = 5) {
+  const config = loadConfig();
+  const db = getDb(config);
+  process.stdout.write(`Watching pending stamps every ${intervalMinutes} min. Ctrl+C to stop.
+
+`);
+  function tick() {
+    const rows = db.prepare(
+      `SELECT id, hash, status, attempt_count, bitcoin_block, confirmed_at FROM stamps WHERE status != 'confirmed' ORDER BY created_at DESC`
+    ).all();
+    const confirmed = db.prepare(`SELECT COUNT(*) as n FROM stamps WHERE status = 'confirmed'`).get();
+    process.stdout.write(`${now()} \u2014 ${rows.length} pendientes, ${confirmed.n} confirmados
+`);
+    for (const row of rows) {
+      process.stdout.write(`  ${row.id.slice(0, 8)}  ${row.status}  (${row.attempt_count} intentos)
+`);
+    }
+    if (rows.length === 0) {
+      process.stdout.write(`  (ning\xFAn sello pendiente)
+`);
+    }
+    process.stdout.write("\n");
+  }
+  function now() {
+    return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 19);
+  }
+  function loop() {
+    tick();
+    setTimeout(loop, Math.max(6e4, intervalMinutes * 60 * 1e3));
+  }
+  loop();
+}
+export {
+  watchPending
+};

package/package.json

@@ -1,32 +1,46 @@
 {
   "name": "@otskit/mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "OpenTimestamps MCP server — stamp, upgrade, verify via AI agents",
   "type": "module",
-  "engines": { "node": ">=18" },
-  "bin": { "ots-mcp": "dist/index.js" },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "ots-mcp": "dist/index.js"
+  },
   "exports": "./dist/index.js",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --clean",
-    "dev":   "tsup src/index.ts --format esm --watch",
-    "test":  "vitest run",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "test": "vitest run",
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@otskit/core": "^0.1.0",
-    "@otskit/client": "^0.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "^12.10.0",
-    "archiver": "^7.0.0"
+    "@otskit/client": "^0.1.1",
+    "@otskit/core": "^0.1.0",
+    "better-sqlite3": "^12.10.0"
   },
   "pnpm": {
-    "onlyBuiltDependencies": ["better-sqlite3", "esbuild"]
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild"
+    ]
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10",
+    "@semantic-release/github": "^12.0.8",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.0.0",
     "@types/better-sqlite3": "^7.6.13",
-    "@types/archiver": "^6.0.3",
     "@types/node": "^22.0.0",
+    "semantic-release": "^25.0.3",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "vitest": "^2.1.4"

package/dist/chunk-45GR42GV.js

@@ -1,115 +0,0 @@
-import {
-  getDataDir,
-  getStamp,
-  insertStamp,
-  listStamps,
-  logOperation
-} from "./chunk-ASPLCXMC.js";
-import {
-  writeAtomic
-} from "./chunk-YFSUDT24.js";
-
-// src/tools/create-timestamp.ts
-import { mkdirSync } from "fs";
-import { join } from "path";
-import { randomUUID } from "crypto";
-import { OpenTimestampsClient } from "@otskit/client";
-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 = join(getDataDir(), "proofs");
-  mkdirSync(proofDir, { recursive: true });
-  const proofPath = join(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/verify-timestamp.ts
-import { readFileSync } from "fs";
-import { OpenTimestampsClient as OpenTimestampsClient2 } 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 = readFileSync(record.proof_path);
-  } catch (e) {
-    return { error: "storage_error", details: String(e) };
-  }
-  const client = new OpenTimestampsClient2({
-    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 {
-  createTimestamp,
-  verifyTimestamp,
-  listPending
-};

package/dist/watch-JWDMAZWS.js

@@ -1,47 +0,0 @@
-import {
-  getDb,
-  loadConfig,
-  upgradeTimestamp
-} from "./chunk-ASPLCXMC.js";
-import "./chunk-YFSUDT24.js";
-
-// src/tools/watch.ts
-async function watchPending(intervalMinutes = 5) {
-  const config = loadConfig();
-  const db = getDb(config);
-  process.stdout.write(`Watching pending stamps every ${intervalMinutes} min. Ctrl+C to stop.
-
-`);
-  async function tick() {
-    const rows = db.prepare(`SELECT id, hash, status FROM stamps WHERE status = 'pending'`).all();
-    if (rows.length === 0) {
-      process.stdout.write(`${now()} All stamps confirmed.
-`);
-      process.exit(0);
-    }
-    process.stdout.write(`${now()} Checking ${rows.length} pending stamps...
-`);
-    for (const row of rows) {
-      const result = await upgradeTimestamp({ id: row.id }, db, config);
-      if ("error" in result) {
-        process.stdout.write(`  ${row.id.slice(0, 8)}... ERROR: ${result.error}
-`);
-      } else if (result.status === "confirmed") {
-        process.stdout.write(`  ${row.id.slice(0, 8)}... CONFIRMED block #${result.bitcoin_block}
-`);
-      } else {
-        process.stdout.write(`  ${row.id.slice(0, 8)}... pending (attempt ${result.attempt_count})
-`);
-      }
-    }
-    process.stdout.write("\n");
-  }
-  function now() {
-    return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 19);
-  }
-  await tick();
-  setInterval(tick, intervalMinutes * 60 * 1e3);
-}
-export {
-  watchPending
-};