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>
This commit is contained in:
Claude
@@ -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
|
||||||
@@ -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
|
||||||
@@ -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
|
||||||
Reference in New Issue
Block a user