Developers

Build, run and extend Splitr

Splitr is open source under Apache-2.0. Run it locally in a minute, host your own copy for $0, or build on top of it.

Quick start

You need Node.js 22+ and Git.

git clone https://github.com/anpixelartist/Splitr.git
cd Splitr
npm install
npm run dev
No Firebase keys? No problem.

Without a .env.local, Splitr runs in local-only mode: a mock identity, data stored in your browser, and no network calls. That's ideal for UI work. To sync between devices, add Firebase keys (see Self-host).

Tech stack

  • Frontend: React 19, TypeScript, Vite, Tailwind CSS, React Router
  • Backend: Firebase Authentication (Google + anonymous) and Cloud Firestore with offline persistence. No custom server for the app itself.
  • AI connector: Cloudflare Worker with OAuth 2.1 and the MCP TypeScript SDK (see MCP server)
  • App shell: installable PWA via vite-plugin-pwa
  • Quality: Vitest unit tests, Firestore rules tests on the emulator, oxlint, GitHub Actions CI

Project layout

src/
  context/AuthContext.tsx   sign-in, account linking, profile & contacts
  context/GroupContext.tsx  groups, expenses, settlements (Firestore + local cache)
  lib/settlement.ts         balance maths, settlement plan, cent-exact splitting
  lib/claims.ts             resolving name-only participants claimed by real users
  lib/payments.ts           payment status: pending / confirmed / rejected / cancelled
  lib/money.ts              currencies and locale-aware formatting
  pages/, components/       UI
firestore.rules             who can read/write what (the real security boundary)
rules-tests/                tests for the rules
firebase.json               hosting + rules + emulator config
mcp/                        AI connector: Cloudflare Worker (MCP server + OAuth)

Scripts

CommandWhat it does
npm run devDev server with hot reload
npm run buildType-check and production build into dist/
npm testUnit tests (src/**/*.test.ts)
npm run test:rulesFirestore security-rules tests on the emulator (needs Java 21+)
npm run lintoxlint
npm run deployBuild and deploy hosting + rules to Firebase

Data model

Four Firestore collections. The group code doubles as the invite.

users/{uid}                     { name, contacts[] }
groups/{code}                   { name, members[], admins[], memberNames{}, participants[],
                                  claims{}, currency, createdBy }
groups/{code}/expenses/{id}     { description, amount, paidBy, splits[], createdBy, createdAt,
                                  editedBy?, editedAt? }
groups/{code}/settlements/{id}  { from, to, amount, recordedBy, createdAt, status, recordedAt,
                                  decidedBy?, decidedAt? }
  • Participants and claims. People without the app are name-only participants. When they join, they can claim their participant. claims maps participant id → uid, and every balance is read through it, so no expense is ever rewritten.
  • Splits. splits[] holds { userId, amount } per person. Equal splits are cent-exact using the currency's minor units (0 digits for JPY, KRW, VND).
  • Currency. One ISO 4217 code per group. Older groups default to USD.

Permissions

firestore.rules is the security boundary. The client is never trusted.

  • Any signed-in user can look up a group by its exact code and join. Groups can't be listed except your own (members array-contains uid).
  • Expenses and settlements are visible to members only.
  • The person who added an expense, or an admin, can edit it. It keeps its date, and edits are stamped with who and when. Admins delete, with a 5-second Undo in the UI.
  • Recorded payments are never removed by deleting an expense, because they're money that really changed hands.
  • A payment counts once the receiver confirms it: immediately if the receiver recorded it or is name-only, otherwise automatically after 7 days of server time. The receiver can reject or undo, and the recorder can cancel while it's pending.

Self-host for $0

Run your own Splitr for your friends on Firebase's free Spark plan. It needs no credit card, so you can't be charged even by accident. Setup takes about 20 minutes.

  1. Create a Firebase project (Analytics off) and confirm it's on Spark.
  2. Create a Firestore database (Standard, production mode, region near your group).
  3. Enable Google and Anonymous sign-in under Authentication.
  4. Register a web app and copy its config into .env.local (start from .env.example).
  5. Link the folder and deploy:
    npx firebase-tools@15 login
    npx firebase-tools@15 use --add
    npm run deploy
  6. Add your *.web.app domain to the Google OAuth client's authorised origins and redirect URIs, so sign-in works on phones.

