@secondlayer/mcp 3.6.0 → 3.7.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);
   });
@@ -339,13 +398,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 +431,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)));
@@ -418,6 +479,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)"),
@@ -512,9 +574,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 +653,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 +699,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 +924,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 +935,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 +997,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 +1059,5 @@ export {
   createServer
 };
 
-//# debugId=ADEBB38A46A46AF464756E2164756E21
+//# debugId=B30584194FF8002264756E2164756E21
 //# sourceMappingURL=index.js.map