Gatherings MCP Server

Instructions

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()