@secondlayer/mcp 3.6.0 → 3.8.0

package/dist/index.js

@@ -5,6 +5,8 @@ import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/resources.ts
+import { CHAIN_TRIGGER_FIELDS, DECODED_EVENT_TYPES } from "@secondlayer/shared";
+import { TRAIT_STANDARDS } from "@secondlayer/stacks/clarity";
 import { TYPE_MAP } from "@secondlayer/subgraphs/schema";
 
 // src/lib/client.ts
@@ -17,10 +19,12 @@ function getClient() {
   if (!instance) {
     const apiKey = readApiKey();
     const baseUrl = process.env.SECONDLAYER_API_URL;
+    const dumpsBaseUrl = process.env.SL_STREAMS_DUMPS_URL;
     instance = new SecondLayer({
       ...apiKey ? { apiKey } : {},
       origin: "mcp",
-      ...baseUrl ? { baseUrl } : {}
+      ...baseUrl ? { baseUrl } : {},
+      ...dumpsBaseUrl ? { dumpsBaseUrl } : {}
     });
   }
   return instance;
@@ -99,6 +103,11 @@ function defineTool(server, name, description, schema, handler) {
 }
 
 // src/resources.ts
+var TRAIT_BLURBS = {
+  "sip-009": "Non-fungible token (NFT) standard",
+  "sip-010": "Fungible token standard",
+  "sip-013": "Semi-fungible token standard"
+};
 var FILTERS_REFERENCE = [
   {
     type: "stx_transfer",
@@ -193,7 +202,7 @@ function buildCapabilities() {
   });
   return {
     products,
-    discoverFirst: "Call datasets_list / contracts_find to learn what exists before querying."
+    discoverFirst: "Call datasets_list / index_discover / contracts_find to learn what exists (and which filters each surface accepts) before querying."
   };
 }
 var READ_AUTH_TIERS = {
@@ -252,6 +261,56 @@ function registerResources(server) {
       }
     ]
   }));
+  server.resource("traits", "secondlayer://traits", {
+    description: "SIP trait standards the platform can classify and scaffold against — the valid values for contracts_find `trait` and subgraph scaffold `--trait`."
+  }, async () => ({
+    contents: [
+      {
+        uri: "secondlayer://traits",
+        mimeType: "application/json",
+        text: JSON.stringify({
+          traits: TRAIT_STANDARDS.map((id) => ({
+            id,
+            description: TRAIT_BLURBS[id]
+          }))
+        }, null, 2)
+      }
+    ]
+  }));
+  server.resource("streams-filters", "secondlayer://streams-filters", {
+    description: "Streams firehose vocabulary — the decoded event types and the filter fields accepted by streams_events / streams_consume."
+  }, async () => ({
+    contents: [
+      {
+        uri: "secondlayer://streams-filters",
+        mimeType: "application/json",
+        text: JSON.stringify({
+          eventTypes: [...DECODED_EVENT_TYPES],
+          filters: {
+            types: "include only these event types (array)",
+            notTypes: "exclude these event types (array)",
+            contractId: "match a contract id",
+            sender: "match the sender principal",
+            recipient: "match the recipient principal",
+            assetIdentifier: "match the asset identifier (contract::asset)",
+            fromHeight: "start block height (inclusive)",
+            toHeight: "end block height (inclusive)"
+          }
+        }, null, 2)
+      }
+    ]
+  }));
+  server.resource("chain-triggers", "secondlayer://chain-triggers", {
+    description: "Chain-subscription trigger types and the filter fields each accepts (for subscriptions_create triggers)."
+  }, async () => ({
+    contents: [
+      {
+        uri: "secondlayer://chain-triggers",
+        mimeType: "application/json",
+        text: JSON.stringify(CHAIN_TRIGGER_FIELDS, null, 2)
+      }
+    ]
+  }));
 }
 
 // src/tools/account.ts
@@ -276,7 +335,7 @@ function registerAccountTools(server) {
     const result = await apiRequest("PATCH", "/api/accounts/me", body);
     return jsonResponse(result);
   });
