@secondlayer/mcp 3.9.0 → 3.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin-http.js +231 -213
- package/dist/bin-http.js.map +8 -9
- package/dist/bin.js +231 -213
- package/dist/bin.js.map +8 -9
- package/dist/index.js +231 -213
- package/dist/index.js.map +8 -9
- package/package.json +4 -4
package/dist/bin.js
CHANGED
|
@@ -15,21 +15,49 @@ import { TRAIT_STANDARDS } from "@secondlayer/stacks/clarity";
|
|
|
15
15
|
import { TYPE_MAP } from "@secondlayer/subgraphs/schema";
|
|
16
16
|
|
|
17
17
|
// src/lib/client.ts
|
|
18
|
-
import { SecondLayer } from "@secondlayer/sdk";
|
|
18
|
+
import { SecondLayer, readX402Receipt, withX402 } from "@secondlayer/sdk";
|
|
19
|
+
import { privateKeyToAccount } from "@secondlayer/stacks/accounts";
|
|
19
20
|
var instance = null;
|
|
20
21
|
function readApiKey() {
|
|
21
22
|
return process.env.SL_API_KEY;
|
|
22
23
|
}
|
|
24
|
+
function buildFetchImpl() {
|
|
25
|
+
const key = process.env.X402_PRIVATE_KEY;
|
|
26
|
+
if (!key)
|
|
27
|
+
return;
|
|
28
|
+
const account = privateKeyToAccount(key);
|
|
29
|
+
const topUpUsd = Number(process.env.X402_TOPUP_USD ?? "");
|
|
30
|
+
const paid = withX402(fetch, {
|
|
31
|
+
account,
|
|
32
|
+
...Number.isFinite(topUpUsd) && topUpUsd > 0 ? {
|
|
33
|
+
topUp: {
|
|
34
|
+
usd: topUpUsd,
|
|
35
|
+
whenBelow: Number(process.env.X402_TOPUP_WHEN_BELOW ?? "0.5")
|
|
36
|
+
}
|
|
37
|
+
} : {}
|
|
38
|
+
});
|
|
39
|
+
const wrapped = async (input, init) => {
|
|
40
|
+
const res = await paid(input, init);
|
|
41
|
+
const receipt = readX402Receipt(res);
|
|
42
|
+
if (receipt) {
|
|
43
|
+
console.error(`[x402] paid call settled tier=${receipt.state ?? "confirmed"} txid=${receipt.txid}`);
|
|
44
|
+
}
|
|
45
|
+
return res;
|
|
46
|
+
};
|
|
47
|
+
return wrapped;
|
|
48
|
+
}
|
|
23
49
|
function getClient() {
|
|
24
50
|
if (!instance) {
|
|
25
51
|
const apiKey = readApiKey();
|
|
26
52
|
const baseUrl = process.env.SECONDLAYER_API_URL;
|
|
27
53
|
const dumpsBaseUrl = process.env.SL_STREAMS_DUMPS_URL;
|
|
54
|
+
const fetchImpl = buildFetchImpl();
|
|
28
55
|
instance = new SecondLayer({
|
|
29
56
|
...apiKey ? { apiKey } : {},
|
|
30
57
|
origin: "mcp",
|
|
31
58
|
...baseUrl ? { baseUrl } : {},
|
|
32
|
-
...dumpsBaseUrl ? { dumpsBaseUrl } : {}
|
|
59
|
+
...dumpsBaseUrl ? { dumpsBaseUrl } : {},
|
|
60
|
+
...fetchImpl ? { fetchImpl } : {}
|
|
33
61
|
});
|
|
34
62
|
}
|
|
35
63
|
return instance;
|
|
@@ -170,7 +198,6 @@ var COLUMN_TYPES = [
|
|
|
170
198
|
}
|
|
171
199
|
];
|
|
172
200
|
var PRODUCT_BLURBS = {
|
|
173
|
-
datasets: "public foundation datasets",
|
|
174
201
|
index: "decoded L2 events, contract calls, blocks, transactions, stacking, mempool",
|
|
175
202
|
streams: "raw canonical chain event firehose",
|
|
176
203
|
contracts: "trait-based contract discovery",
|
|
@@ -181,7 +208,6 @@ var PRODUCT_BLURBS = {
|
|
|
181
208
|
scaffold: "generate typed contract clients from a deployment or ABI"
|
|
182
209
|
};
|
|
183
210
|
var PRODUCT_ORDER = [
|
|
184
|
-
"datasets",
|
|
185
211
|
"index",
|
|
186
212
|
"streams",
|
|
187
213
|
"contracts",
|
|
@@ -210,11 +236,17 @@ function buildCapabilities() {
|
|
|
210
236
|
});
|
|
211
237
|
return {
|
|
212
238
|
products,
|
|
213
|
-
discoverFirst: "Call
|
|
239
|
+
discoverFirst: "Call index_discover / contracts_find to learn what exists (and which filters each surface accepts) before querying."
|
|
214
240
|
};
|
|
215
241
|
}
|
|
242
|
+
var X402_CAPABILITY = {
|
|
243
|
+
what: "Index and Streams reads (/v1/index/*, /v1/streams/*) accept x402 v2 pay-per-call (network stacks:1, sponsored transfers — the payer holds sBTC/STX/USDCx, never gas). Index grants 1,000 free reads/day/IP before any 402; a paid Streams call opens a 500-call/1h PAYMENT-SESSION.",
|
|
244
|
+
paidWrites: "POST /v1/subgraphs (x402 $2) deploys a subgraph owned by the paying wallet — live from deploy, 7-day TTL, renewable via POST /v1/subgraphs/{name}/renew ($0.50/wk); claiming the account clears the expiry.",
|
|
245
|
+
prepaid: "POST /v1/x402/deposit?usd=N loads a prepaid tab (PAYMENT-BALANCE token, $0.25 min) — calls debit it instantly, no per-call on-chain settle. GET /v1/x402/balance reads it.",
|
|
246
|
+
discovery: "GET /v1/x402/supported on the API host for scheme, assets, prices, quotas, sessions, and prepaid metadata.",
|
|
247
|
+
autopay: "Set X402_PRIVATE_KEY (a Stacks private key holding an accepted token) and this MCP server pays 402 challenges automatically (sessions replayed). Add X402_TOPUP_USD (and optionally X402_TOPUP_WHEN_BELOW) for an autonomous prepaid tab that refills itself. Receipts are logged per paid call."
|
|
248
|
+
};
|
|
216
249
|
var READ_AUTH_TIERS = {
|
|
217
|
-
datasets: "open — no API key required",
|
|
218
250
|
index: "anonymous reads allowed; free-tier API keys are rejected (Build+ required)",
|
|
219
251
|
streams: "API key required (SL_API_KEY) — keyless calls return 401",
|
|
220
252
|
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"
|
|
@@ -224,7 +256,10 @@ async function buildContext(deps = { clientProvider: getClient }) {
|
|
|
224
256
|
const orNull = (v) => v == null ? unavailable : v;
|
|
225
257
|
const snap = await deps.clientProvider().context().catch(() => null);
|
|
226
258
|
return {
|
|
227
|
-
authState: {
|
|
259
|
+
authState: {
|
|
260
|
+
apiKeySet: Boolean(process.env.SL_API_KEY),
|
|
261
|
+
x402WalletSet: Boolean(process.env.X402_PRIVATE_KEY)
|
|
262
|
+
},
|
|
228
263
|
whatExists: {
|
|
229
264
|
account: orNull(snap?.account),
|
|
230
265
|
streamsTip: orNull(snap?.streamsTip),
|
|
@@ -236,7 +271,8 @@ async function buildContext(deps = { clientProvider: getClient }) {
|
|
|
236
271
|
activeOperations: orNull(snap?.activeOperations)
|
|
237
272
|
},
|
|
238
273
|
whatYouCanDo: buildCapabilities(),
|
|
239
|
-
readAuthTiers: READ_AUTH_TIERS
|
|
274
|
+
readAuthTiers: READ_AUTH_TIERS,
|
|
275
|
+
payPerCall: X402_CAPABILITY
|
|
240
276
|
};
|
|
241
277
|
}
|
|
242
278
|
function registerResources(server) {
|
|
@@ -424,43 +460,20 @@ function registerContractTools(server, clientProvider = getClient) {
|
|
|
424
460
|
});
|
|
425
461
|
}
|
|
426
462
|
|
|
427
|
-
// src/tools/datasets.ts
|
|
428
|
-
import { z as z3 } from "zod/v4";
|
|
429
|
-
function registerDatasetTools(server, clientProvider = getClient) {
|
|
430
|
-
defineTool(server, "datasets_list", "List the Foundation Datasets catalog with freshness — the discovery endpoint for what dataset slugs exist and how current each is. Reads are public.", {}, async () => {
|
|
431
|
-
const catalog = await clientProvider().datasets.listDatasets();
|
|
432
|
-
return jsonResponse(catalog);
|
|
433
|
-
});
|
|
434
|
-
defineTool(server, "datasets_query", 'Query ANY Foundation Dataset by slug — every family returned by datasets_list is queryable, including bespoke ones (bns/resolve with {"fqn":"alice.btc"}, bns/names, bns/namespaces, network-health/summary) and any dataset added later. Accepts family ("sbtc-events") or path ("sbtc/events") slug forms. Filters are passed through as documented query params (e.g. {"sender": "SP...", "from_block": "150000"}). Returns { rows, next_cursor, tip }; single-record datasets like bns/resolve return 0-or-1 rows (empty = not found). Call datasets_list first to discover slugs and their filters.', {
|
|
435
|
-
slug: z3.string().describe("Dataset slug from datasets_list (e.g. stx-transfers)"),
|
|
436
|
-
filters: z3.record(z3.string(), z3.string()).optional().describe("Documented per-dataset query params (snake_case values)"),
|
|
437
|
-
limit: z3.number().optional().describe("Max rows for this page"),
|
|
438
|
-
cursor: z3.string().optional().describe("Opaque cursor from a prior response's next_cursor")
|
|
439
|
-
}, async ({ slug, filters, limit, cursor }) => {
|
|
440
|
-
const params = { ...filters ?? {} };
|
|
441
|
-
if (limit !== undefined)
|
|
442
|
-
params.limit = limit;
|
|
443
|
-
if (cursor !== undefined)
|
|
444
|
-
params.cursor = cursor;
|
|
445
|
-
const result = await clientProvider().datasets.get(slug, params);
|
|
446
|
-
return jsonResponse(result);
|
|
447
|
-
});
|
|
448
|
-
}
|
|
449
|
-
|
|
450
463
|
// src/tools/index.ts
|
|
451
464
|
import { DECODED_EVENT_TYPES as DECODED_EVENT_TYPES2 } from "@secondlayer/shared";
|
|
452
465
|
import {
|
|
453
466
|
INDEX_CODEGEN_TABLES,
|
|
454
467
|
generateIndexSchema
|
|
455
468
|
} from "@secondlayer/subgraphs";
|
|
456
|
-
import { z as
|
|
469
|
+
import { z as z3 } from "zod/v4";
|
|
457
470
|
var INDEX_EVENT_TYPES = DECODED_EVENT_TYPES2;
|
|
458
471
|
var rangeFilters = {
|
|
459
|
-
contractId:
|
|
460
|
-
fromHeight:
|
|
461
|
-
toHeight:
|
|
462
|
-
cursor:
|
|
463
|
-
limit:
|
|
472
|
+
contractId: z3.string().optional().describe("Filter by contract id"),
|
|
473
|
+
fromHeight: z3.number().optional().describe("Start block height (inclusive)"),
|
|
474
|
+
toHeight: z3.number().optional().describe("End block height (inclusive)"),
|
|
475
|
+
cursor: z3.string().optional().describe("Opaque cursor from a prior response's next_cursor"),
|
|
476
|
+
limit: z3.number().optional().describe("Max rows for this page")
|
|
464
477
|
};
|
|
465
478
|
var heightFilters = {
|
|
466
479
|
fromHeight: rangeFilters.fromHeight,
|
|
@@ -472,89 +485,95 @@ var notFound = (message) => jsonResponse({ error: { type: "not_found", status: 4
|
|
|
472
485
|
function registerIndexTools(server, clientProvider = getClient) {
|
|
473
486
|
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).", {
|
|
474
487
|
...rangeFilters,
|
|
475
|
-
sender:
|
|
476
|
-
recipient:
|
|
488
|
+
sender: z3.string().optional().describe("Filter by sender principal"),
|
|
489
|
+
recipient: z3.string().optional().describe("Filter by recipient principal")
|
|
477
490
|
}, async (params) => jsonResponse(await clientProvider().index.ftTransfers.list(params)));
|
|
478
491
|
defineTool(server, "index_nft_transfers", "List decoded SIP-009 non-fungible-token transfers from the Index. Anonymous reads allowed (free-tier keys rejected).", {
|
|
479
492
|
...rangeFilters,
|
|
480
|
-
sender:
|
|
481
|
-
recipient:
|
|
482
|
-
assetIdentifier:
|
|
493
|
+
sender: z3.string().optional().describe("Filter by sender principal"),
|
|
494
|
+
recipient: z3.string().optional().describe("Filter by recipient principal"),
|
|
495
|
+
assetIdentifier: z3.string().optional().describe("Filter by asset identifier (contract::asset)")
|
|
483
496
|
}, async (params) => jsonResponse(await clientProvider().index.nftTransfers.list(params)));
|
|
484
497
|
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.", {
|
|
485
|
-
eventType:
|
|
498
|
+
eventType: z3.enum(INDEX_EVENT_TYPES).describe("Required. Decoded event type to list."),
|
|
486
499
|
...rangeFilters,
|
|
487
|
-
sender:
|
|
488
|
-
recipient:
|
|
489
|
-
assetIdentifier:
|
|
490
|
-
trait:
|
|
500
|
+
sender: z3.string().optional().describe("Filter by sender principal"),
|
|
501
|
+
recipient: z3.string().optional().describe("Filter by recipient principal"),
|
|
502
|
+
assetIdentifier: z3.string().optional().describe("Filter by asset identifier where applicable"),
|
|
503
|
+
trait: z3.string().optional().describe("Match contracts conforming to a trait/standard (e.g. sip-010). Mutually exclusive with contractId; contract-keyed event types only.")
|
|
491
504
|
}, async (params) => jsonResponse(await clientProvider().index.events.list(params)));
|
|
492
505
|
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.", {
|
|
493
506
|
...rangeFilters,
|
|
494
|
-
functionName:
|
|
495
|
-
sender:
|
|
496
|
-
trait:
|
|
507
|
+
functionName: z3.string().optional().describe("Filter by called function name"),
|
|
508
|
+
sender: z3.string().optional().describe("Filter by caller principal"),
|
|
509
|
+
trait: z3.string().optional().describe("Match contracts conforming to a trait/standard (e.g. sip-010). Mutually exclusive with contractId.")
|
|
497
510
|
}, async (params) => jsonResponse(await clientProvider().index.contractCalls.list(params)));
|
|
498
511
|
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)));
|
|
499
512
|
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)));
|
|
500
513
|
defineTool(server, "index_block", "Get a single block from the Index by height or block hash. Returns not_found if unknown.", {
|
|
501
|
-
ref:
|
|
514
|
+
ref: z3.string().describe("Block height (digits) or block hash (0x… string)")
|
|
502
515
|
}, async ({ ref }) => {
|
|
503
516
|
const block = await clientProvider().index.blocks.get(/^\d+$/.test(ref) ? Number(ref) : ref);
|
|
504
517
|
return block ? jsonResponse(block) : notFound(`No block for ref ${ref}`);
|
|
505
518
|
});
|
|
506
519
|
defineTool(server, "index_transactions", "List decoded transactions from the Index. Filter by type, sender, or contract. Anonymous reads allowed (free-tier keys rejected).", {
|
|
507
520
|
...rangeFilters,
|
|
508
|
-
type:
|
|
509
|
-
sender:
|
|
521
|
+
type: z3.string().optional().describe("Filter by transaction type"),
|
|
522
|
+
sender: z3.string().optional().describe("Filter by sender principal")
|
|
510
523
|
}, async (params) => jsonResponse(await clientProvider().index.transactions.list(params)));
|
|
511
|
-
defineTool(server, "index_transaction", "Get a single transaction from the Index by tx_id. Returns not_found if unknown.", { txId:
|
|
524
|
+
defineTool(server, "index_transaction", "Get a single transaction from the Index by tx_id. Returns not_found if unknown.", { txId: z3.string().describe("Transaction id (0x… hash)") }, async ({ txId }) => {
|
|
512
525
|
const tx = await clientProvider().index.transactions.get(txId);
|
|
513
526
|
return tx ? jsonResponse(tx) : notFound(`No transaction for ${txId}`);
|
|
514
527
|
});
|
|
515
|
-
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:
|
|
528
|
+
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: z3.string().describe("Transaction id (0x… hash)") }, async ({ txId }) => {
|
|
516
529
|
const proof = await clientProvider().index.transactions.getProof(txId);
|
|
517
530
|
return proof ? jsonResponse(proof) : notFound(`No proof available for ${txId}`);
|
|
518
531
|
});
|
|
519
532
|
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).", {
|
|
520
533
|
...heightFilters,
|
|
521
|
-
functionName:
|
|
522
|
-
stacker:
|
|
523
|
-
caller:
|
|
534
|
+
functionName: z3.string().optional().describe("Filter by PoX function name"),
|
|
535
|
+
stacker: z3.string().optional().describe("Filter by stacker principal"),
|
|
536
|
+
caller: z3.string().optional().describe("Filter by caller principal")
|
|
524
537
|
}, async (params) => jsonResponse(await clientProvider().index.stacking.list(params)));
|
|
525
538
|
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).", {
|
|
526
|
-
sender:
|
|
527
|
-
type:
|
|
528
|
-
contractId:
|
|
529
|
-
cursor:
|
|
530
|
-
limit:
|
|
539
|
+
sender: z3.string().optional().describe("Filter by sender principal"),
|
|
540
|
+
type: z3.string().optional().describe("Filter by transaction type"),
|
|
541
|
+
contractId: z3.string().optional().describe("Filter to pending calls to a single contract"),
|
|
542
|
+
cursor: z3.string().optional().describe("Opaque cursor from a prior response's next_cursor"),
|
|
543
|
+
limit: z3.number().optional().describe("Max rows for this page")
|
|
531
544
|
}, async (params) => jsonResponse(await clientProvider().index.mempool.list(params)));
|
|
532
|
-
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:
|
|
545
|
+
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: z3.string().describe("Transaction id (0x… hash)") }, async ({ txId }) => {
|
|
533
546
|
const tx = await clientProvider().index.mempool.get(txId);
|
|
534
547
|
return tx ? jsonResponse(tx) : notFound(`No pending tx for ${txId}`);
|
|
535
548
|
});
|
|
536
549
|
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()));
|
|
537
550
|
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()));
|
|
538
551
|
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(", ")}.`, {
|
|
539
|
-
target:
|
|
540
|
-
tables:
|
|
541
|
-
schemaName:
|
|
552
|
+
target: z3.enum(["prisma", "kysely", "drizzle", "json-schema"]).optional().describe("Output target (default kysely)"),
|
|
553
|
+
tables: z3.array(z3.string()).optional().describe("Subset of Index tables (default: all)"),
|
|
554
|
+
schemaName: z3.string().optional().describe("Postgres schema to qualify table names with")
|
|
542
555
|
}, async ({ target = "kysely", tables, schemaName }) => {
|
|
543
556
|
const out = generateIndexSchema(target, { tables, schemaName });
|
|
544
557
|
return { content: [{ type: "text", text: out }] };
|
|
545
558
|
});
|
|
559
|
+
defineTool(server, "batch_query", "Run up to 10 public /v1 reads in one round trip (POST /v1/batch). Each item keeps its own auth/quota/pay-per-call semantics; results return in order with per-item status. Paths must start with /v1/index, /v1/subgraphs, /v1/streams, or /v1/contracts.", {
|
|
560
|
+
requests: z3.array(z3.object({
|
|
561
|
+
path: z3.string().describe("Public /v1 read path"),
|
|
562
|
+
params: z3.record(z3.string(), z3.string()).optional()
|
|
563
|
+
})).min(1).max(10).describe("Read descriptors, executed concurrently")
|
|
564
|
+
}, async (params) => jsonResponse(await clientProvider().batch(params.requests)));
|
|
546
565
|
}
|
|
547
566
|
|
|
548
567
|
// src/tools/projects.ts
|
|
549
|
-
import { z as
|
|
568
|
+
import { z as z4 } from "zod/v4";
|
|
550
569
|
function registerProjectTools(server, clientProvider = getClient) {
|
|
551
570
|
defineTool(server, "project_list", "List the account's projects. Requires an account-level (owner) API key.", {}, async () => jsonResponse(await clientProvider().projects.list()));
|
|
552
|
-
defineTool(server, "project_get", "Get a single project by slug.", { slug:
|
|
571
|
+
defineTool(server, "project_get", "Get a single project by slug.", { slug: z4.string().describe("Project slug") }, async ({ slug }) => jsonResponse(await clientProvider().projects.get(slug)));
|
|
553
572
|
defineTool(server, "project_create", "Create a project. The slug is derived from the name when omitted. Requires an account-level (owner) API key.", {
|
|
554
|
-
name:
|
|
555
|
-
slug:
|
|
556
|
-
network:
|
|
557
|
-
nodeRpc:
|
|
573
|
+
name: z4.string().describe("Project name"),
|
|
574
|
+
slug: z4.string().optional().describe("URL slug (auto-derived from name if omitted)"),
|
|
575
|
+
network: z4.string().optional().describe("Network (e.g. mainnet, testnet)"),
|
|
576
|
+
nodeRpc: z4.string().optional().describe("Custom node RPC URL")
|
|
558
577
|
}, async ({ name, slug, network, nodeRpc }) => jsonResponse(await clientProvider().projects.create({
|
|
559
578
|
name,
|
|
560
579
|
slug,
|
|
@@ -562,12 +581,12 @@ function registerProjectTools(server, clientProvider = getClient) {
|
|
|
562
581
|
nodeRpc
|
|
563
582
|
})));
|
|
564
583
|
defineTool(server, "project_update", "Update a project. `slug` selects the project; `newSlug` renames it. Requires an account-level (owner) API key.", {
|
|
565
|
-
slug:
|
|
566
|
-
newSlug:
|
|
567
|
-
name:
|
|
568
|
-
network:
|
|
569
|
-
nodeRpc:
|
|
570
|
-
settings:
|
|
584
|
+
slug: z4.string().describe("Slug of the project to update"),
|
|
585
|
+
newSlug: z4.string().optional().describe("New slug (renames the project)"),
|
|
586
|
+
name: z4.string().optional().describe("New display name"),
|
|
587
|
+
network: z4.string().optional().describe("Network (e.g. mainnet, testnet)"),
|
|
588
|
+
nodeRpc: z4.string().optional().describe("Custom node RPC URL"),
|
|
589
|
+
settings: z4.record(z4.string(), z4.unknown()).optional().describe("Arbitrary project settings to merge")
|
|
571
590
|
}, async ({ slug, newSlug, name, network, nodeRpc, settings }) => jsonResponse(await clientProvider().projects.update(slug, {
|
|
572
591
|
...newSlug !== undefined ? { slug: newSlug } : {},
|
|
573
592
|
...name !== undefined ? { name } : {},
|
|
@@ -575,8 +594,8 @@ function registerProjectTools(server, clientProvider = getClient) {
|
|
|
575
594
|
...nodeRpc !== undefined ? { nodeRpc } : {},
|
|
576
595
|
...settings !== undefined ? { settings } : {}
|
|
577
596
|
})));
|
|
578
|
-
defineTool(server, "project_delete", "Delete a project permanently. The account's last remaining project cannot be deleted.", { slug:
|
|
579
|
-
defineTool(server, "project_team_list", "List a project's team members and pending invitations.", { slug:
|
|
597
|
+
defineTool(server, "project_delete", "Delete a project permanently. The account's last remaining project cannot be deleted.", { slug: z4.string().describe("Project slug") }, async ({ slug }) => jsonResponse(await clientProvider().projects.delete(slug)));
|
|
598
|
+
defineTool(server, "project_team_list", "List a project's team members and pending invitations.", { slug: z4.string().describe("Project slug") }, async ({ slug }) => jsonResponse(await clientProvider().projects.team(slug)));
|
|
580
599
|
}
|
|
581
600
|
|
|
582
601
|
// src/tools/scaffold.ts
|
|
@@ -585,7 +604,7 @@ import {
|
|
|
585
604
|
generateTraitSubgraph
|
|
586
605
|
} from "@secondlayer/scaffold";
|
|
587
606
|
import { TRAIT_STANDARDS as TRAIT_STANDARDS2 } from "@secondlayer/stacks/clarity";
|
|
588
|
-
import { z as
|
|
607
|
+
import { z as z5 } from "zod/v4";
|
|
589
608
|
async function fetchAbi(contractId) {
|
|
590
609
|
const contract = await getClient().contracts.get(contractId, {
|
|
591
610
|
includeAbi: true
|
|
@@ -600,24 +619,24 @@ async function fetchAbi(contractId) {
|
|
|
600
619
|
}
|
|
601
620
|
function registerScaffoldTools(server) {
|
|
602
621
|
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.", {
|
|
603
|
-
trait:
|
|
604
|
-
subgraphName:
|
|
622
|
+
trait: z5.enum(TRAIT_STANDARDS2).describe("SIP standard to index (sip-009 | sip-010 | sip-013)"),
|
|
623
|
+
subgraphName: z5.string().optional().describe("Override the subgraph name (defaults to <trait>-transfers)")
|
|
605
624
|
}, async ({ trait, subgraphName }) => {
|
|
606
625
|
const code = generateTraitSubgraph({ trait, name: subgraphName });
|
|
607
626
|
return { content: [{ type: "text", text: code }] };
|
|
608
627
|
});
|
|
609
628
|
defineTool(server, "scaffold_from_contract", "Generate a subgraph scaffold from a deployed Stacks contract. Fetches the ABI automatically.", {
|
|
610
|
-
contractId:
|
|
611
|
-
subgraphName:
|
|
629
|
+
contractId: z5.string().describe("Fully qualified contract ID (e.g. SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01)"),
|
|
630
|
+
subgraphName: z5.string().optional().describe("Override the subgraph name (defaults to contract name)")
|
|
612
631
|
}, async ({ contractId, subgraphName }) => {
|
|
613
632
|
const { functions, maps } = await fetchAbi(contractId);
|
|
614
633
|
const code = generateSubgraphCode(contractId, functions, subgraphName, maps);
|
|
615
634
|
return { content: [{ type: "text", text: code }] };
|
|
616
635
|
});
|
|
617
636
|
defineTool(server, "scaffold_from_abi", "Generate a subgraph scaffold from a provided ABI JSON. Use when you already have the ABI.", {
|
|
618
|
-
abi:
|
|
619
|
-
contractId:
|
|
620
|
-
subgraphName:
|
|
637
|
+
abi: z5.string().describe("ABI JSON string (the full contract ABI object)"),
|
|
638
|
+
contractId: z5.string().describe("Fully qualified contract ID"),
|
|
639
|
+
subgraphName: z5.string().optional().describe("Override the subgraph name")
|
|
621
640
|
}, async ({ abi, contractId, subgraphName }) => {
|
|
622
641
|
let parsed;
|
|
623
642
|
try {
|
|
@@ -636,7 +655,7 @@ function registerScaffoldTools(server) {
|
|
|
636
655
|
// src/tools/streams.ts
|
|
637
656
|
import { AuthError } from "@secondlayer/sdk";
|
|
638
657
|
import { DECODED_EVENT_TYPES as DECODED_EVENT_TYPES3 } from "@secondlayer/shared";
|
|
639
|
-
import { z as
|
|
658
|
+
import { z as z6 } from "zod/v4";
|
|
640
659
|
var STREAMS_EVENT_TYPES = DECODED_EVENT_TYPES3;
|
|
641
660
|
async function withStreamsAuthHint(fn) {
|
|
642
661
|
try {
|
|
@@ -651,28 +670,28 @@ async function withStreamsAuthHint(fn) {
|
|
|
651
670
|
function registerStreamsTools(server, clientProvider = getClient) {
|
|
652
671
|
defineTool(server, "streams_tip", "Get the current Streams chain tip (latest processed block + lag). Streams requires an API key (SL_API_KEY).", {}, async () => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.tip())));
|
|
653
672
|
defineTool(server, "streams_events", "List raw chain events from the Streams firehose. Streams requires an API key (SL_API_KEY). Filter by event types, principals, contract, asset, or block range; page with cursor.", {
|
|
654
|
-
types:
|
|
655
|
-
notTypes:
|
|
656
|
-
contractId:
|
|
657
|
-
sender:
|
|
658
|
-
recipient:
|
|
659
|
-
assetIdentifier:
|
|
660
|
-
fromHeight:
|
|
661
|
-
toHeight:
|
|
662
|
-
cursor:
|
|
663
|
-
limit:
|
|
673
|
+
types: z6.array(z6.enum(STREAMS_EVENT_TYPES)).optional().describe("Event types to include"),
|
|
674
|
+
notTypes: z6.array(z6.enum(STREAMS_EVENT_TYPES)).optional().describe("Event types to exclude (applied after types)"),
|
|
675
|
+
contractId: z6.string().optional().describe("Filter by contract id"),
|
|
676
|
+
sender: z6.string().optional().describe("Filter by sender principal"),
|
|
677
|
+
recipient: z6.string().optional().describe("Filter by recipient principal"),
|
|
678
|
+
assetIdentifier: z6.string().optional().describe("Filter by asset identifier"),
|
|
679
|
+
fromHeight: z6.number().optional().describe("Start block height (inclusive)"),
|
|
680
|
+
toHeight: z6.number().optional().describe("End block height (inclusive)"),
|
|
681
|
+
cursor: z6.string().optional().describe("Opaque cursor from a prior response"),
|
|
682
|
+
limit: z6.number().optional().describe("Max events for this page")
|
|
664
683
|
}, async (params) => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.events.list(params))));
|
|
665
684
|
defineTool(server, "streams_consume", "Consume a bounded, reorg-aware run of Streams events from a cursor. Walks up to maxPages pages and returns the events, any reorgs observed, and a resume `cursor` to pass back as fromCursor next call — the agent-native consume/resume primitive. Streams requires an API key (SL_API_KEY).", {
|
|
666
|
-
fromCursor:
|
|
667
|
-
types:
|
|
668
|
-
notTypes:
|
|
669
|
-
contractId:
|
|
670
|
-
sender:
|
|
671
|
-
recipient:
|
|
672
|
-
assetIdentifier:
|
|
673
|
-
batchSize:
|
|
674
|
-
maxPages:
|
|
675
|
-
finalizedOnly:
|
|
685
|
+
fromCursor: z6.string().optional().describe("Resume cursor from a prior consume (omit to start at genesis)"),
|
|
686
|
+
types: z6.array(z6.enum(STREAMS_EVENT_TYPES)).optional().describe("Event types to include"),
|
|
687
|
+
notTypes: z6.array(z6.enum(STREAMS_EVENT_TYPES)).optional().describe("Event types to exclude"),
|
|
688
|
+
contractId: z6.string().optional().describe("Filter by contract id"),
|
|
689
|
+
sender: z6.string().optional().describe("Filter by sender principal"),
|
|
690
|
+
recipient: z6.string().optional().describe("Filter by recipient principal"),
|
|
691
|
+
assetIdentifier: z6.string().optional().describe("Filter by asset identifier"),
|
|
692
|
+
batchSize: z6.number().optional().describe("Events per page (1–1000, default 100)"),
|
|
693
|
+
maxPages: z6.number().optional().describe("Max pages to walk this call (1–20, default 5)"),
|
|
694
|
+
finalizedOnly: z6.boolean().optional().describe("Only emit finalized events; skip reorg handling")
|
|
676
695
|
}, async (params) => withStreamsAuthHint(async () => {
|
|
677
696
|
const maxPages = Math.min(Math.max(params.maxPages ?? 5, 1), 20);
|
|
678
697
|
const batchSize = Math.min(Math.max(params.batchSize ?? 100, 1), 1000);
|
|
@@ -704,15 +723,15 @@ function registerStreamsTools(server, clientProvider = getClient) {
|
|
|
704
723
|
pages: result.pages
|
|
705
724
|
});
|
|
706
725
|
}));
|
|
707
|
-
defineTool(server, "streams_event_by_txid", "List all Streams events emitted by a single transaction. Streams requires an API key (SL_API_KEY).", { txId:
|
|
726
|
+
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))));
|
|
708
727
|
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).", {
|
|
709
|
-
heightOrHash:
|
|
728
|
+
heightOrHash: z6.string().describe("Block height (digits) or block hash (0x… string)")
|
|
710
729
|
}, async ({ heightOrHash }) => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.blocks.events(/^\d+$/.test(heightOrHash) ? Number(heightOrHash) : heightOrHash))));
|
|
711
730
|
defineTool(server, "streams_reorgs", "List chain reorgs observed by Streams since a cursor. Streams requires an API key (SL_API_KEY).", {
|
|
712
|
-
since:
|
|
713
|
-
limit:
|
|
731
|
+
since: z6.string().describe("Cursor to list reorgs since (block:index or ISO timestamp)"),
|
|
732
|
+
limit: z6.number().optional().describe("Max reorgs to return")
|
|
714
733
|
}, async (params) => withStreamsAuthHint(async () => jsonResponse(await clientProvider().streams.reorgs.list(params))));
|
|
715
|
-
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:
|
|
734
|
+
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))));
|
|
716
735
|
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())));
|
|
717
736
|
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()));
|
|
718
737
|
}
|
|
@@ -725,7 +744,7 @@ import {
|
|
|
725
744
|
generateKyselySchema,
|
|
726
745
|
generatePrismaSchema
|
|
727
746
|
} from "@secondlayer/subgraphs";
|
|
728
|
-
import { z as
|
|
747
|
+
import { z as z7 } from "zod/v4";
|
|
729
748
|
function registerSubgraphTools(server, clientProvider = getClient) {
|
|
730
749
|
defineTool(server, "subgraphs_list", "List all deployed subgraphs. Returns summary fields only, including visibility — public subgraphs are anon-readable at /v1/subgraphs/<name>.", {}, async () => {
|
|
731
750
|
const { data } = await clientProvider().subgraphs.list();
|
|
@@ -738,16 +757,16 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
738
757
|
]
|
|
739
758
|
};
|
|
740
759
|
});
|
|
741
|
-
defineTool(server, "subgraphs_get", "Get full details of a subgraph including schema, health, and table columns.", { name:
|
|
760
|
+
defineTool(server, "subgraphs_get", "Get full details of a subgraph including schema, health, and table columns.", { name: z7.string().describe("Subgraph name") }, async ({ name }) => {
|
|
742
761
|
const detail = await clientProvider().subgraphs.get(name);
|
|
743
762
|
return {
|
|
744
763
|
content: [{ type: "text", text: JSON.stringify(detail, null, 2) }]
|
|
745
764
|
};
|
|
746
765
|
});
|
|
747
766
|
defineTool(server, "subgraphs_spec", "Get generated API documentation for a subgraph. Defaults to compact agent schema; supports OpenAPI JSON and Markdown.", {
|
|
748
|
-
name:
|
|
749
|
-
format:
|
|
750
|
-
serverUrl:
|
|
767
|
+
name: z7.string().describe("Subgraph name"),
|
|
768
|
+
format: z7.enum(["agent", "openapi", "markdown"]).optional().describe("Spec format to return. Defaults to agent."),
|
|
769
|
+
serverUrl: z7.string().optional().describe("Override the server URL embedded in generated docs.")
|
|
751
770
|
}, async ({ name, format = "agent", serverUrl }) => {
|
|
752
771
|
const options = serverUrl ? { serverUrl } : undefined;
|
|
753
772
|
const spec = format === "openapi" ? await clientProvider().subgraphs.openapi(name, options) : format === "markdown" ? await clientProvider().subgraphs.markdown(name, options) : await clientProvider().subgraphs.schema(name, options);
|
|
@@ -761,15 +780,15 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
761
780
|
};
|
|
762
781
|
});
|
|
763
782
|
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.', {
|
|
764
|
-
name:
|
|
765
|
-
table:
|
|
766
|
-
filters:
|
|
767
|
-
sort:
|
|
768
|
-
order:
|
|
769
|
-
limit:
|
|
770
|
-
offset:
|
|
771
|
-
fields:
|
|
772
|
-
count:
|
|
783
|
+
name: z7.string().describe("Subgraph name"),
|
|
784
|
+
table: z7.string().describe("Table name"),
|
|
785
|
+
filters: z7.record(z7.string(), z7.string()).optional().describe('Column filters — plain values or with operators (e.g. {"amount.gte": "1000", "sender": "SP..."})'),
|
|
786
|
+
sort: z7.string().optional().describe("Column to sort by"),
|
|
787
|
+
order: z7.enum(["asc", "desc"]).optional().describe("Sort order"),
|
|
788
|
+
limit: z7.number().max(200).optional().describe("Max rows (default 50, max 200)"),
|
|
789
|
+
offset: z7.number().optional().describe("Offset for pagination"),
|
|
790
|
+
fields: z7.string().optional().describe('Comma-separated column list to return (e.g. "sender,amount")'),
|
|
791
|
+
count: z7.boolean().optional().describe("If true, return row count instead of rows")
|
|
773
792
|
}, async ({
|
|
774
793
|
name,
|
|
775
794
|
table,
|
|
@@ -802,14 +821,14 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
802
821
|
};
|
|
803
822
|
});
|
|
804
823
|
defineTool(server, "subgraphs_aggregate", `Compute scalar aggregates over a subgraph table's filtered rows. Supports count, countDistinct, and sum/min/max (numeric columns only — uint/int plus the system _block_height). Filters use the same grammar as subgraphs_query (e.g. {"amount.gte": "1000"}). sum/min/max come back as lossless strings; counts as numbers. With no aggregate requested, returns the row count.`, {
|
|
805
|
-
name:
|
|
806
|
-
table:
|
|
807
|
-
filters:
|
|
808
|
-
count:
|
|
809
|
-
countDistinct:
|
|
810
|
-
sum:
|
|
811
|
-
min:
|
|
812
|
-
max:
|
|
824
|
+
name: z7.string().describe("Subgraph name"),
|
|
825
|
+
table: z7.string().describe("Table name"),
|
|
826
|
+
filters: z7.record(z7.string(), z7.string()).optional().describe('Column filters — plain values or with operators (e.g. {"amount.gte": "1000", "sender": "SP..."})'),
|
|
827
|
+
count: z7.boolean().optional().describe("Include COUNT(*) of matching rows"),
|
|
828
|
+
countDistinct: z7.array(z7.string()).optional().describe("Columns to count distinct values of"),
|
|
829
|
+
sum: z7.array(z7.string()).optional().describe("Numeric columns to sum (lossless string result)"),
|
|
830
|
+
min: z7.array(z7.string()).optional().describe("Numeric columns to take the minimum of"),
|
|
831
|
+
max: z7.array(z7.string()).optional().describe("Numeric columns to take the maximum of")
|
|
813
832
|
}, async ({ name, table, filters, count, countDistinct, sum, min, max }) => {
|
|
814
833
|
const result = await clientProvider().subgraphs.queryTableAggregate(name, table, { filters, count, countDistinct, sum, min, max });
|
|
815
834
|
return {
|
|
@@ -817,9 +836,9 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
817
836
|
};
|
|
818
837
|
});
|
|
819
838
|
defineTool(server, "subgraphs_reindex", "Reindex a subgraph from a specific block range. Returns an operationId — poll subgraphs_operation to track progress to completion.", {
|
|
820
|
-
name:
|
|
821
|
-
fromBlock:
|
|
822
|
-
toBlock:
|
|
839
|
+
name: z7.string().describe("Subgraph name"),
|
|
840
|
+
fromBlock: z7.number().optional().describe("Start block (defaults to beginning)"),
|
|
841
|
+
toBlock: z7.number().optional().describe("End block (defaults to latest)")
|
|
823
842
|
}, async ({ name, fromBlock, toBlock }) => {
|
|
824
843
|
const result = await clientProvider().subgraphs.reindex(name, {
|
|
825
844
|
fromBlock,
|
|
@@ -830,8 +849,8 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
830
849
|
};
|
|
831
850
|
});
|
|
832
851
|
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.", {
|
|
833
|
-
name:
|
|
834
|
-
operationId:
|
|
852
|
+
name: z7.string().describe("Subgraph name"),
|
|
853
|
+
operationId: z7.string().optional().describe("Operation id from reindex/backfill/stop; omit to list recent operations")
|
|
835
854
|
}, async ({ name, operationId }) => {
|
|
836
855
|
const result = operationId ? await clientProvider().subgraphs.getOperation(name, operationId) : await clientProvider().subgraphs.operations(name);
|
|
837
856
|
return {
|
|
@@ -839,9 +858,9 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
839
858
|
};
|
|
840
859
|
});
|
|
841
860
|
defineTool(server, "subgraphs_backfill", "Backfill a subgraph over a block range. Non-destructive forward fill (does not drop existing data) — unlike subgraphs_reindex, and the only data-fill path for BYO subgraphs (reindex is blocked there). Both blocks required. Returns an operationId — poll subgraphs_operation to track progress.", {
|
|
842
|
-
name:
|
|
843
|
-
fromBlock:
|
|
844
|
-
toBlock:
|
|
861
|
+
name: z7.string().describe("Subgraph name"),
|
|
862
|
+
fromBlock: z7.number().int().nonnegative().describe("Start block (inclusive)"),
|
|
863
|
+
toBlock: z7.number().int().nonnegative().describe("End block (inclusive)")
|
|
845
864
|
}, async ({ name, fromBlock, toBlock }) => {
|
|
846
865
|
const result = await clientProvider().subgraphs.backfill(name, {
|
|
847
866
|
fromBlock,
|
|
@@ -851,17 +870,17 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
851
870
|
content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
|
|
852
871
|
};
|
|
853
872
|
});
|
|
854
|
-
defineTool(server, "subgraphs_stop", "Cancel an in-flight reindex or backfill operation for a subgraph. Returns the stop request status; poll subgraphs_operation to confirm it reaches a terminal state.", { name:
|
|
873
|
+
defineTool(server, "subgraphs_stop", "Cancel an in-flight reindex or backfill operation for a subgraph. Returns the stop request status; poll subgraphs_operation to confirm it reaches a terminal state.", { name: z7.string().describe("Subgraph name") }, async ({ name }) => {
|
|
855
874
|
const result = await clientProvider().subgraphs.stop(name);
|
|
856
875
|
return {
|
|
857
876
|
content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
|
|
858
877
|
};
|
|
859
878
|
});
|
|
860
879
|
defineTool(server, "subgraphs_gaps", "List indexing gaps (missing block ranges) for a subgraph. Each gap reports start/end/size, reason, and detected/resolved timestamps. Feed an unresolved gap's range into subgraphs_backfill to fill it. Defaults to unresolved gaps.", {
|
|
861
|
-
name:
|
|
862
|
-
limit:
|
|
863
|
-
offset:
|
|
864
|
-
resolved:
|
|
880
|
+
name: z7.string().describe("Subgraph name"),
|
|
881
|
+
limit: z7.number().int().positive().optional().describe("Max gaps to return"),
|
|
882
|
+
offset: z7.number().int().nonnegative().optional().describe("Pagination offset"),
|
|
883
|
+
resolved: z7.boolean().optional().describe("Filter by resolved state (omit for unresolved only)")
|
|
865
884
|
}, async ({ name, limit, offset, resolved }) => {
|
|
866
885
|
const result = await clientProvider().subgraphs.gaps(name, {
|
|
867
886
|
limit,
|
|
@@ -872,16 +891,16 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
872
891
|
content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
|
|
873
892
|
};
|
|
874
893
|
});
|
|
875
|
-
defineTool(server, "subgraphs_delete", "Delete a subgraph permanently.", { name:
|
|
894
|
+
defineTool(server, "subgraphs_delete", "Delete a subgraph permanently.", { name: z7.string().describe("Subgraph name") }, async ({ name }) => {
|
|
876
895
|
const result = await clientProvider().subgraphs.delete(name);
|
|
877
896
|
return { content: [{ type: "text", text: result.message }] };
|
|
878
897
|
});
|
|
879
898
|
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.", {
|
|
880
|
-
code:
|
|
881
|
-
startBlock:
|
|
882
|
-
databaseUrl:
|
|
883
|
-
dryRun:
|
|
884
|
-
visibility:
|
|
899
|
+
code: z7.string().describe("TypeScript source code containing a defineSubgraph() call"),
|
|
900
|
+
startBlock: z7.number().int().nonnegative().optional().describe("Override the definition startBlock for this deploy"),
|
|
901
|
+
databaseUrl: z7.string().optional().describe("BYO data plane: Postgres connection string to host the subgraph's schema and rows in your own database"),
|
|
902
|
+
dryRun: z7.boolean().optional().describe("Validate and preview the deploy (schema/DDL, BYO connection) without writing changes"),
|
|
903
|
+
visibility: z7.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.")
|
|
885
904
|
}, async ({ code, startBlock, databaseUrl, dryRun, visibility }) => {
|
|
886
905
|
const bundled = await bundleSubgraphCode(code);
|
|
887
906
|
try {
|
|
@@ -915,29 +934,29 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
915
934
|
throw err;
|
|
916
935
|
}
|
|
917
936
|
});
|
|
918
|
-
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:
|
|
937
|
+
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: z7.string().describe("Subgraph name") }, async ({ name }) => {
|
|
919
938
|
const result = await clientProvider().subgraphs.publish(name);
|
|
920
939
|
return {
|
|
921
940
|
content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
|
|
922
941
|
};
|
|
923
942
|
});
|
|
924
|
-
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:
|
|
943
|
+
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: z7.string().describe("Subgraph name") }, async ({ name }) => {
|
|
925
944
|
const result = await clientProvider().subgraphs.unpublish(name);
|
|
926
945
|
return {
|
|
927
946
|
content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
|
|
928
947
|
};
|
|
929
948
|
});
|
|
930
|
-
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:
|
|
949
|
+
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: z7.string().describe("Subgraph name") }, async ({ name }) => {
|
|
931
950
|
const source = await clientProvider().subgraphs.getSource(name);
|
|
932
951
|
return {
|
|
933
952
|
content: [{ type: "text", text: JSON.stringify(source, null, 2) }]
|
|
934
953
|
};
|
|
935
954
|
});
|
|
936
955
|
defineTool(server, "subgraphs_codegen", "Generate a typed ORM schema (Prisma, Drizzle, or Kysely) for a subgraph's tables so they can be queried from a BYO database. Pass either `code` (defineSubgraph source) or `name` (a deployed subgraph — its captured source is used). Returns the schema as text.", {
|
|
937
|
-
code:
|
|
938
|
-
name:
|
|
939
|
-
target:
|
|
940
|
-
schemaName:
|
|
956
|
+
code: z7.string().optional().describe("defineSubgraph() source (mutually exclusive with name)"),
|
|
957
|
+
name: z7.string().optional().describe("Deployed subgraph name (mutually exclusive with code)"),
|
|
958
|
+
target: z7.enum(["prisma", "drizzle", "kysely"]).optional().describe("ORM target (default prisma)"),
|
|
959
|
+
schemaName: z7.string().optional().describe("Postgres schema name (defaults to subgraph_<name>)")
|
|
941
960
|
}, async ({ code, name, target = "prisma", schemaName }) => {
|
|
942
961
|
if (code && name || !code && !name) {
|
|
943
962
|
throw new Error("Provide exactly one of `code` or `name`.");
|
|
@@ -966,7 +985,7 @@ function registerSubgraphTools(server, clientProvider = getClient) {
|
|
|
966
985
|
|
|
967
986
|
// src/tools/subscriptions.ts
|
|
968
987
|
import { CHAIN_TRIGGER_TYPES } from "@secondlayer/shared";
|
|
969
|
-
import { z as
|
|
988
|
+
import { z as z8 } from "zod/v4";
|
|
970
989
|
function registerSubscriptionTools(server, clientProvider = getClient) {
|
|
971
990
|
defineTool(server, "subscriptions_list", "List all subscriptions for the current account. Returns summary fields (no secrets).", {}, async () => {
|
|
972
991
|
const { data } = await clientProvider().subscriptions.list();
|
|
@@ -974,34 +993,34 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
|
|
|
974
993
|
content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
|
|
975
994
|
};
|
|
976
995
|
});
|
|
977
|
-
defineTool(server, "subscriptions_get", "Get full detail for a subscription (filter, auth, retry config, circuit state).", { id:
|
|
996
|
+
defineTool(server, "subscriptions_get", "Get full detail for a subscription (filter, auth, retry config, circuit state).", { id: z8.string().describe("Subscription id") }, async ({ id }) => {
|
|
978
997
|
const detail = await clientProvider().subscriptions.get(id);
|
|
979
998
|
return {
|
|
980
999
|
content: [{ type: "text", text: JSON.stringify(detail, null, 2) }]
|
|
981
1000
|
};
|
|
982
1001
|
});
|
|
983
1002
|
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.", {
|
|
984
|
-
name:
|
|
985
|
-
subgraphName:
|
|
986
|
-
tableName:
|
|
987
|
-
triggers:
|
|
988
|
-
type:
|
|
989
|
-
contractId:
|
|
990
|
-
functionName:
|
|
991
|
-
caller:
|
|
992
|
-
sender:
|
|
993
|
-
recipient:
|
|
994
|
-
assetIdentifier:
|
|
995
|
-
deployer:
|
|
996
|
-
contractName:
|
|
997
|
-
topic:
|
|
998
|
-
lockedAddress:
|
|
999
|
-
trait:
|
|
1000
|
-
minAmount:
|
|
1001
|
-
maxAmount:
|
|
1003
|
+
name: z8.string().describe("Human-readable name, unique per account"),
|
|
1004
|
+
subgraphName: z8.string().optional().describe("Subgraph to subscribe to (subgraph subscription)"),
|
|
1005
|
+
tableName: z8.string().optional().describe("Table within the subgraph (subgraph subscription)"),
|
|
1006
|
+
triggers: z8.array(z8.object({
|
|
1007
|
+
type: z8.enum(CHAIN_TRIGGER_TYPES),
|
|
1008
|
+
contractId: z8.string().optional(),
|
|
1009
|
+
functionName: z8.string().optional(),
|
|
1010
|
+
caller: z8.string().optional(),
|
|
1011
|
+
sender: z8.string().optional(),
|
|
1012
|
+
recipient: z8.string().optional(),
|
|
1013
|
+
assetIdentifier: z8.string().optional(),
|
|
1014
|
+
deployer: z8.string().optional(),
|
|
1015
|
+
contractName: z8.string().optional(),
|
|
1016
|
+
topic: z8.string().optional(),
|
|
1017
|
+
lockedAddress: z8.string().optional(),
|
|
1018
|
+
trait: z8.string().optional(),
|
|
1019
|
+
minAmount: z8.union([z8.string(), z8.number()]).optional(),
|
|
1020
|
+
maxAmount: z8.union([z8.string(), z8.number()]).optional()
|
|
1002
1021
|
})).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."),
|
|
1003
|
-
url:
|
|
1004
|
-
format:
|
|
1022
|
+
url: z8.string().describe("Webhook URL"),
|
|
1023
|
+
format: z8.enum([
|
|
1005
1024
|
"standard-webhooks",
|
|
1006
1025
|
"inngest",
|
|
1007
1026
|
"trigger",
|
|
@@ -1009,9 +1028,9 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
|
|
|
1009
1028
|
"cloudevents",
|
|
1010
1029
|
"raw"
|
|
1011
1030
|
]).optional().describe("Wire format (default standard-webhooks)"),
|
|
1012
|
-
runtime:
|
|
1013
|
-
filter:
|
|
1014
|
-
authConfig:
|
|
1031
|
+
runtime: z8.enum(["inngest", "trigger", "cloudflare", "node"]).optional().describe("Receiver runtime label (display only)"),
|
|
1032
|
+
filter: z8.record(z8.string(), z8.unknown()).optional().describe('Scalar filter DSL, e.g. {"amount": {"gte": 100}, "sender": "SP..."}'),
|
|
1033
|
+
authConfig: z8.record(z8.string(), z8.unknown()).optional().describe('Receiver auth sent with each delivery, e.g. {"type": "bearer", "token": "..."}')
|
|
1015
1034
|
}, async (input) => {
|
|
1016
1035
|
const res = await clientProvider().subscriptions.create(input);
|
|
1017
1036
|
return {
|
|
@@ -1019,12 +1038,12 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
|
|
|
1019
1038
|
};
|
|
1020
1039
|
});
|
|
1021
1040
|
defineTool(server, "subscriptions_update", "Patch a subscription (name, url, filter, authConfig, format, runtime, retry, timeout, concurrency).", {
|
|
1022
|
-
id:
|
|
1023
|
-
name:
|
|
1024
|
-
url:
|
|
1025
|
-
filter:
|
|
1026
|
-
authConfig:
|
|
1027
|
-
format:
|
|
1041
|
+
id: z8.string(),
|
|
1042
|
+
name: z8.string().optional().describe("Rename the subscription"),
|
|
1043
|
+
url: z8.string().optional(),
|
|
1044
|
+
filter: z8.record(z8.string(), z8.unknown()).optional(),
|
|
1045
|
+
authConfig: z8.record(z8.string(), z8.unknown()).optional().describe("Receiver auth sent with each delivery (bearer/etc.)"),
|
|
1046
|
+
format: z8.enum([
|
|
1028
1047
|
"standard-webhooks",
|
|
1029
1048
|
"inngest",
|
|
1030
1049
|
"trigger",
|
|
@@ -1032,51 +1051,51 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
|
|
|
1032
1051
|
"cloudevents",
|
|
1033
1052
|
"raw"
|
|
1034
1053
|
]).optional(),
|
|
1035
|
-
runtime:
|
|
1036
|
-
maxRetries:
|
|
1037
|
-
timeoutMs:
|
|
1038
|
-
concurrency:
|
|
1054
|
+
runtime: z8.enum(["inngest", "trigger", "cloudflare", "node"]).nullable().optional(),
|
|
1055
|
+
maxRetries: z8.number().int().min(0).optional(),
|
|
1056
|
+
timeoutMs: z8.number().int().min(100).optional(),
|
|
1057
|
+
concurrency: z8.number().int().min(1).optional()
|
|
1039
1058
|
}, async ({ id, ...patch }) => {
|
|
1040
1059
|
const res = await clientProvider().subscriptions.update(id, patch);
|
|
1041
1060
|
return {
|
|
1042
1061
|
content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
|
|
1043
1062
|
};
|
|
1044
1063
|
});
|
|
1045
|
-
defineTool(server, "subscriptions_pause", "Pause a subscription. Pending rows remain queued until resumed.", { id:
|
|
1064
|
+
defineTool(server, "subscriptions_pause", "Pause a subscription. Pending rows remain queued until resumed.", { id: z8.string() }, async ({ id }) => {
|
|
1046
1065
|
const res = await clientProvider().subscriptions.pause(id);
|
|
1047
1066
|
return {
|
|
1048
1067
|
content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
|
|
1049
1068
|
};
|
|
1050
1069
|
});
|
|
1051
|
-
defineTool(server, "subscriptions_resume", "Resume a paused or circuit-open subscription and reset circuit failures.", { id:
|
|
1070
|
+
defineTool(server, "subscriptions_resume", "Resume a paused or circuit-open subscription and reset circuit failures.", { id: z8.string() }, async ({ id }) => {
|
|
1052
1071
|
const res = await clientProvider().subscriptions.resume(id);
|
|
1053
1072
|
return {
|
|
1054
1073
|
content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
|
|
1055
1074
|
};
|
|
1056
1075
|
});
|
|
1057
|
-
defineTool(server, "subscriptions_delete", "Delete a subscription. Pending outbox rows are cascade-deleted.", { id:
|
|
1076
|
+
defineTool(server, "subscriptions_delete", "Delete a subscription. Pending outbox rows are cascade-deleted.", { id: z8.string() }, async ({ id }) => {
|
|
1058
1077
|
const res = await clientProvider().subscriptions.delete(id);
|
|
1059
1078
|
return {
|
|
1060
1079
|
content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
|
|
1061
1080
|
};
|
|
1062
1081
|
});
|
|
1063
|
-
defineTool(server, "subscriptions_rotate_secret", "Rotate a subscription signing secret. Returns the new plaintext secret once.", { id:
|
|
1082
|
+
defineTool(server, "subscriptions_rotate_secret", "Rotate a subscription signing secret. Returns the new plaintext secret once.", { id: z8.string() }, async ({ id }) => {
|
|
1064
1083
|
const res = await clientProvider().subscriptions.rotateSecret(id);
|
|
1065
1084
|
return {
|
|
1066
1085
|
content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
|
|
1067
1086
|
};
|
|
1068
1087
|
});
|
|
1069
|
-
defineTool(server, "subscriptions_test", "Send a one-off test webhook to a subscription's URL (built for its format, SSRF-guarded). Logged as a delivery row — check subscriptions_recent_deliveries. Returns {ok, statusCode, error, durationMs, deliveryId}.", { id:
|
|
1088
|
+
defineTool(server, "subscriptions_test", "Send a one-off test webhook to a subscription's URL (built for its format, SSRF-guarded). Logged as a delivery row — check subscriptions_recent_deliveries. Returns {ok, statusCode, error, durationMs, deliveryId}.", { id: z8.string().describe("Subscription id") }, async ({ id }) => {
|
|
1070
1089
|
const res = await clientProvider().subscriptions.test(id);
|
|
1071
1090
|
return {
|
|
1072
1091
|
content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
|
|
1073
1092
|
};
|
|
1074
1093
|
});
|
|
1075
1094
|
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.", {
|
|
1076
|
-
id:
|
|
1077
|
-
fromBlock:
|
|
1078
|
-
toBlock:
|
|
1079
|
-
force:
|
|
1095
|
+
id: z8.string(),
|
|
1096
|
+
fromBlock: z8.number().int().nonnegative(),
|
|
1097
|
+
toBlock: z8.number().int().nonnegative(),
|
|
1098
|
+
force: z8.string().optional().describe("Idempotency suffix to force a duplicate replay of the range")
|
|
1080
1099
|
}, async ({ id, fromBlock, toBlock, force }) => {
|
|
1081
1100
|
const res = await clientProvider().subscriptions.replay(id, {
|
|
1082
1101
|
fromBlock,
|
|
@@ -1087,22 +1106,22 @@ function registerSubscriptionTools(server, clientProvider = getClient) {
|
|
|
1087
1106
|
content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
|
|
1088
1107
|
};
|
|
1089
1108
|
});
|
|
1090
|
-
defineTool(server, "subscriptions_dead", "Return the last 100 dead-letter outbox rows for a subscription.", { id:
|
|
1109
|
+
defineTool(server, "subscriptions_dead", "Return the last 100 dead-letter outbox rows for a subscription.", { id: z8.string() }, async ({ id }) => {
|
|
1091
1110
|
const { data } = await clientProvider().subscriptions.dead(id);
|
|
1092
1111
|
return {
|
|
1093
1112
|
content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
|
|
1094
1113
|
};
|
|
1095
1114
|
});
|
|
1096
1115
|
defineTool(server, "subscriptions_requeue_dead", "Requeue one dead-letter outbox row for delivery retry.", {
|
|
1097
|
-
id:
|
|
1098
|
-
outboxId:
|
|
1116
|
+
id: z8.string(),
|
|
1117
|
+
outboxId: z8.string()
|
|
1099
1118
|
}, async ({ id, outboxId }) => {
|
|
1100
1119
|
const res = await clientProvider().subscriptions.requeueDead(id, outboxId);
|
|
1101
1120
|
return {
|
|
1102
1121
|
content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
|
|
1103
1122
|
};
|
|
1104
1123
|
});
|
|
1105
|
-
defineTool(server, "subscriptions_recent_deliveries", "Return the last 100 delivery attempts (attempt #, status code, duration, truncated response).", { id:
|
|
1124
|
+
defineTool(server, "subscriptions_recent_deliveries", "Return the last 100 delivery attempts (attempt #, status code, duration, truncated response).", { id: z8.string() }, async ({ id }) => {
|
|
1106
1125
|
const { data } = await clientProvider().subscriptions.recentDeliveries(id);
|
|
1107
1126
|
return {
|
|
1108
1127
|
content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
|
|
@@ -1123,7 +1142,6 @@ function createServer() {
|
|
|
1123
1142
|
registerSubscriptionTools(server);
|
|
1124
1143
|
registerAccountTools(server);
|
|
1125
1144
|
registerProjectTools(server);
|
|
1126
|
-
registerDatasetTools(server);
|
|
1127
1145
|
registerIndexTools(server);
|
|
1128
1146
|
registerStreamsTools(server);
|
|
1129
1147
|
registerContractTools(server);
|
|
@@ -1136,5 +1154,5 @@ var server = createServer();
|
|
|
1136
1154
|
var transport = new StdioServerTransport;
|
|
1137
1155
|
await server.connect(transport);
|
|
1138
1156
|
|
|
1139
|
-
//# debugId=
|
|
1157
|
+
//# debugId=DF363B254E9A96CE64756E2164756E21
|
|
1140
1158
|
//# sourceMappingURL=bin.js.map
|