clubber/openspec/changes/archive/2025-11-21-add-graphql-tools/specs/mcp-integration/spec.md at dd772db29866117570c87620ba0b408ecf70155c

Files

T

gurixandClaude dd772db298 chore: archive add-graphql-tools change

Archive completed change proposal to openspec/changes/archive/.
Updated specs with new GraphQL introspection and MCP tool requirements:

- graphql-api: Added GraphQL Introspection Support requirement
- mcp-integration: Added 3 requirements for GraphQL tools
  - Get GraphQL Schema Tool
  - Execute GraphQL Query Tool
  - Tool Input Schema for GraphQL Execution

All requirements include comprehensive scenarios and are now part
of the active specification.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-21 12:08:58 +01:00

3.3 KiB

Raw Blame History

ADDED Requirements

Requirement: Get GraphQL Schema Tool

The MCP server SHALL provide a get_graphql_schema tool that returns the complete GraphQL schema definition via introspection.

Scenario: Get GraphQL schema successfully

GIVEN the GraphQL API is running and accessible
WHEN the get_graphql_schema tool is invoked
THEN the tool SHALL execute an introspection query
AND return the complete schema including types, queries, mutations, and field descriptions
AND format the result as human-readable text with structured schema information

Scenario: Schema retrieval when API is unavailable

GIVEN the GraphQL API is not running
WHEN the get_graphql_schema tool is invoked
THEN the tool SHALL return an error indicating the API is unreachable
AND provide guidance on starting the API

Requirement: Execute GraphQL Query Tool

The MCP server SHALL provide an execute_graphql_query tool that executes arbitrary GraphQL queries and mutations.

Scenario: Execute valid GraphQL query

GIVEN a valid GraphQL query is provided
WHEN the execute_graphql_query tool is invoked with the query
THEN the tool SHALL send the query to the GraphQL API
AND return the query results as formatted JSON
AND include all requested fields in the response

Scenario: Execute GraphQL query with variables

GIVEN a GraphQL query with variable placeholders
WHEN the execute_graphql_query tool is invoked with query and variables
THEN the tool SHALL substitute variables correctly
AND execute the query with the provided variable values
AND return the results

Scenario: Execute GraphQL mutation

GIVEN a valid GraphQL mutation query
WHEN the execute_graphql_query tool is invoked with the mutation
THEN the tool SHALL execute the mutation
AND return the mutation results including any modified data
AND persist changes to the database

Scenario: Execute invalid GraphQL query

GIVEN a GraphQL query with syntax errors
WHEN the execute_graphql_query tool is invoked
THEN the tool SHALL return a GraphQL validation error
AND include details about the syntax error
AND not modify any data

Scenario: Execute query with GraphQL validation errors

GIVEN a GraphQL query requesting non-existent fields
WHEN the execute_graphql_query tool is invoked
THEN the tool SHALL return a GraphQL validation error
AND indicate which fields are invalid
AND not execute the query

Requirement: Tool Input Schema for GraphQL Execution

The execute_graphql_query tool SHALL accept a query string and optional variables object.

Scenario: Tool accepts query without variables

GIVEN a simple GraphQL query without variables
WHEN the tool is invoked with only the query parameter
THEN the query SHALL execute successfully
AND no variables are passed to the GraphQL API

Scenario: Tool accepts query with variables

GIVEN a GraphQL query using variables
WHEN the tool is invoked with query and variables parameters
THEN both parameters SHALL be validated
AND variables SHALL be passed as a JSON object to the GraphQL API
AND the query executes with variable substitution

3.3 KiB Raw Blame History