-  defineTool(server, "account_billing", "Show the account's plan and subscription/billing status. Requires an API key.", {}, async () => {
+  defineTool(server, "account_billing", "Show the account's plan and subscription/billing status. Requires an API key. (Plan upgrade / Stripe portal / checkout are deliberately not agent tools — they are session-only human-payment flows; use account_set_caps to bound spend.)", {}, async () => {
     const result = await apiRequest("GET", "/api/billing/status");
     return jsonResponse(result);
   });
@@ -304,6 +363,7 @@ function registerAccountTools(server) {
 }
 
 // src/tools/contracts.ts
+import { generateContractInterface } from "@secondlayer/scaffold";
 import { z as z2 } from "zod/v4";
 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.', {
@@ -313,6 +373,47 @@ function registerContractTools(server, clientProvider = getClient) {
     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")
   }, async (params) => jsonResponse(await clientProvider().contracts.list(params)));
+  defineTool(server, "get_contract_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. Feed the ABI into scaffold_from_abi or generate a typed client.", {
+    contractId: z2.string().describe("Fully qualified contract id (e.g. SP….amm-pool-v2-01)")
+  }, async ({ contractId }) => {
+    const contract = await clientProvider().contracts.get(contractId, {
+      includeAbi: true
+    });
+    return contract ? jsonResponse(contract) : jsonResponse({
+      error: {
+        type: "not_found",
+        status: 404,
+        message: `Contract not in registry: ${contractId}`
+      }
+    }, true);
+  });
+  defineTool(server, "generate_contract_interface", "Generate a typed TypeScript contract-client interface (typed methods + map/var/constant readers) from a deployed contract's ABI (fetched from the registry). Returns not_found if the contract isn't in the registry.", {
+    contractId: z2.string().describe("Fully qualified contract id (e.g. SP….amm-pool-v2-01)")
+  }, async ({ contractId }) => {
+    const c = await clientProvider().contracts.get(contractId, {
+      includeAbi: true
+    });
+    if (!c || !c.abi) {
+      return jsonResponse({
+        error: {
+          type: "not_found",
+          status: 404,
+          message: `Contract not in registry: ${contractId}`
+        }
+      }, true);
+    }
+    const [address, contractName] = contractId.split(".");
+    const name = (contractName ?? contractId).replace(/[^a-zA-Z0-9]/g, "_");
+    const code = generateContractInterface([
+      {
+        name,
+        address,
+        contractName: contractName ?? "",
+        abi: c.abi
+      }
+    ]);
+    return { content: [{ type: "text", text: code }] };
+  });
 }
 
 // src/tools/datasets.ts
@@ -339,13 +440,13 @@ function registerDatasetTools(server, clientProvider = getClient) {
 }
 
 // src/tools/index.ts
-import { DECODED_EVENT_TYPES } from "@secondlayer/shared";
+import { DECODED_EVENT_TYPES as DECODED_EVENT_TYPES2 } from "@secondlayer/shared";
 import {
-  generateIndexSchema,
-  INDEX_CODEGEN_TABLES
+  INDEX_CODEGEN_TABLES,
+  generateIndexSchema
 } from "@secondlayer/subgraphs";
 import { z as z4 } from "zod/v4";
-var INDEX_EVENT_TYPES = DECODED_EVENT_TYPES;
+var INDEX_EVENT_TYPES = DECODED_EVENT_TYPES2;
 var rangeFilters = {
   contractId: z4.string().optional().describe("Filter by contract id"),
   fromHeight: z4.number().optional().describe("Start block height (inclusive)"),
@@ -372,17 +473,19 @@ function registerIndexTools(server, clientProvider = getClient) {
     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). For ft/nft transfers prefer index_ft_transfers / index_nft_transfers.", {
+  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: z4.enum(INDEX_EVENT_TYPES).describe("Required. Decoded event type to list."),
     ...rangeFilters,
     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")
+    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.")
   }, 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). Note: contract-call cursors are a SEPARATE keyspace from event cursors — they are not interchangeable.", {
