@secondlayer/mcp 7.4.0 → 7.5.0

package/README.md

@@ -3,7 +3,7 @@
 Gives your coding agent direct access to the Stacks data on your own instance —
 Index (decoded rows), Subgraphs (tables you define, served from your instance),
 and Streams (raw inputs). Exposes the golden-path tools only: Index reads, the
-subgraph lifecycle, subscriptions, contract discovery/scaffolding, instance
+subgraph lifecycle, webhooks, contract discovery/scaffolding, instance
 status, archive verify/bootstrap, and hosted credits/quote. Everything else
 (single-record lookups, mempool, stacking, proofs, live Streams reads) is
 available over REST `/v1` + OpenAPI. There is no `consume` tool.
@@ -16,7 +16,7 @@ bun add @secondlayer/mcp
 
 ## Auth
 
-Most reads are public: `index_*` and `contracts_find` work with no key. Subgraph tools need an `INSTANCE_TOKEN` past loopback; separately, **public** subgraphs are anon-readable over HTTP at `GET /v1/subgraphs/<name>/<table>` (`{ rows, next_cursor, tip }` cursor envelope), while private ones need the instance token (anon → 404). `streams_dumps` needs no key: the dumps manifest is public; the tool only needs `SL_STREAMS_DUMPS_URL` configured. Every other `streams_*` tool is key-mandatory (keyless → 401). Writes (deploy, reindex, delete, subscriptions) need a key: set `INSTANCE_TOKEN` from `secondlayer init`. Hosted credits/quote use `SECONDLAYER_API_KEY` (`sk-sl_*`). Read `secondlayer://context` first: it reports auth state and read-auth tiers.
+Most reads are public: `index_*` and `contracts_find` work with no key. Subgraph tools need an `INSTANCE_TOKEN` past loopback; separately, **public** subgraphs are anon-readable over HTTP at `GET /v1/subgraphs/<name>/<table>` (`{ rows, next_cursor, tip }` cursor envelope), while private ones need the instance token (anon → 404). `streams_dumps` needs no key: the dumps manifest is public; the tool only needs `SL_STREAMS_DUMPS_URL` configured. Every other `streams_*` tool is key-mandatory (keyless → 401). Writes (deploy, reindex, delete, webhooks) need a key: set `INSTANCE_TOKEN` from `secondlayer init`. Hosted credits/quote use `SECONDLAYER_API_KEY` (`sk-sl_*`). Read `secondlayer://context` first: it reports auth state and read-auth tiers.
 
 ## Quick Start — Stdio (IDE)
 
@@ -65,7 +65,7 @@ bunx -p @secondlayer/mcp secondlayer-mcp-http
 | --- | --- |
 | **Index** (9) | `index_events`, `index_ft_transfers`, `index_nft_transfers`, `index_contract_calls`, `index_blocks`, `index_transactions`, `index_print_schema`, `index_discover`, `batch_query` |
 | **Subgraphs** (12) | `subgraphs_list`, `subgraphs_status`, `subgraphs_spec`, `subgraphs_scaffold`, `subgraphs_deploy`, `subgraphs_delete`, `subgraphs_query`, `subgraphs_backfill`, `subgraphs_reindex`, `subgraphs_stop`, `subgraphs_operations`, `subgraphs_gaps` |
-| **Subscriptions** (13) | `subscriptions_create`, `subscriptions_list`, `subscriptions_get`, `subscriptions_update`, `subscriptions_delete`, `subscriptions_test`, `subscriptions_pause`, `subscriptions_resume`, `subscriptions_rotate_secret`, `subscriptions_deliveries`, `subscriptions_dead`, `subscriptions_requeue`, `subscriptions_replay` |
+| **Webhooks** (13) | `webhooks_create`, `webhooks_list`, `webhooks_get`, `webhooks_update`, `webhooks_delete`, `webhooks_test`, `webhooks_pause`, `webhooks_resume`, `webhooks_rotate_secret`, `webhooks_deliveries`, `webhooks_dead`, `webhooks_requeue`, `webhooks_replay` |
 | **Streams** (7) | `streams_tip`, `streams_events`, `streams_events_by_tx`, `streams_block_events`, `streams_canonical`, `streams_reorgs`, `streams_dumps` |
 | **Contracts** (2) | `contracts_find`, `contracts_get_abi` |
 | **Instance** (1) | `instance_status` |
@@ -75,7 +75,7 @@ bunx -p @secondlayer/mcp secondlayer-mcp-http
 | **Account** (2) | `account_whoami`, `account_create_key` (only when pointed at `https://api.secondlayer.tools`) |
 
 Verify after mutating: `subgraphs_operations` for deploy/reindex/backfill/stop,
-`subscriptions_deliveries` for create/test/replay. Empty index: `setup` or
+`webhooks_deliveries` for create/test/replay. Empty index: `setup` or
 `archive_bootstrap`, poll `instance_status` until decoders are ok, then
 `archive_verify`, then `codegen_index_schema`.
 
