@helm-protocol/ttt-mcp 0.2.2 → 0.3.1

package/dist/index.js

@@ -7,192 +7,234 @@ var import_http = require("http");
 var import_zod = require("zod");
 var import_tools = require("./tools");
 var import_auth = require("./auth");
-const IS_STDIO = !process.env.PORT;
-const server = new import_mcp.McpServer({
-  name: "ttt-mcp",
-  version: "0.1.0"
-});
-server.tool(
-  "pot_generate",
-  "Generate a Proof of Time for a transaction. Returns potHash, timestamp, stratum, and GRG integrity shards.",
-  {
-    txHash: import_zod.z.string().describe("Transaction hash (hex with 0x prefix)"),
-    chainId: import_zod.z.number().describe("Chain ID (e.g. 8453 for Base, 84532 for Base Sepolia)"),
-    poolAddress: import_zod.z.string().describe("DEX pool contract address")
-  },
-  async (args) => {
-    if (IS_STDIO) {
-      const apiKey = (0, import_auth.resolveApiKey)();
-      const rl = (0, import_auth.checkRateLimit)(apiKey, "stdio");
-      if (!rl.allowed) {
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            error: "rate_limit_exceeded",
-            message: `Free tier: ${import_auth.FREE_TIER_LIMIT} calls/day. Set TTT_API_KEY env var for unlimited access. \u2192 kenosian.com/pricing`,
-            remaining: 0,
-            tier: "free"
-          }) }],
-          isError: true
-        };
+var import_server = require("./server");
+async function restoreDAGFromRedis() {
+  try {
+    await Promise.race([
+      import_tools.redis.connect(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 3e3))
+    ]);
+  } catch {
+    return 0;
+  }
+  let cursor = "0";
+  let restored = 0;
+  const entries = [];
+  try {
+    do {
+      const [next, keys] = await import_tools.redis.scan(cursor, "MATCH", "dag:*", "COUNT", "200");
+      cursor = next;
+      if (keys.length === 0) continue;
+      const values = await import_tools.redis.mget(...keys);
+      for (const v of values) {
+        if (!v) continue;
+        try {
+          const entry = JSON.parse(v);
+          if (entry.eventId) entries.push(entry);
+        } catch {
+        }
       }
-    }
+    } while (cursor !== "0");
+  } catch {
+    return 0;
+  }
+  entries.sort((a, b) => a.createdAt - b.createdAt);
+  for (const e of entries) {
     try {
-      const result = await (0, import_tools.potGenerate)(args);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      (0, import_tools.restoreDagEntry)({
+        eventId: e.eventId,
+        prevEventId: e.prevEventId,
+        potHash: e.potHash,
+        timestamp: e.timestamp,
+        stratum: e.stratum,
+        mode: e.mode,
+        createdAt: e.createdAt,
+        chainId: e.chainId,
+        poolAddress: e.poolAddress
+      });
+      restored++;
+    } catch {
+    }
+  }
+  if (restored > 0) {
+    console.error(`[ttt-mcp] DAG restored from Redis: ${restored} entries`);
+  }
+  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: `Error: ${message}` }],
-        isError: true
+        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) }] };
   }
-);
-server.tool(
-  "pot_verify",
-  "Verify a Proof of Time using its hash and GRG shards. Returns validity, mode (turbo/full), and timestamp.",
-  {
-    potHash: import_zod.z.string().describe("PoT hash to verify (hex with 0x prefix)"),
-    grgShards: import_zod.z.array(import_zod.z.string()).describe("Array of hex-encoded GRG integrity shards"),
-    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)")
-  },
-  async (args) => {
-    if (IS_STDIO) {
-      const apiKey = (0, import_auth.resolveApiKey)();
-      const rl = (0, import_auth.checkRateLimit)(apiKey, "stdio");
-      if (!rl.allowed) {
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            error: "rate_limit_exceeded",
-            message: `Free tier: ${import_auth.FREE_TIER_LIMIT} calls/day. Set TTT_API_KEY env var for unlimited access. \u2192 kenosian.com/pricing`,
-            remaining: 0,
-            tier: "free"
-          }) }],
-          isError: true
-        };
+  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+function buildMcpServer() {
+  const s = new import_mcp.McpServer({ name: "ttt-mcp", version: "0.3.1" });
+  s.tool(
+    "pot_generate",
+    "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"),
+      txHash: import_zod.z.string().optional().describe("Transaction hash (DeFi, hex with 0x prefix)"),
+      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 toolSuccess(result);
+      } catch (err) {
+        return toolError(err);
       }
     }
-    try {
-      const result = await (0, import_tools.potVerify)(args);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        content: [{ type: "text", text: `Error: ${message}` }],
-        isError: true
-      };
+  );
+  s.tool(
+    "pot_verify",
+    "Verify a Proof of Time using its hash and integrity shards. Returns validity, mode (turbo/full), and timestamp.",
+    {
+      potHash: import_zod.z.string().describe("PoT hash to verify (hex with 0x prefix)"),
+      grgShards: import_zod.z.array(import_zod.z.string()).describe("Array of hex-encoded cryptographic integrity shards"),
+      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 toolSuccess(result);
+      } catch (err) {
+        return toolError(err);
+      }
     }
