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