@secondlayer/mcp 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,106 @@
+# @secondlayer/mcp
+
+MCP server for the Second Layer indexing platform.
+
+## Install
+
+```bash
+bun add @secondlayer/mcp
+```
+
+## Quick Start — Stdio (IDE)
+
+Add to your Claude Desktop or Cursor config:
+
+```json
+{
+  "mcpServers": {
+    "secondlayer": {
+      "command": "npx",
+      "args": ["@secondlayer/mcp"],
+      "env": {
+        "SECONDLAYER_API_KEY": "sl_live_..."
+      }
+    }
+  }
+}
+```
+
+## Quick Start — HTTP (Remote)
+
+```bash
+export SECONDLAYER_API_KEY=sl_live_...
+export SECONDLAYER_MCP_SECRET=your-secret
+npx @secondlayer/mcp-http
+# Listening on port 3100
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `SECONDLAYER_API_KEY` | Yes | — | API key |
+| `SECONDLAYER_MCP_PORT` | No | `3100` | HTTP transport port |
+| `SECONDLAYER_MCP_SECRET` | No | — | Bearer token for HTTP auth. Disabled if unset. |
+
+## Tools
+
+22 tools across 5 domains.
+
+| Domain | Tools |
+| --- | --- |
+| **Streams** (11) | `streams_list`, `streams_get`, `streams_create`, `streams_update`, `streams_delete`, `streams_toggle`, `streams_deliveries`, `streams_pause_all`, `streams_resume_all`, `streams_replay`, `streams_rotate_secret` |
+| **Subgraphs** (6) | `subgraphs_list`, `subgraphs_get`, `subgraphs_query`, `subgraphs_reindex`, `subgraphs_delete`, `subgraphs_deploy` |
+| **Scaffold** (2) | `scaffold_from_contract`, `scaffold_from_abi` |
+| **Templates** (2) | `templates_list`, `templates_get` |
+| **Account** (1) | `account_whoami` |
+
+### `subgraphs_query` enhancements
+
+- `fields` — comma-separated column projection (e.g. `"sender,amount_x"`)
+- `count` — boolean, returns row count instead of rows
+- Filter operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`
+- Max limit raised from 50 to 200
+
+## Resources
+
+3 MCP resources for agent context:
+
+| URI | Description |
+| --- | --- |
+| `secondlayer://filters` | Filter types reference |
+| `secondlayer://column-types` | Column type mappings and options |
+| `secondlayer://templates` | Available subgraph templates |
+
+## Error Handling
+
+All tools return structured errors with `isError: true`:
+
+```json
+{ "error": { "type": "not_found", "status": 404, "message": "Stream not found" } }
+```
+
+| Error type | Status | When |
+| --- | --- | --- |
+| `unauthorized` | 401 | Invalid or missing API key |
+| `not_found` | 404 | Resource doesn't exist |
+| `rate_limited` | 429 | Too many requests |
+| `server_error` | 5xx | Server-side failure |
+| `error` | other | Validation, bundling, etc. |
+
+Bundle/deploy errors use descriptive prefixes: `"Bundle failed:"`, `"Module evaluation failed:"`, `"Validation failed:"`.
+
+HTTP transport enforces a 1MB body limit (413) and JSON parse safety (400). Scaffold ABI fetch has a 10s timeout.
+
+## Programmatic Usage
+
+```typescript
+import { createServer } from "@secondlayer/mcp";
+
+const server = createServer();
+// Connect to your own transport
+```
+
+## License
+
+MIT

package/dist/bin-http.js

@@ -5,6 +5,9 @@ import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
 // src/server.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/tools/templates.ts
@@ -13,7 +16,20 @@ import { templates, getTemplateById, getTemplatesByCategory } from "@secondlayer
 
 // src/lib/tool.ts
 function defineTool(server, name, description, schema, handler) {
-  server.tool(name, description, schema, handler);
+  const wrappedHandler = async (args) => {
+    try {
+      return await handler(args);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const status = err instanceof Error && "status" in err ? err.status : 0;
+      const type = status === 401 ? "unauthorized" : status === 404 ? "not_found" : status === 429 ? "rate_limited" : status >= 500 ? "server_error" : "error";
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: { type, status, message } }) }],
+        isError: true
+      };
+    }
+  };
+  server.tool(name, description, schema, wrappedHandler);
 }
 
 // src/tools/templates.ts
