substreams-search-mcp 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# Substreams Search MCP Server
+
+MCP server that lets AI agents search the [substreams.dev](https://substreams.dev) package registry.
+
+## Tool: `search_substreams`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | string (required) | — | Search term, e.g. `"solana dex"` or `"uniswap"` |
+| `sort` | string | `"most_downloaded"` | `most_downloaded`, `alphabetical`, `most_used`, `last_uploaded` |
+| `network` | string | — | Filter by chain: `ethereum`, `solana`, `arbitrum-one`, etc. |
+
+Returns JSON with package name, URL, creator, network, version, published date, and download count.
+
+## Setup
+
+```bash
+git clone https://github.com/PaulieB14/substreams-search-mcp.git
+cd substreams-search-mcp
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "substreams-search": {
+      "command": "/path/to/substreams-search-mcp/.venv/bin/python3",
+      "args": ["/path/to/substreams-search-mcp/server.py"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "substreams-search": {
+      "command": "/path/to/substreams-search-mcp/.venv/bin/python3",
+      "args": ["/path/to/substreams-search-mcp/server.py"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "substreams-search": {
+      "command": "/path/to/substreams-search-mcp/.venv/bin/python3",
+      "args": ["/path/to/substreams-search-mcp/server.py"]
+    }
+  }
+}
+```
+
+## How it works
+
+The substreams.dev registry has no public API. This server scrapes the package listing pages, paginates through all results, deduplicates, and returns structured JSON. Multi-word queries search for the first word server-side and filter the rest client-side.

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { parse } from "node-html-parser";
+const REGISTRY_URL = "https://substreams.dev/packages";
+const PAGE_SIZE = 24;
+const MAX_PAGES = 50;
+function parseCards(html) {
+    const root = parse(html);
+    const grid = root.querySelector("#packages-grid");
+    if (!grid)
+        return [];
+    const packages = [];
+    for (const link of grid.querySelectorAll("a.block")) {
+        const href = link.getAttribute("href");
+        if (!href)
+            continue;
+        const nameEl = link.querySelector("p.font-semibold");
+        const name = nameEl?.text?.trim() || href.split("/")[2] || "";
+        const creatorBtn = link.querySelector("button.user-filter-link");
+        const creator = creatorBtn?.getAttribute("data-user") || creatorBtn?.text?.trim() || "";
+        const networkBtn = link.querySelector("button.network-filter-link");
+        const network = networkBtn?.getAttribute("data-network") || "";
+        const bottom = link.querySelector("div.absolute");
+        let version = "";
+        let published = "";
+        let downloads = "";
+        if (bottom) {
+            for (const row of bottom.querySelectorAll("div.flex-row")) {
+                const labels = row.querySelectorAll("p");
+                if (labels.length < 2)
+                    continue;
+                const label = labels[0].text.trim().toLowerCase();
+                const value = labels[labels.length - 1].text.trim();
+                if (label.includes("version"))
+                    version = value;
+                else if (label.includes("publish"))
+                    published = value;
+                else if (label.includes("download"))
+                    downloads = value;
+            }
+        }
+        packages.push({
+            name,
+            url: `https://substreams.dev${href}`,
+            creator,
+            network,
+            version,
+            published,
+            downloads,
+        });
+    }
+    return packages;
+}
+async function fetchPackages(query, sort = "most_downloaded", network) {
+    const words = query.trim().split(/\s+/);
+    const searchTerm = words[0] || query;
+    const extraWords = words.slice(1).map((w) => w.toLowerCase());
+    const allPackages = [];
+    const seenUrls = new Set();
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const params = new URLSearchParams({
+            search: searchTerm,
+            sort,
+            page: String(page),
+        });
+        if (network)
+            params.set("network", network);
+        const resp = await fetch(`${REGISTRY_URL}?${params}`);
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}: ${resp.statusText}`);
+        const html = await resp.text();
+        const pagePackages = parseCards(html);
+        if (pagePackages.length === 0)
+            break;
+        for (const pkg of pagePackages) {
+            if (!seenUrls.has(pkg.url)) {
+                seenUrls.add(pkg.url);
+                allPackages.push(pkg);
+            }
+        }
+        if (pagePackages.length < PAGE_SIZE)
+            break;
+    }
+    if (extraWords.length > 0) {
+        return allPackages.filter((p) => extraWords.every((w) => p.name.toLowerCase().includes(w) ||
+            p.creator.toLowerCase().includes(w) ||
+            p.network.toLowerCase().includes(w)));
+    }
+    return allPackages;
+}
+const server = new McpServer({
+    name: "substreams-search",
+    version: "1.0.0",
+});
+server.registerTool("search_substreams", {
+    description: "Search the substreams.dev package registry for blockchain data stream packages. " +
+        "Multi-word queries filter results to match all words.",
+    inputSchema: {
+        query: z
+            .string()
+            .describe("Search term, e.g. 'solana dex' or 'uniswap'"),
+        sort: z
+            .enum(["most_downloaded", "alphabetical", "most_used", "last_uploaded"])
+            .optional()
+            .default("most_downloaded")
+            .describe("Sort order"),
+        network: z
+            .string()
+            .optional()
+            .describe("Filter by blockchain network, e.g. 'ethereum', 'solana', 'arbitrum-one'"),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ query, sort, network }) => {
+    const packages = await fetchPackages(query, sort, network);
+    const result = packages.length === 0
+        ? { results: [], message: `No packages found for '${query}'` }
+        : { results: packages, count: packages.length };
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("substreams-search-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,MAAM,YAAY,GAAG,iCAAiC,CAAC;AACvD,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,SAAS,GAAG,EAAE,CAAC;AAYrB,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAClD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAE9D,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,yBAAyB,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,UAAU,EAAE,YAAY,CAAC,WAAW,CAAC,IAAI,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAExF,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,4BAA4B,CAAC,CAAC;QACpE,MAAM,OAAO,GAAG,UAAU,EAAE,YAAY,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAE/D,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC;QAClD,IAAI,OAAO,GAAG,EAAE,CAAC;QACjB,IAAI,SAAS,GAAG,EAAE,CAAC;QACnB,IAAI,SAAS,GAAG,EAAE,CAAC;QAEnB,IAAI,MAAM,EAAE,CAAC;YACX,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC1D,MAAM,MAAM,GAAG,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;gBACzC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;oBAAE,SAAS;gBAChC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;gBAClD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACpD,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;oBAAE,OAAO,GAAG,KAAK,CAAC;qBAC1C,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;oBAAE,SAAS,GAAG,KAAK,CAAC;qBACjD,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;oBAAE,SAAS,GAAG,KAAK,CAAC;YACzD,CAAC;QACH,CAAC;QAED,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI;YACJ,GAAG,EAAE,yBAAyB,IAAI,EAAE;YACpC,OAAO;YACP,OAAO;YACP,OAAO;YACP,SAAS;YACT,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,KAAa,EACb,OAAe,iBAAiB,EAChC,OAAgB;IAEhB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;IACrC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAE9D,MAAM,WAAW,GAAc,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IAEnC,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;YACjC,MAAM,EAAE,UAAU;YAClB,IAAI;YACJ,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;SACnB,CAAC,CAAC;QACH,IAAI,OAAO;YAAE,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAE5C,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,YAAY,IAAI,MAAM,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAEzE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAEtC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAErC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACtB,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,GAAG,SAAS;YAAE,MAAM;IAC7C,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9B,UAAU,CAAC,KAAK,CACd,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;YAChC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;YACnC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CACtC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,mBAAmB;IACzB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;IACE,WAAW,EACT,kFAAkF;QAClF,uDAAuD;IACzD,WAAW,EAAE;QACX,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,CAAC,6CAA6C,CAAC;QAC1D,IAAI,EAAE,CAAC;aACJ,IAAI,CAAC,CAAC,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;aACvE,QAAQ,EAAE;aACV,OAAO,CAAC,iBAAiB,CAAC;aAC1B,QAAQ,CAAC,YAAY,CAAC;QACzB,OAAO,EAAE,CAAC;aACP,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,yEAAyE,CAC1E;KACJ;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IACjC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAE3D,MAAM,MAAM,GACV,QAAQ,CAAC,MAAM,KAAK,CAAC;QACnB,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,0BAA0B,KAAK,GAAG,EAAE;QAC9D,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IAEpD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC5E,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;AAC1D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "substreams-search-mcp",
+  "version": "1.0.0",
+  "description": "MCP server to search the substreams.dev package registry",
+  "type": "module",
+  "bin": {
+    "substreams-search-mcp": "build/index.js"
+  },
+  "main": "./build/index.js",
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "start": "node build/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [
+    "mcp",
+    "substreams",
+    "blockchain",
+    "ai",
+    "claude",
+    "the-graph"
+  ],
+  "author": "PaulieB14",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PaulieB14/substreams-search-mcp.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "node-html-parser": "^7.0.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}