MCP 服务器

Subgraph Registry MCP

Agent-friendly semantic classification of all subgraphs on The Graph Network. Pre-computed index of 15,500+ subgraphs with domain classification, protocol type detection, schema fingerprinting, canonical entity mapping, and composite reliability scoring.

README

Subgraph Registry

Agent-friendly semantic classification of all subgraphs on The Graph Network.

Pre-computed index of 15,500+ subgraphs with domain classification, protocol type detection, schema fingerprinting, canonical entity mapping, and composite reliability scoring.

The Problem

Agents querying The Graph need to discover and select the right subgraph before they can query data. Today this requires 3-4 tool calls (search, check volumes, fetch schema, infer structure) before any real work happens. This registry flips that: agents start with structured knowledge, not a blank slate.

What It Does

Crawls all active subgraphs from the Graph Network meta-subgraph (subgraphs indexing subgraphs)
Fetches the GraphQL schema for every deployment
Classifies each subgraph by:
- Domain: DeFi, NFTs, DAOs, Gaming, Identity, Infrastructure, Social, Analytics
- Protocol Type: DEX, Lending, Bridge, Staking, Options, Perpetuals, Marketplace, etc.
- Canonical Entities: Maps schema types to a standard vocabulary (Pool -> liquidity_pool, Swap -> trade, etc.)
- Schema Family: Groups forks/clones by schema fingerprint
Scores reliability (see Reliability Score below)
Publishes as JSON registry + SQLite database + REST API

Quick Start

cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Create .env with your Graph API key
echo "GATEWAY_API_KEY=your-key-here" > .env

# Full crawl + classify (all 15K+ subgraphs, ~11 min)
python registry.py

# Or limit to top N by signal
python registry.py --max 500

# Start API server
python server.py

API Endpoints

GET /summary                    Registry overview and stats
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 /search?q=uniswap           Free-text search
GET /recommend?goal=...&chain=  Agent-optimized recommendation

Example: Agent Recommendation

curl "http://localhost:3847/recommend?goal=query+DEX+trades+on+Arbitrum&chain=arbitrum-one"

Returns the top subgraphs matching the intent, with reliability scores and query instructions.

Example: Filter by Entity Type

curl "http://localhost:3847/subgraphs?entity=liquidity_pool&network=base&min_reliability=0.5"

Weekly Sync

# Run weekly incremental updates (only fetches new/changed subgraphs)
python scheduler.py

# One-shot incremental
python scheduler.py --once

Architecture

Graph Network Subgraph (meta-subgraph, 140M queries/month)
    |
    v
crawler.py ---- async httpx, ID-based cursor pagination (bypasses 5K skip limit)
    |
    v
classifier.py - rule-based domain/protocol classification + schema fingerprinting
    |
    v
registry.py --- builds JSON registry + SQLite + indices
    |
    v
server.py ----- FastAPI REST API with /recommend endpoint (:3847)
    |
    v
scheduler.py -- weekly incremental sync via updatedAt filtering

MCP Server (src/index.js)
    |
    ├── stdio transport  ←── Claude Desktop / Claude Code (npx command)
    └── SSE/HTTP :3848   ←── OpenClaw / remote agents (--http flag)

Output

File	Size	Description
`registry.json`	~130 MB	Full registry with all entity details
`registry.db`	~8 MB	SQLite with indexed lookups
`sync-state.json`	<1 KB	Last sync timestamp for incremental updates

Classification Results (as of March 2026)

Domain	Count	Network	Count
DeFi	11,841	Ethereum	2,471
NFTs	893	Base	1,845
Infrastructure	602	BSC	1,664
DAO	450	Arbitrum	1,442
Identity	424	Polygon	1,364
Analytics	348	Optimism	593
Gaming	255	Avalanche	454
Social	78

Reliability Score

Each subgraph gets a composite reliability score (0–1) based on four on-chain signals:

Signal	Weight	What it measures	Source
Query Fees	30%	GRT fees earned from actual usage — proves real demand	Network subgraph
Query Volume	30%	30-day query count — recent activity level	QoS subgraph
Curation Signal	20%	GRT tokens curated — community vote of confidence	Network subgraph
Indexer Stake	20%	GRT staked by indexers — skin in the game	Network subgraph

All values are log-scaled and capped at 1.0. Usage signals (fees + volume) are weighted higher at 60% because they prove real demand. A 0.5 penalty is applied if the subgraph has been denied/deprecated.

What the scores mean:

0.7–1.0: High reliability — strong signal, active indexers, real usage (e.g. Uniswap, Aave)
0.3–0.7: Moderate — some signal and usage, likely functional
0.0–0.3: Low — minimal signal, may be inactive or a test deployment

MCP Server

The registry is available as an MCP server for agent integration. It supports dual transport — stdio for local clients (Claude Desktop, Claude Code) and SSE/HTTP for remote agents (OpenClaw, custom agent frameworks).

It exposes 4 tools:

search_subgraphs — filter by domain, network, protocol type, entity, or keyword
recommend_subgraph — natural language goal to best subgraphs
get_subgraph_detail — full classification for a specific subgraph
list_registry_stats — registry overview (domains, networks, counts)

Install via NPM

npx subgraph-registry-mcp

Add to Claude Desktop (stdio)

{
  "mcpServers": {
    "subgraph-registry": {
      "command": "npx",
      "args": ["subgraph-registry-mcp"]
    }
  }
}

Add to OpenClaw / Remote Agents (SSE)

Start the server with the HTTP transport:

# Dual transport — stdio + SSE on port 3848
npx subgraph-registry-mcp --http

# SSE only (for remote/server deployments)
npx subgraph-registry-mcp --http-only

# Custom port
MCP_HTTP_PORT=4000 npx subgraph-registry-mcp --http

Then point your agent at the SSE endpoint:

{
  "mcpServers": {
    "subgraph-registry": {
      "url": "http://localhost:3848/sse"
    }
  }
}

Transport Modes

Invocation	Transports	Use case
`npx subgraph-registry-mcp`	stdio	Claude Desktop, Claude Code
`npx subgraph-registry-mcp --http`	stdio + SSE :3848	Dual — local + remote agents
`npx subgraph-registry-mcp --http-only`	SSE :3848	OpenClaw, remote deployments

A /health endpoint is available at http://localhost:3848/health when HTTP transport is active.

The server auto-downloads the pre-built registry (8MB SQLite) from GitHub on first run — no local build needed.

How It Stays Current

The Graph Network subgraph indexes all subgraph deployments on-chain. The crawler queries updatedAt_gte: lastSyncTimestamp to fetch only what changed since the last run. Weekly syncs keep the registry fresh without full rebuilds.