@secondlayer/mcp 3.7.0 → 3.9.0

package/README.md

@@ -10,7 +10,7 @@ bun add @secondlayer/mcp
 
 ## Auth
 
-Most reads are public — subgraph reads, `datasets_*`, `index_*`, and `contracts_find` work with no key. **`streams_*` requires an `SL_API_KEY`** (and the Index tools reject free-tier keys — Build+ for keyed access). Writes (deploy, reindex, delete, subscriptions) and account tools need a key: create one (prefixed `sk-sl_`) in the platform console at https://secondlayer.tools/platform/api-keys and set it as `SL_API_KEY`. Read `secondlayer://context` first — it reports auth state and read-auth tiers.
+Most reads are public — `datasets_*`, `index_*`, and `contracts_find` work with no key. Subgraph tools need an `SL_API_KEY`; separately, **public** subgraphs are anon-readable over HTTP at `GET /v1/subgraphs/<name>/<table>` (`{ rows, next_cursor, tip }` cursor envelope), while private ones need the owning account's key (anon → 404). **`streams_*` requires an `SL_API_KEY`** (and the Index tools reject free-tier keys — Build+ for keyed access). Writes (deploy, publish/unpublish, reindex, delete, subscriptions) and account tools need a key: create one (prefixed `sk-sl_`) in the platform console at https://secondlayer.tools/platform/api-keys and set it as `SL_API_KEY`. Read `secondlayer://context` first — it reports auth state and read-auth tiers.
 
 ## Quick Start — Stdio (IDE)
 
@@ -52,7 +52,7 @@ bunx -p @secondlayer/mcp secondlayer-mcp-http
 
 | Domain | Tools |
 | --- | --- |
-| **Subgraphs** (11) | `subgraphs_list`, `subgraphs_get`, `subgraphs_spec`, `subgraphs_query`, `subgraphs_aggregate`, `subgraphs_reindex`, `subgraphs_operation`, `subgraphs_delete`, `subgraphs_deploy`, `subgraphs_read_source`, `subgraphs_codegen` |
+| **Subgraphs** (16) | `subgraphs_list`, `subgraphs_get`, `subgraphs_spec`, `subgraphs_query`, `subgraphs_aggregate`, `subgraphs_reindex`, `subgraphs_operation`, `subgraphs_backfill`, `subgraphs_stop`, `subgraphs_gaps`, `subgraphs_delete`, `subgraphs_deploy`, `subgraphs_publish`, `subgraphs_unpublish`, `subgraphs_read_source`, `subgraphs_codegen` |
 | **Subscriptions** (12) | `subscriptions_list`, `subscriptions_get`, `subscriptions_create`, `subscriptions_update`, `subscriptions_pause`, `subscriptions_resume`, `subscriptions_delete`, `subscriptions_rotate_secret`, `subscriptions_replay`, `subscriptions_recent_deliveries`, `subscriptions_dead`, `subscriptions_requeue_dead` |
 | **Datasets** (2) | `datasets_list`, `datasets_query` |
 | **Index** (4) | `index_ft_transfers`, `index_nft_transfers`, `index_events`, `index_contract_calls` |
@@ -75,6 +75,10 @@ a webhook on raw chain events (contract / event / function / trait) with no
 subgraph (e.g. `[{ "type": "contract_call", "contractId": "SP....amm",
 "functionName": "swap-*" }]`).
 
+### Subgraph visibility
+
+`subgraphs_deploy` takes a `visibility` param (`public` | `private`; defaults: managed → public, BYO `databaseUrl` → private). Flip later with `subgraphs_publish` / `subgraphs_unpublish` — publishing claims the name in the single global public namespace (409 `PUBLIC_NAME_TAKEN` if claimed). Public subgraphs are anon-readable at `GET /v1/subgraphs/<name>/<table>`.
+
 ### `subgraphs_query` enhancements
 
 - `fields` — comma-separated column projection (e.g. `"sender,amount_x"`)

package/dist/bin-http.js

