gurix/clubber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
gurix
2025-11-20 14:28:02 +01:00
co-authored by Claude
parent 7c5201498b
commit 093cba8f6d
5 changed files with 102 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/changes/add-mcp-server/proposal.md → openspec/changes/archive/2025-11-20-add-mcp-server/proposal.md
View File
openspec/changes/add-mcp-server/specs/mcp-integration/spec.md → openspec/changes/archive/2025-11-20-add-mcp-server/specs/mcp-integration/spec.md
View File
openspec/changes/add-mcp-server/tasks.md → openspec/changes/archive/2025-11-20-add-mcp-server/tasks.md
View File
openspec/specs/mcp-integration/spec.md
+101
View File
@@ -0,0 +1,101 @@
# 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