@@ -88,10 +88,10 @@ Point the server at your instance with `SECONDLAYER_API_URL` (default
 `secondlayer init`. `account_*` tools appear only when the server is pointed at
 `https://api.secondlayer.tools`.
 
-### `subscriptions_create` kinds
+### `webhooks_create` kinds
 
-Subscriptions are polymorphic. Pass `subgraphName` + `tableName` for a
-**subgraph** subscription, or a `triggers` array for a **chain** subscription —
+Webhooks are polymorphic. Pass `subgraphName` + `tableName` for a
+**subgraph** webhook, or a `triggers` array for a **chain** webhook —
 a webhook on raw chain events (contract / event / function / trait) with no
 subgraph (e.g. `[{ "type": "contract_call", "contractId": "SP....amm",
 "functionName": "swap-*" }]`).
@@ -107,11 +107,11 @@ subgraph (e.g. `[{ "type": "contract_call", "contractId": "SP....amm",
 
 | URI | Description |
 | --- | --- |
-| `secondlayer://context` | Live state — what exists (your subgraphs, subscriptions, account), what you can do, and read-auth tiers. Read first. |
+| `secondlayer://context` | Live state — what exists (your subgraphs, webhooks, account), what you can do, and read-auth tiers. Read first. |
 | `secondlayer://filters` | Subgraph source filter types and their fields |
 | `secondlayer://column-types` | Column type mappings and options |
 | `secondlayer://traits` | SIP trait standards (valid `trait` values) |
-| `secondlayer://chain-triggers` | Chain-subscription trigger types and fields |
+| `secondlayer://chain-triggers` | Chain-webhook trigger types and fields |
 
 ## Error Handling
 

package/dist/bin-http.js

@@ -8,7 +8,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 
 // src/server.ts
 import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -23,10 +23,13 @@ function isHostedArchiveUrl(url) {
 }
 
 // src/resources.ts
+import {
+  ResourceTemplate
+} from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CHAIN_TRIGGER_FIELDS } from "@secondlayer/shared";
 import { BOOTSTRAP_STEP } from "@secondlayer/shared/archive/instance-diagnosis";
 import { TRAIT_STANDARDS } from "@secondlayer/stacks/clarity";
-import { filterFieldsByType } from "@secondlayer/subgraphs";
+import { camelizeKeys, filterFieldsByType } from "@secondlayer/subgraphs";
 import { TYPE_MAP } from "@secondlayer/subgraphs/schema";
 
 // src/lib/client.ts
@@ -187,7 +190,8 @@ var PRODUCT_BLURBS = {
   streams: "raw chain event firehose — cursor-paginated reads, tip/canonical/reorg checks, bulk parquet dumps",
   contracts: "trait-based contract discovery and ABIs",
   subgraphs: "author/scaffold/deploy/query custom indexes",
-  subscriptions: "webhook delivery on subgraph rows or raw chain events",
+  webhooks: "a signed POST to a URL you run, on subgraph rows or raw chain events",
+  subscriptions: "a signed POST to a URL you run, on subgraph rows or raw chain events",
   account: "identity and self-provisioned API keys",
   codegen: "ORM schemas for the tables you read",
   instance: "decoder health and empty-index diagnosis",
@@ -200,6 +204,7 @@ var PRODUCT_ORDER = [
   "streams",
   "contracts",
   "subgraphs",
+  "webhooks",
   "subscriptions",
   "account",
   "codegen",
@@ -256,7 +261,8 @@ async function buildContext(deps = { clientProvider: getClient }) {
       streamsTip: orNull(snap?.streamsTip),
       indexTip: orNull(snap?.indexTip),
       subgraphs: snap?.subgraphs.value ? snap.subgraphs.value.map(formatSubgraphSummary) : orNull(snap?.subgraphs),
-      subscriptions: orNull(snap?.subscriptions),
+      webhooks: orNull(snap?.webhooks),
+      subscriptions: orNull(snap?.webhooks),
       activeOperations: orNull(snap?.activeOperations),
       instance: instance2
     },
@@ -267,7 +273,7 @@ async function buildContext(deps = { clientProvider: getClient }) {
 }
 function registerResources(server) {
   server.resource("context", "secondlayer://context", {
-    description: "Live agent context — what exists (your subgraphs, subscriptions, account), what you can do, and read-auth tiers. Read this first."
+    description: "Live agent context — what exists (your subgraphs, webhooks, account), what you can do, and read-auth tiers. Read this first."
   }, async () => ({
     contents: [
       {
@@ -312,7 +318,7 @@ function registerResources(server) {
     ]
   }));
   server.resource("chain-triggers", "secondlayer://chain-triggers", {
-    description: "Chain-subscription trigger types and the filter fields each accepts (for subscriptions_create triggers)."
+    description: "Chain-webhook trigger types and the filter fields each accepts (for webhooks_create triggers)."
   }, async () => ({
     contents: [
       {
@@ -322,6 +328,73 @@ function registerResources(server) {
       }
     ]
   }));
+  server.resource("samples", new ResourceTemplate("secondlayer://samples/{contractId}", {
+    list: undefined
+  }), {
+    description: "Decoded camelCase print samples for a contract (schema + up to 5 events). Use before writing a print_event handler."
+  }, async (uri, variables) => {
+    const contractId = String(Array.isArray(variables.contractId) ? variables.contractId[0] : variables.contractId ?? "");
+    const body = await buildSamplesResource(contractId);
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(body, null, 2)
+        }
+      ]
+    };
+  });
+}
+function jsonSafe(value) {
+  if (typeof value === "bigint")
+    return value.toString();
+  if (value === null || value === undefined)
+    return value;
+  if (Array.isArray(value))
+    return value.map(jsonSafe);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = jsonSafe(v);
+    }
+    return out;
+  }
+  return value;
+}
+async function buildSamplesResource(contractId, clientProvider = getClient) {
+  const client = clientProvider();
+  const printSchema = await client.index.printSchema(contractId);
+  const envelope = await client.index.events.list({
+    eventType: "print",
+    contractId,
+    limit: 5
+  });
+  const schema = printSchema?.topics.map((t) => ({
+    topic: t.topic,
+    fields: t.fields.map((f) => ({
+      camel: f.camel_name,
+      snake: f.name.replace(/-/g, "_"),
+      column_type: f.column_type,
+      always: f.always_present
+    }))
+  })) ?? [];
+  const samples = (envelope.events ?? []).slice(0, 5).map((ev) => {
+    const payload = ev.payload;
+    const data = jsonSafe(camelizeKeys(payload?.value));
+    return {
+      txId: ev.tx_id,
+      height: ev.block_height,
+      topic: payload?.topic ?? "",
+      data: data ?? {}
+    };
+  });
+  return {
+    contractId,
+    handlerShape: "event.data is camelCase; columns are snake_case",
+    schema,
+    samples
+  };
 }
 
 // src/tools/account.ts
@@ -480,7 +553,11 @@ function registerInstanceTools(server, clientProvider = getClient) {
 }
 
 // src/tools/scaffold.ts
-import { generateSubgraphCode } from "@secondlayer/scaffold";
+import {
+  generatePrintSchemaSubgraph,
+  generateSubgraphCode,
+  generateTokenSubgraphFromAbi
+} from "@secondlayer/scaffold";
 import { z as z6 } from "zod";
 async function fetchAbi(clientProvider, contractId) {
   const contract = await clientProvider().contracts.get(contractId, {
@@ -492,14 +569,32 @@ async function fetchAbi(clientProvider, contractId) {
   if (!abi) {
     throw new Error(`No ABI available for ${contractId} (abi_status: ${contract.abi_status})`);
   }
-  return { functions: abi.functions ?? [] };
+  return { functions: abi.functions ?? [], abi };
 }
 function registerScaffoldTools(server, clientProvider = getClient) {
-  defineTool(server, "subgraphs_scaffold", "Generate a subgraph scaffold from a deployed Stacks contract. Fetches the ABI automatically. Returns TypeScript source — review it, then pass it to subgraphs_deploy.", {
+  defineTool(server, "subgraphs_scaffold", "Generate a subgraph from observed print events when available; ABI token transfers or public functions only when the contract has never printed. Review the TypeScript, run subgraphs_test until ok: true with written >= 1, read skipped, then subgraphs_deploy. dryRun is DDL only.", {
     contractId: z6.string().describe("Fully qualified contract ID (e.g. SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01)"),
     subgraphName: z6.string().optional().describe("Override the subgraph name (defaults to contract name)")
   }, async ({ contractId, subgraphName }) => {
-    const { functions } = await fetchAbi(clientProvider, contractId);
+    const printSchema = await clientProvider().index.printSchema(contractId);
+    if (printSchema && printSchema.topics.length > 0) {
+      const code2 = generatePrintSchemaSubgraph({
+        contractId,
+        name: subgraphName,
+        topics: printSchema.topics,
+        sample: printSchema.sample
+      });
+      return { content: [{ type: "text", text: code2 }] };
+    }
+    const { functions, abi } = await fetchAbi(clientProvider, contractId);
+    const token = generateTokenSubgraphFromAbi({
+      contractId,
+      abi,
+      name: subgraphName
+    });
+    if (token) {
+      return { content: [{ type: "text", text: token }] };
+    }
     const code = generateSubgraphCode(contractId, functions, subgraphName);
     return { content: [{ type: "text", text: code }] };
   });
@@ -752,14 +847,42 @@ function registerStreamsTools(server, clientProvider = getClient) {
 }
 
 // src/tools/subgraphs.ts
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 import { bundleSubgraphCode } from "@secondlayer/bundler";
+import { DECODED_EVENT_TYPES as DECODED_EVENT_TYPES2 } from "@secondlayer/shared";
+import {
+  runSubgraphTest
+} from "@secondlayer/subgraphs/testing";
 import { z as z9 } from "zod";
+function eventTypeFor(filter) {
+  if (filter.type === "contract_deploy")
+    return null;
+  const candidate = filter.type === "print_event" ? "print" : filter.type;
+  return DECODED_EVENT_TYPES2.includes(candidate) ? candidate : null;
+}
+function skipReason(name, filter) {
+  return filter.type === "contract_deploy" ? `source "${name}" (contract_deploy) has no Index list endpoint — skipped.` : `source "${name}" (${filter.type}) is not readable from Index — skipped.`;
+}
+async function loadBundledDefinition(handlerCode) {
+  const dir = await mkdtemp(join(tmpdir(), "sl-mcp-sg-test-"));
+  try {
+    const file = join(dir, `handler-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`);
+    await writeFile(file, handlerCode);
+    const mod = await import(pathToFileURL(file).href);
+    return mod.default ?? {};
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
 function registerSubgraphTools(server, clientProvider = getClient) {
   defineTool(server, "subgraphs_list", "List all deployed subgraphs. Returns summary fields only; read rows with subgraphs_query.", {}, async () => {
     const { data } = await clientProvider().subgraphs.list();
     return jsonResponse(data.map(formatSubgraphSummary));
   });
-  defineTool(server, "subgraphs_status", "Get full details of a subgraph including schema, health, and table columns.", { name: z9.string().describe("Subgraph name") }, async ({ name }) => {
+  defineTool(server, "subgraphs_status", "Get full details of a subgraph including schema, health (incl. health.emptyMapping when processed events wrote 0 rows), and table columns.", { name: z9.string().describe("Subgraph name") }, async ({ name }) => {
     const detail = await clientProvider().subgraphs.status(name);
     return jsonResponse(detail);
   });
@@ -855,10 +978,10 @@ function registerSubgraphTools(server, clientProvider = getClient) {
     const result = await clientProvider().subgraphs.delete(name);
     return textResponse(result.message);
   });
-  defineTool(server, "subgraphs_deploy", "Deploy a subgraph from TypeScript code. Pass the full defineSubgraph() source — it will be bundled, validated, and deployed. Optional startBlock overrides the source definition for this deploy. Set dryRun to validate and preview the schema/DDL without writing anything. Call `subgraphs_reindex` separately if you need a forced reindex.", {
+  defineTool(server, "subgraphs_deploy", "Deploy a subgraph from TypeScript code. Pass the full defineSubgraph() source — it will be bundled, validated, and deployed. Optional startBlock overrides the source definition for this deploy. dryRun validates schema/DDL only and does not run handlers — call subgraphs_test first and deploy only when it returns ok: true with written >= 1. Call subgraphs_reindex separately if you need a forced reindex.", {
     code: z9.string().describe("TypeScript source code containing a defineSubgraph() call"),
     startBlock: z9.number().int().nonnegative().optional().describe("Override the definition startBlock for this deploy"),
-    dryRun: z9.boolean().optional().describe("Validate and preview the deploy (schema/DDL) without writing changes")
+    dryRun: z9.boolean().optional().describe("Validate schema/DDL only — does not run handlers. Use subgraphs_test to prove a mapping writes rows.")
   }, async ({ code, startBlock, dryRun }) => {
     const bundled = await bundleSubgraphCode(code);
     const result = await clientProvider().subgraphs.deploy({
@@ -874,24 +997,201 @@ function registerSubgraphTools(server, clientProvider = getClient) {
     });
     return jsonResponse(result);
   });
+  defineTool(server, "subgraphs_test", "Prove a subgraph mapping writes rows against Index data before deploy. Pass full defineSubgraph() source plus a height range. Returns ok/written/tables; EMPTY_MAPPING means events matched but 0 rows were written — read hint for observed event.data keys and do not invent fields. subgraphs_deploy dryRun is DDL only; do not deploy until ok: true with written >= 1.", {
+    code: z9.string().describe("TypeScript source containing a defineSubgraph() call"),
+    fromHeight: z9.number().int().nonnegative().describe("Start block height (inclusive)"),
+    toHeight: z9.number().int().nonnegative().optional().describe("End block height (inclusive); default fromHeight+100"),
+    limit: z9.number().int().positive().max(200).optional().describe("Max Index rows per source (default 50, max 200)")
+  }, async ({ code, fromHeight, toHeight, limit }) => {
+    const bundled = await bundleSubgraphCode(code);
+    const def = await loadBundledDefinition(bundled.handlerCode);
+    if (!def.handlers || !def.schema) {
+      return jsonResponse({
+        ok: false,
+        code: "NO_SOURCES",
+        matched: 0,
+        written: 0,
+        tables: [],
+        hint: "Bundled module must default-export defineSubgraph() with handlers and schema."
+      }, true);
+    }
+    const sources = bundled.sources ?? {};
+    const to = toHeight ?? fromHeight + 100;
+    const pageLimit = Math.min(limit ?? 50, 200);
+    const index = clientProvider().index;
+    const events = {};
+    const skipped = [];
+    let sourcesTested = 0;
+    for (const [name, filter] of Object.entries(sources)) {
+      if (filter.type === "contract_call") {
+        sourcesTested++;
+        const envelope2 = await index.contractCalls.list({
+          ...filter.contractId ? {
+            contractId: Array.isArray(filter.contractId) ? filter.contractId : filter.contractId
+          } : {},
+          ...filter.functionName ? { functionName: filter.functionName } : {},
+          fromHeight,
+          toHeight: to,
+          limit: pageLimit
+        });
+        events[name] = envelope2.contract_calls;
+        continue;
+      }
+      const eventType = eventTypeFor(filter);
+      if (eventType === null) {
+        skipped.push({ source: name, reason: skipReason(name, filter) });
+        continue;
+      }
+      sourcesTested++;
+      const envelope = await index.events.list({
+        eventType,
+        ...filter.contractId ? {
+          contractId: Array.isArray(filter.contractId) ? filter.contractId : filter.contractId
+        } : {},
+        fromHeight,
+        toHeight: to,
+        limit: pageLimit
+      });
+      events[name] = envelope.events;
+    }
+    if (sourcesTested === 0) {
+      return jsonResponse({
+        ok: false,
+        code: "NO_SOURCES",
+        matched: 0,
+        written: 0,
+        tables: [],
+        hint: "No sources were tested — every source is unreadable from Index.",
+        skipped
+      }, true);
+    }
+    const result = await runSubgraphTest({
+      schema: def.schema,
+      handlers: def.handlers,
+      sources,
+      events
+    });
+    const body = { ...result, skipped };
+    if (skipped.length > 0) {
+      const skipHints = skipped.map((s) => s.reason).join(" ");
+      body.hint = result.hint ? `${result.hint} ${skipHints}` : skipHints;
+    }
+    return jsonResponse(body, !result.ok);
+  });
 }
 
-// src/tools/subscriptions.ts
+// src/tools/webhooks.ts
 import { CHAIN_TRIGGER_TYPES } from "@secondlayer/shared";
 import { z as z10 } from "zod";
-function registerSubscriptionTools(server, clientProvider = getClient) {
-  defineTool(server, "subscriptions_list", "List all subscriptions for the current account. Returns summary fields (no secrets).", {}, async () => {
-    const { data } = await clientProvider().subscriptions.list();
+function registerWebhookTools(server, clientProvider = getClient) {
+  defineTool(server, "webhooks_list", "List all webhooks for the current account. Returns summary fields (no secrets).", {}, async () => {
+    const { data } = await clientProvider().webhooks.list();
+    return jsonResponse(data);
+  });
+  defineTool(server, "webhooks_get", "Get full detail for a webhook (filter, auth, retry config, circuit state).", { id: z10.string().describe("Webhook id") }, async ({ id }) => {
+    const detail = await clientProvider().webhooks.get(id);
+    return jsonResponse(detail);
+  });
+  defineTool(server, "webhooks_create", "Create a webhook. Two kinds (mutually exclusive): a SUBGRAPH webhook fires on a subgraph table's rows (set subgraphName + tableName + optional filter); a CHAIN webhook fires on raw chain events with no subgraph (set triggers). Returns `signingSecret` ONCE — forward it to the user so they can wire it into their receiver.", {
+    name: z10.string().describe("Human-readable name, unique per account"),
+    subgraphName: z10.string().optional().describe("Subgraph to subscribe to (subgraph webhook)"),
+    tableName: z10.string().optional().describe("Table within the subgraph (subgraph webhook)"),
+    triggers: z10.array(z10.object({
+      type: z10.enum(CHAIN_TRIGGER_TYPES),
+      contractId: z10.string().optional(),
+      functionName: z10.string().optional(),
+      caller: z10.string().optional(),
+      sender: z10.string().optional(),
+      recipient: z10.string().optional(),
+      assetIdentifier: z10.string().optional(),
+      deployer: z10.string().optional(),
+      contractName: z10.string().optional(),
+      topic: z10.string().optional(),
+      lockedAddress: z10.string().optional(),
+      trait: z10.string().optional(),
+      minAmount: z10.union([z10.string(), z10.number()]).optional(),
+      maxAmount: z10.union([z10.string(), z10.number()]).optional()
+    })).optional().describe("Chain triggers (chain webhook) — provide INSTEAD of subgraphName/tableName. Each targets a raw chain event/tx; string fields accept `*` wildcards, `trait` scopes to a SIP/trait. Per-type accepted fields: see the secondlayer://chain-triggers resource. Forward-looking: starts at chain tip, no backfill."),
+    url: z10.string().describe("Webhook URL"),
+    format: z10.enum([
+      "standard-webhooks",
+      "inngest",
+      "trigger",
+      "cloudflare",
+      "cloudevents",
+      "raw"
+    ]).optional().describe("Wire format (default standard-webhooks)"),
+    runtime: z10.enum(["inngest", "trigger", "cloudflare", "node"]).optional().describe("Receiver runtime label (display only)"),
+    filter: z10.record(z10.string(), z10.unknown()).optional().describe('Scalar filter DSL, e.g. {"amount": {"gte": 100}, "sender": "SP..."}'),
+    authConfig: z10.record(z10.string(), z10.unknown()).optional().describe('Receiver auth sent with each delivery, e.g. {"type": "bearer", "token": "..."}')
+  }, async (input) => {
+    const res = await clientProvider().webhooks.create(input);
+    return jsonResponse(res);
+  });
+  defineTool(server, "webhooks_update", "Patch a webhook (name, url, filter, authConfig, format, runtime, retry, timeout, concurrency).", {
+    id: z10.string(),
+    name: z10.string().optional().describe("Rename the webhook"),
+    url: z10.string().optional(),
+    filter: z10.record(z10.string(), z10.unknown()).optional(),
+    authConfig: z10.record(z10.string(), z10.unknown()).optional().describe("Receiver auth sent with each delivery (bearer/etc.)"),
+    format: z10.enum([
+      "standard-webhooks",
+      "inngest",
+      "trigger",
+      "cloudflare",
+      "cloudevents",
+      "raw"
+    ]).optional(),
+    runtime: z10.enum(["inngest", "trigger", "cloudflare", "node"]).nullable().optional(),
+    maxRetries: z10.number().int().min(0).optional(),
+    timeoutMs: z10.number().int().min(100).optional(),
+    concurrency: z10.number().int().min(1).optional()
+  }, async ({ id, ...patch }) => {
+    const res = await clientProvider().webhooks.update(id, patch);
+    return jsonResponse(res);
+  });
+  defineTool(server, "webhooks_delete", "Delete a webhook. Pending outbox rows are cascade-deleted.", { id: z10.string() }, async ({ id }) => {
+    const res = await clientProvider().webhooks.delete(id);
+    return jsonResponse(res);
+  });
+  defineTool(server, "webhooks_test", "Send a one-off test webhook to a webhook's URL (built for its format, SSRF-guarded). Logged as a delivery row. Returns {ok, statusCode, error, durationMs, deliveryId}.", { id: z10.string().describe("Webhook id") }, async ({ id }) => {
+    const res = await clientProvider().webhooks.test(id);
+    return jsonResponse(res);
+  });
+  defineTool(server, "webhooks_pause", "Pause a webhook: stops delivery attempts and stops queueing new ones. Nothing is deleted — resume picks the webhook back up from the tip. Verify with webhooks_get (status).", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.pause(id)));
+  defineTool(server, "webhooks_resume", "Resume a paused webhook (also clears a tripped circuit breaker). Deliveries restart from the current tip — use webhooks_replay for the blocks missed while paused. Verify with webhooks_get (status).", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.resume(id)));
+  defineTool(server, "webhooks_rotate_secret", "Rotate a webhook's signing secret. Returns the NEW `signingSecret` ONCE — forward it to the user; deliveries signed with the old secret stop verifying as soon as this returns, so the receiver must be updated.", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.rotateSecret(id)));
+  defineTool(server, "webhooks_deliveries", "List recent delivery attempts for a webhook — status code, attempt count, error, duration, timestamps. THIS IS THE VERIFY CALL: after webhooks_create, webhooks_test, or webhooks_replay, read it to confirm the webhook actually landed (and to see the receiver's response when it didn't) instead of trusting the enqueue result.", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.deliveries(id)));
+  defineTool(server, "webhooks_dead", "List a webhook's dead-letter queue — deliveries that exhausted their retries, with the outbox id, payload, and last error. Diagnose the receiver first (webhooks_get for the URL/auth, webhooks_test for a live probe), then requeue rows with webhooks_requeue.", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.dead(id)));
+  defineTool(server, "webhooks_requeue", "Requeue ONE dead-lettered delivery for another attempt, by its outbox id from webhooks_dead. Fix the receiver first — a requeue against a still-broken endpoint just dies again. Verify with webhooks_deliveries.", {
+    id: z10.string().describe("Webhook id"),
+    outboxId: z10.string().describe("Outbox id of the dead delivery (from webhooks_dead)")
+  }, async ({ id, outboxId }) => jsonResponse(await clientProvider().webhooks.requeue(id, outboxId)));
+  defineTool(server, "webhooks_replay", "Replay a block range for a webhook. Replays run at 10% of batch capacity — use sparingly. Pass `force` (a short idempotency suffix) to re-run a range that was already replayed.", {
+    id: z10.string(),
+    fromBlock: z10.number().int().nonnegative(),
+    toBlock: z10.number().int().nonnegative(),
+    force: z10.string().optional().describe("Idempotency suffix to force a duplicate replay of the range")
+  }, async ({ id, fromBlock, toBlock, force }) => {
+    const res = await clientProvider().webhooks.replay(id, {
+      fromBlock,
+      toBlock,
+      ...force !== undefined ? { force } : {}
+    });
+    return jsonResponse(res);
+  });
+  defineTool(server, "subscriptions_list", "Deprecated alias of webhooks_list. Removed next minor. List all webhooks for the current account. Returns summary fields (no secrets).", {}, async () => {
+    const { data } = await clientProvider().webhooks.list();
     return jsonResponse(data);
   });
-  defineTool(server, "subscriptions_get", "Get full detail for a subscription (filter, auth, retry config, circuit state).", { id: z10.string().describe("Subscription id") }, async ({ id }) => {
-    const detail = await clientProvider().subscriptions.get(id);
+  defineTool(server, "subscriptions_get", "Deprecated alias of webhooks_get. Removed next minor. Get full detail for a webhook (filter, auth, retry config, circuit state).", { id: z10.string().describe("Webhook id") }, async ({ id }) => {
+    const detail = await clientProvider().webhooks.get(id);
     return jsonResponse(detail);
   });
-  defineTool(server, "subscriptions_create", "Create a subscription. Two kinds (mutually exclusive): a SUBGRAPH subscription fires on a subgraph table's rows (set subgraphName + tableName + optional filter); a CHAIN subscription fires on raw chain events with no subgraph (set triggers). Returns `signingSecret` ONCE — forward it to the user so they can wire it into their receiver.", {
+  defineTool(server, "subscriptions_create", "Deprecated alias of webhooks_create. Removed next minor. Create a webhook. Two kinds (mutually exclusive): a SUBGRAPH webhook fires on a subgraph table's rows (set subgraphName + tableName + optional filter); a CHAIN webhook fires on raw chain events with no subgraph (set triggers). Returns `signingSecret` ONCE — forward it to the user so they can wire it into their receiver.", {
     name: z10.string().describe("Human-readable name, unique per account"),
-    subgraphName: z10.string().optional().describe("Subgraph to subscribe to (subgraph subscription)"),
-    tableName: z10.string().optional().describe("Table within the subgraph (subgraph subscription)"),
+    subgraphName: z10.string().optional().describe("Subgraph to subscribe to (subgraph webhook)"),
+    tableName: z10.string().optional().describe("Table within the subgraph (subgraph webhook)"),
     triggers: z10.array(z10.object({
       type: z10.enum(CHAIN_TRIGGER_TYPES),
       contractId: z10.string().optional(),
@@ -907,7 +1207,7 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
       trait: z10.string().optional(),
       minAmount: z10.union([z10.string(), z10.number()]).optional(),
       maxAmount: z10.union([z10.string(), z10.number()]).optional()
-    })).optional().describe("Chain triggers (chain subscription) — provide INSTEAD of subgraphName/tableName. Each targets a raw chain event/tx; string fields accept `*` wildcards, `trait` scopes to a SIP/trait. Per-type accepted fields: see the secondlayer://chain-triggers resource. Forward-looking: starts at chain tip, no backfill."),
+    })).optional().describe("Chain triggers (chain webhook) — provide INSTEAD of subgraphName/tableName. Each targets a raw chain event/tx; string fields accept `*` wildcards, `trait` scopes to a SIP/trait. Per-type accepted fields: see the secondlayer://chain-triggers resource. Forward-looking: starts at chain tip, no backfill."),
     url: z10.string().describe("Webhook URL"),
     format: z10.enum([
       "standard-webhooks",
@@ -921,12 +1221,12 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
     filter: z10.record(z10.string(), z10.unknown()).optional().describe('Scalar filter DSL, e.g. {"amount": {"gte": 100}, "sender": "SP..."}'),
     authConfig: z10.record(z10.string(), z10.unknown()).optional().describe('Receiver auth sent with each delivery, e.g. {"type": "bearer", "token": "..."}')
   }, async (input) => {
-    const res = await clientProvider().subscriptions.create(input);
+    const res = await clientProvider().webhooks.create(input);
     return jsonResponse(res);
   });
-  defineTool(server, "subscriptions_update", "Patch a subscription (name, url, filter, authConfig, format, runtime, retry, timeout, concurrency).", {
+  defineTool(server, "subscriptions_update", "Deprecated alias of webhooks_update. Removed next minor. Patch a webhook (name, url, filter, authConfig, format, runtime, retry, timeout, concurrency).", {
     id: z10.string(),
-    name: z10.string().optional().describe("Rename the subscription"),
+    name: z10.string().optional().describe("Rename the webhook"),
     url: z10.string().optional(),
     filter: z10.record(z10.string(), z10.unknown()).optional(),
     authConfig: z10.record(z10.string(), z10.unknown()).optional().describe("Receiver auth sent with each delivery (bearer/etc.)"),
@@ -943,33 +1243,33 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
     timeoutMs: z10.number().int().min(100).optional(),
     concurrency: z10.number().int().min(1).optional()
   }, async ({ id, ...patch }) => {
-    const res = await clientProvider().subscriptions.update(id, patch);
+    const res = await clientProvider().webhooks.update(id, patch);
     return jsonResponse(res);
   });
-  defineTool(server, "subscriptions_delete", "Delete a subscription. Pending outbox rows are cascade-deleted.", { id: z10.string() }, async ({ id }) => {
-    const res = await clientProvider().subscriptions.delete(id);
+  defineTool(server, "subscriptions_delete", "Deprecated alias of webhooks_delete. Removed next minor. Delete a webhook. Pending outbox rows are cascade-deleted.", { id: z10.string() }, async ({ id }) => {
+    const res = await clientProvider().webhooks.delete(id);
     return jsonResponse(res);
   });
-  defineTool(server, "subscriptions_test", "Send a one-off test webhook to a subscription's URL (built for its format, SSRF-guarded). Logged as a delivery row. Returns {ok, statusCode, error, durationMs, deliveryId}.", { id: z10.string().describe("Subscription id") }, async ({ id }) => {
-    const res = await clientProvider().subscriptions.test(id);
+  defineTool(server, "subscriptions_test", "Deprecated alias of webhooks_test. Removed next minor. Send a one-off test webhook to a webhook's URL (built for its format, SSRF-guarded). Logged as a delivery row. Returns {ok, statusCode, error, durationMs, deliveryId}.", { id: z10.string().describe("Webhook id") }, async ({ id }) => {
+    const res = await clientProvider().webhooks.test(id);
     return jsonResponse(res);
   });
-  defineTool(server, "subscriptions_pause", "Pause a subscription: stops delivery attempts and stops queueing new ones. Nothing is deleted — resume picks the subscription back up from the tip. Verify with subscriptions_get (status).", { id: z10.string().describe("Subscription id") }, async ({ id }) => jsonResponse(await clientProvider().subscriptions.pause(id)));
-  defineTool(server, "subscriptions_resume", "Resume a paused subscription (also clears a tripped circuit breaker). Deliveries restart from the current tip — use subscriptions_replay for the blocks missed while paused. Verify with subscriptions_get (status).", { id: z10.string().describe("Subscription id") }, async ({ id }) => jsonResponse(await clientProvider().subscriptions.resume(id)));
-  defineTool(server, "subscriptions_rotate_secret", "Rotate a subscription's webhook signing secret. Returns the NEW `signingSecret` ONCE — forward it to the user; deliveries signed with the old secret stop verifying as soon as this returns, so the receiver must be updated.", { id: z10.string().describe("Subscription id") }, async ({ id }) => jsonResponse(await clientProvider().subscriptions.rotateSecret(id)));
-  defineTool(server, "subscriptions_deliveries", "List recent delivery attempts for a subscription — status code, attempt count, error, duration, timestamps. THIS IS THE VERIFY CALL: after subscriptions_create, subscriptions_test, or subscriptions_replay, read it to confirm the webhook actually landed (and to see the receiver's response when it didn't) instead of trusting the enqueue result.", { id: z10.string().describe("Subscription id") }, async ({ id }) => jsonResponse(await clientProvider().subscriptions.deliveries(id)));
-  defineTool(server, "subscriptions_dead", "List a subscription's dead-letter queue — deliveries that exhausted their retries, with the outbox id, payload, and last error. Diagnose the receiver first (subscriptions_get for the URL/auth, subscriptions_test for a live probe), then requeue rows with subscriptions_requeue.", { id: z10.string().describe("Subscription id") }, async ({ id }) => jsonResponse(await clientProvider().subscriptions.dead(id)));
-  defineTool(server, "subscriptions_requeue", "Requeue ONE dead-lettered delivery for another attempt, by its outbox id from subscriptions_dead. Fix the receiver first — a requeue against a still-broken endpoint just dies again. Verify with subscriptions_deliveries.", {
-    id: z10.string().describe("Subscription id"),
-    outboxId: z10.string().describe("Outbox id of the dead delivery (from subscriptions_dead)")
-  }, async ({ id, outboxId }) => jsonResponse(await clientProvider().subscriptions.requeue(id, outboxId)));
-  defineTool(server, "subscriptions_replay", "Replay a block range for a subscription. Replays run at 10% of batch capacity — use sparingly. Pass `force` (a short idempotency suffix) to re-run a range that was already replayed.", {
+  defineTool(server, "subscriptions_pause", "Deprecated alias of webhooks_pause. Removed next minor. Pause a webhook: stops delivery attempts and stops queueing new ones. Nothing is deleted — resume picks the webhook back up from the tip. Verify with webhooks_get (status).", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.pause(id)));
+  defineTool(server, "subscriptions_resume", "Deprecated alias of webhooks_resume. Removed next minor. Resume a paused webhook (also clears a tripped circuit breaker). Deliveries restart from the current tip — use webhooks_replay for the blocks missed while paused. Verify with webhooks_get (status).", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.resume(id)));
+  defineTool(server, "subscriptions_rotate_secret", "Deprecated alias of webhooks_rotate_secret. Removed next minor. Rotate a webhook's signing secret. Returns the NEW `signingSecret` ONCE — forward it to the user; deliveries signed with the old secret stop verifying as soon as this returns, so the receiver must be updated.", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.rotateSecret(id)));
+  defineTool(server, "subscriptions_deliveries", "Deprecated alias of webhooks_deliveries. Removed next minor. List recent delivery attempts for a webhook — status code, attempt count, error, duration, timestamps. THIS IS THE VERIFY CALL: after webhooks_create, webhooks_test, or webhooks_replay, read it to confirm the webhook actually landed (and to see the receiver's response when it didn't) instead of trusting the enqueue result.", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.deliveries(id)));
+  defineTool(server, "subscriptions_dead", "Deprecated alias of webhooks_dead. Removed next minor. List a webhook's dead-letter queue — deliveries that exhausted their retries, with the outbox id, payload, and last error. Diagnose the receiver first (webhooks_get for the URL/auth, webhooks_test for a live probe), then requeue rows with webhooks_requeue.", { id: z10.string().describe("Webhook id") }, async ({ id }) => jsonResponse(await clientProvider().webhooks.dead(id)));
+  defineTool(server, "subscriptions_requeue", "Deprecated alias of webhooks_requeue. Removed next minor. Requeue ONE dead-lettered delivery for another attempt, by its outbox id from webhooks_dead. Fix the receiver first — a requeue against a still-broken endpoint just dies again. Verify with webhooks_deliveries.", {
+    id: z10.string().describe("Webhook id"),
+    outboxId: z10.string().describe("Outbox id of the dead delivery (from webhooks_dead)")
+  }, async ({ id, outboxId }) => jsonResponse(await clientProvider().webhooks.requeue(id, outboxId)));
+  defineTool(server, "subscriptions_replay", "Deprecated alias of webhooks_replay. Removed next minor. Replay a block range for a webhook. Replays run at 10% of batch capacity — use sparingly. Pass `force` (a short idempotency suffix) to re-run a range that was already replayed.", {
     id: z10.string(),
     fromBlock: z10.number().int().nonnegative(),
     toBlock: z10.number().int().nonnegative(),
     force: z10.string().optional().describe("Idempotency suffix to force a duplicate replay of the range")
   }, async ({ id, fromBlock, toBlock, force }) => {
-    const res = await clientProvider().subscriptions.replay(id, {
+    const res = await clientProvider().webhooks.replay(id, {
       fromBlock,
       toBlock,
       ...force !== undefined ? { force } : {}
@@ -980,7 +1280,7 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
 
 // src/server.ts
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync(join(__dirname2, "../package.json"), "utf-8"));
+var pkg = JSON.parse(readFileSync(join2(__dirname2, "../package.json"), "utf-8"));
 function createServer() {
   const server = new McpServer({
     name: "secondlayer",
@@ -988,7 +1288,7 @@ function createServer() {
   });
   registerScaffoldTools(server);
   registerSubgraphTools(server);
-  registerSubscriptionTools(server);
+  registerWebhookTools(server);
   registerIndexTools(server);
   registerStreamsTools(server);
   registerContractTools(server);
@@ -1090,5 +1390,5 @@ httpServer.listen(port, () => {
     console.error("Warning: SECONDLAYER_MCP_SECRET not set, authentication disabled");
 });
 
-//# debugId=978D99EF4EC8A61364756E2164756E21
+//# debugId=E0F49AE0DC13C56764756E2164756E21
 //# sourceMappingURL=bin-http.js.map