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
@@ -210,6 +210,106 @@ curl -X POST http://127.0.0.1:8000/graphql \
  -d '{"query": "mutation { createMember(input: { firstName: \"Charlie\" }) { id firstName } }"}'
 ```

+## MCP Server
+
+The MCP (Model Context Protocol) server enables AI assistants like Claude to manage society members through natural language interactions.
+
+### What is MCP?
+
+The Model Context Protocol (MCP) is a standard protocol that allows AI assistants to use tools and access external systems. The Clubber MCP server provides 4 tools that connect to the GraphQL API:
+
+- **list_members** - List all members with their complete information
+- **get_member** - Get detailed information about a specific member by ID
+- **create_member** - Create a new member (only firstName required)
+- **update_member** - Update an existing member's information
+
+### Running the MCP Server
+
+The MCP server requires the GraphQL API to be running first:
+
+```bash
+# Terminal 1: Start the GraphQL API
+uv run uvicorn src.main:app --host 127.0.0.1 --port 8000
+
+# Terminal 2: Run the MCP server
+python -m src.mcp_server
+```
+
+### Configuration
+
+The MCP server can be configured via environment variables:
+
+```bash
+# Use a custom API URL (default: http://127.0.0.1:8000/graphql)
+export CLUBBER_API_URL="http://localhost:3000/graphql"
+python -m src.mcp_server
+```
+
+### Integrating with Claude Code
+
+To use the MCP server with Claude Code, add it to your MCP configuration:
+
+**For macOS/Linux** (`~/Library/Application Support/Claude/claude_desktop_config.json` or `~/.config/claude/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "clubber": {
+      "command": "python",
+      "args": ["-m", "src.mcp_server"],
+      "cwd": "/absolute/path/to/clubber",
+      "env": {
+        "CLUBBER_API_URL": "http://127.0.0.1:8000/graphql"
+      }
+    }
+  }
+}
+```
+
+After adding the configuration, restart Claude Code. You can then use natural language to manage members:
+
+- "List all members in the society"
+- "Create a new member named Alice"
+- "Update member 5's email to alice@example.com"
+- "Show me details for member 3"
+
+### MCP Server Usage Examples
+
+Once configured, you can interact with the MCP server through Claude Code:
+
+**Example 1: Create a member**
+```
+User: Create a new member named Bob Smith with email bob@example.com
+
+Claude uses create_member tool:
+- firstName: "Bob"
+- lastName: "Smith"
+- email: "bob@example.com"
+
+Result: Member created with ID 1
+```
+
+**Example 2: Update member information**
+```
+User: Update member 1's phone number to +41791234567
+
+Claude uses update_member tool:
+- id: 1
+- phone: "+41791234567"
+
+Result: Member updated successfully
+```
+
+**Example 3: List all members**
+```
+User: Show me all members in the society
+
+Claude uses list_members tool and displays formatted results:
+- Bob Smith (bob@example.com, +41791234567)
+- Alice Johnson (alice@example.com)
+...
+```
+
 ## Development Workflow

 This project uses [OpenSpec](https://openspec.dev) for specification-driven development: