Files

T

gurixandClaude 093cba8f6d chore: archive add-mcp-server proposal and create mcp-integration spec

Archived the add-mcp-server proposal to archive/2025-11-20-add-mcp-server/
and created the mcp-integration capability spec with 7 requirements.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-20 14:28:02 +01:00

4.3 KiB

Raw Blame History

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

4.3 KiB Raw Blame History