From 093cba8f6d7b46beb6558a9cee236c40a116440e Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Thu, 20 Nov 2025 14:28:02 +0100 Subject: [PATCH] chore: archive add-mcp-server proposal and create mcp-integration spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../2025-11-20-add-mcp-server}/proposal.md | 0 .../specs/mcp-integration/spec.md | 0 .../2025-11-20-add-mcp-server}/tasks.md | 0 openspec/specs/mcp-integration/spec.md | 101 ++++++++++++++++++ tree/add-mcp-server | 1 + 5 files changed, 102 insertions(+) rename openspec/changes/{add-mcp-server => archive/2025-11-20-add-mcp-server}/proposal.md (100%) rename openspec/changes/{add-mcp-server => archive/2025-11-20-add-mcp-server}/specs/mcp-integration/spec.md (100%) rename openspec/changes/{add-mcp-server => archive/2025-11-20-add-mcp-server}/tasks.md (100%) create mode 100644 openspec/specs/mcp-integration/spec.md create mode 160000 tree/add-mcp-server diff --git a/openspec/changes/add-mcp-server/proposal.md b/openspec/changes/archive/2025-11-20-add-mcp-server/proposal.md similarity index 100% rename from openspec/changes/add-mcp-server/proposal.md rename to openspec/changes/archive/2025-11-20-add-mcp-server/proposal.md diff --git a/openspec/changes/add-mcp-server/specs/mcp-integration/spec.md b/openspec/changes/archive/2025-11-20-add-mcp-server/specs/mcp-integration/spec.md similarity index 100% rename from openspec/changes/add-mcp-server/specs/mcp-integration/spec.md rename to openspec/changes/archive/2025-11-20-add-mcp-server/specs/mcp-integration/spec.md diff --git a/openspec/changes/add-mcp-server/tasks.md b/openspec/changes/archive/2025-11-20-add-mcp-server/tasks.md similarity index 100% rename from openspec/changes/add-mcp-server/tasks.md rename to openspec/changes/archive/2025-11-20-add-mcp-server/tasks.md diff --git a/openspec/specs/mcp-integration/spec.md b/openspec/specs/mcp-integration/spec.md new file mode 100644 index 0000000..c8edc09 --- /dev/null +++ b/openspec/specs/mcp-integration/spec.md @@ -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 + diff --git a/tree/add-mcp-server b/tree/add-mcp-server new file mode 160000 index 0000000..8d14e7e --- /dev/null +++ b/tree/add-mcp-server @@ -0,0 +1 @@ +Subproject commit 8d14e7e75ac0f605d700439496f221d602e6314f