@secondlayer/mcp 6.0.0 → 7.0.0

package/dist/bin.js

@@ -16,10 +16,10 @@ import { filterFieldsByType } from "@secondlayer/subgraphs";
 import { TYPE_MAP } from "@secondlayer/subgraphs/schema";
 
 // src/lib/client.ts
-import { SecondLayer } from "@secondlayer/sdk";
+import { SecondLayer, resolveApiKey } from "@secondlayer/sdk";
 var instance = null;
 function readApiKey() {
-  return process.env.SL_API_KEY;
+  return resolveApiKey();
 }
 function getClient() {
   if (!instance) {
@@ -35,17 +35,35 @@ function getClient() {
   }
   return instance;
 }
+var keyHint = " — set INSTANCE_TOKEN from `sl init` for writes (SL_API_KEY is a legacy alias)";
+async function apiRequest(method, path, body) {
+  const apiKey = readApiKey();
+  const baseUrl = process.env.SECONDLAYER_API_URL || process.env.SL_API_URL || "http://127.0.0.1:3800";
+  const res = await fetch(`${baseUrl}${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+    },
+    body: body ? JSON.stringify(body) : undefined
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    const needsKey = !apiKey && (res.status === 401 || res.status === 403);
+    throw Object.assign(new Error((text || `HTTP ${res.status}`) + (needsKey ? keyHint : "")), { status: res.status });
+  }
+  if (res.status === 204)
+    return;
+  return res.json();
+}
 
 // src/lib/format.ts
 function formatSubgraphSummary(s) {
-  const apiUrl = process.env.SECONDLAYER_API_URL || process.env.SL_API_URL || "http://127.0.0.1:3800";
   return {
     name: s.name,
     status: s.status,
     tables: Array.isArray(s.tables) ? s.tables : Object.keys(s.tables),
-    lastProcessedBlock: s.lastProcessedBlock,
-    ...s.visibility ? { visibility: s.visibility } : {},
-    ...s.visibility === "public" ? { publicUrl: `${apiUrl}/v1/subgraphs/${s.name}` } : {}
+    lastProcessedBlock: s.lastProcessedBlock
   };
 }
 function withCap(items, cap) {
@@ -73,7 +91,7 @@ var registeredToolNames = new Set;
 function getRegisteredToolNames() {
   return [...registeredToolNames];
 }
-function defineTool(server, name, description, schema, handler, options = {}) {
+function defineTool(server, name, description, schema, handler) {
   const wrappedHandler = async (args) => {
     try {
       return await handler(args);
@@ -94,9 +112,6 @@ function defineTool(server, name, description, schema, handler, options = {}) {
   };
   registeredToolNames.add(name);
   server.tool(name, description, schema, wrappedHandler);
-  for (const alias of options.aliases ?? []) {
-    server.tool(alias, `Deprecated alias for \`${name}\`. ${description}`, schema, wrappedHandler);
-  }
 }
 
 // src/resources.ts
