@secondlayer/mcp 3.1.1 → 3.3.0

package/README.md

@@ -61,6 +61,14 @@ bunx -p @secondlayer/mcp secondlayer-mcp-http
 | **Scaffold** (2) | `scaffold_from_contract`, `scaffold_from_abi` |
 | **Account** (3) | `account_whoami`, `account_update`, `account_billing` |
 
+### `subscriptions_create` kinds
+
+Subscriptions are polymorphic. Pass `subgraphName` + `tableName` for a
+**subgraph** subscription, or a `triggers` array for a **chain** subscription —
+a webhook on raw chain events (contract / event / function / trait) with no
+subgraph (e.g. `[{ "type": "contract_call", "contractId": "SP....amm",
+"functionName": "swap-*" }]`).
+
 ### `subgraphs_query` enhancements
 
 - `fields` — comma-separated column projection (e.g. `"sender,amount_x"`)

package/dist/bin-http.js

@@ -75,6 +75,34 @@ function jsonResponse(data, isError) {
   };
 }
 
+// src/lib/tool.ts
+var registeredToolNames = new Set;
+function getRegisteredToolNames() {
+  return [...registeredToolNames];
+}
+function defineTool(server, name, description, schema, handler) {
+  const wrappedHandler = async (args) => {
+    try {
+      return await handler(args);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const status = err instanceof Error && "status" in err ? err.status : 0;
+      const type = status === 401 ? "unauthorized" : status === 404 ? "not_found" : status === 429 ? "rate_limited" : status >= 500 ? "server_error" : "error";
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: { type, status, message } })
+          }
+        ],
+        isError: true
+      };
+    }
+  };
+  registeredToolNames.add(name);
+  server.tool(name, description, schema, wrappedHandler);
+}
+
 // src/resources.ts
 var FILTERS_REFERENCE = [
   {
@@ -130,39 +158,69 @@ var COLUMN_TYPES = [
     description: "Column options: nullable allows NULL, indexed creates a B-tree index, search enables full-text search"
   }
 ];
-var CAPABILITIES = {
-  products: [
-    "datasets — public foundation datasets (datasets_list, datasets_query)",
-    "index — decoded L2 events + contract calls (index_ft_transfers, index_nft_transfers, index_events, index_contract_calls)",
-    "streams — raw chain event firehose (streams_tip, streams_events)",
-    "contracts — trait-based contract discovery (contracts_find)",
-    "subgraphs — author/deploy/query custom indexes (subgraphs_deploy, subgraphs_query, subgraphs_list, subgraphs_get, subgraphs_reindex, subgraphs_delete)",
-    "subscriptions — webhook delivery of subgraph rows (subscriptions_create, subscriptions_list, subscriptions_update, …)",
-    "account — identity + plan (account_whoami)"
-  ],
-  discoverFirst: "Call datasets_list / contracts_find to learn what exists before querying."
+var PRODUCT_BLURBS = {
+  datasets: "public foundation datasets",
+  index: "decoded L2 events, contract calls, blocks, transactions, stacking, mempool",
+  streams: "raw canonical chain event firehose",
+  contracts: "trait-based contract discovery",
+  subgraphs: "author/deploy/query custom indexes",
+  subscriptions: "webhook delivery on subgraph rows or raw chain events",
+  account: "identity, plan, billing, and API keys",
+  scaffold: "generate typed contract clients from a deployment or ABI"
 };
+var PRODUCT_ORDER = [
+  "datasets",
+  "index",
+  "streams",
+  "contracts",
+  "subgraphs",
+  "subscriptions",
+  "account",
+  "scaffold"
+];
+function buildCapabilities() {
+  const byPrefix = new Map;
+  for (const name of getRegisteredToolNames()) {
+    const prefix = name.slice(0, name.indexOf("_"));
+    const tools = byPrefix.get(prefix) ?? [];
+    tools.push(name);
+    byPrefix.set(prefix, tools);
+  }
+  const order = [
+    ...PRODUCT_ORDER.filter((p) => byPrefix.has(p)),
+    ...[...byPrefix.keys()].filter((p) => !PRODUCT_ORDER.includes(p))
+  ];
+  const products = order.map((p) => {
+    const tools = byPrefix.get(p) ?? [];
+    const blurb = PRODUCT_BLURBS[p];
+    return blurb ? `${p} — ${blurb} (${tools.join(", ")})` : `${p} (${tools.join(", ")})`;
+  });
+  return {
+    products,
+    discoverFirst: "Call datasets_list / contracts_find to learn what exists before querying."
+  };
+}
 var READ_AUTH_TIERS = {
   datasets: "open — no API key required",
   index: "anonymous reads allowed; free-tier API keys are rejected (Build+ required)",
   streams: "API key required (SL_API_KEY) — keyless calls return 401",
   subgraphs: "reads public during open beta; writes require an API key"
 };
-async function buildContext(deps = {
-  clientProvider: getClient,
-  accountRequest: () => apiRequest("GET", "/api/accounts/me")
-}) {
+async function buildContext(deps = { clientProvider: getClient }) {
   const unavailable = "unavailable: set SL_API_KEY";
-  const subgraphs = await deps.clientProvider().subgraphs.list().then((r) => r.data.map(formatSubgraphSummary)).catch(() => unavailable);
-  const subscriptions = await deps.clientProvider().subscriptions.list().then((r) => ({
-    count: r.data.length,
-    statuses: r.data.map((s) => s.status)
-  })).catch(() => unavailable);
-  const account = await deps.accountRequest().catch(() => unavailable);
+  const orNull = (v) => v == null ? unavailable : v;
+  const snap = await deps.clientProvider().context().catch(() => null);
   return {
     authState: { apiKeySet: Boolean(process.env.SL_API_KEY) },
-    whatExists: { subgraphs, subscriptions, account },
-    whatYouCanDo: CAPABILITIES,
+    whatExists: {
+      account: orNull(snap?.account),
+      streamsTip: orNull(snap?.streamsTip),
+      indexTip: orNull(snap?.indexTip),
+      subgraphs: snap?.subgraphs ? snap.subgraphs.map(formatSubgraphSummary) : unavailable,
+      subscriptions: orNull(snap?.subscriptions),
+      activeOperations: orNull(snap?.activeOperations)
+    },
+    whatYouCanDo: buildCapabilities(),
     readAuthTiers: READ_AUTH_TIERS
   };
 }
@@ -200,31 +258,6 @@ function registerResources(server) {
 
 // src/tools/account.ts
 import { z } from "zod/v4";
-
-// src/lib/tool.ts
-function defineTool(server, name, description, schema, handler) {
-  const wrappedHandler = async (args) => {
-    try {
-      return await handler(args);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const status = err instanceof Error && "status" in err ? err.status : 0;
-      const type = status === 401 ? "unauthorized" : status === 404 ? "not_found" : status === 429 ? "rate_limited" : status >= 500 ? "server_error" : "error";
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ error: { type, status, message } })
-          }
-        ],
-        isError: true
-      };
-    }
-  };
-  server.tool(name, description, schema, wrappedHandler);
-}
-
-// src/tools/account.ts
 function registerAccountTools(server) {
   defineTool(server, "account_whoami", "Show the authenticated account's email and plan.", {}, async () => {
     const result = await apiRequest("GET", "/api/accounts/me");
@@ -249,6 +282,10 @@ function registerAccountTools(server) {
     const result = await apiRequest("GET", "/api/billing/status");
     return jsonResponse(result);
   });
+  defineTool(server, "account_create_key", "Mint a scoped streams/index read API key so the agent can self-provision access. Requires an account-level (owner) API key. The returned `key` is shown ONCE — forward it to the user to set as SL_API_KEY.", {
+    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 getClient().apiKeys.create({ product, name })));
 }
 
 // src/tools/contracts.ts
@@ -287,20 +324,9 @@ function registerDatasetTools(server, clientProvider = getClient) {
 }
 
 // src/tools/index.ts
+import { DECODED_EVENT_TYPES } from "@secondlayer/shared";
 import { z as z4 } from "zod/v4";
-var INDEX_EVENT_TYPES = [
-  "ft_transfer",
-  "nft_transfer",
-  "stx_transfer",
-  "stx_mint",
-  "stx_burn",
-  "stx_lock",
-  "ft_mint",
-  "ft_burn",
-  "nft_mint",
-  "nft_burn",
-  "print"
-];
+var INDEX_EVENT_TYPES = DECODED_EVENT_TYPES;
 var rangeFilters = {
   contractId: z4.string().optional().describe("Filter by contract id"),
   fromHeight: z4.number().optional().describe("Start block height (inclusive)"),
@@ -308,6 +334,13 @@ var rangeFilters = {
   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,
+  toHeight: rangeFilters.toHeight,
+  cursor: rangeFilters.cursor,
+  limit: rangeFilters.limit
+};
+var notFound = (message) => jsonResponse({ error: { type: "not_found", status: 404, message } }, true);
 function registerIndexTools(server, clientProvider = getClient) {
   defineTool(server, "index_ft_transfers", "List decoded SIP-010 fungible-token transfers from the Index (L2 decoded layer). Anonymous reads allowed (free-tier API keys are rejected — Build+ required).", {
     ...rangeFilters,
@@ -332,6 +365,41 @@ function registerIndexTools(server, clientProvider = getClient) {
     functionName: z4.string().optional().describe("Filter by called function name"),
     sender: z4.string().optional().describe("Filter by caller principal")
   }, async (params) => jsonResponse(await clientProvider().index.contractCalls.list(params)));
+  defineTool(server, "index_canonical", "List the canonical Stacks block sequence from the Index (height + hash). Anonymous reads allowed (free-tier keys rejected).", { ...heightFilters }, async (params) => jsonResponse(await clientProvider().index.canonical.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_block", "Get a single block from the Index by height or block hash. Returns not_found if unknown.", {
+    ref: z4.string().describe("Block height (digits) or block hash (0x… string)")
+  }, async ({ ref }) => {
+    const block = await clientProvider().index.blocks.get(/^\d+$/.test(ref) ? Number(ref) : ref);
+    return block ? jsonResponse(block) : notFound(`No block for ref ${ref}`);
+  });
+  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: 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_transaction", "Get a single transaction from the Index by tx_id. Returns not_found if unknown.", { txId: z4.string().describe("Transaction id (0x… hash)") }, async ({ txId }) => {
+    const tx = await clientProvider().index.transactions.get(txId);
+    return tx ? jsonResponse(tx) : notFound(`No transaction for ${txId}`);
+  });
+  defineTool(server, "index_stacking", "List decoded PoX-4 stacking actions from the Index (stack-stx, delegate-stx, etc.). Anonymous reads allowed (free-tier keys rejected).", {
+    ...heightFilters,
+    functionName: z4.string().optional().describe("Filter by PoX function name"),
+    stacker: z4.string().optional().describe("Filter by stacker principal"),
+    caller: z4.string().optional().describe("Filter by caller principal")
+  }, async (params) => jsonResponse(await clientProvider().index.stacking.list(params)));
+  defineTool(server, "index_mempool", "List pending (unconfirmed) transactions from the Index mempool. Sequence-cursor paginated (no height range). Anonymous reads allowed (free-tier keys rejected).", {
+    sender: z4.string().optional().describe("Filter by sender principal"),
+    type: z4.string().optional().describe("Filter by transaction type"),
+    contractId: z4.string().optional().describe("Filter to pending calls to a single contract"),
+    cursor: z4.string().optional().describe("Opaque cursor from a prior response's next_cursor"),
+    limit: z4.number().optional().describe("Max rows for this page")
+  }, async (params) => jsonResponse(await clientProvider().index.mempool.list(params)));
+  defineTool(server, "index_mempool_tx", "Get a single pending transaction from the Index mempool by tx_id. Returns not_found once it is mined or dropped.", { txId: z4.string().describe("Transaction id (0x… hash)") }, async ({ txId }) => {
+    const tx = await clientProvider().index.mempool.get(txId);
+    return tx ? jsonResponse(tx) : notFound(`No pending tx for ${txId}`);
+  });
+  defineTool(server, "index_usage", "Your own Index consumption (decoded events today + this month) and tier limits. Requires a Build+ API key (anonymous reads can't report usage).", {}, async () => jsonResponse(await clientProvider().index.usage()));
 }
 
 // src/tools/scaffold.ts
@@ -383,20 +451,9 @@ function registerScaffoldTools(server) {
 
 // src/tools/streams.ts
 import { AuthError } from "@secondlayer/sdk";
+import { DECODED_EVENT_TYPES as DECODED_EVENT_TYPES2 } from "@secondlayer/shared";
 import { z as z6 } from "zod/v4";
-var STREAMS_EVENT_TYPES = [
-  "stx_transfer",
-  "stx_mint",
-  "stx_burn",
-  "stx_lock",
-  "ft_transfer",
-  "ft_mint",
-  "ft_burn",
-  "nft_transfer",
-  "nft_mint",
-  "nft_burn",
-  "print"
-];
+var STREAMS_EVENT_TYPES = DECODED_EVENT_TYPES2;
 async function withStreamsAuthHint(fn) {
   try {
     return await fn();
@@ -416,11 +473,21 @@ function registerStreamsTools(server, clientProvider = getClient) {
     sender: z6.string().optional().describe("Filter by sender principal"),
     recipient: z6.string().optional().describe("Filter by recipient principal"),
     assetIdentifier: z6.string().optional().describe("Filter by asset identifier"),
-    fromBlock: z6.number().optional().describe("Start block (inclusive)"),
-    toBlock: z6.number().optional().describe("End block (inclusive)"),
+    fromHeight: z6.number().optional().describe("Start block height (inclusive)"),
+    toHeight: z6.number().optional().describe("End block height (inclusive)"),
     cursor: z6.string().optional().describe("Opaque cursor from a prior response"),
     limit: z6.number().optional().describe("Max events for this page")
   }, async (params) => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.events.list(params))));
+  defineTool(server, "streams_event_by_txid", "List all Streams events emitted by a single transaction. Streams requires an API key (SL_API_KEY).", { txId: z6.string().describe("Transaction id (0x… hash)") }, async ({ txId }) => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.events.byTxId(txId))));
+  defineTool(server, "streams_block_events", "List all Streams events in a single block, by height or block hash. Streams requires an API key (SL_API_KEY).", {
+    heightOrHash: z6.string().describe("Block height (digits) or block hash (0x… string)")
+  }, async ({ heightOrHash }) => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.blocks.events(/^\d+$/.test(heightOrHash) ? Number(heightOrHash) : heightOrHash))));
+  defineTool(server, "streams_reorgs", "List chain reorgs observed by Streams since a cursor. Streams requires an API key (SL_API_KEY).", {
+    since: z6.string().describe("Cursor to list reorgs since (block:index or ISO timestamp)"),
+    limit: z6.number().optional().describe("Max reorgs to return")
+  }, async (params) => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.reorgs.list(params))));
+  defineTool(server, "streams_canonical", "Get the canonical block at a given height from Streams (height + hashes + is_canonical). Streams requires an API key (SL_API_KEY).", { height: z6.number().describe("Block height") }, async ({ height }) => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.canonical(height))));
+  defineTool(server, "streams_usage", "Your own Streams consumption (events today + this month) and tier limits (rate limit, retention). Streams requires an API key (SL_API_KEY).", {}, async () => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.usage())));
 }
 
 // src/tools/subgraphs.ts
