diff --git a/openspec/changes/add-graphql-tools/proposal.md b/openspec/changes/archive/2025-11-21-add-graphql-tools/proposal.md similarity index 100% rename from openspec/changes/add-graphql-tools/proposal.md rename to openspec/changes/archive/2025-11-21-add-graphql-tools/proposal.md diff --git a/openspec/changes/add-graphql-tools/specs/graphql-api/spec.md b/openspec/changes/archive/2025-11-21-add-graphql-tools/specs/graphql-api/spec.md similarity index 100% rename from openspec/changes/add-graphql-tools/specs/graphql-api/spec.md rename to openspec/changes/archive/2025-11-21-add-graphql-tools/specs/graphql-api/spec.md diff --git a/openspec/changes/add-graphql-tools/specs/mcp-integration/spec.md b/openspec/changes/archive/2025-11-21-add-graphql-tools/specs/mcp-integration/spec.md similarity index 100% rename from openspec/changes/add-graphql-tools/specs/mcp-integration/spec.md rename to openspec/changes/archive/2025-11-21-add-graphql-tools/specs/mcp-integration/spec.md diff --git a/openspec/changes/add-graphql-tools/tasks.md b/openspec/changes/archive/2025-11-21-add-graphql-tools/tasks.md similarity index 100% rename from openspec/changes/add-graphql-tools/tasks.md rename to openspec/changes/archive/2025-11-21-add-graphql-tools/tasks.md diff --git a/openspec/specs/graphql-api/spec.md b/openspec/specs/graphql-api/spec.md index 3492597..8d6bb11 100644 --- a/openspec/specs/graphql-api/spec.md +++ b/openspec/specs/graphql-api/spec.md @@ -303,3 +303,26 @@ The system MUST provide clear, actionable error messages for validation failures **And** client receives generic "Internal server error" message **And** HTTP status code is 500 +### 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 + diff --git a/openspec/specs/mcp-integration/spec.md b/openspec/specs/mcp-integration/spec.md index c8edc09..7a9bfb7 100644 --- a/openspec/specs/mcp-integration/spec.md +++ b/openspec/specs/mcp-integration/spec.md @@ -99,3 +99,73 @@ The MCP server SHALL handle errors gracefully and return meaningful error messag - **WHEN** an MCP tool is invoked with invalid data - **THEN** the tool SHALL return the validation error message to the client +### 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 +