@@ -128,12 +143,11 @@ var COLUMN_TYPES = [
 ];
 var PRODUCT_BLURBS = {
   index: "decoded events, transfers, contract calls, blocks, transactions",
-  streams: "bulk parquet dumps of the raw chain event firehose",
+  streams: "raw chain event firehose — cursor-paginated reads, tip/canonical/reorg checks, bulk parquet dumps",
   contracts: "trait-based contract discovery and ABIs",
-  subgraphs: "author/deploy/query custom indexes",
+  subgraphs: "author/scaffold/deploy/query custom indexes",
   subscriptions: "webhook delivery on subgraph rows or raw chain events",
   account: "identity and self-provisioned API keys",
-  scaffold: "generate deploy-ready subgraph code from a deployed contract",
   codegen: "ORM schemas for the tables you read"
 };
 var PRODUCT_ORDER = [
@@ -143,7 +157,6 @@ var PRODUCT_ORDER = [
   "subgraphs",
   "subscriptions",
   "account",
-  "scaffold",
   "codegen"
 ];
 function buildCapabilities() {
@@ -169,17 +182,17 @@ function buildCapabilities() {
   };
 }
 var READ_AUTH_TIERS = {
-  index: "anonymous reads allowed; free-tier API keys are rejected (Build+ required)",
-  streams: "API key required (SL_API_KEY) — keyless calls return 401",
-  subgraphs: "public subgraphs anon-readable at /v1/subgraphs/<name>/<table> ({ rows, next_cursor, tip } cursor envelope); private subgraphs need the owning account's API key (anon → 404); writes require an API key"
+  index: "keyless while the API is only reachable on loopback; the instance token is required once it is published past loopback",
+  streams: "keyless while the API is only reachable on loopback; the instance token is required once it is published past loopback",
+  subgraphs: "reads at /v1/subgraphs/<name>/<table> ({ rows, next_cursor, tip } cursor envelope) follow the same loopback rule as the other read planes; writes always require the instance token"
 };
 async function buildContext(deps = { clientProvider: getClient }) {
-  const unavailable = "unavailable: set SL_API_KEY";
+  const unavailable = "unavailable: set INSTANCE_TOKEN";
   const orNull = (v) => v == null ? unavailable : v;
   const snap = await deps.clientProvider().context().catch(() => null);
   return {
     authState: {
-      apiKeySet: Boolean(process.env.SL_API_KEY)
+      apiKeySet: Boolean(readApiKey())
     },
     whatExists: {
       account: orNull(snap?.account),
@@ -252,18 +265,31 @@ function registerResources(server) {
   }));
 }
 
+// src/tools/account.ts
+import { z } from "zod";
+function registerAccountTools(server) {
+  defineTool(server, "account_whoami", "Show the authenticated account's email.", {}, async () => {
+    const result = await apiRequest("GET", "/api/accounts/me");
+    return jsonResponse(result);
+  });
+  defineTool(server, "account_create_key", "Mint a scoped streams/index read key. Only the metered archive deployment can do this — a self-hosted instance has no account system and returns 404, so on your own instance use the INSTANCE_TOKEN from `secondlayer init` instead. The returned `key` is shown ONCE.", {
+    product: z.enum(["streams", "index"]).optional().describe("Key scope (default streams)"),
+    name: z.string().optional().describe("Optional label for the key")
+  }, async ({ product, name }) => jsonResponse(await apiRequest("POST", "/api/keys", { product, name })));
+}
+
 // src/tools/codegen.ts
 import {
   generateIndexSchema
 } from "@secondlayer/subgraphs";
-import { z } from "zod";
+import { z as z2 } from "zod";
 var TARGETS = ["prisma", "kysely", "drizzle", "json-schema"];
 function registerCodegenTools(server) {
   defineTool(server, "codegen_index_schema", "Generate an ORM schema for the Index tables (blocks, transactions, decoded_events, …) — the same output as `sl codegen index`. Returns the file contents as text; write it wherever your project keeps its schema. Use `tables` to emit only what you read.", {
-    target: z.enum(TARGETS).optional().describe("Output flavor (default kysely)"),
-    tables: z.array(z.string()).optional().describe("Restrict to these Index tables (default: all)"),
-    schemaName: z.string().optional().describe("Postgres schema to qualify table names with"),
-    datasourceEnv: z.string().optional().describe("Prisma only: datasource url env var (default DATABASE_URL)")
+    target: z2.enum(TARGETS).optional().describe("Output flavor (default kysely)"),
+    tables: z2.array(z2.string()).optional().describe("Restrict to these Index tables (default: all)"),
+    schemaName: z2.string().optional().describe("Postgres schema to qualify table names with"),
+    datasourceEnv: z2.string().optional().describe("Prisma only: datasource url env var (default DATABASE_URL)")
   }, ({ target, tables, schemaName, datasourceEnv }) => textResponse(generateIndexSchema(target ?? "kysely", {
     tables,
     schemaName,
@@ -272,17 +298,17 @@ function registerCodegenTools(server) {
 }
 
 // src/tools/contracts.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 function registerContractTools(server, clientProvider = getClient) {
   defineTool(server, "contracts_find", 'Discover deployed Stacks contracts conforming to a trait (e.g. "sip-010", "sip-009", "sip-013"). The discovery endpoint for "which contracts implement X". Reads are public.', {
-    trait: z2.string().describe('Required. Trait to match (e.g. "sip-010").'),
-    conformance: z2.enum(["declared", "inferred", "any"]).optional().describe("declared = parsed from source, inferred = ABI shape-match, any = either (default)"),
-    include: z2.literal("abi").optional().describe(`Set to "abi" to include each contract's full ABI`),
-    limit: z2.number().optional().describe("Page size, 1–500 (default 100)"),
-    cursor: z2.string().optional().describe("Opaque cursor from a prior response's next_cursor")
+    trait: z3.string().describe('Required. Trait to match (e.g. "sip-010").'),
+    conformance: z3.enum(["declared", "inferred", "any"]).optional().describe("declared = parsed from source, inferred = ABI shape-match, any = either (default)"),
+    include: z3.literal("abi").optional().describe(`Set to "abi" to include each contract's full ABI`),
+    limit: z3.number().optional().describe("Page size, 1–500 (default 100)"),
+    cursor: z3.string().optional().describe("Opaque cursor from a prior response's next_cursor")
   }, async (params) => jsonResponse(await clientProvider().contracts.list(params)));
-  defineTool(server, "contracts_get_abi", "Fetch a single deployed contract's ABI from the registry (prod-safe). Returns the contract's metadata + full ABI (functions, maps, variables, fungible/non-fungible tokens). Returns not_found if the contract isn't in the registry. Use it to inspect a contract before scaffold_from_contract.", {
-    contractId: z2.string().describe("Fully qualified contract id (e.g. SP….amm-pool-v2-01)")
+  defineTool(server, "contracts_get_abi", "Fetch a single deployed contract's ABI from the registry (prod-safe). Returns the contract's metadata + full ABI (functions, maps, variables, fungible/non-fungible tokens). Returns not_found if the contract isn't in the registry. Use it to inspect a contract before subgraphs_scaffold.", {
+    contractId: z3.string().describe("Fully qualified contract id (e.g. SP….amm-pool-v2-01)")
   }, async ({ contractId }) => {
     const contract = await clientProvider().contracts.get(contractId, {
       includeAbi: true
@@ -294,19 +320,19 @@ function registerContractTools(server, clientProvider = getClient) {
         message: `Contract not in registry: ${contractId}`
       }
     }, true);
-  }, { aliases: ["get_contract_abi"] });
+  });
 }
 
 // src/tools/index.ts
 import { DECODED_EVENT_TYPES } from "@secondlayer/shared";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var INDEX_EVENT_TYPES = DECODED_EVENT_TYPES;
 var rangeFilters = {
-  contractId: z3.string().optional().describe("Filter by contract id"),
-  fromHeight: z3.number().optional().describe("Start block height (inclusive)"),
-  toHeight: z3.number().optional().describe("End block height (inclusive)"),
-  cursor: z3.string().optional().describe("Opaque cursor from a prior response's next_cursor"),
-  limit: z3.number().optional().describe("Max rows for this page")
+  contractId: z4.string().optional().describe("Filter by contract id"),
+  fromHeight: z4.number().optional().describe("Start block height (inclusive)"),
+  toHeight: z4.number().optional().describe("End block height (inclusive)"),
+  cursor: z4.string().optional().describe("Opaque cursor from a prior response's next_cursor"),
+  limit: z4.number().optional().describe("Max rows for this page")
 };
 var heightFilters = {
   fromHeight: rangeFilters.fromHeight,
@@ -317,52 +343,52 @@ var heightFilters = {
 function registerIndexTools(server, clientProvider = getClient) {
   defineTool(server, "index_ft_transfers", "List decoded SIP-010 fungible-token transfers from the Index (decoded layer). Anonymous reads allowed (free-tier API keys are rejected — Build+ required).", {
     ...rangeFilters,
-    sender: z3.string().optional().describe("Filter by sender principal"),
-    recipient: z3.string().optional().describe("Filter by recipient principal"),
-    assetIdentifier: z3.string().optional().describe("Filter by asset identifier (contract::asset), e.g. SP…sbtc-token::sbtc-token")
+    sender: z4.string().optional().describe("Filter by sender principal"),
+    recipient: z4.string().optional().describe("Filter by recipient principal"),
+    assetIdentifier: z4.string().optional().describe("Filter by asset identifier (contract::asset), e.g. SP…sbtc-token::sbtc-token")
   }, async (params) => jsonResponse(await clientProvider().index.ftTransfers.list(params)));
   defineTool(server, "index_nft_transfers", "List decoded SIP-009 non-fungible-token transfers from the Index. Anonymous reads allowed (free-tier keys rejected).", {
     ...rangeFilters,
-    sender: z3.string().optional().describe("Filter by sender principal"),
-    recipient: z3.string().optional().describe("Filter by recipient principal"),
-    assetIdentifier: z3.string().optional().describe("Filter by asset identifier (contract::asset)")
+    sender: z4.string().optional().describe("Filter by sender principal"),
+    recipient: z4.string().optional().describe("Filter by recipient principal"),
+    assetIdentifier: z4.string().optional().describe("Filter by asset identifier (contract::asset)")
   }, async (params) => jsonResponse(await clientProvider().index.nftTransfers.list(params)));
   defineTool(server, "index_events", "List decoded chain events from the Index by event type. Use this for event types without a dedicated tool (stx_*, ft_mint/burn, nft_mint/burn, print), and for trait-scoped queries: set `trait` (e.g. sip-010) to match all contracts conforming to a standard — pair with contracts_find to discover traits. For ft/nft transfers without a trait prefer index_ft_transfers / index_nft_transfers.", {
-    eventType: z3.enum(INDEX_EVENT_TYPES).describe("Required. Decoded event type to list."),
+    eventType: z4.enum(INDEX_EVENT_TYPES).describe("Required. Decoded event type to list."),
     ...rangeFilters,
-    sender: z3.string().optional().describe("Filter by sender principal"),
-    recipient: z3.string().optional().describe("Filter by recipient principal"),
-    assetIdentifier: z3.string().optional().describe("Filter by asset identifier where applicable"),
-    trait: z3.string().optional().describe("Match contracts conforming to a trait/standard (e.g. sip-010). Mutually exclusive with contractId; contract-keyed event types only."),
-    txContext: z3.boolean().optional().describe("Join the submitting transaction into each event (tx_sender, tx_type, tx_status, tx_contract_id, tx_function_name). For print events it's the only source of the submitting sender.")
+    sender: z4.string().optional().describe("Filter by sender principal"),
+    recipient: z4.string().optional().describe("Filter by recipient principal"),
+    assetIdentifier: z4.string().optional().describe("Filter by asset identifier where applicable"),
+    trait: z4.string().optional().describe("Match contracts conforming to a trait/standard (e.g. sip-010). Mutually exclusive with contractId; contract-keyed event types only."),
+    txContext: z4.boolean().optional().describe("Join the submitting transaction into each event (tx_sender, tx_type, tx_status, tx_contract_id, tx_function_name). For print events it's the only source of the submitting sender.")
   }, async (params) => jsonResponse(await clientProvider().index.events.list(params)));
   defineTool(server, "index_contract_calls", "List decoded contract calls from the Index (function name, args, result). Set `trait` (e.g. sip-010) to match calls to all contracts conforming to a standard. Note: contract-call cursors are a SEPARATE keyspace from event cursors — they are not interchangeable.", {
     ...rangeFilters,
-    functionName: z3.string().optional().describe("Filter by called function name"),
-    sender: z3.string().optional().describe("Filter by caller principal"),
-    trait: z3.string().optional().describe("Match contracts conforming to a trait/standard (e.g. sip-010). Mutually exclusive with contractId.")
+    functionName: z4.string().optional().describe("Filter by called function name"),
+    sender: z4.string().optional().describe("Filter by caller principal"),
+    trait: z4.string().optional().describe("Match contracts conforming to a trait/standard (e.g. sip-010). Mutually exclusive with contractId.")
   }, async (params) => jsonResponse(await clientProvider().index.contractCalls.list(params)));
   defineTool(server, "index_blocks", "List decoded blocks from the Index. Anonymous reads allowed (free-tier keys rejected).", { ...heightFilters }, async (params) => jsonResponse(await clientProvider().index.blocks.list(params)));
   defineTool(server, "index_transactions", "List decoded transactions from the Index. Filter by type, sender, or contract. Anonymous reads allowed (free-tier keys rejected).", {
     ...rangeFilters,
-    type: z3.string().optional().describe("Filter by transaction type"),
-    sender: z3.string().optional().describe("Filter by sender principal")
+    type: z4.string().optional().describe("Filter by transaction type"),
+    sender: z4.string().optional().describe("Filter by sender principal")
   }, async (params) => jsonResponse(await clientProvider().index.transactions.list(params)));
   defineTool(server, "index_print_schema", "Empirical per-topic print payload schemas for a contract, inferred from sampled on-chain events: each topic's fields with observed Clarity types, decoded TS types, subgraph column types, and presence rates. Use before writing print_event subgraph handlers to learn what's on e.data. Anonymous read.", {
-    contractId: z3.string().describe("Contract id (SP….name) whose print events to profile")
+    contractId: z4.string().describe("Contract id (SP….name) whose print events to profile")
   }, async (params) => jsonResponse(await clientProvider().index.printSchema(params.contractId)));
   defineTool(server, "index_discover", "Discover the Index vocabulary: every event type and its columns, allowed/equality filters, and required-non-null fields (and which types accept `trait`). Read this before building Index queries instead of guessing filters. Anonymous read.", {}, async () => jsonResponse(await clientProvider().index.discover()));
   defineTool(server, "batch_query", "Run up to 10 public /v1 reads in one round trip (POST /v1/batch). Each item keeps its own auth/quota/pay-per-call semantics; results return in order with per-item status. Paths must start with /v1/index, /v1/subgraphs, /v1/streams, or /v1/contracts.", {
-    requests: z3.array(z3.object({
-      path: z3.string().describe("Public /v1 read path"),
-      params: z3.record(z3.string(), z3.string()).optional()
+    requests: z4.array(z4.object({
+      path: z4.string().describe("Public /v1 read path"),
+      params: z4.record(z4.string(), z4.string()).optional()
     })).min(1).max(10).describe("Read descriptors, executed concurrently")
   }, async (params) => jsonResponse(await clientProvider().batch(params.requests)));
 }
 
 // src/tools/scaffold.ts
 import { generateSubgraphCode } from "@secondlayer/scaffold";
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 async function fetchAbi(clientProvider, contractId) {
   const contract = await clientProvider().contracts.get(contractId, {
     includeAbi: true
@@ -376,9 +402,9 @@ async function fetchAbi(clientProvider, contractId) {
   return { functions: abi.functions ?? [] };
 }
 function registerScaffoldTools(server, clientProvider = getClient) {
-  defineTool(server, "scaffold_from_contract", "Generate a subgraph scaffold from a deployed Stacks contract. Fetches the ABI automatically.", {
-    contractId: z4.string().describe("Fully qualified contract ID (e.g. SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01)"),
-    subgraphName: z4.string().optional().describe("Override the subgraph name (defaults to contract name)")
+  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.", {
+    contractId: z5.string().describe("Fully qualified contract ID (e.g. SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01)"),
+    subgraphName: z5.string().optional().describe("Override the subgraph name (defaults to contract name)")
   }, async ({ contractId, subgraphName }) => {
     const { functions } = await fetchAbi(clientProvider, contractId);
     const code = generateSubgraphCode(contractId, functions, subgraphName);
@@ -387,32 +413,75 @@ function registerScaffoldTools(server, clientProvider = getClient) {
 }
 
 // src/tools/streams.ts
+import { STREAMS_EVENT_TYPES } from "@secondlayer/shared";
+import { z as z6 } from "zod";
+var filterValue = z6.union([z6.string(), z6.array(z6.string())]);
 function registerStreamsTools(server, clientProvider = getClient) {
-  defineTool(server, "streams_dumps", "List the Streams bulk parquet dumps manifest — coverage range, latest_finalized_cursor, and per-file metadata (block range, row count, size, sha256, signed URL). This is the cold backfill path for downloading all raw data; fetch the file URLs directly (e.g. with DuckDB). Requires the dumps base URL to be configured (SL_STREAMS_DUMPS_URL). Live Streams reads (tip, events, consume) are REST-only: see /v1/streams/* in the OpenAPI spec.", {}, async () => jsonResponse(await clientProvider().streams.dumps.list()));
+  defineTool(server, "streams_tip", "Current canonical chain tip as Streams sees it: block height/hash, burn height, finalized_height, lag_seconds, and the oldest seekable height/cursor for this key's retention window. Call it before a cursor walk to know where the stream ends, and after an ingest to check lag.", {}, async () => jsonResponse(await clientProvider().streams.tip()));
+  defineTool(server, "streams_events", "List raw chain events from Streams — ONE page per call, newest filters applied server-side. Returns { events, next_cursor, tip, reorgs }. To follow the chain live, poll this tool with `cursor` set to the previous response's `next_cursor` (input is exclusive, so no duplicates); there is no open-stream tool because a tool call cannot hold a connection. ALWAYS narrow with types/contractId/sender/recipient — an unfiltered page is the full firehose.", {
+    cursor: z6.string().optional().describe("Resume strictly after this cursor (`<block_height>:<event_index>`, e.g. 951475:3) — pass a prior response's next_cursor"),
+    fromHeight: z6.number().int().nonnegative().optional().describe("Start block height (inclusive)"),
+    toHeight: z6.number().int().nonnegative().optional().describe("End block height (inclusive)"),
+    types: z6.array(z6.enum(STREAMS_EVENT_TYPES)).optional().describe("Event types to include"),
+    notTypes: z6.array(z6.enum(STREAMS_EVENT_TYPES)).optional().describe("Event types to exclude (applied after types)"),
+    contractId: filterValue.optional().describe("Contract id, or a list of contract ids to OR together"),
+    sender: filterValue.optional().describe("Sender principal, or a list to OR together"),
+    recipient: filterValue.optional().describe("Recipient principal, or a list to OR together"),
+    assetIdentifier: z6.string().optional().describe("Asset identifier (contract::asset), e.g. SP…sbtc-token::sbtc-token"),
+    limit: z6.number().int().min(1).max(1000).optional().describe("Page size, 1–1000 (default 100)")
+  }, async (params) => jsonResponse(await clientProvider().streams.events.list(params)));
+  defineTool(server, "streams_events_by_tx", "List every event emitted by a single transaction, in emission order. Use it to explain one transaction end to end after finding it in streams_events or the Index.", {
+    txId: z6.string().describe("Transaction id (0x-prefixed)")
+  }, async ({ txId }) => jsonResponse(await clientProvider().streams.events.byTxId(txId)));
+  defineTool(server, "streams_block_events", "List every event in one block, addressed by block height or block hash. Use it to audit a block a consumer flagged, or to diff what a reorg replaced.", {
+    heightOrHash: z6.union([z6.number().int().nonnegative(), z6.string()]).describe("Block height (number) or block hash (0x-prefixed string)")
+  }, async ({ heightOrHash }) => jsonResponse(await clientProvider().streams.blocks.events(heightOrHash)));
+  defineTool(server, "streams_canonical", "Get the canonical block at a height: hash, burn block hash, parent, and whether the height is still canonical. Use it to confirm a height you already consumed was not reorged away before you trust derived state.", {
+    height: z6.number().int().nonnegative().describe("Block height")
+  }, async ({ height }) => jsonResponse(await clientProvider().streams.canonical(height)));
+  defineTool(server, "streams_reorgs", "List reorgs detected since a point in time, newest last, with the new canonical tip for each. Returns { reorgs, next_since } — resume with next_since. Call it when a consumer's derived state disagrees with streams_canonical, or on a schedule to know which heights to reprocess.", {
+    since: z6.string().describe("Required. ISO 8601 timestamp, or a `next_since` resume token from a prior response"),
+    limit: z6.number().int().positive().optional().describe("Max reorgs to return")
+  }, async ({ since, limit }) => jsonResponse(await clientProvider().streams.reorgs.list({
+    since,
+    ...limit !== undefined ? { limit } : {}
+  })));
+  defineTool(server, "streams_dumps", "List the Streams bulk parquet dumps manifest — coverage range, latest_finalized_cursor, and per-file metadata (block range, row count, size, sha256, signed URL). This is the cold backfill path for downloading all raw data; fetch the file URLs directly (e.g. with DuckDB). Requires the dumps base URL to be configured (SL_STREAMS_DUMPS_URL). For live reads use streams_events (cursor-paginated) and streams_tip.", {}, async () => jsonResponse(await clientProvider().streams.dumps.list()));
 }
 
 // src/tools/subgraphs.ts
 import { bundleSubgraphCode } from "@secondlayer/bundler";
-import { z as z5 } from "zod";
+import { z as z7 } from "zod";
 function registerSubgraphTools(server, clientProvider = getClient) {
-  defineTool(server, "subgraphs_list", "List all deployed subgraphs. Returns summary fields only, including visibility — public subgraphs are anon-readable at /v1/subgraphs/<name>.", {}, async () => {
+  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_get", "Get full details of a subgraph including schema, health, and table columns.", { name: z5.string().describe("Subgraph name") }, async ({ name }) => {
-    const detail = await clientProvider().subgraphs.get(name);
+  defineTool(server, "subgraphs_status", "Get full details of a subgraph including schema, health, and table columns.", { name: z7.string().describe("Subgraph name") }, async ({ name }) => {
+    const detail = await clientProvider().subgraphs.status(name);
     return jsonResponse(detail);
   });
-  defineTool(server, "subgraphs_query", 'Query rows from a subgraph table (max 200 rows). Filters support operators: "amount.gte": "1000", "sender.neq": "SP...", "name.like": "%token%". Available operators: eq, neq, gt, gte, lt, lte, like. To TAIL new rows (no streaming over MCP): sort=_id, order=desc for the latest, then poll forward with the filter {"_id.gt": "<last _id seen>"}, order=asc — when tailing with a `fields` list, include "_id" in it or the next poll filter cannot be formed. Fetch one row by id with {"_id": "<id>"}. Public subgraphs are also keyless over HTTP at GET /v1/subgraphs/<name>/<table> — { rows, next_cursor, tip } envelope, resume with ?cursor=<next_cursor> + _order=asc|desc (no _offset/_sort on /v1); hand that URL to third parties.', {
-    name: z5.string().describe("Subgraph name"),
-    table: z5.string().describe("Table name"),
-    filters: z5.record(z5.string(), z5.string()).optional().describe('Column filters — plain values or with operators (e.g. {"amount.gte": "1000", "sender": "SP..."})'),
-    sort: z5.string().optional().describe("Column to sort by"),
-    order: z5.enum(["asc", "desc"]).optional().describe("Sort order"),
-    limit: z5.number().max(200).optional().describe("Max rows (default 50, max 200)"),
-    offset: z5.number().optional().describe("Offset for pagination"),
-    fields: z5.string().optional().describe('Comma-separated column list to return (e.g. "sender,amount")'),
-    count: z5.boolean().optional().describe("If true, return row count instead of rows")
+  defineTool(server, "subgraphs_spec", "Fetch a subgraph's self-describing spec — the tables, columns, filters, and read URLs a consumer needs, without guessing. `agent` (default) returns the compact JSON schema built for tool use, `openapi` the OpenAPI document for the subgraph's read routes, `markdown` human-readable docs. Read it before writing queries against an unfamiliar subgraph.", {
+    name: z7.string().describe("Subgraph name"),
+    format: z7.enum(["agent", "openapi", "markdown"]).optional().describe("agent = JSON schema for tool use (default), openapi = OpenAPI JSON, markdown = docs.md")
+  }, async ({ name, format }) => {
+    const client = clientProvider();
+    if (format === "openapi")
+      return jsonResponse(await client.subgraphs.openapi(name));
+    if (format === "markdown")
+      return textResponse(await client.subgraphs.markdown(name));
+    return jsonResponse(await client.subgraphs.schema(name));
+  });
+  defineTool(server, "subgraphs_query", 'Query rows from a subgraph table (max 200 rows). Filters support operators: "amount.gte": "1000", "sender.neq": "SP...", "name.like": "%token%". Available operators: eq, neq, gt, gte, lt, lte, like. To TAIL new rows (no streaming over MCP): sort=_id, order=desc for the latest, then poll forward with the filter {"_id.gt": "<last _id seen>"}, order=asc — when tailing with a `fields` list, include "_id" in it or the next poll filter cannot be formed. Fetch one row by id with {"_id": "<id>"}. The same rows are readable over HTTP at GET /v1/subgraphs/<name>/<table> — { rows, next_cursor, tip } envelope, resume with ?cursor=<next_cursor> + _order=asc|desc (no _offset/_sort on /v1); hand that URL to third parties.', {
+    name: z7.string().describe("Subgraph name"),
+    table: z7.string().describe("Table name"),
+    filters: z7.record(z7.string(), z7.string()).optional().describe('Column filters — plain values or with operators (e.g. {"amount.gte": "1000", "sender": "SP..."})'),
+    sort: z7.string().optional().describe("Column to sort by"),
+    order: z7.enum(["asc", "desc"]).optional().describe("Sort order"),
+    limit: z7.number().max(200).optional().describe("Max rows (default 50, max 200)"),
+    offset: z7.number().optional().describe("Offset for pagination"),
+    fields: z7.string().optional().describe('Comma-separated column list to return (e.g. "sender,amount")'),
+    count: z7.boolean().optional().describe("If true, return row count instead of rows")
   }, async ({
     name,
     table,
@@ -439,16 +508,16 @@ function registerSubgraphTools(server, clientProvider = getClient) {
     const result = withCap(rows, Math.min(limit ?? 50, 200));
     return jsonResponse(result);
   });
-  defineTool(server, "subgraphs_reindex", "Reindex a subgraph: drops and rebuilds the whole subgraph from its start block to chain tip. Takes no block range — use subgraphs_backfill to process a specific range. Returns an operationId — check subgraphs_get (health) or the REST operations endpoint to track progress to completion.", {
-    name: z5.string().describe("Subgraph name")
+  defineTool(server, "subgraphs_reindex", "Reindex a subgraph: drops and rebuilds the whole subgraph from its start block to chain tip. Takes no block range — use subgraphs_backfill to process a specific range. Returns an operationId — check subgraphs_status (health) or the REST operations endpoint to track progress to completion.", {
+    name: z7.string().describe("Subgraph name")
   }, async ({ name }) => {
     const result = await clientProvider().subgraphs.reindex(name);
     return jsonResponse(result);
   });
-  defineTool(server, "subgraphs_backfill", "Backfill a subgraph over a block range. Non-destructive forward fill (does not drop existing data) — unlike subgraphs_reindex, and the only data-fill path for BYO subgraphs (reindex is blocked there). Both blocks required. Returns an operationId — check subgraphs_get (health) or the REST operations endpoint to track progress.", {
-    name: z5.string().describe("Subgraph name"),
-    fromBlock: z5.number().int().nonnegative().describe("Start block (inclusive)"),
-    toBlock: z5.number().int().nonnegative().describe("End block (inclusive)")
+  defineTool(server, "subgraphs_backfill", "Backfill a subgraph over a block range. Non-destructive forward fill (does not drop existing data) — unlike subgraphs_reindex, and the only data-fill path for BYO subgraphs (reindex is blocked there). Both blocks required. Returns an operationId — check subgraphs_status (health) or the REST operations endpoint to track progress.", {
+    name: z7.string().describe("Subgraph name"),
+    fromBlock: z7.number().int().nonnegative().describe("Start block (inclusive)"),
+    toBlock: z7.number().int().nonnegative().describe("End block (inclusive)")
   }, async ({ name, fromBlock, toBlock }) => {
     const result = await clientProvider().subgraphs.backfill(name, {
       fromBlock,
@@ -456,15 +525,15 @@ function registerSubgraphTools(server, clientProvider = getClient) {
     });
     return jsonResponse(result);
   });
-  defineTool(server, "subgraphs_stop", "Cancel an in-flight reindex or backfill operation for a subgraph. Returns the stop request status; check subgraphs_get (health) or the REST operations endpoint to confirm it reaches a terminal state.", { name: z5.string().describe("Subgraph name") }, async ({ name }) => {
+  defineTool(server, "subgraphs_stop", "Cancel an in-flight reindex or backfill operation for a subgraph. Returns the stop request status; check subgraphs_status (health) or the REST operations endpoint to confirm it reaches a terminal state.", { name: z7.string().describe("Subgraph name") }, async ({ name }) => {
     const result = await clientProvider().subgraphs.stop(name);
     return jsonResponse(result);
   });
   defineTool(server, "subgraphs_gaps", "List indexing gaps (missing block ranges) for a subgraph. Each gap reports start/end/size, reason, and detected/resolved timestamps. Feed an unresolved gap's range into subgraphs_backfill to fill it. Defaults to unresolved gaps.", {
-    name: z5.string().describe("Subgraph name"),
-    limit: z5.number().int().positive().optional().describe("Max gaps to return"),
-    offset: z5.number().int().nonnegative().optional().describe("Pagination offset"),
-    resolved: z5.boolean().optional().describe("Filter by resolved state (omit for unresolved only)")
+    name: z7.string().describe("Subgraph name"),
+    limit: z7.number().int().positive().optional().describe("Max gaps to return"),
+    offset: z7.number().int().nonnegative().optional().describe("Pagination offset"),
+    resolved: z7.boolean().optional().describe("Filter by resolved state (omit for unresolved only)")
   }, async ({ name, limit, offset, resolved }) => {
     const result = await clientProvider().subgraphs.gaps(name, {
       limit,
@@ -473,14 +542,21 @@ function registerSubgraphTools(server, clientProvider = getClient) {
     });
     return jsonResponse(result);
   });
-  defineTool(server, "subgraphs_delete", "Delete a subgraph permanently.", { name: z5.string().describe("Subgraph name") }, async ({ name }) => {
+  defineTool(server, "subgraphs_operations", "Operation history for a subgraph (deploy/reindex/backfill/stop), newest first — status, block range, progress, and error. THIS IS THE VERIFY CALL: after subgraphs_deploy, subgraphs_reindex, subgraphs_backfill, or subgraphs_stop, poll it with the returned operationId until `status` is terminal (completed/failed/cancelled) before reporting success. Omit operationId for the recent history.", {
+    name: z7.string().describe("Subgraph name"),
+    operationId: z7.string().optional().describe("Fetch one operation by id (the operationId returned by reindex/backfill/stop); omit for recent history")
+  }, async ({ name, operationId }) => {
+    const client = clientProvider();
+    return jsonResponse(operationId ? await client.subgraphs.getOperation(name, operationId) : await client.subgraphs.operations(name));
+  });
+  defineTool(server, "subgraphs_delete", "Delete a subgraph permanently.", { name: z7.string().describe("Subgraph name") }, async ({ name }) => {
     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.", {
-    code: z5.string().describe("TypeScript source code containing a defineSubgraph() call"),
-    startBlock: z5.number().int().nonnegative().optional().describe("Override the definition startBlock for this deploy"),
-    dryRun: z5.boolean().optional().describe("Validate and preview the deploy (schema/DDL) without writing changes")
+    code: z7.string().describe("TypeScript source code containing a defineSubgraph() call"),
+    startBlock: z7.number().int().nonnegative().optional().describe("Override the definition startBlock for this deploy"),
+    dryRun: z7.boolean().optional().describe("Validate and preview the deploy (schema/DDL) without writing changes")
   }, async ({ code, startBlock, dryRun }) => {
     const bundled = await bundleSubgraphCode(code);
     const result = await clientProvider().subgraphs.deploy({
@@ -500,38 +576,38 @@ function registerSubgraphTools(server, clientProvider = getClient) {
 
 // src/tools/subscriptions.ts
 import { CHAIN_TRIGGER_TYPES } from "@secondlayer/shared";
-import { z as z6 } from "zod";
+import { z as z8 } 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();
     return jsonResponse(data);
   });
-  defineTool(server, "subscriptions_get", "Get full detail for a subscription (filter, auth, retry config, circuit state).", { id: z6.string().describe("Subscription id") }, async ({ id }) => {
+  defineTool(server, "subscriptions_get", "Get full detail for a subscription (filter, auth, retry config, circuit state).", { id: z8.string().describe("Subscription id") }, async ({ id }) => {
     const detail = await clientProvider().subscriptions.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.", {
-    name: z6.string().describe("Human-readable name, unique per account"),
-    subgraphName: z6.string().optional().describe("Subgraph to subscribe to (subgraph subscription)"),
-    tableName: z6.string().optional().describe("Table within the subgraph (subgraph subscription)"),
-    triggers: z6.array(z6.object({
-      type: z6.enum(CHAIN_TRIGGER_TYPES),
-      contractId: z6.string().optional(),
-      functionName: z6.string().optional(),
-      caller: z6.string().optional(),
-      sender: z6.string().optional(),
-      recipient: z6.string().optional(),
-      assetIdentifier: z6.string().optional(),
-      deployer: z6.string().optional(),
-      contractName: z6.string().optional(),
-      topic: z6.string().optional(),
-      lockedAddress: z6.string().optional(),
-      trait: z6.string().optional(),
-      minAmount: z6.union([z6.string(), z6.number()]).optional(),
-      maxAmount: z6.union([z6.string(), z6.number()]).optional()
+    name: z8.string().describe("Human-readable name, unique per account"),
+    subgraphName: z8.string().optional().describe("Subgraph to subscribe to (subgraph subscription)"),
+    tableName: z8.string().optional().describe("Table within the subgraph (subgraph subscription)"),
+    triggers: z8.array(z8.object({
+      type: z8.enum(CHAIN_TRIGGER_TYPES),
+      contractId: z8.string().optional(),
+      functionName: z8.string().optional(),
+      caller: z8.string().optional(),
+      sender: z8.string().optional(),
+      recipient: z8.string().optional(),
+      assetIdentifier: z8.string().optional(),
+      deployer: z8.string().optional(),
+      contractName: z8.string().optional(),
+      topic: z8.string().optional(),
+      lockedAddress: z8.string().optional(),
+      trait: z8.string().optional(),
+      minAmount: z8.union([z8.string(), z8.number()]).optional(),
+      maxAmount: z8.union([z8.string(), z8.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."),
-    url: z6.string().describe("Webhook URL"),
-    format: z6.enum([
+    url: z8.string().describe("Webhook URL"),
+    format: z8.enum([
       "standard-webhooks",
       "inngest",
       "trigger",
@@ -539,20 +615,20 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
       "cloudevents",
       "raw"
     ]).optional().describe("Wire format (default standard-webhooks)"),
-    runtime: z6.enum(["inngest", "trigger", "cloudflare", "node"]).optional().describe("Receiver runtime label (display only)"),
-    filter: z6.record(z6.string(), z6.unknown()).optional().describe('Scalar filter DSL, e.g. {"amount": {"gte": 100}, "sender": "SP..."}'),
-    authConfig: z6.record(z6.string(), z6.unknown()).optional().describe('Receiver auth sent with each delivery, e.g. {"type": "bearer", "token": "..."}')
+    runtime: z8.enum(["inngest", "trigger", "cloudflare", "node"]).optional().describe("Receiver runtime label (display only)"),
+    filter: z8.record(z8.string(), z8.unknown()).optional().describe('Scalar filter DSL, e.g. {"amount": {"gte": 100}, "sender": "SP..."}'),
+    authConfig: z8.record(z8.string(), z8.unknown()).optional().describe('Receiver auth sent with each delivery, e.g. {"type": "bearer", "token": "..."}')
   }, async (input) => {
     const res = await clientProvider().subscriptions.create(input);
     return jsonResponse(res);
   });
   defineTool(server, "subscriptions_update", "Patch a subscription (name, url, filter, authConfig, format, runtime, retry, timeout, concurrency).", {
-    id: z6.string(),
-    name: z6.string().optional().describe("Rename the subscription"),
-    url: z6.string().optional(),
-    filter: z6.record(z6.string(), z6.unknown()).optional(),
-    authConfig: z6.record(z6.string(), z6.unknown()).optional().describe("Receiver auth sent with each delivery (bearer/etc.)"),
-    format: z6.enum([
+    id: z8.string(),
+    name: z8.string().optional().describe("Rename the subscription"),
+    url: z8.string().optional(),
+    filter: z8.record(z8.string(), z8.unknown()).optional(),
+    authConfig: z8.record(z8.string(), z8.unknown()).optional().describe("Receiver auth sent with each delivery (bearer/etc.)"),
+    format: z8.enum([
       "standard-webhooks",
       "inngest",
       "trigger",
@@ -560,27 +636,36 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
       "cloudevents",
       "raw"
     ]).optional(),
-    runtime: z6.enum(["inngest", "trigger", "cloudflare", "node"]).nullable().optional(),
-    maxRetries: z6.number().int().min(0).optional(),
-    timeoutMs: z6.number().int().min(100).optional(),
-    concurrency: z6.number().int().min(1).optional()
+    runtime: z8.enum(["inngest", "trigger", "cloudflare", "node"]).nullable().optional(),
+    maxRetries: z8.number().int().min(0).optional(),
+    timeoutMs: z8.number().int().min(100).optional(),
+    concurrency: z8.number().int().min(1).optional()
   }, async ({ id, ...patch }) => {
     const res = await clientProvider().subscriptions.update(id, patch);
     return jsonResponse(res);
   });
-  defineTool(server, "subscriptions_delete", "Delete a subscription. Pending outbox rows are cascade-deleted.", { id: z6.string() }, async ({ id }) => {
+  defineTool(server, "subscriptions_delete", "Delete a subscription. Pending outbox rows are cascade-deleted.", { id: z8.string() }, async ({ id }) => {
     const res = await clientProvider().subscriptions.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: z6.string().describe("Subscription id") }, async ({ id }) => {
+  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: z8.string().describe("Subscription id") }, async ({ id }) => {
     const res = await clientProvider().subscriptions.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: z8.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: z8.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: z8.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: z8.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: z8.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: z8.string().describe("Subscription id"),
+    outboxId: z8.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.", {
-    id: z6.string(),
-    fromBlock: z6.number().int().nonnegative(),
-    toBlock: z6.number().int().nonnegative(),
-    force: z6.string().optional().describe("Idempotency suffix to force a duplicate replay of the range")
+    id: z8.string(),
+    fromBlock: z8.number().int().nonnegative(),
+    toBlock: z8.number().int().nonnegative(),
+    force: z8.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, {
       fromBlock,
@@ -606,6 +691,7 @@ function createServer() {
   registerStreamsTools(server);
   registerContractTools(server);
   registerCodegenTools(server);
+  registerAccountTools(server);
   registerResources(server);
   return server;
 }
@@ -615,5 +701,5 @@ var server = createServer();
 var transport = new StdioServerTransport;
 await server.connect(transport);
 
-//# debugId=47C86EEF1415CCE464756E2164756E21
+//# debugId=08F9439BE660189C64756E2164756E21
 //# sourceMappingURL=bin.js.map