---
name: graphql-inspector
description: >-
  GraphQL schema inspection and query execution skill. Guides AI agents through
  progressive schema discovery — scan first, drill down second, execute last.
  Enforces read-only by default with token-efficient workflows.
compatibility: "OpenCode with graphql-tools MCP server"
metadata:
  author: kokorolx
  version: "1.0.0"
---

# GraphQL Inspector Skill

**Version**: 1.0.0 | **MCP Server**: `graphql-tools` | **Default Mode**: Read-Only

## Overview

This skill teaches AI agents the optimal workflow for exploring and querying GraphQL APIs via the `graphql-tools` MCP server. The core principle is **progressive disclosure** — start cheap, drill down only when needed.

## When to Use This Skill

| Trigger | Action |
|---------|--------|
| "What queries/mutations are available?" | `filter_queries` / `filter_mutations` with `detailed=false` |
| "How do I call X query?" | `get_field_details` for args + return type |
| "What fields does Type Y have?" | `get_type_details` |
| "Run this query" | `execute_query` (read-only) |
| "What does the schema look like?" | `filter_queries` + `filter_mutations` + `filter_types` (NOT `get_graphql_schema`) |

## Golden Rule: Progressive Disclosure

**NEVER start with `get_graphql_schema`.** It dumps the entire schema and wastes tokens.

Follow this flow instead:

```
Step 1: SCAN (cheap, small payload)
  filter_queries(detailed=false)    → list query names + descriptions
  filter_mutations(detailed=false)  → list mutation names + descriptions

Step 2: DRILL DOWN (only for fields you need)
  get_field_details(field_name="targetField", operation_type="query")
  → get arguments, return type, deprecation info

Step 3: UNDERSTAND TYPES (only if return/input types are complex)
  get_type_details(type_name="ComplexType")
  → get fields, enums, interfaces
  filter_types(kind="INPUT_OBJECT", search="CreateInput")
  → find input types for mutations

Step 4: EXECUTE (only after understanding the schema)
  execute_query(query="query { ... }")
  → run read-only query with known structure
```

## Available Tools

### Inspection Tools (always available, all read-only)

| Tool | Purpose | When to Use |
|------|---------|-------------|
| `filter_queries` | List available queries | **First step** — scan what's available |
| `filter_mutations` | List available mutations | **First step** — scan what's available |
| `filter_types` | List types by kind/search | Find INPUT_OBJECT types for mutation args |
| `get_field_details` | Deep dive into one field | **Second step** — get args + return type |
| `get_type_details` | Deep dive into one type | Understand complex return/input types |
| `get_graphql_schema` | Full schema dump (SDL) | **Last resort only** — very large payload |

### Execution Tools

| Tool | Purpose | Availability |
|------|---------|-------------|
| `execute_query` | Run read-only GraphQL query | Always available |
| `execute_mutation` | Run GraphQL mutation | Only when `ALLOW_MUTATIONS=true` |

## Workflow Examples

### Example 1: "What can I query?"

```
1. filter_queries(detailed=false)
   → Returns: [{ name: "getUser", description: "Fetch user by ID" }, ...]

2. Found interesting query "getUser", need args:
   get_field_details(field_name="getUser", operation_type="query")
   → Returns: args=[{name: "id", type: "ID!"}], return_type="User"

3. Need to know User fields:
   get_type_details(type_name="User")
   → Returns: fields=[{name: "id"}, {name: "email"}, {name: "name"}, ...]

4. Now execute with confidence:
   execute_query(query="query { getUser(id: \"123\") { id name email } }")
```

### Example 2: "Find queries related to orders"

```
1. filter_queries(search="order", detailed=false)
   → Returns matching queries with names + descriptions

2. If need more detail on a specific one:
   get_field_details(field_name="getOrderById", operation_type="query")
```

### Example 3: "What input does createUser mutation need?"

```
1. get_field_details(field_name="createUser", operation_type="mutation")
   → Returns: args=[{name: "input", type: "CreateUserInput!"}]

2. filter_types(kind="INPUT_OBJECT", search="CreateUserInput")
   → Returns input type with all fields and their types
```

### Example 4: "Show me all enum types"

```
1. filter_types(kind="ENUM", detailed=true)
   → Returns all enums with their values
```

## Common Parameters

All tools accept these optional auth parameters:

| Parameter | Description |
|-----------|-------------|
| `endpoint` | GraphQL endpoint URL (default from server config) |
| `username` | Basic auth username |
| `password` | Basic auth password |
| `bearer_token` | Bearer token for auth |

## Anti-Patterns (DO NOT)

| Bad Practice | Why | Do Instead |
|-------------|-----|------------|
| Start with `get_graphql_schema` | Dumps entire schema, wastes tokens | `filter_queries(detailed=false)` |
| Use `detailed=true` on first call | Returns args/types for ALL fields | `detailed=false` first, then `get_field_details` for specific fields |
| Execute query without understanding schema | Likely wrong field names or args | Scan → drill down → execute |
| Call `execute_mutation` without checking availability | Will error if mutations disabled | Check if tool is listed first |
| Guess field names in queries | Will get GraphQL errors | Always inspect schema first |

## Safety Model

The server enforces 3 layers of protection:

1. **Tool Listing**: `execute_mutation` is hidden when `ALLOW_MUTATIONS` is not set
2. **Execution Guard**: `execute_mutation` rejects at runtime even if called directly
3. **AST Validation**: GraphQL documents are parsed — operation type verified at AST level

**Default is read-only.** Mutations require explicit `ALLOW_MUTATIONS=true` env var on the server.

## Token Efficiency Tips

- `filter_queries(detailed=false)` returns ~50 bytes per field vs ~500 bytes with `detailed=true`
- Use `search` parameter to narrow results before drilling down
- `get_field_details` for ONE field is cheaper than `filter_queries(detailed=true)` for ALL fields
- Cache awareness: repeated calls to same endpoint use 5-minute server cache

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Unknown tool: execute_mutation" | Mutations disabled (default). Set `ALLOW_MUTATIONS=true` on server |
| "Mutations are not allowed in read-only mode" | Query sent to `execute_query` contains a mutation. Use `execute_mutation` instead |
| "Subscriptions are not supported" | Subscriptions are intentionally blocked |
| Empty results from filter | Check endpoint is correct and accessible |
| Auth errors | Verify credentials — try `get_graphql_schema` with auth params first |