@secondlayer/mcp 7.3.0 → 7.4.1

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/server.ts
 import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -15,16 +15,23 @@ function isHostedArchiveUrl(url) {
 }
 
 // src/resources.ts
+import {
+  ResourceTemplate
+} from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CHAIN_TRIGGER_FIELDS } from "@secondlayer/shared";
 import { BOOTSTRAP_STEP } from "@secondlayer/shared/archive/instance-diagnosis";
 import { TRAIT_STANDARDS } from "@secondlayer/stacks/clarity";
-import { filterFieldsByType } from "@secondlayer/subgraphs";
+import { camelizeKeys, filterFieldsByType } from "@secondlayer/subgraphs";
 import { TYPE_MAP } from "@secondlayer/subgraphs/schema";
 
 // src/lib/client.ts
-import { SecondLayer, resolveApiKey } from "@secondlayer/sdk";
+import {
+  SecondLayer,
+  resolveAccountKey,
+  resolveApiKey
+} from "@secondlayer/sdk";
 var instance = null;
-var HOSTED_KEY_HINT = "set SL_ARCHIVE_API_KEY (sk-sl_*) for credits; INSTANCE_TOKEN is the instance";
+var HOSTED_KEY_HINT = "set SECONDLAYER_API_KEY (sk-sl_*) for credits; INSTANCE_TOKEN is the instance";
 var DEFAULT_ARCHIVE_OPS_URL = "https://api.secondlayer.tools";
 function readApiKey() {
   return resolveApiKey();
@@ -44,25 +51,30 @@ function getClient() {
   return instance;
 }
 function readArchiveApiKey() {
-  const key = process.env.SL_ARCHIVE_API_KEY;
-  return key && key.length > 0 ? key : undefined;
+  return resolveAccountKey();
 }
 function getArchiveOpsClient() {
-  const apiKey = readArchiveApiKey();
-  if (!apiKey) {
+  const accountKey = readArchiveApiKey();
+  if (!accountKey) {
     throw new Error(HOSTED_KEY_HINT);
   }
   const archiveOpsUrl = process.env.SL_CREDITS_API_URL || process.env.ARCHIVE_OPS_API_URL || DEFAULT_ARCHIVE_OPS_URL;
   return new SecondLayer({
-    apiKey,
+    accountKey,
     origin: "mcp",
     archiveOpsUrl
   });
 }
-var keyHint = " — set INSTANCE_TOKEN from `sl init` for writes (SL_API_KEY is a legacy alias)";
+var keyHint = " — set INSTANCE_TOKEN from `sl init` for writes";
 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";
+  let host = "";
+  try {
+    host = new URL(baseUrl).hostname;
+  } catch {
+    host = "";
+  }
+  const apiKey = host === "api.secondlayer.tools" ? resolveAccountKey() : readApiKey();
   const res = await fetch(`${baseUrl}${path}`, {
     method,
     headers: {
@@ -305,6 +317,73 @@ function registerResources(server) {
       }
     ]
   }));
+  server.resource("samples", new ResourceTemplate("secondlayer://samples/{contractId}", {
+    list: undefined
+  }), {
+    description: "Decoded camelCase print samples for a contract (schema + up to 5 events). Use before writing a print_event handler."
+  }, async (uri, variables) => {
+    const contractId = String(Array.isArray(variables.contractId) ? variables.contractId[0] : variables.contractId ?? "");
+    const body = await buildSamplesResource(contractId);
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(body, null, 2)
+        }
+      ]
+    };
+  });
+}
+function jsonSafe(value) {
+  if (typeof value === "bigint")
+    return value.toString();
+  if (value === null || value === undefined)
+    return value;
+  if (Array.isArray(value))
+    return value.map(jsonSafe);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = jsonSafe(v);
+    }
+    return out;
+  }
+  return value;
+}
+async function buildSamplesResource(contractId, clientProvider = getClient) {
+  const client = clientProvider();
+  const printSchema = await client.index.printSchema(contractId);
+  const envelope = await client.index.events.list({
+    eventType: "print",
+    contractId,
+    limit: 5
+  });
+  const schema = printSchema?.topics.map((t) => ({
+    topic: t.topic,
+    fields: t.fields.map((f) => ({
+      camel: f.camel_name,
+      snake: f.name.replace(/-/g, "_"),
+      column_type: f.column_type,
+      always: f.always_present
+    }))
+  })) ?? [];
+  const samples = (envelope.events ?? []).slice(0, 5).map((ev) => {
+    const payload = ev.payload;
+    const data = jsonSafe(camelizeKeys(payload?.value));
+    return {
+      txId: ev.tx_id,
+      height: ev.block_height,
+      topic: payload?.topic ?? "",
+      data: data ?? {}
+    };
+  });
+  return {
+    contractId,
+    handlerShape: "event.data is camelCase; columns are snake_case",
+    schema,
+    samples
+  };
 }
 
 // src/tools/account.ts