+  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: z4.string().optional().describe("Filter by called function name"),
-    sender: z4.string().optional().describe("Filter by caller principal")
+    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_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)));
@@ -401,6 +504,10 @@ function registerIndexTools(server, clientProvider = getClient) {
     const tx = await clientProvider().index.transactions.get(txId);
     return tx ? jsonResponse(tx) : notFound(`No transaction for ${txId}`);
   });
+  defineTool(server, "index_transaction_proof", "Fetch a transaction's inclusion proof (raw tx + signed Nakamoto block header + merkle path) so it can be verified trustlessly client-side with the SDK's verifyTransactionProof. Returns not_found if the tx/block is unknown; a 503 means the proof can't be assembled on this deployment right now (PROOF_TX_SET_INCOMPLETE, or PROOF_NODE_UNAVAILABLE when the stacks-node header source isn't configured).", { txId: z4.string().describe("Transaction id (0x… hash)") }, async ({ txId }) => {
+    const proof = await clientProvider().index.transactions.getProof(txId);
+    return proof ? jsonResponse(proof) : notFound(`No proof available 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"),
@@ -418,6 +525,7 @@ function registerIndexTools(server, clientProvider = getClient) {
     const tx = await clientProvider().index.mempool.get(txId);
     return tx ? jsonResponse(tx) : notFound(`No pending tx for ${txId}`);
   });
+  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, "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()));
   defineTool(server, "index_codegen", `Generate a typed schema (Prisma, Kysely, Drizzle, or JSON-Schema) for the public Index domain tables so they can be mirrored into a BYO database with full types. Returns the schema as text. Tables: ${INDEX_CODEGEN_TABLES.join(", ")}.`, {
     target: z4.enum(["prisma", "kysely", "drizzle", "json-schema"]).optional().describe("Output target (default kysely)"),
@@ -464,25 +572,32 @@ function registerProjectTools(server, clientProvider = getClient) {
 }
 
 // src/tools/scaffold.ts
-import { generateSubgraphCode } from "@secondlayer/scaffold";
+import {
+  generateSubgraphCode,
+  generateTraitSubgraph
+} from "@secondlayer/scaffold";
+import { TRAIT_STANDARDS as TRAIT_STANDARDS2 } from "@secondlayer/stacks/clarity";
 import { z as z6 } from "zod/v4";
-var API_BASE = process.env.SECONDLAYER_API_URL || "https://api.secondlayer.tools";
 async function fetchAbi(contractId) {
-  const res = await fetch(`${API_BASE}/api/node/contracts/${contractId}/abi`, {
-    signal: AbortSignal.timeout(1e4)
+  const contract = await getClient().contracts.get(contractId, {
+    includeAbi: true
   });
-  if (!res.ok) {
-    if (res.status === 404)
-      throw new Error(`Contract not found: ${contractId}`);
-    throw new Error(`Failed to fetch ABI: HTTP ${res.status}`);
+  if (!contract)
+    throw new Error(`Contract not found: ${contractId}`);
+  const abi = contract.abi;
+  if (!abi) {
+    throw new Error(`No ABI available for ${contractId} (abi_status: ${contract.abi_status})`);
   }
-  const abi = await res.json();
-  return {
-    functions: abi.functions ?? [],
-    maps: abi.maps ?? []
-  };
+  return { functions: abi.functions ?? [], maps: abi.maps ?? [] };
 }
 function registerScaffoldTools(server) {
+  defineTool(server, "scaffold_from_trait", "Generate a deploy-ready subgraph scaffold that indexes EVERY contract conforming to a SIP trait (no specific contract needed) — sip-009 → an nft_transfer source, sip-010/sip-013 → ft_transfer. Use scaffold_from_contract/abi instead when targeting one contract. See the secondlayer://traits resource for valid trait ids.", {
+    trait: z6.enum(TRAIT_STANDARDS2).describe("SIP standard to index (sip-009 | sip-010 | sip-013)"),
+    subgraphName: z6.string().optional().describe("Override the subgraph name (defaults to <trait>-transfers)")
+  }, async ({ trait, subgraphName }) => {
+    const code = generateTraitSubgraph({ trait, name: subgraphName });
+    return { content: [{ type: "text", text: code }] };
+  });
   defineTool(server, "scaffold_from_contract", "Generate a subgraph scaffold from a deployed Stacks contract. Fetches the ABI automatically.", {
     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)")
@@ -512,9 +627,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 { DECODED_EVENT_TYPES as DECODED_EVENT_TYPES3 } from "@secondlayer/shared";
 import { z as z7 } from "zod/v4";
-var STREAMS_EVENT_TYPES = DECODED_EVENT_TYPES2;
+var STREAMS_EVENT_TYPES = DECODED_EVENT_TYPES3;
 async function withStreamsAuthHint(fn) {
   try {
     return await fn();
@@ -591,6 +706,7 @@ function registerStreamsTools(server, clientProvider = getClient) {
   }, 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: z7.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())));
+  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).", {}, async () => jsonResponse(await clientProvider().streams.dumps.list()));
 }
 
 // src/tools/subgraphs.ts
@@ -636,7 +752,7 @@ function registerSubgraphTools(server, clientProvider = getClient) {
       ]
     };
   });
-  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.', {
+  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. Fetch one row by id with {"_id": "<id>"}.', {
     name: z8.string().describe("Subgraph name"),
     table: z8.string().describe("Table name"),
     filters: z8.record(z8.string(), z8.string()).optional().describe('Column filters — plain values or with operators (e.g. {"amount.gte": "1000", "sender": "SP..."})'),
@@ -861,7 +977,7 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
       trait: z9.string().optional(),
       minAmount: z9.union([z9.string(), z9.number()]).optional(),
       maxAmount: z9.union([z9.string(), z9.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."),
+    })).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: z9.string().describe("Webhook URL"),
     format: z9.enum([
       "standard-webhooks",
@@ -872,17 +988,20 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
       "raw"
     ]).optional().describe("Wire format (default standard-webhooks)"),
     runtime: z9.enum(["inngest", "trigger", "cloudflare", "node"]).optional().describe("Receiver runtime label (display only)"),
-    filter: z9.record(z9.string(), z9.unknown()).optional().describe('Scalar filter DSL, e.g. {"amount": {"gte": 100}, "sender": "SP..."}')
+    filter: z9.record(z9.string(), z9.unknown()).optional().describe('Scalar filter DSL, e.g. {"amount": {"gte": 100}, "sender": "SP..."}'),
+    authConfig: z9.record(z9.string(), z9.unknown()).optional().describe('Receiver auth sent with each delivery, e.g. {"type": "bearer", "token": "..."}')
   }, async (input) => {
     const res = await clientProvider().subscriptions.create(input);
     return {
       content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
     };
   });
-  defineTool(server, "subscriptions_update", "Patch a subscription (url, filter, format, runtime, retry, timeout, concurrency).", {
+  defineTool(server, "subscriptions_update", "Patch a subscription (name, url, filter, authConfig, format, runtime, retry, timeout, concurrency).", {
     id: z9.string(),
+    name: z9.string().optional().describe("Rename the subscription"),
     url: z9.string().optional(),
     filter: z9.record(z9.string(), z9.unknown()).optional(),
+    authConfig: z9.record(z9.string(), z9.unknown()).optional().describe("Receiver auth sent with each delivery (bearer/etc.)"),
     format: z9.enum([
       "standard-webhooks",
       "inngest",
@@ -931,14 +1050,16 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
       content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
     };
   });
-  defineTool(server, "subscriptions_replay", "Replay a block range for a subscription. Replays run at 10% of batch capacity — use sparingly.", {
+  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: z9.string(),
     fromBlock: z9.number().int().nonnegative(),
-    toBlock: z9.number().int().nonnegative()
-  }, async ({ id, fromBlock, toBlock }) => {
+    toBlock: z9.number().int().nonnegative(),
+    force: z9.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,
-      toBlock
+      toBlock,
+      ...force !== undefined ? { force } : {}
     });
     return {
       content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
@@ -991,5 +1112,5 @@ export {
   createServer
 };
 
-//# debugId=ADEBB38A46A46AF464756E2164756E21
+//# debugId=EDBF6A8CAB6C22E864756E2164756E21
 //# sourceMappingURL=index.js.map