GRAPHQL Endpoint Discovery

GraphQL Endpoint Discovery

Use this skill before ask-graphql-mcp when the user did not provide an endpoint URL.

Primary goal

Discover likely The Graph project candidates and construct endpoint candidates in this format:

• https://gateway.thegraph.com/api/<Test Key>/subgraphs/id/[id]

Keep <Test Key> literal. Do not replace it.

Trigger

Run this skill when all are true:

• User asks GraphQL/SubQuery/SubGraph data analysis or query execution
• User did not provide a usable endpoint URL
• User request includes at least one topic keyword (protocol, project, chain, metric, etc.)

If user already provided endpoint URL, skip this skill and proceed to ask-graphql-mcp.

Deterministic invocation rules

Use this exact routing logic:

1. If user message contains explicit endpoint URL (http:// or https://) -> do not call this skill.
2. If no endpoint URL and task is GraphQL/SubQuery/SubGraph related -> call this skill.
3. If no endpoint URL and task is not GraphQL related -> do not call this skill.
4. After this skill returns:

• recommended endpoint exists -> call ask-graphql-mcp with that endpoint.
• only medium-confidence candidates -> ask user to pick one candidate first.
• no candidates -> ask user for endpoint directly.

Do not call this skill more than once per user turn unless user provides new keywords/constraints.

Search API

Use:

• https://ask-api.hermes-subnet.ai/indexing/projects/search?q=[keywords]&limit=6

Rules:

1. Build keywords from user intent (project name + chain + metric/domain when available)
2. URL-encode keywords
3. Keep limit=6

Expected response shape:

• data[] with fields including id, source, type, name, description, network, updated_at

Candidate selection workflow

1. Call search API with extracted keywords.
2. Drop obvious mismatches:

• unrelated name/description
• wrong chain/network when user explicitly constrained chain
• stale or vague entries when better matches exist

3. Prioritize candidates by:

• semantic match to user intent (name + description)
• explicit network match
• recency (updated_at)
• source/type confidence (prefer THE_GRAPH + SUBGRAPH when targeting The Graph gateway format)

4. Produce up to 3 endpoint candidates by combining each selected id:

• https://gateway.thegraph.com/api/<Test Key>/subgraphs/id/[id]

5. Handoff to downstream agent (or ask-graphql-mcp) with:

• recommended endpoint (if confidence is high)
• backup candidates (if ambiguity exists)
• one-line rationale per candidate

Decision policy

If at least one candidate is high-confidence:

• continue with ask-graphql-mcp using the recommended endpoint candidate first
• do not execute direct GraphQL query in this skill

If only medium-confidence candidates exist:

• provide 2-3 candidates and ask user to confirm one before running deeper analysis

If no valid candidate exists:

• ask user for endpoint URL directly

Output contract

Return concise structured output:

1. Search keywords used
2. Candidate list (id, name, network, endpoint)
3. Recommended endpoint or none
4. Next action:

• proceed_with_ask_graphql_mcp
• ask_user_to_confirm_candidate
• ask_user_for_endpoint

Handoff rule:

• When next action is proceed_with_ask_graphql_mcp, downstream execution must use Ask MCP path, not hand-written direct GraphQL execution.