feat: add GraphQL schema introspection tools - #17
Conversation
sweden-snow
commented
Apr 9, 2026
sweden-snow
commented
- fetch_catalogue_schema, fetch_discovery_schema, fetch_core_schema, fetch_shop_cart_schema
- Compact SDL output strips built-in types and descriptions
- Auto-summary mode for large schemas (>50k chars)
- Core schema supports domain filter (order, customer, item, etc.)
- Discovery and Core accept optional summary param
- fetch_catalogue_schema, fetch_discovery_schema, fetch_core_schema, fetch_shop_cart_schema - Compact SDL output strips built-in types and descriptions - Auto-summary mode for large schemas (>50k chars) - Core schema supports domain filter (order, customer, item, etc.) - Discovery and Core accept optional summary param
There was a problem hiding this comment.
Pull request overview
Adds a new set of MCP tools to introspect and present Crystallize GraphQL schemas (Catalogue, Discovery, Core, Shop Cart) in a compact, AI-friendly format, with optional summarization for large schemas.
Changes:
- Introduces
schemaTools()with 4 newfetch_*_schematools backed by a shared introspection + compaction pipeline. - Adds optional
summaryparameter (Discovery/Core) and a Coredomainfilter. - Registers the new tools in the MCP server and adds unit tests for basic behavior and error handling.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
src/tools/schema.ts |
Implements introspection query execution, compact SDL-ish rendering, summary mode, auto-summary thresholding, and 4 new tool definitions. |
src/index.ts |
Registers schemaTools() in the MCP server’s tool list. |
tests/schema.test.ts |
Adds tests validating tool metadata, compact output behavior, error handling, and basic Core domain filtering. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| description: | ||
| 'Fetch the GraphQL schema of the Crystallize Core API (admin API). ' + | ||
| 'The Core API is large, so provide a domain to filter the schema (e.g. "order", "customer", "item"). ' + | ||
| 'Common domains: order, customer, subscription, subscriptionPlan, pricelist, pipeline, flow, app, user, webhook, stockLocation. ' + | ||
| 'Omit domain to get a summary of available types. Set summary to true for a compact overview.', | ||
| schema: { |
There was a problem hiding this comment.
The Core tool description says "Omit domain to get a summary of available types", but the current handler defaults to returning the full compacted schema unless summary: true (or the auto-summary threshold is exceeded). This mismatch will confuse tool users; either change the description or adjust the handler to default to summary when domain is omitted.
- Remove redundant `summary` parameter from Discovery and Core tools (auto-summary at 50k threshold is sufficient) - Show filtered type count with domain filter (e.g. "2 of 3 types") - Add auto-summary threshold test
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