@@ -61,11 +61,14 @@ async function apiRequest(method, path, body) {
 
 // src/lib/format.ts
 function formatSubgraphSummary(s) {
+  const apiUrl = process.env.SECONDLAYER_API_URL || "https://api.secondlayer.tools";
   return {
     name: s.name,
     status: s.status,
     tables: Array.isArray(s.tables) ? s.tables : Object.keys(s.tables),
-    lastProcessedBlock: s.lastProcessedBlock
+    lastProcessedBlock: s.lastProcessedBlock,
+    ...s.visibility ? { visibility: s.visibility } : {},
+    ...s.visibility === "public" ? { publicUrl: `${apiUrl}/v1/subgraphs/${s.name}` } : {}
   };
 }
 function withCap(items, cap) {
@@ -217,7 +220,7 @@ 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"
+  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"
 };
 async function buildContext(deps = { clientProvider: getClient }) {
   const unavailable = "unavailable: set SL_API_KEY";
@@ -371,6 +374,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.', {
@@ -380,6 +384,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
@@ -470,6 +515,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"),
@@ -534,25 +583,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)")
@@ -674,7 +730,7 @@ import {
 } from "@secondlayer/subgraphs";
 import { z as z8 } from "zod/v4";
 function registerSubgraphTools(server, clientProvider = getClient) {
-  defineTool(server, "subgraphs_list", "List all deployed subgraphs. Returns summary fields only.", {}, async () => {
+  defineTool(server, "subgraphs_list", "List all deployed subgraphs. Returns summary fields only, including visibility — public subgraphs are anon-readable at /v1/subgraphs/<name>.", {}, async () => {
     const { data } = await clientProvider().subgraphs.list();
     return {
       content: [
@@ -707,7 +763,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. 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>"}.', {
+  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>"}. 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: 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..."})'),
@@ -823,12 +879,13 @@ function registerSubgraphTools(server, clientProvider = getClient) {
     const result = await clientProvider().subgraphs.delete(name);
     return { content: [{ type: "text", text: 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. Set databaseUrl to deploy to your own Postgres (BYO data plane) — the server verifies the connection first; with dryRun it returns the DDL + grant script. A breaking BYO schema change is refused and returns a migration plan (drop + rebuild DDL) instead of deploying. 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. Set dryRun to validate and preview the schema/DDL without writing anything. Set databaseUrl to deploy to your own Postgres (BYO data plane) — the server verifies the connection first; with dryRun it returns the DDL + grant script. A breaking BYO schema change is refused and returns a migration plan (drop + rebuild DDL) instead of deploying. Visibility defaults: managed deploys are public (anon-readable at /v1/subgraphs/<name>, name claimed in the global public namespace), BYO deploys are private. Call `subgraphs_reindex` separately if you need a forced reindex.", {
     code: z8.string().describe("TypeScript source code containing a defineSubgraph() call"),
     startBlock: z8.number().int().nonnegative().optional().describe("Override the definition startBlock for this deploy"),
     databaseUrl: z8.string().optional().describe("BYO data plane: Postgres connection string to host the subgraph's schema and rows in your own database"),
-    dryRun: z8.boolean().optional().describe("Validate and preview the deploy (schema/DDL, BYO connection) without writing changes")
-  }, async ({ code, startBlock, databaseUrl, dryRun }) => {
+    dryRun: z8.boolean().optional().describe("Validate and preview the deploy (schema/DDL, BYO connection) without writing changes"),
+    visibility: z8.enum(["public", "private"]).optional().describe("Read visibility: public = anon /v1 reads + global name claim; private = owning account's key only. Defaults: managed → public, BYO → private.")
+  }, async ({ code, startBlock, databaseUrl, dryRun, visibility }) => {
     const bundled = await bundleSubgraphCode(code);
     try {
       const result = await clientProvider().subgraphs.deploy({
@@ -841,7 +898,8 @@ function registerSubgraphTools(server, clientProvider = getClient) {
         sourceCode: code,
         ...startBlock !== undefined ? { startBlock } : {},
         ...databaseUrl !== undefined ? { databaseUrl } : {},
-        ...dryRun !== undefined ? { dryRun } : {}
+        ...dryRun !== undefined ? { dryRun } : {},
+        ...visibility !== undefined ? { visibility } : {}
       });
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -860,6 +918,18 @@ function registerSubgraphTools(server, clientProvider = getClient) {
       throw err;
     }
   });
+  defineTool(server, "subgraphs_publish", "Make a subgraph publicly readable at /v1/subgraphs/<name> — anyone (or any agent) can read it without a key. Claims the name in the global public namespace; fails with PUBLIC_NAME_TAKEN if another account holds it.", { name: z8.string().describe("Subgraph name") }, async ({ name }) => {
+    const result = await clientProvider().subgraphs.publish(name);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  });
+  defineTool(server, "subgraphs_unpublish", "Make a subgraph private again — /v1 reads then require the owning account's bearer key, and the global public name claim is released.", { name: z8.string().describe("Subgraph name") }, async ({ name }) => {
+    const result = await clientProvider().subgraphs.unpublish(name);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  });
   defineTool(server, "subgraphs_read_source", "Fetch the deployed TypeScript source of a subgraph (plus its stored version). Returns a readOnly payload for subgraphs deployed before source capture — in that case the caller should redeploy via CLI before editing.", { name: z8.string().describe("Subgraph name") }, async ({ name }) => {
     const source = await clientProvider().subgraphs.getSource(name);
     return {
@@ -1150,5 +1220,5 @@ httpServer.listen(port, () => {
     console.error("Warning: SECONDLAYER_MCP_SECRET not set, authentication disabled");
 });
 
-//# debugId=330454369B037F3564756E2164756E21
+//# debugId=38C3E42509C42A3264756E2164756E21
 //# sourceMappingURL=bin-http.js.map