clubber/openspec/changes/archive/2025-11-21-add-graphql-tools/tasks.md

## 1. Setup

- [x] 1.1 Create git worktree for feature branch
- [x] 1.2 Verify GraphQL API introspection is enabled (should be default in Strawberry)

## 2. Implementation
- [x] 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
- [x] 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
- [x] 3.1 Test `get_graphql_schema` tool
  - Verify introspection returns complete schema
  - Test error handling when API is unavailable
- [x] 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
- [x] 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
- [x] 5.1 Verify backward compatibility
  - Ensure existing dedicated tools still work
  - Test that MCP server starts successfully
- [x] 5.2 Manual testing with MCP client
  - Test schema retrieval via MCP
  - Test query execution via MCP
  - Verify formatted output is readable

## 6. Finalization
- [x] 6.1 Run code formatting (Black, isort, ruff)
- [x] 6.2 Review changes for simplicity
- [x] 6.3 Commit changes with conventional commit message
- [x] 6.4 Remove worktree after merge