@@ -228,7 +244,9 @@ ${handlersBlock}
 // src/tools/scaffold.ts
 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`);
+  const res = await fetch(`${API_BASE}/api/node/contracts/${contractId}/abi`, {
+    signal: AbortSignal.timeout(1e4)
+  });
   if (!res.ok) {
     if (res.status === 404)
       throw new Error(`Contract not found: ${contractId}`);
@@ -281,6 +299,24 @@ function getClient() {
   }
   return instance;
 }
+async function apiRequest(method, path, body) {
+  const apiKey = process.env.SECONDLAYER_API_KEY;
+  if (!apiKey)
+    throw new Error("SECONDLAYER_API_KEY required");
+  const baseUrl = process.env.SECONDLAYER_API_URL || "https://api.secondlayer.tools";
+  const res = await fetch(`${baseUrl}${path}`, {
+    method,
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+    body: body ? JSON.stringify(body) : undefined
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw Object.assign(new Error(text || `HTTP ${res.status}`), { status: res.status });
+  }
+  if (res.status === 204)
+    return;
+  return res.json();
+}
 
 // src/lib/format.ts
 function formatStreamSummary(s) {
@@ -434,6 +470,18 @@ function registerStreamTools(server) {
       }]
     };
   });
+  defineTool(server, "streams_replay", "Replay blocks through a stream, re-delivering events for a block range.", {
+    id: z3.string().describe("Stream UUID or prefix"),
+    fromBlock: z3.number().describe("Start block height (inclusive)"),
+    toBlock: z3.number().describe("End block height (inclusive)")
+  }, async ({ id, fromBlock, toBlock }) => {
+    const result = await apiRequest("POST", `/api/streams/${id}/replay`, { fromBlock, toBlock });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+  defineTool(server, "streams_rotate_secret", "Rotate the signing secret for a stream. Returns the new secret.", { id: z3.string().describe("Stream UUID or prefix") }, async ({ id }) => {
+    const result = await getClient().streams.rotateSecret(id);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
 }
 
 // src/tools/subgraphs.ts
@@ -444,19 +492,34 @@ import esbuild from "esbuild";
 import { validateSubgraphDefinition } from "@secondlayer/subgraphs/validate";
 import { sourceKey } from "@secondlayer/subgraphs";
 async function bundleSubgraphCode(code) {
-  const result = await esbuild.build({
-    stdin: { contents: code, loader: "ts", resolveDir: process.cwd() },
-    bundle: true,
-    platform: "node",
-    format: "esm",
-    external: ["@secondlayer/subgraphs"],
-    write: false
-  });
+  let result;
+  try {
+    result = await esbuild.build({
+      stdin: { contents: code, loader: "ts", resolveDir: process.cwd() },
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      external: ["@secondlayer/subgraphs"],
+      write: false
+    });
+  } catch (err) {
+    throw new Error(`Bundle failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
   const handlerCode = new TextDecoder().decode(result.outputFiles[0].contents);
