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
parent a94f7d0321
commit d220c27b67
4 changed files with 172 additions and 0 deletions
@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: GraphQL Introspection Support
+The GraphQL API SHALL support introspection queries that enable clients to discover the complete schema dynamically.
+
+#### Scenario: Introspection query returns schema types
+- **GIVEN** the GraphQL API is running
+- **WHEN** a client executes an introspection query for `__schema`
+- **THEN** the response SHALL include all types defined in the schema
+- **AND** include queries, mutations, and object types
+- **AND** include field names, types, and descriptions
+
+#### Scenario: Introspection query returns type details
+- **GIVEN** the GraphQL API is running
+- **WHEN** a client executes an introspection query for `__type(name: "Member")`
+- **THEN** the response SHALL include complete Member type details
+- **AND** include all fields with their types
+- **AND** include field descriptions where defined
+
+#### Scenario: Introspection is enabled by default
+- **GIVEN** the Strawberry GraphQL schema is configured
+- **WHEN** the schema is created
+- **THEN** introspection SHALL be enabled
+- **AND** the `__schema` and `__type` queries SHALL be available
@@ -0,0 +1,71 @@
+## 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