@helm-protocol/ttt-mcp 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @helm-protocol/ttt-mcp
 
-> Reference implementation of [draft-helmprotocol-tttps-00](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) (IETF Experimental)
+> Reference implementation of [draft-helmprotocol-tttps](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) (IETF Experimental)
 
 **MCP Server for OpenTTT — Proof of Time tools for AI agents**
 
@@ -8,13 +8,13 @@
 
 ## The Problem: Workflow Amnesia
 
-Large Claude Code workflows — 20-agent Dynamic Workflows, multi-day multi-session projects, 100K+ token contexts — all face the same failure mode: **context compression erases action history.**
+Every Claude Code long-horizon workflow hits the same wall: **context compression erases action history.**
 
 Agent B has no memory of what Agent A decided. Agent A resumes after compression with no record of its own prior steps. Duplicate work. Lost decisions. State corruption.
 
-**ttt-mcp is the external nervous system that survives context compression.**
+**ttt-mcp is the external causal chain that survives context compression.**
 
-Every workflow step is anchored to a cryptographic timestamp on an **external server** — physically separate from Claude's context window. When compression happens, agents query their exact action history through the MCP tools and resume with full causal context.
+Every workflow step is anchored to a cryptographic timestamp on an **external server** — physically separate from Claude's context window. When compression happens, agents call `pot_query(eventId)` for O(1) exact step recall and resume with full causal context.
 
 ```
 Claude workflow → [context compressed] → agents call pot_query(eventId)
@@ -24,48 +24,108 @@ Claude workflow → [context compressed] → agents call pot_query(eventId)
 
 ---
 
-## Mathematical Guarantee
+## Mathematical Guarantees
 
 | Layer | Mechanism | Guarantee |
 |-------|-----------|-----------|
-| **Identity** | SHA-3 eventId (256-bit) | Collision probability 2⁻²⁵⁶ ≈ 0 — practically 100% exact step recall |
+| **Identity** | SHA-3 eventId (256-bit) | Collision probability 2⁻²⁵⁶ — practically zero |
+| **Lookup** | O(1) exact retrieval | No context consumed by history reconstruction |
 | **Ordering** | TTTPS causal timestamps | Total order on events — tamper-proof sequence proof |
 | **Causal chain** | prevEventId DAG | O(depth) traversal — depth ~100 for 1B-token workflows |
-| **Fingerprint** | Multi-layer cryptographic pipeline | Formally bounded tamper-evident step identity |
 | **Non-repudiation** | Ed25519 signature | Cryptographic proof of who acted when |
+| **Resilience** | Erasure-coded cryptographic shards | ≥97% recovery at BER=0.05, 99.88% at BER=0.02 (theoretical) |
+| **Persistence** | Redis AOF + 90-day TTL | Server survives context compression and restarts |
 
 ---
 
 ## Quick Start
 
+### Claude Code
+
+```bash
+claude mcp add ttt -- npx -y @helm-protocol/ttt-mcp@0.3.0
+```
+
+With an API key (raises the free limit to your plan's monthly quota):
 ```bash
-# Claude Desktop
+claude mcp add ttt -e TTT_API_KEY=your-key -- npx -y @helm-protocol/ttt-mcp@0.3.0
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
 ```json
 {
   "mcpServers": {
     "ttt": {
       "command": "npx",
-      "args": ["-y", "@helm-protocol/ttt-mcp"]
+      "args": ["-y", "@helm-protocol/ttt-mcp@0.3.0"],
+      "env": { "TTT_API_KEY": "your-key" }
     }
   }
 }
 ```
 
