subgraph-registry-mcp 0.6.5 → 0.7.2

package/README.md

@@ -16,11 +16,13 @@ Agents querying The Graph need to discover and select the right subgraph before
 
 1. **Crawls** all active subgraphs from the Graph Network meta-subgraph
 2. **Fetches** the GraphQL schema for every deployment
-3. **Classifies** each subgraph by domain, protocol type, canonical entities, and schema family
-4. **Scores** reliability using on-chain signals (query fees, volume, curation, stake)
-5. **Returns x402 + legacy query URLs** — agents can pay $0.01 USDC on Base per query (no API key) or use a Studio key
-6. **Publishes** as SQLite database + REST API + MCP server
-7. **Generates** visual dashboards and bot-readable category files (auto-updated with each sync)
+3. **Extracts contract addresses** from each manifest's `dataSources` and `templates` — agents can answer "which subgraph indexes contract 0x… on chain X?"
+4. **Generates a per-subgraph starter GraphQL query** from the parsed schema (real top entity, real fields, sensible orderBy) — no more generic boilerplate that doesn't compile against most subgraphs
+5. **Classifies** each subgraph by domain, protocol type, canonical entities, and schema family
+6. **Scores** reliability using on-chain signals (query fees, volume, curation, stake)
+7. **Returns x402 + legacy query URLs** — agents can pay $0.01 USDC on Base per query (no API key) or use a Studio key
+8. **Publishes** as SQLite database + REST API + MCP server + **per-subgraph JSON-LD at `/.well-known/subgraph/{id}.jsonld`** for ecosystem crawlers
+9. **Generates** visual dashboards and bot-readable category files (auto-updated with each sync)
 
 ---
 
@@ -191,6 +193,28 @@ The server auto-downloads the pre-built registry (8MB SQLite) from GitHub on fir
 
 ---
 
