diff --git a/openspec/changes/add-graphql-tools/proposal.md b/openspec/changes/add-graphql-tools/proposal.md new file mode 100644 index 0000000..325f25a --- /dev/null +++ b/openspec/changes/add-graphql-tools/proposal.md @@ -0,0 +1,24 @@ +## Why + +The current MCP server provides dedicated tools for member management (`list_members`, `get_member`, `create_member`, `update_member`). While these work well for basic operations, they are limited for complex tasks that require: +- Flexible querying with custom field selection +- Complex filters or relationships (future) +- Ad-hoc data exploration by AI agents +- Leveraging GraphQL's full introspection capabilities + +AI agents connected via the MCP server should be able to discover the GraphQL schema dynamically and construct their own queries for complex tasks. + +## What Changes + +- Add `get_graphql_schema` tool to expose the complete GraphQL schema via introspection +- Add `execute_graphql_query` tool to allow AI agents to execute arbitrary GraphQL queries and mutations +- Update README.md with documentation for the new tools +- Keep existing dedicated member tools for backward compatibility and simple operations + +## Impact + +- Affected specs: `mcp-integration`, `graphql-api` +- Affected code: `src/mcp_server.py`, `README.md` +- Breaking changes: None (additive only) +- The dedicated member tools remain available, providing a simpler interface for common operations +- AI agents gain flexibility to handle complex queries without requiring new dedicated tools diff --git a/openspec/changes/add-graphql-tools/specs/graphql-api/spec.md b/openspec/changes/add-graphql-tools/specs/graphql-api/spec.md new file mode 100644 index 0000000..6f0adf8 --- /dev/null +++ b/openspec/changes/add-graphql-tools/specs/graphql-api/spec.md @@ -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 diff --git a/openspec/changes/add-graphql-tools/specs/mcp-integration/spec.md b/openspec/changes/add-graphql-tools/specs/mcp-integration/spec.md new file mode 100644 index 0000000..6d8bcb1 --- /dev/null +++ b/openspec/changes/add-graphql-tools/specs/mcp-integration/spec.md @@ -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 diff --git a/openspec/changes/add-graphql-tools/tasks.md b/openspec/changes/add-graphql-tools/tasks.md new file mode 100644 index 0000000..1fd0957 --- /dev/null +++ b/openspec/changes/add-graphql-tools/tasks.md @@ -0,0 +1,53 @@ +## 1. Setup +- [ ] 1.1 Create git worktree for feature branch +- [ ] 1.2 Verify GraphQL API introspection is enabled (should be default in Strawberry) + +## 2. Implementation +- [ ] 2.1 Add `get_graphql_schema` tool to MCP server + - Add introspection query constant + - Implement tool handler that executes introspection + - Format schema response as readable text + - Add tool to list_tools() handler +- [ ] 2.2 Add `execute_graphql_query` tool to MCP server + - Add tool definition with query and variables parameters + - Implement tool handler that executes arbitrary queries + - Format query results as JSON + - Add proper error handling for invalid queries + - Add tool to list_tools() handler + +## 3. Testing +- [ ] 3.1 Test `get_graphql_schema` tool + - Verify introspection returns complete schema + - Test error handling when API is unavailable +- [ ] 3.2 Test `execute_graphql_query` tool + - Test simple query execution (e.g., list members) + - Test query with variables (e.g., get member by ID) + - Test mutation execution (e.g., create member) + - Test error handling for invalid queries + - Test error handling for validation errors + +## 4. Documentation +- [ ] 4.1 Update README.md + - Add section for new GraphQL tools + - Document `get_graphql_schema` tool usage + - Document `execute_graphql_query` tool with examples + - Explain when to use general tools vs dedicated member tools +- [ ] 4.2 Add usage examples + - Example: Discover schema with AI agent + - Example: Execute custom query + - Example: Execute query with variables + +## 5. Integration +- [ ] 5.1 Verify backward compatibility + - Ensure existing dedicated tools still work + - Test that MCP server starts successfully +- [ ] 5.2 Manual testing with MCP client + - Test schema retrieval via MCP + - Test query execution via MCP + - Verify formatted output is readable + +## 6. Finalization +- [ ] 6.1 Run code formatting (Black, isort, ruff) +- [ ] 6.2 Review changes for simplicity +- [ ] 6.3 Commit changes with conventional commit message +- [ ] 6.4 Remove worktree after merge