@otskit/mcp 0.2.1 → 0.3.0

package/README.md

@@ -1,106 +1,106 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/OTSkit/OTSkit-MCP/master/docs/header.png" alt="OTSkit.ts MCP" width="480" />
-</p>
-
-# @otskit/mcp
-
-[![CI](https://github.com/OTSkit/OTSkit-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/OTSkit/OTSkit-MCP/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@otskit/mcp.svg)](https://www.npmjs.com/package/@otskit/mcp)
-[![npm downloads](https://img.shields.io/npm/dm/@otskit/mcp.svg)](https://www.npmjs.com/package/@otskit/mcp)
-[![TypeScript](https://img.shields.io/badge/TypeScript-6-blue.svg)](https://www.typescriptlang.org/)
-[![Node ≥20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-
-OpenTimestamps MCP server — stamp, upgrade, and verify Bitcoin timestamps via AI agents.
-
-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
-npm install -g @otskit/mcp
-```
-
-## Agent setup
-
-```bash
-ots-mcp setup claude        # Claude Desktop
-ots-mcp setup claude-code   # Claude Code CLI
-ots-mcp setup codex         # Codex CLI
-```
-
-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.
-
-## 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\|claude-code\|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
-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
+<p align="center">
+  <img src="https://raw.githubusercontent.com/OTSkit/OTSkit-MCP/master/docs/header.png" alt="OTSkit.ts MCP" width="480" />
+</p>
+
+# @otskit/mcp
+
+[![CI](https://github.com/OTSkit/OTSkit-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/OTSkit/OTSkit-MCP/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@otskit/mcp.svg)](https://www.npmjs.com/package/@otskit/mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@otskit/mcp.svg)](https://www.npmjs.com/package/@otskit/mcp)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6-blue.svg)](https://www.typescriptlang.org/)
+[![Node ≥20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+OpenTimestamps MCP server — stamp, upgrade, and verify Bitcoin timestamps via AI agents.
+
+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
+npm install -g @otskit/mcp
+```
+
+## Agent setup
+
+```bash
+ots-mcp setup claude        # Claude Desktop
+ots-mcp setup claude-code   # Claude Code CLI
+ots-mcp setup codex         # Codex CLI
+```
+
+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.
+
+## 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\|claude-code\|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
+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/package.json

@@ -1,49 +1,49 @@
-{
-  "name": "@otskit/mcp",
-  "mcpName": "io.github.AlexAlves87/otskit-mcp",
-  "version": "0.2.1",
-  "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": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@otskit/client": "^0.1.1",
-    "@otskit/core": "^0.1.0",
-    "better-sqlite3": "^12.10.0"
-  },
-  "pnpm": {
-    "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/node": "^25.9.1",
-    "semantic-release": "^25.0.3",
-    "tsup": "^8.3.5",
-    "typescript": "^6.0.3",
-    "vitest": "^2.1.4"
-  }
-}
+{
+  "name": "@otskit/mcp",
+  "mcpName": "io.github.otskit/otskit-mcp",
+  "version": "0.3.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": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@otskit/client": "^0.1.1",
+    "@otskit/core": "^0.1.0",
+    "better-sqlite3": "^12.10.0"
+  },
+  "pnpm": {
+    "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/node": "^25.9.1",
+    "semantic-release": "^25.0.3",
+    "tsup": "^8.3.5",
+    "typescript": "^6.0.3",
+    "vitest": "^2.1.4"
+  }
+}

package/dist/chunk-4ZDPWS7C.js

@@ -1,123 +0,0 @@
-// 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
-};