-  }
-);
-server.tool(
-  "pot_query",
-  "Query Proof of Time history from local log and on-chain subgraph.",
-  {
-    startTime: import_zod.z.number().optional().describe("Start time (unix ms). Default: 24h ago"),
-    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")
-  },
-  async (args) => {
-    if (IS_STDIO) {
-      const apiKey = (0, import_auth.resolveApiKey)();
-      const rl = (0, import_auth.checkRateLimit)(apiKey, "stdio");
-      if (!rl.allowed) {
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            error: "rate_limit_exceeded",
-            message: `Free tier: ${import_auth.FREE_TIER_LIMIT} calls/day. Set TTT_API_KEY env var for unlimited access. \u2192 kenosian.com/pricing`,
-            remaining: 0,
-            tier: "free"
-          }) }],
-          isError: true
-        };
+  );
+  s.tool(
+    "pot_query",
+    "Query Proof of Time records. Use eventId for exact O(1) lookup of a specific workflow step (collision probability 2^-256). Use startTime/endTime for time-range queries.",
+    {
+      eventId: import_zod.z.string().optional().describe("Exact eventId lookup \u2014 call this at workflow start to restore action history after context compression"),
+      startTime: import_zod.z.number().optional().describe("Start time (unix ms). Default: 24h ago"),
+      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 toolSuccess(result);
+      } catch (err) {
+        return toolError(err);
       }
     }
-    try {
-      const result = await (0, import_tools.potQuery)(args);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        content: [{ type: "text", text: `Error: ${message}` }],
-        isError: true
-      };
+  );
+  s.tool(
+    "pot_graph",
+    "Traverse the causal chain of workflow steps. Given an eventId, returns the full backward chain (ancestors via prevEventId) and forward chain (steps that follow). Use after context compression to reconstruct the complete workflow timeline.",
+    {
+      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 toolSuccess(result);
+      } catch (err) {
+        return toolError(err);
+      }
     }
-  }
-);
-server.tool(
-  "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")
-  },
-  async (args) => {
-    if (IS_STDIO) {
-      const apiKey = (0, import_auth.resolveApiKey)();
-      const rl = (0, import_auth.checkRateLimit)(apiKey, "stdio");
-      if (!rl.allowed) {
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            error: "rate_limit_exceeded",
-            message: `Free tier: ${import_auth.FREE_TIER_LIMIT} calls/day. Set TTT_API_KEY env var for unlimited access. \u2192 kenosian.com/pricing`,
-            remaining: 0,
-            tier: "free"
-          }) }],
-          isError: true
-        };
+  );
+  s.tool(
+    "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 toolSuccess(result);
+      } catch (err) {
+        return toolError(err);
       }
     }
-    try {
-      const result = await (0, import_tools.potStats)(args);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        content: [{ type: "text", text: `Error: ${message}` }],
-        isError: true
-      };
+  );
+  s.tool(
+    "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 toolSuccess(result);
+      } catch (err) {
+        return toolError(err);
+      }
     }
-  }
-);
-server.tool(
-  "pot_health",
-  "Check PoT system health: time source status, subgraph sync, server uptime, and current mode.",
-  {},
-  async () => {
-    try {
-      const result = await (0, import_tools.potHealth)();
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        content: [{ type: "text", text: `Error: ${message}` }],
-        isError: true
-      };
+  );
+  s.tool(
+    "pot_checkpoint",
+    "Create a compressed rollup checkpoint of workflow history. Call this periodically to prevent token explosion when recovering from context compression. Returns checkpointId, compressed event history, chainIntact status, and nextCheckpointHint (recommended events before next checkpoint).",
+    {
+      fromEventId: import_zod.z.string().optional().describe("Start of range by eventId (optional, use with toEventId)"),
+      toEventId: import_zod.z.string().optional().describe("End of range by eventId (optional, use with fromEventId)"),
+      startTime: import_zod.z.number().optional().describe("Unix ms start time (optional, default: 1h ago)"),
+      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 toolSuccess(result);
+      } catch (err) {
+        return toolError(err);
+      }
     }
-  }
-);
+  );
+  return s;
+}
 async function main() {
+  await restoreDAGFromRedis();
   const port = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
   if (port) {
-    const transport = new import_streamableHttp.StreamableHTTPServerTransport({
-      sessionIdGenerator: void 0
-    });
-    await server.connect(transport);
     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") {
@@ -209,7 +251,8 @@ async function main() {
           res.end(
             JSON.stringify({
               error: "rate_limit_exceeded",
-              message: "Free tier limit reached (100 calls/day). Add X-API-Key header for unlimited access.",
+              message: import_server.FREE_TIER_UPGRADE_MESSAGE,
+              upgradeUrl: import_server.UPGRADE_URL,
               tier: "free"
             })
           );
@@ -233,6 +276,9 @@ async function main() {
         }
       }
       try {
+        const reqServer = buildMcpServer();
+        const transport = new import_streamableHttp.StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+        await reqServer.connect(transport);
         await transport.handleRequest(req, res);
       } catch (err) {
         if (!res.headersSent) {
@@ -245,8 +291,9 @@ async function main() {
       console.error(`[ttt-mcp] OpenTTT MCP Server (HTTP) on port ${port}`);
     });
   } else {
+    const stdioServer = buildMcpServer();
     const transport = new import_stdio.StdioServerTransport();
-    await server.connect(transport);
+    await stdioServer.connect(transport);
     console.error("[ttt-mcp] OpenTTT MCP Server running on stdio");
   }
 }

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
+});