-Add `TTT_API_KEY` for unlimited calls (free tier: 100 calls/day per IP).
+### Cursor
+
+[![Add to Cursor](https://img.shields.io/badge/Add%20to%20Cursor-1a1a1a?style=flat&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=ttt&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBoZWxtLXByb3RvY29sL3R0dC1tY3BAMC4zLjAiXX0=)
+
+One-click install, or add the same `mcpServers` block above to `.cursor/mcp.json`.
+
+Free tier: 100 calls/day per IP — no signup needed.
+
+---
+
+## 5-Minute Test
+
+Once connected, run this sequence in Claude:
+
+**Step 1 — Stamp a workflow step:**
+
+Just tell Claude naturally:
+> "Stamp this step as my-first-step"
+> "Record what I just did as refactor-auth-step1"
+
+Claude calls `pot_generate` automatically. Or call it directly:
+```
+pot_generate(eventId: "my-first-step")
+```
+
+**Step 2 — Simulate context compression:** start a new Claude session
+
+**Step 3 — Recover in the new session:**
+
+Tell Claude:
+> "What did I do in my-first-step?"
+> "Recover my last workflow state"
+
+Or call directly:
+```
+pot_query(eventId: "my-first-step")
+```
+→ Returns exact record. Amnesia gone.
+
+**Step 4 — Build a causal chain:**
+```
+pot_generate(eventId: "step-2", prevEventId: "my-first-step")
+pot_graph(eventId: "step-2", depth: 5)
+```
+→ Full backward chain. Cryptographically ordered.
 
 ---
 
-## Tools
+## 7 Tools
 
-| Tool | Description |
-|------|-------------|
-| `pot_generate` | Stamp a workflow step with eventId + prevEventId (builds causal chain) |
-| `pot_verify` | Verify a Proof of Time using its hash and integrity shards |
-| `pot_query` | O(1) exact lookup by eventId — call this after context compression |
-| `pot_graph` | Traverse full causal DAG — backward + forward chain from any step |
-| `pot_stats` | Get turbo/full mode statistics for a time period |
-| `pot_health` | Check system health: time sources, uptime, current mode |
-| `pot_checkpoint` | Create a compressed rollup checkpoint of workflow history |
+| Tool | Purpose |
+|------|---------|
+| `pot_generate` | Stamp a workflow step with a cryptographic timestamp |
+| `pot_verify` | Verify a PoT signature |
+| `pot_query` | O(1) exact lookup by eventId — core amnesia recovery |
+| `pot_graph` | Traverse causal DAG (backward + forward chain) |
+| `pot_checkpoint` | Roll up events into a compressed summary — use every ~100 events or before long tasks |
+| `pot_stats` | Server statistics and mode status |
+| `pot_health` | Health check |
 
 ---
 
@@ -103,6 +163,19 @@ Traverse the causal chain from any step. Returns backward chain (ancestors) and
 | eventId | string | Yes | Step to traverse from |
 | depth | number | No | Max backward depth. Default: 10, max: 100 |
 
+**Returns:**
+- `backwardChain` — ancestors in chronological order (depth-compressed for large chains)
+- `forwardChain` — steps that follow the given eventId
+- `chainBroken` — `true` if a gap is detected (ancestor was evicted from ring buffer, or the chain root references an unknown entry)
+- `brokenAt` — `"server_restart"` if the gap was caused by a server restart clearing in-memory state; otherwise the eventId at which the break occurred; `null` if chain is intact
+- `reachableDepth` — number of ancestors successfully traversed before the gap (or chain root)
+
+**Causal chain gap causes:**
+- **`server_restart`**: the server restarted and the in-memory DAG was cleared. If Redis is available and `REDIS_URL` is set, the DAG is rebuilt from Redis on startup — reducing restart gaps.
+- **Ring-buffer eviction**: the ring buffer holds the most recent 10,000 events in memory. Ancestors beyond that window show as `chainBroken: true` with `brokenAt` set to the oldest reachable eventId.
+
+**Recovering from a gap**: call `pot_checkpoint` before long tasks to compress and preserve the chain within the token budget, or use Redis persistence to survive restarts.
+
 ### pot_verify
 
 | Parameter | Type | Required | Description |
@@ -138,7 +211,8 @@ Creates a compressed rollup checkpoint of workflow history.
 
 **Returns:**
 - `checkpointId` — unique checkpoint identifier
-- `rollupSummary` — compressed event history (depth-adaptive: full/compact/minimal/rollup)
+- `rollup` — compressed event history (depth-adaptive: full/compact/minimal/rollup)
+- `summary` — human-readable one-line summary of the checkpoint
 - `chainIntact` — whether the causal chain is unbroken
 - `nextCheckpointHint` — recommended events before next checkpoint
 
@@ -187,6 +261,19 @@ const chain = await client.callTool({
 });
 // chain.backwardChain — all ancestor steps in chronological order
 // chain.forwardChain — steps that follow this one
+// chain.chainBroken — true if a gap was detected in the ancestor chain
+// chain.brokenAt    — "server_restart" if the server restarted and cleared
+//                     the in-memory DAG; otherwise the eventId of the oldest
+//                     reachable ancestor before the gap; null if chain intact
+// chain.reachableDepth — how many ancestors were recovered before the gap
+
+// Handle a server-restart gap:
+if (chain.chainBroken && chain.brokenAt === "server_restart") {
+  // Server cleared in-memory state; ancestors before the gap are gone unless
+  // Redis was configured (REDIS_URL) — in that case the DAG was rebuilt on
+  // restart and chainBroken will be false.
+  // Recover by querying the most recent checkpoint or restarting from a known step.
+}
 ```
 
 **Before a long task or every ~100 events — create a checkpoint:**
@@ -201,7 +288,7 @@ const checkpoint = await client.callTool({
   }
 });
 // checkpoint.checkpointId — store this; resume from it after compression
-// checkpoint.rollupSummary — depth-adaptive compressed history (10–200 tokens/event)
+// checkpoint.rollup — depth-adaptive compressed history (10–200 tokens/event)
 // checkpoint.chainIntact: true — causal chain verified unbroken
 // checkpoint.nextCheckpointHint: 87 — suggested events before next checkpoint
 
@@ -230,7 +317,7 @@ const history = await client.callTool({
 
 **Problem**: You got front-run. You can't prove it — mempool timestamps are per-node, unsigned, non-authoritative.
 
-**Solution**: Call `pot_generate` before every submission. The PoT receipt is cryptographically signed by three independent time sources (NIST, Google, Cloudflare), anchored on Base Sepolia TTT ERC-1155. If front-running occurs, you have a timestamped, on-chain record predating the attacker's block inclusion.
+**Solution**: Call `pot_generate` before every submission. The PoT receipt is cryptographically signed using three independent time sources (NIST, Google, Cloudflare). The on-chain hash can be anchored via a separate Base Sepolia TTT ERC-1155 contract. If front-running occurs, you have a timestamped record predating the attacker's block inclusion.
 
 ```typescript
 const pot = await client.callTool({
@@ -240,11 +327,15 @@ const pot = await client.callTool({
 // pot.potHash — your evidence, timestamped by NIST+Google+Cloudflare
 ```
 
+> **Note:** The DeFi path (`txHash` + `chainId` + `poolAddress`) requires a server-side build with the integrity-shard pipeline enabled. It is not available in the public `openttt` npm package; calls without it will throw. The Claude Code path (`eventId`) works out of the box.
+
 ---
 
 ### 3. DEX Protocol — Sandwich Deterrence
 
-**Solution**: Integrate `TTTHookSimple` (Uniswap V4 hook, Base Sepolia: `0x8C633b05b833a476925F7d9818da6E215760F2c7`). Honest builders get `turbo` mode. Tampered sequences get `full` mode (exponential backoff). Economics, not governance.
+**Solution**: Integrate `TTTHookSimple` (Uniswap V4 hook, Base Sepolia: `0x8C633b05b833a476925F7d9818da6E215760F2c7`). Honest builders get `turbo` mode. Tampered sequences get `full` mode (penalty delay). Economics, not governance.
+
+> **Note:** Shard-based verification (`pot_verify` with `grgShards`) requires a server-side build with the integrity-shard pipeline enabled — not available in the public `openttt` npm package.
 
 ---
 
@@ -252,19 +343,21 @@ const pot = await client.callTool({
 
 **Problem**: MiFIR Article 22c / RTS 25 requires microsecond-precision UTC-synchronized timestamps. Hardware PTP appliances cost $50K–$500K.
 
-**Solution**: `pot_generate` produces an Ed25519-signed timestamp with uncertainty bound and multi-source attestation. Structurally compatible with RTS 25 audit record requirements. One API call per trade.
+**Solution**: `pot_generate` produces an Ed25519-signed timestamp with an uncertainty bound and multi-source attestation. Structurally compatible with the RTS 25 audit record format. One API call per trade.
 
 ```typescript
 const audit = await client.callTool({
   name: "pot_generate",
   arguments: { txHash: tradeHash, chainId: 8453 }
 });
-// audit.timestamp: nanosecond precision
-// audit.uncertainty: ±ms bound (RTS 25 required field)
+// audit.timestamp: high-resolution timestamp
+// audit.uncertainty: ± bound (RTS 25 uncertainty field)
 // audit.confidence: fraction of sources that agreed
 ```
 
-**Outcome**: MiFIR-grade audit trail. IETF standardized via `draft-helmprotocol-tttps-00`.
+> **Precision note:** The default network time sources (Roughtime / NTP) provide a few-millisecond uncertainty bound. The MiFIR Art. 22c / RTS 25 ±1ms (and tighter) requirement is met only with an added GEO time source (KTSat); this is a roadmap configuration, not the default deployment.
+
+**Outcome**: Structurally compatible audit trail. IETF specification: `draft-helmprotocol-tttps`.
 
 ---
 
@@ -276,16 +369,48 @@ const audit = await client.callTool({
 
 ---
 
-## Rate Limits & Pricing
+## How It Differs — A Different Job, Not "Better"
 
-```
-Free Tier:   100 calls/day per IP — no API key needed
-BOT Tier:    $199/mo — unlimited, SLA
-DEX Tier:    $499/mo — unlimited, priority support
-FUND Tier:   $2K+/mo — enterprise, dedicated infra
-```
+| Tool | Integration | What it recalls | Integrity | Hot-path cost |
+|------|-------------|-----------------|-----------|---------------|
+| Letta (MemGPT) | owns the agent loop | self-editing semantic memory | none | embedding + vector search per memory op |
+| LangGraph / LangMem | LangGraph only | graph state / semantic | none | checkpoint I/O (+ embeddings) |
+| RAG / vector DB | bolt-on | fuzzy similarity | none | embed + vector search per item |
+| **ttt-mcp** | **2-min MCP retrofit** | **exact causal step (by eventId)** | **Ed25519 + TTTPS timestamp** | **sign + hash + write — 0 embedding calls** |
+
+**The cost difference is structural, not incidental.**
+
+Letta and Mem0 treat agent memory as a semantic search problem — every recall forces an LLM embedding call and a vector search. ttt-mcp bypasses the LLM/embedding layer entirely: state recovery is an O(1) cryptographic hash lookup. Marginal cost is commodity CPU + storage, not API tokens.
+
+**Scope**: agents stamp the steps worth checkpointing — not every token, not every query. Volume tracks decisions, not total chat traffic.
+
+If you need fuzzy semantic search over past conversations, use Letta or a vector DB. If you need a zero-embedding, deterministic state recovery layer for long-horizon workflows that survives context compaction, use ttt-mcp.
+
+---
+
+## Pricing
+
+| Tier | Price | Calls/month |
+|------|-------|-------------|
+| Free | $0 | 100/day per IP — no signup |
+| Dev | $29/mo | 100K |
+| Pro | $99/mo | 1M |
+| Team | $299/mo | 10M + $0.01/1K overage |
+| Enterprise | $999+/mo | 100M calls/mo · $0.001/1K overage · SLA 99.9% |
+| Platform License | Negotiated ($2M+/yr) | Volume cap negotiated · native integration |
+
+**Subscribe:**
 
-Contact: heime.jorgen@proton.me
+Dev **$29/mo** · Pro **$99/mo** · Team **$299/mo** — to subscribe, email [peter@kenosian.com](mailto:peter@kenosian.com).
+
+Enterprise & Platform License: [peter@kenosian.com](mailto:peter@kenosian.com)
+
+Contact: peter@kenosian.com
+
+**Quota mechanics — stdio vs HTTP:**
+
+- **HTTP mode** (Glama / Smithery container, `PORT` set): the per-IP free tier limit (100 calls/day) is enforced locally in the server process.
+- **stdio mode** (Claude Code `npx`, Claude Desktop): there is no per-IP counter. Tool calls are delegated to `api.kenosian.com` via `X-TTT-API-Key`; quota is enforced server-side against your plan's monthly allowance. Without `TTT_API_KEY` the local fallback runs with no daily cap, but plan features (server-side DAG persistence, multi-session causal chains) are unavailable.
 
 ---
 
@@ -294,12 +419,37 @@ Contact: heime.jorgen@proton.me
 - Node.js >= 18
 - Network access for time synthesis (HTTPS to time.nist.gov, time.google.com, time.cloudflare.com)
 
+**Time source tiers (automatic fallback):**
+
+| Tier | Source | Stratum | Notes |
+|------|--------|---------|-------|
+| 1 (preferred) | PTP / hardware clock | 0–1 | Requires local PTP daemon |
+| 2 | Roughtime / NTP (NIST, Google, Cloudflare) | 2–4 | Default for most deployments |
+| 3 (offline fallback) | Local system clock | 16 | RFC 5905 unsynchronized stratum — used when all network sources are unreachable |
+
+The server falls through to stratum 16 automatically; no manual configuration needed. The `stratum` field in every `pot_generate` response indicates which tier was used.
+
+**Redis persistence (optional):**
+
+Redis is not required. The in-memory DAG is authoritative at runtime. If `REDIS_URL` is set, events are written to Redis with a 90-day TTL and the DAG is rebuilt from Redis on server restart — reducing `server_restart` chain gaps. Without Redis, the in-memory DAG is cleared on restart.
+
+---
+
+## Production Tips
+
+**Cold Start warm-up** — On first startup, BatchSigner requires one request to initialize. Call `pot_health` or send a single dummy `pot_generate` before your load balancer health check goes live. Without this, the first request may see p99 ~500ms; subsequent requests stabilize to <10ms.
+
+```bash
+# Kubernetes / Docker: add to your startup script
+curl -s http://your-server/pot/health > /dev/null
+```
+
 ---
 
 ## Learn More
 
 - [OpenTTT SDK](https://www.npmjs.com/package/openttt) — The underlying SDK
-- [IETF Draft: draft-helmprotocol-tttps-00](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) — TTTPS Protocol Specification
+- [IETF Draft: draft-helmprotocol-tttps](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) — TTTPS Protocol Specification
 - [Helm Protocol](https://github.com/Helm-Protocol) — GitHub
 
 ## License

package/dist/auth.js

@@ -66,7 +66,7 @@ function writeUsageFile(entry) {
 }
 function checkRateLimit(apiKey, clientIp) {
   if (apiKey && apiKey.trim().length > 0) {
-    return { allowed: true, remaining: -1, tier: "paid" };
+    return { allowed: true, remaining: -1, tier: "paid", serverDelegated: true };
   }
   const now = Date.now();
   if (clientIp === "stdio") {

package/dist/index.js

@@ -7,6 +7,7 @@ var import_http = require("http");
 var import_zod = require("zod");
 var import_tools = require("./tools");
 var import_auth = require("./auth");
+var import_server = require("./server");
 async function restoreDAGFromRedis() {
   try {
     await Promise.race([
@@ -60,11 +61,50 @@ async function restoreDAGFromRedis() {
   }
   return restored;
 }
+function toolError(err) {
+  if (err instanceof import_server.QuotaExceededError) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            { error: "quota_exceeded", tier: err.tier, message: err.message, upgradeUrl: err.upgradeUrl },
+            null,
+            2
+          )
+        }
+      ],
+      isError: true
+    };
+  }
+  return {
+    content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+    isError: true
+  };
+}
+function toolSuccess(result) {
+  const seal = (0, import_tools.tttsFreshnessSeal)();
+  if (seal && result !== null && typeof result === "object") {
+    const r = result;
+    const notice = r._quotaNotice;
+    if (notice) {
+      const { _quotaNotice: _, ...rest } = r;
+      return {
+        content: [
+          { type: "text", text: JSON.stringify({ ...rest, _tttps_freshness: seal }, null, 2) },
+          { type: "text", text: `\u26A0 Quota notice: ${notice}` }
+        ]
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify({ ...result, _tttps_freshness: seal }, null, 2) }] };
+  }
+  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
 function buildMcpServer() {
-  const s = new import_mcp.McpServer({ name: "ttt-mcp", version: "0.1.0" });
+  const s = new import_mcp.McpServer({ name: "ttt-mcp", version: "0.3.1" });
   s.tool(
     "pot_generate",
-    "Generate a cryptographic Proof of Time timestamp. For Claude Code workflows: use eventId + prevEventId to build a causal chain. For DeFi: use txHash + chainId + poolAddress. Either eventId or txHash is required.",
+    "Generate a cryptographic Proof of Time timestamp (draft-helmprotocol-tttps, https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/). For Claude Code workflows: use eventId + prevEventId to build a causal chain. For DeFi: use txHash + chainId + poolAddress. Either eventId or txHash is required.",
     {
       eventId: import_zod.z.string().optional().describe("Workflow step identifier (Claude Code). E.g. 'refactor_auth_step1'"),
       prevEventId: import_zod.z.string().optional().describe("Previous step's eventId \u2014 links steps into a causal chain"),
@@ -72,12 +112,13 @@ function buildMcpServer() {
       chainId: import_zod.z.number().optional().describe("EVM chain ID (DeFi, e.g. 8453 for Base)"),
       poolAddress: import_zod.z.string().optional().describe("DEX pool contract address (DeFi)")
     },
+    { title: "Generate Proof of Time", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     async (args) => {
       try {
         const result = await (0, import_tools.potGenerate)(args);
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return toolSuccess(result);
       } catch (err) {
-        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        return toolError(err);
       }
     }
   );
@@ -90,12 +131,13 @@ function buildMcpServer() {
       chainId: import_zod.z.number().describe("EVM chain ID (e.g. 84532 for Base Sepolia)"),
       poolAddress: import_zod.z.string().describe("Uniswap V4 pool address (0x-prefixed)")
     },
+    { title: "Verify Proof of Time", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     async (args) => {
       try {
         const result = await (0, import_tools.potVerify)(args);
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return toolSuccess(result);
       } catch (err) {
-        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        return toolError(err);
       }
     }
   );
@@ -108,12 +150,13 @@ function buildMcpServer() {
       endTime: import_zod.z.number().optional().describe("End time (unix ms). Default: now"),
       limit: import_zod.z.number().optional().describe("Max entries to return. Default: 100, max: 1000")
     },
+    { title: "Query Proof of Time Records", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     async (args) => {
       try {
         const result = await (0, import_tools.potQuery)(args);
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return toolSuccess(result);
       } catch (err) {
-        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        return toolError(err);
       }
     }
   );
@@ -124,12 +167,13 @@ function buildMcpServer() {
       eventId: import_zod.z.string().describe("The workflow step to start traversal from"),
       depth: import_zod.z.number().optional().describe("Max backward traversal depth. Default: 10, max: 100")
     },
+    { title: "Traverse PoT Causal Chain", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     async (args) => {
       try {
         const result = await (0, import_tools.potGraph)(args);
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return toolSuccess(result);
       } catch (err) {
-        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        return toolError(err);
       }
     }
   );
@@ -137,12 +181,13 @@ function buildMcpServer() {
     "pot_stats",
     "Get PoT statistics: total swaps, turbo/full counts, and turbo ratio for a given period.",
     { period: import_zod.z.enum(["day", "week", "month"]).describe("Time period for statistics") },
+    { title: "PoT Statistics", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     async (args) => {
       try {
         const result = await (0, import_tools.potStats)(args);
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return toolSuccess(result);
       } catch (err) {
-        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        return toolError(err);
       }
     }
   );
@@ -150,12 +195,13 @@ function buildMcpServer() {
     "pot_health",
     "Check PoT system health: time source status, subgraph sync, server uptime, and current mode.",
     {},
+    { title: "PoT System Health", readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     async () => {
       try {
         const result = await (0, import_tools.potHealth)();
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return toolSuccess(result);
       } catch (err) {
-        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        return toolError(err);
       }
     }
   );
@@ -169,12 +215,13 @@ function buildMcpServer() {
       endTime: import_zod.z.number().optional().describe("Unix ms end time (optional, default: now)"),
       maxTokens: import_zod.z.number().optional().describe("Approximate max tokens for rollup (default: 2000)")
     },
+    { title: "Create PoT Checkpoint", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     async (args) => {
       try {
         const result = await (0, import_tools.potCheckpoint)(args);
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return toolSuccess(result);
       } catch (err) {
-        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        return toolError(err);
       }
     }
   );
@@ -187,7 +234,7 @@ async function main() {
     const httpServer = (0, import_http.createServer)(async (req, res) => {
       if (req.method === "GET" && (req.url === "/health" || req.url === "/ping")) {
         res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ status: "ok", server: "ttt-mcp", version: "0.2.0" }));
+        res.end(JSON.stringify({ status: "ok", server: "ttt-mcp", version: "0.3.1" }));
         return;
       }
       if (req.method === "POST") {
@@ -204,7 +251,8 @@ async function main() {
           res.end(
             JSON.stringify({
               error: "rate_limit_exceeded",
-              message: "Free tier: 100 calls/day reached. Contact heime.jorgen@proton.me for commercial access.",
+              message: import_server.FREE_TIER_UPGRADE_MESSAGE,
+              upgradeUrl: import_server.UPGRADE_URL,
               tier: "free"
             })
           );

package/dist/server.js

@@ -0,0 +1,136 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var server_exports = {};
+__export(server_exports, {
+  FREE_TIER_UPGRADE_MESSAGE: () => FREE_TIER_UPGRADE_MESSAGE,
+  QuotaExceededError: () => QuotaExceededError,
+  SERVER_BASE_URL: () => SERVER_BASE_URL,
+  UPGRADE_MESSAGE: () => UPGRADE_MESSAGE,
+  UPGRADE_URL: () => UPGRADE_URL,
+  delegateToServer: () => delegateToServer
+});
+module.exports = __toCommonJS(server_exports);
+const SERVER_BASE_URL = (process.env.OPENTTT_SERVER_URL?.trim() || "https://api.kenosian.com").replace(/\/+$/, "");
+const UPGRADE_URL = "https://kenosian.com/products/hydra-mcp.html";
+const UPGRADE_MESSAGE = `Plan quota reached. Upgrade your OpenTTT plan at ${UPGRADE_URL} to continue.`;
+const FREE_TIER_UPGRADE_MESSAGE = `Free tier limit reached (${process.env.FREE_TIER_LIMIT ?? "100"} calls/day). Set TTT_API_KEY with a paid plan, or upgrade at ${UPGRADE_URL}.`;
+class QuotaExceededError extends Error {
+  upgradeUrl;
+  tier;
+  constructor(message, tier) {
+    super(message);
+    this.name = "QuotaExceededError";
+    this.upgradeUrl = UPGRADE_URL;
+    this.tier = tier;
+  }
+}
+function parseQuotaAdvisory(headers) {
+  const remaining = headers.get("x-ratelimit-remaining");
+  const limit = headers.get("x-ratelimit-limit");
+  const warningHeader = headers.get("x-ratelimit-warning");
+  const overage = headers.get("x-ratelimit-overage");
+  const tier = headers.get("x-ratelimit-tier");
+  const advisory = {};
+  let hasContent = false;
+  if (tier) {
+    advisory.tier = tier;
+    hasContent = true;
+  }
+  if (remaining !== null) {
+    advisory.remaining = parseInt(remaining, 10);
+    hasContent = true;
+  }
+  if (limit !== null) {
+    advisory.limit = parseInt(limit, 10);
+    hasContent = true;
+  }
+  if (warningHeader) {
+    advisory.warning = warningHeader;
+    hasContent = true;
+  } else if (advisory.remaining !== void 0 && advisory.limit !== void 0 && advisory.limit > 0) {
+    const usedRatio = 1 - advisory.remaining / advisory.limit;
+    if (usedRatio >= 0.8) {
+      advisory.warning = `Approaching plan limit: ${advisory.remaining} of ${advisory.limit} calls remaining this period.`;
+      hasContent = true;
+    }
+  }
+  if (overage?.toLowerCase() === "true") {
+    advisory.overageActive = true;
+    hasContent = true;
+  }
+  return hasContent ? advisory : void 0;
+}
+function buildUrl(path, query) {
+  const url = new URL(SERVER_BASE_URL + path);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+    }
+  }
+  return url.toString();
+}
+async function delegateToServer(opts) {
+  const { apiKey, method, path, body, query, timeoutMs = 8e3 } = opts;
+  const url = buildUrl(path, query);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method,
+      headers: {
+        "X-TTT-API-Key": apiKey,
+        ...method === "POST" ? { "Content-Type": "application/json" } : {}
+      },
+      ...method === "POST" ? { body: JSON.stringify(body ?? {}) } : {},
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (resp.status === 429) {
+    throw new QuotaExceededError(UPGRADE_MESSAGE, "paid");
+  }
+  if (!resp.ok) {
+    let detail = `HTTP ${resp.status}`;
+    try {
+      const j = await resp.json();
+      if (j?.error) detail = j.error;
+    } catch {
+    }
+    throw new Error(`openttt-server error: ${detail}`);
+  }
+  const advisory = parseQuotaAdvisory(resp.headers);
+  let data;
+  try {
+    data = await resp.json();
+  } catch {
+    data = {};
+  }
+  return advisory ? { data, advisory } : { data };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FREE_TIER_UPGRADE_MESSAGE,
+  QuotaExceededError,
+  SERVER_BASE_URL,
+  UPGRADE_MESSAGE,
+  UPGRADE_URL,
+  delegateToServer
+});

package/dist/tools.js

@@ -36,16 +36,31 @@ __export(tools_exports, {
   potStats: () => potStats,
   potVerify: () => potVerify,
   redis: () => redis,
-  restoreDagEntry: () => restoreDagEntry
+  restoreDagEntry: () => restoreDagEntry,
+  tttsFreshnessSeal: () => tttsFreshnessSeal,
+  updateLastPot: () => updateLastPot
 });
 module.exports = __toCommonJS(tools_exports);
 var import_openttt = require("openttt");
 var import_telemetry = require("./telemetry");
+var import_server = require("./server");
 var import_ioredis = __toESM(require("ioredis"));
 const GrgPipeline = (
   // eslint-disable-next-line @typescript-eslint/no-require-imports
   require("openttt").GrgPipeline ?? null
 );
+function applyAdvisory(result, advisory) {
+  if (!advisory) return result;
+  if (result === null || typeof result !== "object") return result;
+  const notices = [];
+  if (advisory.warning) notices.push(advisory.warning);
+  if (advisory.overageActive) notices.push("Overage billing is active \u2014 usage above your plan limit will be charged.");
+  if (notices.length === 0) return result;
+  return { ...result, _quotaNotice: notices.join(" | ") };
+}
+function resolvePaidApiKey() {
+  return process.env.TTT_API_KEY?.trim() || void 0;
+}
 const redis = new import_ioredis.default(process.env.REDIS_URL ?? "redis://127.0.0.1:6379", {
   lazyConnect: true,
   enableOfflineQueue: false,
@@ -101,6 +116,21 @@ function depthThresholdFromTokens(maxTokens, entryCount) {
     rollup: Math.min(minimalDepth, entryCount)
   };
 }
+let _lastPotTimestampNs = null;
+let _lastPotStratum = 16;
+let _lastPotSources = 0;
+function updateLastPot(timestampNs, stratum, sources) {
+  _lastPotTimestampNs = timestampNs;
+  _lastPotStratum = stratum;
+  _lastPotSources = sources;
+}
+function tttsFreshnessSeal() {
+  if (_lastPotTimestampNs === null) return null;
+  const nowNs = BigInt(Date.now()) * 1000000n;
+  const age_ms = Number((nowNs - _lastPotTimestampNs) / 1000000n);
+  const ttlMs = _lastPotStratum <= 3 ? 100 : _lastPotStratum <= 8 ? 1e3 : _lastPotStratum <= 15 ? 5e3 : 0;
+  return { age_ms, stratum: _lastPotStratum, sources: _lastPotSources, ttlMs };
+}
 function restoreDagEntry(entry) {
   if (potByEventId.has(entry.eventId)) return;
   const e = {
@@ -146,6 +176,22 @@ async function potGenerate(args) {
     throw new Error("Either eventId (Claude Code) or txHash (DeFi) is required");
   }
   (0, import_telemetry.telemetryIncrement)("pot_generate");
+  const apiKey = resolvePaidApiKey();
+  if (apiKey && args.eventId) {
+    const { data, advisory } = await (0, import_server.delegateToServer)({
+      apiKey,
+      method: "POST",
+      path: "/pot/generate",
+      body: { eventId: args.eventId, prevEventId: args.prevEventId }
+    });
+    if (data && typeof data === "object") {
+      const d = data;
+      if (typeof d.stratum === "number" && typeof d.sources === "number" && typeof d.timestamp === "string") {
+        updateLastPot(BigInt(d.timestamp), d.stratum, d.sources);
+      }
+    }
+    return applyAdvisory(data, advisory);
+  }
   let pot;
   let isOfflineFallback = false;
   try {
@@ -241,6 +287,7 @@ async function potGenerate(args) {
     ).catch(() => {
     });
   }
+  updateLastPot(pot.timestamp, pot.stratum, pot.sources);
   return serialize({
     potHash,
     eventId: args.eventId ?? null,
@@ -284,6 +331,21 @@ async function potVerify(args) {
 }
 async function potQuery(args) {
   (0, import_telemetry.telemetryIncrement)("pot_query");
+  const apiKey = resolvePaidApiKey();
+  if (apiKey) {
+    const { data, advisory } = await (0, import_server.delegateToServer)({
+      apiKey,
+      method: "GET",
+      path: "/pot/query",
+      query: {
+        eventId: args.eventId,
+        startTimeNs: args.startTime != null ? args.startTime * 1e6 : void 0,
+        endTimeNs: args.endTime != null ? args.endTime * 1e6 : void 0,
+        limit: args.limit
+      }
+    });
+    return applyAdvisory(data, advisory);
+  }
   if (args.eventId) {
     const entry = potByEventId.get(args.eventId);
     return serialize({
@@ -338,6 +400,16 @@ async function potQuery(args) {
 }
 async function potGraph(args) {
   (0, import_telemetry.telemetryIncrement)("pot_graph");
+  const apiKey = resolvePaidApiKey();
+  if (apiKey) {
+    const { data, advisory } = await (0, import_server.delegateToServer)({
+      apiKey,
+      method: "GET",
+      path: "/pot/graph",
+      query: { eventId: args.eventId, depth: args.depth }
+    });
+    return applyAdvisory(data, advisory);
+  }
   const maxDepth = Math.min(args.depth ?? 10, 100);
   const backwardChain = [];
   let cursor = potByEventId.get(args.eventId);
@@ -367,6 +439,15 @@ async function potGraph(args) {
 }
 async function potStats(args) {
   (0, import_telemetry.telemetryIncrement)("pot_stats");
+  const apiKey = resolvePaidApiKey();
+  if (apiKey) {
+    const { data, advisory } = await (0, import_server.delegateToServer)({
+      apiKey,
+      method: "GET",
+      path: "/pot/stats"
+    });
+    return applyAdvisory(data, advisory);
+  }
   const now = Date.now();
   const periodMs = {
     day: 864e5,
@@ -447,6 +528,22 @@ async function potHealth() {
 }
 async function potCheckpoint(args) {
   (0, import_telemetry.telemetryIncrement)("pot_checkpoint");
+  const apiKey = resolvePaidApiKey();
+  if (apiKey) {
+    const { data, advisory } = await (0, import_server.delegateToServer)({
+      apiKey,
+      method: "GET",
+      path: "/pot/checkpoint",
+      query: {
+        fromEventId: args.fromEventId,
+        toEventId: args.toEventId,
+        startTime: args.startTime,
+        endTime: args.endTime,
+        maxTokens: args.maxTokens
+      }
+    });
+    return applyAdvisory(data, advisory);
+  }
   const now = Date.now();
   const startTime = args.startTime ?? now - 36e5;
   const endTime = args.endTime ?? now;
@@ -470,7 +567,7 @@ async function potCheckpoint(args) {
   const depthThreshold = args.maxTokens ? depthThresholdFromTokens(args.maxTokens, entries.length) : void 0;
   const compressed = entries.map((e, i) => compressEntry(e, i + 1, depthThreshold));
   const chainIntact = !entries.some((e) => e.eventId && evictedEventIds.has(e.eventId));
-  const nextCheckpointHint = Math.max(10, 100 - eventCount % 100);
+  const nextCheckpointHint = Math.max(10, 240 - eventCount % 240);
   const checkpointId = `ckpt_${now}_${eventCount}`;
   const firstTs = entries[0]?.timestamp ?? null;
   const lastTs = entries[entries.length - 1]?.timestamp ?? null;
@@ -494,5 +591,7 @@ async function potCheckpoint(args) {
   potStats,
   potVerify,
   redis,
-  restoreDagEntry
+  restoreDagEntry,
+  tttsFreshnessSeal,
+  updateLastPot
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helm-protocol/ttt-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "MCP Server for OpenTTT — Proof of Time tools for AI agents",
   "main": "dist/index.js",
   "bin": {
@@ -11,10 +11,11 @@
     "README.md"
   ],
   "scripts": {
-    "build": "esbuild index.ts tools.ts telemetry.ts auth.ts --platform=node --target=node18 --format=cjs --outdir=dist",
+    "build": "esbuild index.ts tools.ts telemetry.ts auth.ts server.ts --platform=node --target=node18 --format=cjs --outdir=dist",
     "start": "node dist/index.js",
     "dev": "npx ts-node index.ts",
-    "test": "jest --forceExit"
+    "test": "jest --forceExit",
+    "typecheck": "NODE_OPTIONS='--max-old-space-size=4096' tsc --noEmit"
   },
   "jest": {
     "preset": "ts-jest",
@@ -51,7 +52,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "ioredis": "^5.11.0",
     "openttt": "^0.2.13",
     "zod": "^3.25.0"