clubber/openspec/specs/mcp-integration/spec.md

# mcp-integration Specification

## Purpose
TBD - created by archiving change add-mcp-server. Update Purpose after archive.
## Requirements
### Requirement: MCP Server Implementation
The system SHALL provide an MCP (Model Context Protocol) server that exposes member management functionality as standardized AI tools.

#### Scenario: MCP server starts successfully
- **GIVEN** the GraphQL API is running at http://127.0.0.1:8000/graphql
- **WHEN** the MCP server is started with `python -m src.mcp_server`
- **THEN** the server SHALL initialize and listen for MCP protocol requests via stdio transport

#### Scenario: MCP server connects to GraphQL API
- **GIVEN** the MCP server is running
- **WHEN** an MCP tool is invoked
- **THEN** the server SHALL send GraphQL queries to the configured API endpoint via HTTP

### Requirement: List Members Tool
The MCP server SHALL provide a `list_members` tool that retrieves all members from the GraphQL API.

#### Scenario: List all members successfully
- **GIVEN** the GraphQL API has 3 members in the database
- **WHEN** the `list_members` tool is invoked
- **THEN** the tool SHALL return a JSON array containing all 3 members with their complete data

#### Scenario: List members when database is empty
- **GIVEN** the GraphQL API has no members
- **WHEN** the `list_members` tool is invoked
- **THEN** the tool SHALL return an empty JSON array

### Requirement: Get Member Tool
The MCP server SHALL provide a `get_member` tool that retrieves a single member by ID.

#### Scenario: Get member by valid ID
- **GIVEN** a member exists with ID 1
- **WHEN** the `get_member` tool is invoked with id=1
- **THEN** the tool SHALL return the member's complete data as JSON

#### Scenario: Get member with nonexistent ID
- **GIVEN** no member exists with ID 999
- **WHEN** the `get_member` tool is invoked with id=999
- **THEN** the tool SHALL return an error indicating the member was not found

### Requirement: Create Member Tool
The MCP server SHALL provide a `create_member` tool that creates new members via the GraphQL API.

#### Scenario: Create member with minimal data
- **GIVEN** only a first name "Alice" is provided
- **WHEN** the `create_member` tool is invoked
- **THEN** the tool SHALL create a new member with firstName="Alice" and return the created member with generated ID

#### Scenario: Create member with complete data
- **GIVEN** complete member data including name, address, email, and phone
- **WHEN** the `create_member` tool is invoked
- **THEN** the tool SHALL create a member with all fields populated and return the created member

#### Scenario: Create member with invalid email
- **GIVEN** an invalid email format "not-an-email"
- **WHEN** the `create_member` tool is invoked with this email
- **THEN** the tool SHALL return a validation error from the GraphQL API

### Requirement: Update Member Tool
The MCP server SHALL provide an `update_member` tool that updates existing member information.

#### Scenario: Update member successfully
- **GIVEN** a member exists with ID 1
- **WHEN** the `update_member` tool is invoked with id=1 and email="updated@example.com"
- **THEN** the tool SHALL update the member's email and return the updated member data

#### Scenario: Update member with invalid ID
- **GIVEN** no member exists with ID 999
- **WHEN** the `update_member` tool is invoked with id=999
- **THEN** the tool SHALL return an error indicating the member was not found

### Requirement: Configuration
The MCP server SHALL support configuration via environment variables.

#### Scenario: Custom API URL configuration
- **GIVEN** environment variable CLUBBER_API_URL is set to "http://localhost:3000/graphql"
- **WHEN** the MCP server starts
- **THEN** the server SHALL use "http://localhost:3000/graphql" as the GraphQL endpoint

#### Scenario: Default API URL
- **GIVEN** no CLUBBER_API_URL environment variable is set
- **WHEN** the MCP server starts
- **THEN** the server SHALL default to "http://127.0.0.1:8000/graphql"

### Requirement: Error Handling
The MCP server SHALL handle errors gracefully and return meaningful error messages.

#### Scenario: GraphQL API unavailable
- **GIVEN** the GraphQL API is not running
- **WHEN** any MCP tool is invoked
- **THEN** the tool SHALL return an error indicating the API is unreachable

#### Scenario: GraphQL validation error
- **GIVEN** the GraphQL API returns a validation error
- **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