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

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