@@ -334,14 +413,14 @@ function registerArchiveTools(server, clientProvider = getClient, archiveOpsClie
     toBlock,
     target
   })));
-  defineTool(server, "archive_latest", "Signed pointer to the official archive tree (hosted). Needs SL_ARCHIVE_API_KEY (sk-sl_*), not INSTANCE_TOKEN. Use the returned origin as --against for archive_bootstrap. Do not download parquet.", {
+  defineTool(server, "archive_latest", "Signed pointer to the official archive tree (hosted). Needs SECONDLAYER_API_KEY (sk-sl_*), not INSTANCE_TOKEN. Use the returned origin as --against for archive_bootstrap. Do not download parquet.", {
     against: z2.string().optional().describe("Override latest.json URL (default official tree)")
   }, async ({ against }) => jsonResponse(await archiveOpsClientProvider().archive.latest(against)));
-  defineTool(server, "archive_quote", "Price a hosted archive fetch (metered). Needs SL_ARCHIVE_API_KEY (sk-sl_*), not INSTANCE_TOKEN. Quote happens here; bootstrap/repair also quote inside the CLI. Do not download parquet.", {
+  defineTool(server, "archive_quote", "Price a hosted archive fetch (metered). Needs SECONDLAYER_API_KEY (sk-sl_*), not INSTANCE_TOKEN. Quote happens here; bootstrap/repair also quote inside the CLI. Do not download parquet.", {
     paths: z2.array(z2.string()).describe("Partition paths to price"),
     flow: z2.enum(FLOW).describe("bootstrap or repair")
   }, async ({ paths, flow }) => jsonResponse(await archiveOpsClientProvider().archive.quote({ paths, flow })));
-  defineTool(server, "credits_balance", "Archive credits balance at api.secondlayer.tools. Needs SL_ARCHIVE_API_KEY (sk-sl_*); INSTANCE_TOKEN is the instance.", {}, async () => jsonResponse(await archiveOpsClientProvider().archive.credits.balance()));
+  defineTool(server, "credits_balance", "Archive credits balance at api.secondlayer.tools. Needs SECONDLAYER_API_KEY (sk-sl_*); INSTANCE_TOKEN is the instance.", {}, async () => jsonResponse(await archiveOpsClientProvider().archive.credits.balance()));
 }
 
 // src/tools/codegen.ts
@@ -463,7 +542,11 @@ function registerInstanceTools(server, clientProvider = getClient) {
 }
 
 // src/tools/scaffold.ts
-import { generateSubgraphCode } from "@secondlayer/scaffold";
+import {
+  generatePrintSchemaSubgraph,
+  generateSubgraphCode,
+  generateTokenSubgraphFromAbi
+} from "@secondlayer/scaffold";
 import { z as z6 } from "zod";
 async function fetchAbi(clientProvider, contractId) {
   const contract = await clientProvider().contracts.get(contractId, {
@@ -475,14 +558,32 @@ async function fetchAbi(clientProvider, contractId) {
   if (!abi) {
     throw new Error(`No ABI available for ${contractId} (abi_status: ${contract.abi_status})`);
   }
-  return { functions: abi.functions ?? [] };
+  return { functions: abi.functions ?? [], abi };
 }
 function registerScaffoldTools(server, clientProvider = getClient) {
-  defineTool(server, "subgraphs_scaffold", "Generate a subgraph scaffold from a deployed Stacks contract. Fetches the ABI automatically. Returns TypeScript source — review it, then pass it to subgraphs_deploy.", {
+  defineTool(server, "subgraphs_scaffold", "Generate a subgraph from observed print events when available; ABI token transfers or public functions only when the contract has never printed. Review the TypeScript, run subgraphs_test until ok: true with written >= 1, read skipped, then subgraphs_deploy. dryRun is DDL only.", {
     contractId: z6.string().describe("Fully qualified contract ID (e.g. SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01)"),
     subgraphName: z6.string().optional().describe("Override the subgraph name (defaults to contract name)")
   }, async ({ contractId, subgraphName }) => {
-    const { functions } = await fetchAbi(clientProvider, contractId);
+    const printSchema = await clientProvider().index.printSchema(contractId);
+    if (printSchema && printSchema.topics.length > 0) {
+      const code2 = generatePrintSchemaSubgraph({
+        contractId,
+        name: subgraphName,
+        topics: printSchema.topics,
+        sample: printSchema.sample
+      });
+      return { content: [{ type: "text", text: code2 }] };
+    }
+    const { functions, abi } = await fetchAbi(clientProvider, contractId);
+    const token = generateTokenSubgraphFromAbi({
+      contractId,
+      abi,
+      name: subgraphName
+    });
+    if (token) {
+      return { content: [{ type: "text", text: token }] };
+    }
     const code = generateSubgraphCode(contractId, functions, subgraphName);
     return { content: [{ type: "text", text: code }] };
   });
@@ -735,14 +836,42 @@ function registerStreamsTools(server, clientProvider = getClient) {
 }
 
 // src/tools/subgraphs.ts
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 import { bundleSubgraphCode } from "@secondlayer/bundler";
+import { DECODED_EVENT_TYPES as DECODED_EVENT_TYPES2 } from "@secondlayer/shared";
+import {
+  runSubgraphTest
+} from "@secondlayer/subgraphs/testing";
 import { z as z9 } from "zod";
+function eventTypeFor(filter) {
+  if (filter.type === "contract_deploy")
+    return null;
+  const candidate = filter.type === "print_event" ? "print" : filter.type;
+  return DECODED_EVENT_TYPES2.includes(candidate) ? candidate : null;
+}
+function skipReason(name, filter) {
+  return filter.type === "contract_deploy" ? `source "${name}" (contract_deploy) has no Index list endpoint — skipped.` : `source "${name}" (${filter.type}) is not readable from Index — skipped.`;
+}
+async function loadBundledDefinition(handlerCode) {
+  const dir = await mkdtemp(join(tmpdir(), "sl-mcp-sg-test-"));
+  try {
+    const file = join(dir, `handler-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`);
+    await writeFile(file, handlerCode);
+    const mod = await import(pathToFileURL(file).href);
+    return mod.default ?? {};
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
 function registerSubgraphTools(server, clientProvider = getClient) {
   defineTool(server, "subgraphs_list", "List all deployed subgraphs. Returns summary fields only; read rows with subgraphs_query.", {}, async () => {
     const { data } = await clientProvider().subgraphs.list();
     return jsonResponse(data.map(formatSubgraphSummary));
   });
-  defineTool(server, "subgraphs_status", "Get full details of a subgraph including schema, health, and table columns.", { name: z9.string().describe("Subgraph name") }, async ({ name }) => {
+  defineTool(server, "subgraphs_status", "Get full details of a subgraph including schema, health (incl. health.emptyMapping when processed events wrote 0 rows), and table columns.", { name: z9.string().describe("Subgraph name") }, async ({ name }) => {
     const detail = await clientProvider().subgraphs.status(name);
     return jsonResponse(detail);
   });
@@ -838,10 +967,10 @@ function registerSubgraphTools(server, clientProvider = getClient) {
     const result = await clientProvider().subgraphs.delete(name);
     return textResponse(result.message);
   });
-  defineTool(server, "subgraphs_deploy", "Deploy a subgraph from TypeScript code. Pass the full defineSubgraph() source — it will be bundled, validated, and deployed. Optional startBlock overrides the source definition for this deploy. Set dryRun to validate and preview the schema/DDL without writing anything. Call `subgraphs_reindex` separately if you need a forced reindex.", {
+  defineTool(server, "subgraphs_deploy", "Deploy a subgraph from TypeScript code. Pass the full defineSubgraph() source — it will be bundled, validated, and deployed. Optional startBlock overrides the source definition for this deploy. dryRun validates schema/DDL only and does not run handlers — call subgraphs_test first and deploy only when it returns ok: true with written >= 1. Call subgraphs_reindex separately if you need a forced reindex.", {
     code: z9.string().describe("TypeScript source code containing a defineSubgraph() call"),
     startBlock: z9.number().int().nonnegative().optional().describe("Override the definition startBlock for this deploy"),
-    dryRun: z9.boolean().optional().describe("Validate and preview the deploy (schema/DDL) without writing changes")
+    dryRun: z9.boolean().optional().describe("Validate schema/DDL only — does not run handlers. Use subgraphs_test to prove a mapping writes rows.")
   }, async ({ code, startBlock, dryRun }) => {
     const bundled = await bundleSubgraphCode(code);
     const result = await clientProvider().subgraphs.deploy({
@@ -857,6 +986,87 @@ function registerSubgraphTools(server, clientProvider = getClient) {
     });
     return jsonResponse(result);
   });
+  defineTool(server, "subgraphs_test", "Prove a subgraph mapping writes rows against Index data before deploy. Pass full defineSubgraph() source plus a height range. Returns ok/written/tables; EMPTY_MAPPING means events matched but 0 rows were written — read hint for observed event.data keys and do not invent fields. subgraphs_deploy dryRun is DDL only; do not deploy until ok: true with written >= 1.", {
+    code: z9.string().describe("TypeScript source containing a defineSubgraph() call"),
+    fromHeight: z9.number().int().nonnegative().describe("Start block height (inclusive)"),
+    toHeight: z9.number().int().nonnegative().optional().describe("End block height (inclusive); default fromHeight+100"),
+    limit: z9.number().int().positive().max(200).optional().describe("Max Index rows per source (default 50, max 200)")
+  }, async ({ code, fromHeight, toHeight, limit }) => {
+    const bundled = await bundleSubgraphCode(code);
+    const def = await loadBundledDefinition(bundled.handlerCode);
+    if (!def.handlers || !def.schema) {
+      return jsonResponse({
+        ok: false,
+        code: "NO_SOURCES",
+        matched: 0,
+        written: 0,
+        tables: [],
+        hint: "Bundled module must default-export defineSubgraph() with handlers and schema."
+      }, true);
+    }
+    const sources = bundled.sources ?? {};
+    const to = toHeight ?? fromHeight + 100;
+    const pageLimit = Math.min(limit ?? 50, 200);
+    const index = clientProvider().index;
+    const events = {};
+    const skipped = [];
+    let sourcesTested = 0;
+    for (const [name, filter] of Object.entries(sources)) {
+      if (filter.type === "contract_call") {
+        sourcesTested++;
+        const envelope2 = await index.contractCalls.list({
+          ...filter.contractId ? {
+            contractId: Array.isArray(filter.contractId) ? filter.contractId : filter.contractId
+          } : {},
+          ...filter.functionName ? { functionName: filter.functionName } : {},
+          fromHeight,
+          toHeight: to,
+          limit: pageLimit
+        });
+        events[name] = envelope2.contract_calls;
+        continue;
+      }
+      const eventType = eventTypeFor(filter);
+      if (eventType === null) {
+        skipped.push({ source: name, reason: skipReason(name, filter) });
+        continue;
+      }
+      sourcesTested++;
+      const envelope = await index.events.list({
+        eventType,
+        ...filter.contractId ? {
+          contractId: Array.isArray(filter.contractId) ? filter.contractId : filter.contractId
+        } : {},
+        fromHeight,
+        toHeight: to,
+        limit: pageLimit
+      });
+      events[name] = envelope.events;
+    }
+    if (sourcesTested === 0) {
+      return jsonResponse({
+        ok: false,
+        code: "NO_SOURCES",
+        matched: 0,
+        written: 0,
+        tables: [],
+        hint: "No sources were tested — every source is unreadable from Index.",
+        skipped
+      }, true);
+    }
+    const result = await runSubgraphTest({
+      schema: def.schema,
+      handlers: def.handlers,
+      sources,
+      events
+    });
+    const body = { ...result, skipped };
+    if (skipped.length > 0) {
+      const skipHints = skipped.map((s) => s.reason).join(" ");
+      body.hint = result.hint ? `${result.hint} ${skipHints}` : skipHints;
+    }
+    return jsonResponse(body, !result.ok);
+  });
 }
 
 // src/tools/subscriptions.ts
@@ -963,7 +1173,7 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
 
 // src/server.ts
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync(join(__dirname2, "../package.json"), "utf-8"));
+var pkg = JSON.parse(readFileSync(join2(__dirname2, "../package.json"), "utf-8"));
 function createServer() {
   const server = new McpServer({
     name: "secondlayer",
@@ -990,5 +1200,5 @@ export {
   createServer
 };
 
-//# debugId=A7587A1A05F911B064756E2164756E21
+//# debugId=F1D65205F9CD817664756E2164756E21
 //# sourceMappingURL=index.js.map