-  const dataUri = `data:text/javascript;base64,${Buffer.from(handlerCode).toString("base64")}`;
-  const mod = await import(dataUri);
+  let mod;
+  try {
+    const dataUri = `data:text/javascript;base64,${Buffer.from(handlerCode).toString("base64")}`;
+    mod = await import(dataUri);
+  } catch (err) {
+    throw new Error(`Module evaluation failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
   const def = mod.default ?? mod;
-  const validated = validateSubgraphDefinition(def);
+  let validated;
+  try {
+    validated = validateSubgraphDefinition(def);
+  } catch (err) {
+    throw new Error(`Validation failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
   return {
     name: validated.name,
     version: validated.version,
@@ -479,23 +542,31 @@ function registerSubgraphTools(server) {
     const detail = await getClient().subgraphs.get(name);
     return { content: [{ type: "text", text: JSON.stringify(detail, null, 2) }] };
   });
-  defineTool(server, "subgraphs_query", "Query rows from a subgraph table (max 50 rows).", {
+  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.', {
     name: z4.string().describe("Subgraph name"),
     table: z4.string().describe("Table name"),
-    filters: z4.record(z4.string(), z4.string()).optional().describe('Column filters as key-value pairs (e.g. {"sender": "SP..."})'),
+    filters: z4.record(z4.string(), z4.string()).optional().describe('Column filters — plain values or with operators (e.g. {"amount.gte": "1000", "sender": "SP..."})'),
     sort: z4.string().optional().describe("Column to sort by"),
     order: z4.enum(["asc", "desc"]).optional().describe("Sort order"),
-    limit: z4.number().max(50).optional().describe("Max rows (default 50)"),
-    offset: z4.number().optional().describe("Offset for pagination")
-  }, async ({ name, table, filters, sort, order, limit, offset }) => {
+    limit: z4.number().max(200).optional().describe("Max rows (default 50, max 200)"),
+    offset: z4.number().optional().describe("Offset for pagination"),
+    fields: z4.string().optional().describe('Comma-separated column list to return (e.g. "sender,amount")'),
+    count: z4.boolean().optional().describe("If true, return row count instead of rows")
+  }, async ({ name, table, filters, sort, order, limit, offset, fields, count }) => {
+    if (count) {
+      const result2 = await getClient().subgraphs.queryTableCount(name, table, { filters, sort, order });
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
     const rows = await getClient().subgraphs.queryTable(name, table, {
       filters,
       sort,
       order,
       limit: limit ?? 50,
-      offset
+      offset,
+      fields
     });
-    const result = withCap(rows, 50);
+    const cap = limit ?? 50;
+    const result = withCap(rows, cap > 200 ? 200 : cap);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
   defineTool(server, "subgraphs_reindex", "Reindex a subgraph from a specific block range.", {
@@ -530,16 +601,81 @@ function registerSubgraphTools(server) {
   });
 }
 
+// src/tools/account.ts
+function registerAccountTools(server) {
+  defineTool(server, "account_whoami", "Show the authenticated account's email and plan.", {}, async () => {
+    const result = await apiRequest("GET", "/api/accounts/me");
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+}
+
+// src/resources.ts
+import { templates as templates2 } from "@secondlayer/subgraphs/templates";
+var FILTERS_REFERENCE = [
+  { type: "stx_transfer", fields: ["sender", "recipient", "minAmount", "maxAmount"] },
+  { type: "stx_mint", fields: ["recipient", "minAmount"] },
+  { type: "stx_burn", fields: ["sender", "minAmount"] },
+  { type: "stx_lock", fields: ["lockedAddress", "minAmount"] },
+  { type: "ft_transfer", fields: ["sender", "recipient", "assetIdentifier", "minAmount"] },
+  { type: "ft_mint", fields: ["recipient", "assetIdentifier", "minAmount"] },
+  { type: "ft_burn", fields: ["sender", "assetIdentifier", "minAmount"] },
+  { type: "nft_transfer", fields: ["sender", "recipient", "assetIdentifier", "tokenId"] },
+  { type: "nft_mint", fields: ["recipient", "assetIdentifier", "tokenId"] },
+  { type: "nft_burn", fields: ["sender", "assetIdentifier", "tokenId"] },
+  { type: "contract_call", fields: ["contractId", "functionName", "caller"] },
+  { type: "contract_deploy", fields: ["deployer", "contractName"] },
+  { type: "print_event", fields: ["contractId", "topic", "contains"] }
+];
+var COLUMN_TYPES = [
+  { type: "uint", sqlType: "bigint", description: "Unsigned integer (Clarity uint)" },
+  { type: "int", sqlType: "bigint", description: "Signed integer (Clarity int)" },
+  { type: "text", sqlType: "text", description: "UTF-8 string" },
+  { type: "principal", sqlType: "text", description: "Stacks address (standard or contract)" },
+  { type: "bool", sqlType: "boolean", description: "Boolean value" },
+  { type: "json", sqlType: "jsonb", description: "Arbitrary JSON data" },
+  {
+    options: ["nullable", "indexed", "search"],
+    description: "Column options: nullable allows NULL, indexed creates a B-tree index, search enables full-text search"
+  }
+];
+function registerResources(server) {
+  server.resource("filters", "secondlayer://filters", { description: "Stream filter types and their available fields" }, async () => ({
+    contents: [{
+      uri: "secondlayer://filters",
+      mimeType: "application/json",
+      text: JSON.stringify(FILTERS_REFERENCE, null, 2)
+    }]
+  }));
+  server.resource("column-types", "secondlayer://column-types", { description: "Subgraph column types, SQL mappings, and options" }, async () => ({
+    contents: [{
+      uri: "secondlayer://column-types",
+      mimeType: "application/json",
+      text: JSON.stringify(COLUMN_TYPES, null, 2)
+    }]
+  }));
+  server.resource("templates", "secondlayer://templates", { description: "Available subgraph templates with descriptions and categories" }, async () => ({
+    contents: [{
+      uri: "secondlayer://templates",
+      mimeType: "application/json",
+      text: JSON.stringify(templates2.map(({ id, name, description, category }) => ({ id, name, description, category })), null, 2)
+    }]
+  }));
+}
+
 // src/server.ts
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(join(__dirname2, "../package.json"), "utf-8"));
 function createServer() {
   const server = new McpServer({
     name: "secondlayer",
-    version: "0.1.0"
+    version: pkg.version
   });
   registerTemplateTools(server);
   registerScaffoldTools(server);
   registerStreamTools(server);
   registerSubgraphTools(server);
+  registerAccountTools(server);
+  registerResources(server);
   return server;
 }
 
@@ -564,10 +700,24 @@ var httpServer = createHttpServer(async (req, res) => {
   }
   const sessionId = req.headers["mcp-session-id"];
   if (req.method === "POST") {
+    const MAX_BODY = 1048576;
     const chunks = [];
-    for await (const chunk of req)
+    let totalSize = 0;
+    for await (const chunk of req) {
+      totalSize += chunk.length;
+      if (totalSize > MAX_BODY) {
+        res.writeHead(413).end(JSON.stringify({ error: "Request body too large" }));
+        return;
+      }
       chunks.push(chunk);
-    const body = JSON.parse(Buffer.concat(chunks).toString());
+    }
+    let body;
+    try {
+      body = JSON.parse(Buffer.concat(chunks).toString());
+    } catch {
+      res.writeHead(400).end(JSON.stringify({ error: "Invalid JSON" }));
+      return;
+    }
     const isInitialize = Array.isArray(body) ? body.some((m) => m.method === "initialize") : body.method === "initialize";
     if (isInitialize) {
       const transport = new StreamableHTTPServerTransport({
@@ -615,5 +765,5 @@ httpServer.listen(port, () => {
     console.error("Warning: SECONDLAYER_MCP_SECRET not set, authentication disabled");
 });
 
-//# debugId=EE7F6293C5F1832F64756E2164756E21
+//# debugId=B8BDE1F4EEC0CB2664756E2164756E21
 //# sourceMappingURL=bin-http.js.map