@@ -501,7 +568,7 @@ function registerSubgraphTools(server, clientProvider = getClient) {
       content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
     };
   });
-  defineTool(server, "subgraphs_reindex", "Reindex a subgraph from a specific block range.", {
+  defineTool(server, "subgraphs_reindex", "Reindex a subgraph from a specific block range. Returns an operationId — poll subgraphs_operation to track progress to completion.", {
     name: z7.string().describe("Subgraph name"),
     fromBlock: z7.number().optional().describe("Start block (defaults to beginning)"),
     toBlock: z7.number().optional().describe("End block (defaults to latest)")
@@ -514,6 +581,15 @@ function registerSubgraphTools(server, clientProvider = getClient) {
       content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
     };
   });
+  defineTool(server, "subgraphs_operation", "Check reindex/backfill progress. With operationId, returns that operation's status (poll until status is completed/failed/cancelled); without it, lists recent operations for the subgraph.", {
+    name: z7.string().describe("Subgraph name"),
+    operationId: z7.string().optional().describe("Operation id from reindex/backfill/stop; omit to list recent operations")
+  }, async ({ name, operationId }) => {
+    const result = operationId ? await clientProvider().subgraphs.getOperation(name, operationId) : await clientProvider().subgraphs.operations(name);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  });
   defineTool(server, "subgraphs_delete", "Delete a subgraph permanently.", { name: z7.string().describe("Subgraph name") }, async ({ name }) => {
     const result = await clientProvider().subgraphs.delete(name);
     return { content: [{ type: "text", text: result.message }] };
@@ -546,6 +622,7 @@ function registerSubgraphTools(server, clientProvider = getClient) {
 }
 
 // src/tools/subscriptions.ts
+import { CHAIN_TRIGGER_TYPES } from "@secondlayer/shared";
 import { z as z8 } from "zod/v4";
 function registerSubscriptionTools(server, clientProvider = getClient) {
   defineTool(server, "subscriptions_list", "List all subscriptions for the current account. Returns summary fields (no secrets).", {}, async () => {
@@ -560,10 +637,26 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
       content: [{ type: "text", text: JSON.stringify(detail, null, 2) }]
     };
   });
-  defineTool(server, "subscriptions_create", "Create a subscription. Returns `signingSecret` ONCE — forward it to the user so they can wire it into their receiver.", {
+  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: z8.string().describe("Human-readable name, unique per account"),
-    subgraphName: z8.string().describe("Subgraph to subscribe to"),
-    tableName: z8.string().describe("Table within the subgraph"),
+    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. Forward-looking: starts at chain tip, no backfill."),
     url: z8.string().describe("Webhook URL"),
     format: z8.enum([
       "standard-webhooks",
@@ -769,5 +862,5 @@ httpServer.listen(port, () => {
     console.error("Warning: SECONDLAYER_MCP_SECRET not set, authentication disabled");
 });
 
-//# debugId=D41ACEAFF3E3A4CC64756E2164756E21
+//# debugId=587F4DDF9A78B13764756E2164756E21
 //# sourceMappingURL=bin-http.js.map