A toolset for managing members of non-profit societies (Vereine) with AI-powered administration.
## Overview
Clubber provides a GraphQL API for member management combined with an MCP (Model Context Protocol) server that enables AI assistants to help with society administration tasks.
**Current Status**: Early development - OpenSpec documentation and project structure in place.
## Architecture
The system consists of two main components:
1.**GraphQL API** - Core backend for member data management
- Built with FastAPI and Strawberry GraphQL
- Database-agnostic design (SQLite for development, PostgreSQL for production)
- SQLAlchemy 2.0 ORM with async support
2.**MCP Server** - AI assistant integration layer
- Connects to the GraphQL API
- Provides tools for AI agents to manage society operations
- Service account authentication
## Tech Stack
- **Python 3.11+** - Primary language
- **uv** - Fast package and project manager
- **FastAPI** - Async web framework
- **Strawberry GraphQL** - Type-safe GraphQL with Python type hints
- **SQLAlchemy 2.0** - Database ORM
- **Alembic** - Database migrations
## Project Structure
```
clubber/
├── openspec/ # Specification-driven development
│ ├── project.md # Project conventions and context
-`apartmentNumber` (optional) - Apartment or unit number
-`zip` (optional) - Postal code
-`city` (optional) - City
-`country` (optional) - Country
-`email` (optional) - Email address (validated when provided)
-`phone` (optional) - Phone number in E.164 format (validated when provided)
**Key Feature**: Only `firstName` is required. All other fields are optional and can be populated later. Email and phone are validated only when provided (not when null/empty).
### GraphQL Queries
List all members:
```graphql
{
members{
id
firstName
lastName
email
phone
city
}
}
```
Get a single member:
```graphql
{
member(id:1){
id
firstName
lastName
email
street
city
country
}
}
```
### GraphQL Mutations
Create a member (minimal - only firstName):
```graphql
mutation{
createMember(input:{
firstName:"Alice"
}){
id
firstName
email
}
}
```
Create a member with all fields:
```graphql
mutation{
createMember(input:{
firstName:"Bob"
lastName:"Johnson"
street:"123 Main St"
apartmentNumber:"4B"
zip:"12345"
city:"Springfield"
country:"USA"
email:"bob.johnson@example.com"
phone:"+14155551234"
}){
id
firstName
lastName
email
phone
}
}
```
Update a member:
```graphql
mutation{
updateMember(input:{
id:1
email:"updated@example.com"
phone:"+14155559999"
}){
id
firstName
email
phone
}
}
```
Delete a member:
```graphql
mutation{
deleteMember(id:2)
}
```
### Using curl
Query members:
```bash
curl -X POST http://127.0.0.1:8000/graphql \
-H "Content-Type: application/json"\
-d '{"query": "{ members { id firstName lastName email } }"}'
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 6 tools that connect to the GraphQL API:
**Note**: The `uv run` command ensures the virtual environment and dependencies are properly activated. The MCP server will use the current working directory where Claude Code is running, so make sure to open Claude Code from the clubber project directory.