The full, step-by-step guide covers CI deploys on merge to main, custom domains and free-tier limits: DEPLOYMENT.md.

Free limit (Spark)Typical use, ~20 people
50,000 Firestore reads / day3,000 to 10,000
20,000 Firestore writes / dayunder 500
1 GiB Firestore storageunder 5 MB
360 MB hosting transfer / dayabout 1 MB per person per release

MCP server

The Splitr AI Connector is a remote MCP server in the repo's mcp/ folder. It runs on Cloudflare Workers (free plan) at https://splitr-mcp.splitr.workers.dev/mcp. Available

Design rules

  • Acts as the user. No Firebase Admin SDK or service account. Every Firestore REST call carries the user's own ID token, so firestore.rules decides everything. test/integration proves it against the emulators.
  • OAuth 2.1 + PKCE with dynamic client registration and Client ID Metadata Documents (@cloudflare/workers-oauth-provider). /authorize signs in with Firebase Auth (Google). The Firebase refresh token is encrypted in the grant's props and swapped for an ID token (cached about 55 minutes) per call. KV holds OAuth state only.
  • Stateless. Each request builds a fresh MCP server bound to that person (@modelcontextprotocol/server), so no Durable Objects are needed.
  • Shared business logic. Imports ../src/lib and ../src/types directly, so the connector's numbers always match the app.
  • Guest accounts are refused at sign-in, with a message to switch to Google first.
FileWhat it does
src/index.tsWorker entry: OAuth provider, routes, /mcp
src/server.tsMCP server and the list of tools
src/auth.ts/authorize consent and Google sign-in page, refresh-time checks
src/token.tsFirebase Secure Token exchange and ID-token cache
src/firestore.tsThin Firestore REST client that acts as the user
src/group.tsLoads a group like the app does: names, balances, fuzzy group matching
src/tools/*.tsOne file per tool (reference)

Deploy your own

cd mcp
npm install
npx wrangler login
npx wrangler kv namespace create OAUTH_KV   # put the printed id in wrangler.toml
npx wrangler secret put FIREBASE_API_KEY    # same values as the app's VITE_FIREBASE_*
npx wrangler secret put FIREBASE_AUTH_DOMAIN
npx wrangler secret put FIREBASE_PROJECT_ID
npm run deploy

Then add the Worker's host (for example splitr-mcp.<your-subdomain>.workers.dev) under Firebase Authentication → Settings → Authorized domains. Otherwise sign-in shows auth/unauthorized-domain. Your connector URL is that address plus /mcp.

Local development

Needs Java 21+ for the Firestore emulator.

# Terminal 1 (repo root): emulators with the real firestore.rules
npx firebase-tools@15 emulators:start --only auth,firestore --project demo-splitr

# Terminal 2 (mcp/)
cp .dev.vars.example .dev.vars
npm run dev                               # http://localhost:8787/mcp
npx @modelcontextprotocol/inspector       # Streamable HTTP, then "Quick OAuth Flow"
npm test                   # unit tests (mocked Firestore)
npm run test:integration   # Auth + Firestore emulators, real rules
npm run typecheck

Free-tier headroom

  • Workers: 100,000 requests a day. One tool call is one request.
  • KV: 100,000 reads and 1,000 writes a day. Writes happen only on connect and token refresh.
  • Firestore (Spark): 50,000 reads a day. An overview call for someone in 5 groups of 100 expenses reads about 500 documents, so ~20 people asking a few questions a day fit comfortably.
  • Bundle: about 270 KB gzipped, against a 3 MB limit.

Full guide, including adding it to each assistant: mcp/README.md.

Contributing

Bug fixes, translations and ideas are welcome.

  1. Check open issues, or open one to discuss bigger changes first.
  2. Branch off main using feat/… or fix/….
  3. Make sure these pass before opening a PR:
    npm run lint && npm test && npm run build && npm run test:rules
  4. If you change firestore.rules, add tests in rules-tests/.
  5. Open a pull request to main. CI runs the checks, and merges deploy automatically.

Found a security problem? Please report it privately (see Security), not in a public issue.

License

Splitr is released under the Apache License 2.0. You can use, modify and redistribute it, including commercially, as long as you keep the licence and notices.