Gatherings MCP Server

Instructions

Implementation Reference

• src/index.ts:118-139 (registration)

  MCP tool registration for 'record_payment' including name, description, and input schema.

  {
    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:121-138 (schema)

  Input schema definition for the 'record_payment' MCP tool.

  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 for 'record_payment': validates input using isExpenseArgs and constructs the CLI command to invoke the Python script.

  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;

• gatherings.py:182-208 (handler)

  CLI command handler for 'record-payment': invokes service.record_payment and formats JSON or text output.

  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: validates gathering and member, creates a new Payment record in the database, commits, and returns updated objects.

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