Bill Tracker Skill

When the user asks about their bills, account balances, or whether they can afford something, use the bash tool to call the Bill Tracker API.

Required environment

• BILL_TRACKER_URL - Base URL (e.g. https://your-server.com or http://localhost:1337)
• BILL_TRACKER_SESSION_TOKEN - Session token for authentication (obtained once via POST /api/mcp/token)

Getting a session token

Bill Tracker uses magic-link auth (no passwords). Two steps:

1. Request a verification code (sent to email):

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}' \
  "${BILL_TRACKER_URL}/api/mcp/request-code"

2. Exchange the code from your email for a session token:

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"code":"123456"}' \
  "${BILL_TRACKER_URL}/api/mcp/token"

Store the returned sessionToken in BILL_TRACKER_SESSION_TOKEN. Tokens are long-lived; no need to re-verify on every request. (Codes expire in 10 minutes.)

Endpoints

1. Upcoming transactions (bills and income due soon)

POST ${BILL_TRACKER_URL}/api/mcp/upcoming-transactions
X-Parse-Session-Token: ${BILL_TRACKER_SESSION_TOKEN}
Body: { "days": 3 }

Default days is 3. Increase for a longer window (e.g. days=7).

2. Account balances

POST ${BILL_TRACKER_URL}/api/mcp/account-balances
X-Parse-Session-Token: ${BILL_TRACKER_SESSION_TOKEN}

Returns each account with name, type, balance, and a totalBalance (cash minus debt).

3. Can I afford X?

POST ${BILL_TRACKER_URL}/api/mcp/can-afford
X-Parse-Session-Token: ${BILL_TRACKER_SESSION_TOKEN}
Body: { "amount": 500, "horizonDays": 90 }

Replace 500 with the amount in dollars. horizonDays defaults to 90.

Returns either canAfford: true with the date they can afford it, or canAfford: false with a message.

How to call

Use curl with POST. Pass X-Parse-Session-Token (or Authorization: Bearer $BILL_TRACKER_SESSION_TOKEN) for authentication. The token identifies the user—no email or password needed. Parse the JSON response and summarize clearly for the user.

Example (upcoming transactions):

curl -s -X POST -H "X-Parse-Session-Token: $BILL_TRACKER_SESSION_TOKEN" -H "Content-Type: application/json" \
  -d '{"days": 3}' \
  "${BILL_TRACKER_URL}/api/mcp/upcoming-transactions"

Example (account balances):

curl -s -X POST -H "X-Parse-Session-Token: $BILL_TRACKER_SESSION_TOKEN" -H "Content-Type: application/json" \
  -d '{}' \
  "${BILL_TRACKER_URL}/api/mcp/account-balances"

Example (can afford):

curl -s -X POST -H "X-Parse-Session-Token: $BILL_TRACKER_SESSION_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 500}' \
  "${BILL_TRACKER_URL}/api/mcp/can-afford"