Gatherings MCP Server

Instructions

Implementation Reference

• services.py:67-97 (handler)

  Core handler function that implements the reimbursement calculation logic: retrieves the gathering, computes for each member (expense_per_member - total_expenses + total_payments), and returns dict of member_name to amount (negative=gets reimbursed).
  def calculate_reimbursements(self, gathering_id: str) -> Dict[str, float]: """ Calculate reimbursements for a gathering. Args: gathering_id: The ID of the gathering Returns: A dictionary mapping member names to reimbursement amounts (negative values mean the member gets reimbursed, positive values mean they owe money) Raises: ValueError: If the gathering doesn't exist """ gathering = self.get_gathering(gathering_id) if not gathering: raise ValueError(f"Gathering '{gathering_id}' not found") # Calculate how much each member has paid and should pay expense_per_member = gathering.expense_per_member # Calculate reimbursements reimbursements = {} for member in gathering.members: # Amount to pay = total share - expenses + payments # If negative, member gets reimbursed; if positive, member owes money to_pay = expense_per_member - member.total_expenses + member.total_payments reimbursements[member.name] = to_pay return reimbursements
• src/index.ts:104-117 (schema)

  MCP tool schema definition: name, description, and inputSchema requiring a single 'gathering_id' string property.
  { name: 'calculate_reimbursements', description: 'Calculate reimbursements for a gathering', inputSchema: { type: 'object', properties: { gathering_id: { type: 'string', description: 'ID of the gathering', }, }, required: ['gathering_id'], }, },
• src/index.ts:309-314 (handler)

  MCP CallToolRequest handler case for calculate_reimbursements: validates input using isGatheringIdArg type guard and constructs the Python CLI subcommand.
  case 'calculate_reimbursements': if (!isGatheringIdArg(args)) { throw new McpError(ErrorCode.InvalidParams, 'Invalid calculate_reimbursements arguments'); } command += ` calculate "${args.gathering_id}"`; break;
• gatherings.py:144-181 (helper)

  CLI handler for 'calculate' command (invoked by MCP via python CLI): calls service.calculate_reimbursements, enhances output with types and totals, prints JSON or human-readable format.
  def handle_calculate(service, args): """Handle the calculate command.""" try: reimbursements = service.calculate_reimbursements(args.gathering_id) gathering = service.get_gathering(args.gathering_id) result = { "success": True, "calculation": { "total_expenses": gathering.total_expenses, "expense_per_member": gathering.expense_per_member, "reimbursements": { name: {"amount": amount, "type": "gets_reimbursed" if amount < 0 else "needs_to_pay"} for name, amount in reimbursements.items() } } } if args.json: print(json.dumps(result)) else: print(f"Total expenses: ${gathering.total_expenses:.2f}") print(f"Expense per member: ${gathering.expense_per_member:.2f}") print("Reimbursements:") for name, amount in reimbursements.items(): if amount < 0: print(f" {name} gets reimbursed ${abs(amount):.2f}") else: print(f" {name} needs to pay ${amount:.2f}") 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