gurix/clubber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2a6584078c77074db0159d4a7b4bd3e16fb7c36f
clubber/openspec/specs/mcp-integration/spec.md
T

7.7 KiB
Raw Blame History

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 node dist/mcp_server.js (after building)
  • 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

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

Requirement: Get GraphQL Schema Tool

The MCP server SHALL provide a get_graphql_schema tool that returns the complete GraphQL schema definition via introspection.

Scenario: Get GraphQL schema successfully

  • GIVEN the GraphQL API is running and accessible
  • WHEN the get_graphql_schema tool is invoked
  • THEN the tool SHALL execute an introspection query
  • AND return the complete schema including types, queries, mutations, and field descriptions
  • AND format the result as human-readable text with structured schema information

Scenario: Schema retrieval when API is unavailable

  • GIVEN the GraphQL API is not running
  • WHEN the get_graphql_schema tool is invoked
  • THEN the tool SHALL return an error indicating the API is unreachable
  • AND provide guidance on starting the API

Requirement: Execute GraphQL Query Tool

The MCP server SHALL provide an execute_graphql_query tool that executes arbitrary GraphQL queries and mutations.

Scenario: Execute valid GraphQL query

  • GIVEN a valid GraphQL query is provided
  • WHEN the execute_graphql_query tool is invoked with the query
  • THEN the tool SHALL send the query to the GraphQL API
  • AND return the query results as formatted JSON
  • AND include all requested fields in the response

Scenario: Execute GraphQL query with variables

  • GIVEN a GraphQL query with variable placeholders
  • WHEN the execute_graphql_query tool is invoked with query and variables
  • THEN the tool SHALL substitute variables correctly
  • AND execute the query with the provided variable values
  • AND return the results

Scenario: Execute GraphQL mutation

  • GIVEN a valid GraphQL mutation query
  • WHEN the execute_graphql_query tool is invoked with the mutation
  • THEN the tool SHALL execute the mutation
  • AND return the mutation results including any modified data
  • AND persist changes to the database

Scenario: Execute invalid GraphQL query

  • GIVEN a GraphQL query with syntax errors
  • WHEN the execute_graphql_query tool is invoked
  • THEN the tool SHALL return a GraphQL validation error
  • AND include details about the syntax error
  • AND not modify any data

Scenario: Execute query with GraphQL validation errors

  • GIVEN a GraphQL query requesting non-existent fields
  • WHEN the execute_graphql_query tool is invoked
  • THEN the tool SHALL return a GraphQL validation error
  • AND indicate which fields are invalid
  • AND not execute the query

Requirement: Tool Input Schema for GraphQL Execution

The execute_graphql_query tool SHALL accept a query string and optional variables object.

Scenario: Tool accepts query without variables

  • GIVEN a simple GraphQL query without variables
  • WHEN the tool is invoked with only the query parameter
  • THEN the query SHALL execute successfully
  • AND no variables are passed to the GraphQL API

Scenario: Tool accepts query with variables

  • GIVEN a GraphQL query using variables
  • WHEN the tool is invoked with query and variables parameters
  • THEN both parameters SHALL be validated
  • AND variables SHALL be passed as a JSON object to the GraphQL API
  • AND the query executes with variable substitution
Reference in New Issue View Git Blame Copy Permalink