clubber/openspec/changes/add-graphql-tools/specs/mcp-integration/spec.md at d220c27b67c207aa2f016da8d1ed6a801e135b5c

Files

T

gurixandClaude d220c27b67 docs: add OpenSpec proposal for GraphQL tools

Add comprehensive proposal for general GraphQL tools in MCP server:
- proposal.md: Problem statement and impact analysis
- tasks.md: Implementation checklist
- specs/mcp-integration/spec.md: 3 new MCP tool requirements
- specs/graphql-api/spec.md: GraphQL introspection requirement

Proposal introduces get_graphql_schema and execute_graphql_query tools
to enable AI agents to discover and interact with the GraphQL API
dynamically for complex tasks beyond dedicated member tools.

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

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

2025-11-21 11:58:55 +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