Gatherings MCP Server

Instructions

Implementation Reference

• src/index.ts:119-139 (schema)

  MCP tool schema definition for record_payment, including input parameters and descriptions.
  name: 'record_payment', description: 'Record a payment made by a member', inputSchema: { type: 'object', properties: { gathering_id: { type: 'string', description: 'ID of the gathering', }, member_name: { type: 'string', description: 'Name of the member making the payment', }, amount: { type: 'number', description: 'Amount paid (negative for reimbursements)', }, }, required: ['gathering_id', 'member_name', 'amount'], }, },
• src/index.ts:316-321 (handler)

  MCP CallTool handler case for record_payment: validates input using isExpenseArgs and builds Python CLI command.
  case 'record_payment': if (!isExpenseArgs(args)) { throw new McpError(ErrorCode.InvalidParams, 'Invalid record_payment arguments'); } command += ` record-payment "${args.gathering_id}" "${args.member_name}" ${args.amount}`; break;
• src/index.ts:269-273 (helper)

  Type guard helper function used for validating record_payment (and add_expense) arguments.
  const isExpenseArgs = (args: any): args is { gathering_id: string; member_name: string; amount: number } => typeof args === 'object' && args !== null && typeof args.gathering_id === 'string' && typeof args.member_name === 'string' && typeof args.amount === 'number';
• gatherings.py:182-208 (handler)

  CLI command handler for record-payment: invokes service.record_payment and formats response.
  def handle_record_payment(service, args): """Handle the record-payment command.""" try: gathering, member = service.record_payment(args.gathering_id, args.member_name, args.amount) result = { "success": True, "payment": { "member": member.name, "amount": args.amount, "type": "reimbursement" if args.amount < 0 else "payment" } } if args.json: print(json.dumps(result)) else: if args.amount < 0: print(f"Recorded reimbursement of ${abs(args.amount):.2f} to {member.name}") else: print(f"Recorded payment of ${args.amount:.2f} from {member.name}") 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:431-487 (handler)

  Core database handler implementation: validates gathering and member, creates and commits Payment record to database.
  def record_payment(self, gathering_id: str, member_name: str, amount: float) -> Tuple[Gathering, Member]: """ Record a payment made by a member. Args: gathering_id: The ID of the gathering member_name: The name of the member amount: The payment amount (positive for payments, negative for reimbursements) Returns: Tuple of (updated Gathering, Member who paid/received) Raises: ValueError: If the gathering is closed, the member doesn't exist, or the payment is invalid """ session = self.Session() try: # Get the gathering gathering = session.query(Gathering).filter_by(id=gathering_id).first() if not gathering: raise ValueError(f"Gathering '{gathering_id}' not found") # Check if gathering is open if gathering.status == GatheringStatus.CLOSED: raise ValueError(f"Cannot record payment to closed gathering '{gathering_id}'") # Get the member member = session.query(Member).filter_by(gathering_id=gathering_id, name=member_name).first() if not member: raise ValueError(f"Member '{member_name}' not found in gathering '{gathering_id}'") # Add the payment payment = Payment(member_id=member.id, amount=amount) session.add(payment) session.commit() # Get fresh copies of the gathering and member updated_gathering = self.get_gathering(gathering_id) # Find the member in the updated gathering updated_member = None for m in updated_gathering.members: if m.name == member_name: updated_member = m break if not updated_member: raise ValueError(f"Cannot find member '{member_name}' after recording payment") return updated_gathering, updated_member except Exception as e: session.rollback() raise e finally: session.close()