feat: add MCP server for AI-powered member management

This change implements a Model Context Protocol (MCP) server that enables AI assistants to manage society members through natural language interactions. Changes: - Add MCP server implementation (src/mcp_server.py) - Implement 4 core tools: * list_members - Query all members * get_member - Get specific member by ID * create_member - Create new member * update_member - Update member information - Add mcp and httpx dependencies to pyproject.toml - Update README with comprehensive MCP server documentation - Create OpenSpec proposal in openspec/changes/add-mcp-server/ The MCP server connects to the GraphQL API via HTTP and provides structured tools that abstract away GraphQL complexity. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-20 13:54:52 +01:00
parent 5bb27bdadf
commit 8d14e7e75a
7 changed files with 1096 additions and 0 deletions
@@ -0,0 +1,99 @@
+# 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