# MCP Integration Specification

## ADDED 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