+## Well-Known JSON-LD Manifest
+
+Stable, machine-readable per-subgraph manifest that other crawlers and agent frameworks can index without going through MCP. Served by the Node MCP HTTP transport:
+
+```
+GET /.well-known/subgraph/{id}.jsonld     Full per-subgraph manifest (JSON-LD)
+GET /subgraphs/{id}.jsonld                 Alias (same payload)
+GET /.well-known/subgraph-index.jsonld     Discovery list — top 100 by reliability with @id links
+```
+
+Each manifest includes classification, parsed entities, contract addresses (from the indexed `dataSources`), endpoints (x402 + API-key), a per-subgraph starter query generated from the actual schema, pricing, and metadata. The `@context` + `@type` make the shape auto-discoverable.
+
+```bash
+# Start the HTTP transport
+npx subgraph-registry-mcp --http-only
+
+# Fetch the manifest for Uniswap V3 Mainnet
+curl http://localhost:3848/.well-known/subgraph/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV.jsonld
+```
+
+---
+
 ## REST API
 
 ```
@@ -199,7 +223,7 @@ GET /domains                    Domain breakdown
 GET /networks                   Network breakdown
 GET /families                   Schema family groups (fork/clone detection)
 GET /subgraphs                  Filter subgraphs
-GET /subgraphs/{id}             Full detail for one subgraph
+GET /subgraphs/{id}             Full detail for one subgraph (now includes contract_addresses and example_query)
 GET /search?q=uniswap           Free-text search
 GET /recommend?goal=...&chain=  Agent-optimized recommendation
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "subgraph-registry-mcp",
-  "version": "0.6.5",
+  "version": "0.7.2",
   "mcpName": "io.github.PaulieB14/subgraph-registry-mcp",
   "description": "MCP server for agent-friendly subgraph discovery on The Graph Network. 14,733 classified subgraphs with x402 query URLs ($0.01 USDC on Base, no API key required), reliability scoring, and protocol classification.",
   "type": "module",

package/src/index.js

@@ -45,7 +45,7 @@ const GITHUB_DB_URL =
 //   3. Paste the new hash here and bump package.json version
 //   4. Update SKILL.md "Verifying the registry" section
 const EXPECTED_DB_SHA256 =
-  "76cf707f196a9876c35b085bac775e51970e7306a7890c598b46996c46593bed";
+  "76943c2037bc63546408ca8d8531ce8b76415fccfb455e13cc4c805d5f440f68";
 // Skip-verification escape hatch (set to "1" only if you're rebuilding the DB
 // locally and know what you're doing — never set in agent-runtime defaults).
 const SKIP_VERIFY = process.env.SUBGRAPH_REGISTRY_SKIP_VERIFY === "1";
@@ -365,6 +365,13 @@ function getSubgraphDetail({ subgraph_id }) {
   result.canonical_entities = JSON.parse(result.canonical_entities);
   result.categories = JSON.parse(result.categories);
   if (result.all_entities) result.all_entities = JSON.parse(result.all_entities);
+  // Contract addresses extracted from the manifest — list of
+  // {kind, name, address, network, startBlock}. Null on subgraphs we
+  // haven't crawled with manifest support yet, or substreams-powered ones.
+  if (result.contract_addresses) {
+    try { result.contract_addresses = JSON.parse(result.contract_addresses); }
+    catch { /* leave as string if not valid JSON */ }
+  }
   if (!result.description && result.auto_description) {
     result.description = result.auto_description;
   }
@@ -372,6 +379,14 @@ function getSubgraphDetail({ subgraph_id }) {
   result.query_url = endpoints.query_url;
   result.query_url_x402 = endpoints.query_url_x402;
   result.pricing = endpoints.pricing;
+
+  // Per-subgraph starter query generated by the crawler from this subgraph's
+  // parsed schema. Falls back to the legacy generic example when the column
+  // is empty (pre-feature DBs).
+  const FALLBACK_EXAMPLE =
+    "{ pools(first: 5, orderBy: totalValueLockedUSD, orderDirection: desc) { id token0 { symbol } token1 { symbol } totalValueLockedUSD } }";
+  const exampleQuery = result.example_query || FALLBACK_EXAMPLE;
+
   result.query_instructions = {
     recommended: "x402",
     x402: {
@@ -379,17 +394,60 @@ function getSubgraphDetail({ subgraph_id }) {
       payment: endpoints.pricing,
       flow: "POST GraphQL to url. Gateway returns HTTP 402 with a base64 payment-required header containing the payment manifest. Sign $0.01 USDC on Base with an x402 client and retry. No API key, no signup.",
       client_libraries: ["@graphprotocol/client-x402", "x402-fetch"],
-      example_query: "{ pools(first: 5, orderBy: totalValueLockedUSD, orderDirection: desc) { id token0 { symbol } token1 { symbol } totalValueLockedUSD } }",
+      example_query: exampleQuery,
     },
     api_key_legacy: {
       url: endpoints.query_url,
       flow: "Get an API key from https://thegraph.com/studio/apikeys/, replace [api-key] in the url, then POST GraphQL.",
     },
-    schema_hint: "Use the all_entities field above to see what entities and fields are available to query.",
+    schema_hint: result.example_query
+      ? "example_query above was generated from this subgraph's actual schema. Adapt the entity name + field selection as needed."
+      : "Use the all_entities field above to see what entities and fields are available to query.",
   };
   return result;
 }
 
+
+// ── JSON-LD per-subgraph well-known shape ─────────────────────────────────
+// Stable, machine-readable manifest other crawlers and agents can index
+// without going through MCP. Served at /.well-known/subgraph/{id}.jsonld and
+// /subgraphs/{id}.jsonld (alias, same payload).
+const JSONLD_CONTEXT = "https://subgraph-registry.paulieb14.dev/context.jsonld";
+
+function buildJsonLdManifest(row) {
+  if (!row) return null;
+  const detail = getSubgraphDetail({ subgraph_id: row.id });
+  if (detail?.error) return null;
+  return {
+    "@context": JSONLD_CONTEXT,
+    "@type": "SubgraphDeployment",
+    "@id": `https://subgraph-registry.paulieb14.dev/subgraphs/${row.id}`,
+    id: row.id,
+    ipfsHash: row.ipfs_hash,
+    name: row.display_name,
+    description: row.description || row.auto_description,
+    network: row.network,
+    classification: {
+      domain: row.domain,
+      protocolType: row.protocol_type,
+      confidence: row.classification_confidence,
+    },
+    entities: detail.all_entities || [],
+    canonicalEntities: detail.canonical_entities || [],
+    contracts: detail.contract_addresses || null,
+    reliabilityScore: row.reliability_score,
+    activeIndexers: row.active_allocation_count,
+    queryVolume30d: row.query_volume_30d,
+    endpoints: {
+      x402: detail.query_url_x402,
+      apiKey: detail.query_url,
+    },
+    exampleQuery: detail.query_instructions?.x402?.example_query || null,
+    poweredBySubstreams: !!row.powered_by_substreams,
+    pricing: detail.pricing,
+  };
+}
+
 function listRegistryStats() {
   const d = getDb();
   const domains = d
@@ -542,8 +600,59 @@ function startHttpTransport(port) {
     res.json({ status: "ok", subgraphs: getDb().prepare("SELECT COUNT(*) as c FROM subgraphs").get().c });
   });
 
