create_gathering

Create a new social event to track expenses and calculate reimbursements for settling balances between friends.

Instructions

Create a new gathering

Input Schema

TableJSON Schema

Name	Required	Description	Default
`gathering_id`	Yes	Unique ID for the gathering (format: yyyy-mm-dd-type)
`members`	Yes	Number of members in the gathering

Implementation Reference

src/index.ts:295-300 (handler)

MCP CallTool request handler logic for the 'create_gathering' tool. Validates arguments using a type guard and appends the appropriate CLI command to execute the Python gatherings.py 'create' subcommand.

case 'create_gathering':
  if (!isCreateGatheringArgs(args)) {
    throw new McpError(ErrorCode.InvalidParams, 'Invalid create_gathering arguments');
  }
  command += ` create "${args.gathering_id}" --members ${args.members}`;
  break;

src/index.ts:64-81 (registration)

Tool registration in the ListTools handler response, defining the name, description, and input schema for 'create_gathering'.

{
  name: 'create_gathering',
  description: 'Create a new gathering',
  inputSchema: {
    type: 'object',
    properties: {
      gathering_id: {
        type: 'string',
        description: 'Unique ID for the gathering (format: yyyy-mm-dd-type)',
      },
      members: {
        type: 'number',
        description: 'Number of members in the gathering',
      },
    },
    required: ['gathering_id', 'members'],
  },
},

src/index.ts:260-263 (schema)

TypeScript type guard used for runtime validation of 'create_gathering' tool input arguments.

const isCreateGatheringArgs = (args: any): args is { gathering_id: string; members: number } =>
  typeof args === 'object' && args !== null &&
  typeof args.gathering_id === 'string' &&
  typeof args.members === 'number';

gatherings.py:91-117 (helper)

CLI handler function for the 'create' subcommand invoked by the MCP server via subprocess execution. Calls the GatheringService.create_gathering method.

def handle_create(service, args):
    """Handle the create command."""
    try:
        gathering = service.create_gathering(args.gathering_id, args.members)
        result = {
            "success": True,
            "gathering": {
                "id": gathering.id,
                "total_members": gathering.total_members,
                "status": gathering.status.value
            }
        }
        if args.json:
            print(json.dumps(result))
        else:
            print(f"Created gathering: {gathering.id}")
            print(f"Total members: {gathering.total_members}")
            print(f"Status: {gathering.status.value}")
        return True
    except ValueError as e:
        error = {"success": False, "error": str(e)}
        if args.json:
            print(json.dumps(error))
        else:
            print(f"Error: {e}")
        return False

models.py:159-211 (helper)

Core implementation in DatabaseManager.create_gathering: validates ID format, creates Gathering record, adds unnamed placeholder members (member0001 etc.), commits to SQLite DB.

def create_gathering(self, gathering_id: str, total_members: int) -> Gathering:
    """
    Create a new gathering.
    
    Args:
        gathering_id: A unique ID for the gathering (format: yyyy-mm-dd-type)
        total_members: The number of members in the gathering
        
    Returns:
        The created Gathering object
        
    Raises:
        ValueError: If the gathering ID is invalid or already exists
    """
    # Validate gathering_id format
    try:
        date_part = "-".join(gathering_id.split("-")[:3])
        datetime.strptime(date_part, "%Y-%m-%d")
    except (ValueError, IndexError):
        raise ValueError("Gathering ID must start with a valid date in format yyyy-mm-dd-type")
    
    session = self.Session()
    try:
        # Check if gathering already exists
        existing_gathering = session.query(Gathering).filter_by(id=gathering_id).first()
        if (existing_gathering):
            raise ValueError(f"Gathering with ID '{gathering_id}' already exists")
        
        # Create the gathering
        gathering = Gathering(
            id=gathering_id,
            total_members=total_members,
            status=GatheringStatus.OPEN
        )
        session.add(gathering)
        
        # Create unnamed members
        for i in range(1, total_members + 1):
            member_name = f"member{i:04d}"
            member = Member(name=member_name, gathering_id=gathering_id)
            session.add(member)
        
        session.commit()
        
        # Create a new session to fetch the complete gathering with all relationships
        return self.get_gathering(gathering_id)
        
    except Exception as e:
        session.rollback()
        raise e
    finally:
        session.close()

Gatherings MCP Server