clubber/openspec/changes/update-mcp-server-for-organization-members/design.md

Design: Update MCP Server for Organization Members

MCP Tool Definition Changes

Tool: create_member

Current State:

• Description: "Create a new member. Only firstName is required..."
• Required field: firstName
• Missing fields: memberType, companyName

Changes Needed:

• Update description to explain conditional requirements:
  • INDIVIDUAL members require firstName
  • ORGANIZATION members require companyName
  • memberType defaults to INDIVIDUAL if not specified
• Add memberType property (enum: INDIVIDUAL, ORGANIZATION)
• Add companyName property (string, optional)
• Make firstName optional in schema (validation happens server-side)
• Remove firstName from required array

Tool: update_member

Current State:

• Missing fields: memberType, companyName

Changes Needed:

• Add memberType property (enum: INDIVIDUAL, ORGANIZATION)
• Add companyName property (string, optional)
• Update description to mention type transitions

Tools: list_members and get_member

Current State:

• No input changes needed (query tools)
• Output fields come from GraphQL queries

Changes Needed:

• No changes to tool definitions
• GraphQL queries will be updated to include new fields

GraphQL Query Updates

Query: listMembers (line ~297)

Add fields:

memberType
companyName

Query: getMember (line ~328)

Add fields:

memberType
companyName

Mutation: createMember (line ~371)

Add fields to response:

memberType
companyName

Mutation: updateMember (line ~402)

Add fields to response:

memberType
companyName

Member Formatting Logic

Function: formatMember (line ~580)

Current State:

• Line 583: Always displays "Name: firstName lastName"
• Assumes all members are individuals

Changes Needed:

1. Check member.memberType to determine formatting approach
2. For INDIVIDUAL members:
   • Display: Type: Individual
   • Display: Name: firstName lastName
3. For ORGANIZATION members:
   • Display: Type: Organization
   • Display: Company: companyName
   • Optionally display: Contact Person: firstName lastName (if present)

Example Output:

For Individual:

ID: 1
Type: Individual
Name: John Doe
Email: john@example.com
...

For Organization:

ID: 2
Type: Organization
Company: Acme Corporation
Contact Person: Jane Smith
Email: info@acme.com
...

Function: formatMembers (line ~622)

Current State:

• Calls formatMember() for each member
• No changes needed (delegates to formatMember)

Schema Discovery

The MCP server includes a get_graphql_schema tool that performs introspection. This tool will automatically discover the new MemberType enum without code changes, but we should verify it works correctly.

Implementation Strategy

1. Update tool definitions (create_member and update_member)

   • Add memberType and companyName properties
   • Update descriptions
   • Adjust required fields

2. Update GraphQL queries/mutations

   • Add memberType and companyName to all member queries
   • Add to all mutation responses

3. Update formatMember function

   • Add type checking logic
   • Branch formatting based on memberType
   • Handle both individual and organization display

4. Test changes

   • Verify individual member creation (existing behavior)
   • Verify organization member creation (new behavior)
   • Verify member listing shows correct formatting
   • Verify schema introspection includes MemberType enum

Backward Compatibility

• Existing MCP clients not providing memberType will default to INDIVIDUAL (GraphQL default)
• Existing queries will work as before (new fields are optional in responses)
• Member formatting will gracefully handle missing memberType (defaults to INDIVIDUAL)

File Changes Summary

Single File to Modify:

• src/mcp_server.ts - All changes are in this file
  • Lines 154-189: update_member tool definition
  • Lines 191-228: update_member tool definition
  • Lines 297-314: listMembers query
  • Lines 328-344: getMember query
  • Lines 371-388: createMember mutation
  • Lines 402-419: updateMember mutation
  • Lines 580-620: formatMember function