+  // ── Stable per-subgraph manifest for ecosystem crawlers ───────────────
+  // Other tools (E&N tooling, indexer dashboards, agent frameworks) can
+  // hit this without needing MCP. JSON-LD so the shape is auto-discoverable.
+  const serveManifest = (req, res) => {
+    const id = req.params.id;
+    const row = getDb()
+      .prepare("SELECT * FROM subgraphs WHERE id = ? OR ipfs_hash = ?")
+      .get(id, id);
+    if (!row) {
+      res.status(404).json({ error: `Subgraph '${id}' not found` });
+      return;
+    }
+    const manifest = buildJsonLdManifest(row);
+    if (!manifest) {
+      res.status(500).json({ error: "Manifest build failed" });
+      return;
+    }
+    res.type("application/ld+json").json(manifest);
+  };
+
+  // Canonical .well-known location + a friendlier alias under /subgraphs/
+  app.get("/.well-known/subgraph/:id.jsonld", serveManifest);
+  app.get("/subgraphs/:id.jsonld", serveManifest);
+
+  // Discovery index so a crawler that doesn't know the ID can find one:
+  // returns the top 100 by reliability with their .jsonld URLs.
+  app.get("/.well-known/subgraph-index.jsonld", (_req, res) => {
+    const rows = getDb()
+      .prepare(
+        "SELECT id, display_name, network, domain, reliability_score " +
+        "FROM subgraphs WHERE active_allocation_count > 0 " +
+        "ORDER BY reliability_score DESC LIMIT 100"
+      ).all();
+    res.type("application/ld+json").json({
+      "@context": JSONLD_CONTEXT,
+      "@type": "SubgraphIndex",
+      generatedAt: new Date().toISOString(),
+      count: rows.length,
+      subgraphs: rows.map((r) => ({
+        "@id": `https://subgraph-registry.paulieb14.dev/subgraphs/${r.id}`,
+        id: r.id,
+        name: r.display_name,
+        network: r.network,
+        domain: r.domain,
+        reliabilityScore: r.reliability_score,
+        manifest: `/.well-known/subgraph/${r.id}.jsonld`,
+      })),
+    });
+  });
+
   app.listen(port, () => {
     console.error(`SSE transport listening on http://localhost:${port}/sse`);
+    console.error(`Well-known manifest at http://localhost:${port}/.well-known/subgraph/{id}.jsonld`);
   });
 }