freelancer-payment-protection
About
MCP server wrapping the fpp CLI for freelancer client payment-risk checks.
Details
- Author
- rudrendupaul
- Categories
- Finance
Jump to
Setup
Install freelancer-payment-protection in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/rudrendupaul/freelancer-payment-protection
Follow the installation instructions in the repository README, then restart your MCP client.
MCP server wrapping the fpp CLI for freelancer client payment-risk checks.
Claude drafts jurisdiction-referenced demand letters and 0–100 client risk scores with full reasoning, wired into a self-hosted FastAPI + Next.js dashboard and a scriptable CLI.
Built byRudrendu Paul&Sourav Nandy
Note on the license:this project is MIT licensed. Copyright is held by Rudrendu Paul and Sourav Nandy. SeeLicensebelow for full terms.
pip install freelancer-payment-protection-cli # or: uvx freelancer-payment-protection-cli --help # or: npx freelancer-payment-protection-cli --help
That installsfpp, a typed command-line client for the FastAPI backend below (invoices, escalations, client risk scoring,--jsonon every data command). It talks to afreelancer-payment-protectionAPI instance you run yourself. SeeRun the full stack locallyto stand one up, or pointFPP_API_URLat one that's already running.
- What This Is
- Features
- Run the full stack locally
- Command-Line Interface
- API Reference
- Comparison
- Architecture
- MCP Server
- Security
- What's Not Implemented Yet
- FAQ
- Contributing
- License
FreshBooks and HoneyBook stop at "invoice sent." Neither drafts what to say when a client goes quiet, and neither scores a client's risk of non-payment before you start the work. This project is a FastAPI + Next.js app, backed by Claude, that does two specific things well: it drafts a stage-appropriate escalation email or a jurisdiction-referenced demand letter for an overdue invoice, and it scores a client's payment risk from 0–100 with a full factor breakdown, both with an AI-generated confidence/reasoning trail a human reviews before anything goes out.
It is not a set-and-forget automation system. There's no background scheduler enforcing wait times between stages and no live sync with FreshBooks/QuickBooks/Wave today. SeeWhat's Not Implemented Yetfor the honest gap between the architecture diagram and what's wired up. What's real: the AI drafting, the risk scoring, the evidence locker, and a CLI that scripts all three.
Verified against a fresh clone.Prerequisites:Node.js 20+, pnpm 9.x, Python 3.12.x (3.13/3.14 aren't supported by this checkout: 3.14 fails atpip installfor one of the pinned backend dependencies).
[!WARNING] Requires Python 3.12.x specifically. 3.13 and 3.14 are not yet supported.
git clone https://github.com/RudrenduPaul/freelancer-payment-protection.git cd freelancer-payment-protection pnpm install # Backend env cp apps/api/.env.example apps/api/.env # apps/api/.env.example ships two values that don't parse as written. See the # Troubleshooting question in the FAQ before you skip this: # ALLOWED_ORIGINS=["http://localhost:3000"] (needs the JSON-array brackets) # delete the DATABASE_URL= line entirely (Settings doesn't accept it; the # app already defaults to sqlite:///./dev.db without it) cp apps/web/.env.example apps/web/.env.local pip install -r apps/api/requirements.txt python -m alembic -c packages/db/migrations/alembic.ini upgrade head python scripts/seed_dev.py pnpm dev
The seed script needs no external services and produces 8 clients, 16 invoices, and pre-generated escalation events, all queryable through the API or the CLI once seeded. Verified end to end in a fresh venv:alembic upgrade headruns clean,seed_dev.pypopulates SQLite, anduvicorn app.main:appboots and serves/healthand/health/readyonce the two.envfixes above are applied.
Logging into theweb dashboardneeds a real (free tier is fine)Supabaseproject.apps/api/app/middleware/auth.pyvalidates a Supabase-issued JWT with no local bypass. The seeded data is fully reachable through the API/CLI without one. AI features (demand letters, risk scoring, escalation drafts) need a realANTHROPIC_API_KEYinapps/api/.env; without one, risk scoring falls back to the heuristic score and the other two AI routes return a 503.
Verified against the installed package's actual--helpoutput.
fpp login Log in (prompts for email/password) fpp logout Delete cached credentials fpp whoami [--json] Show cached workspace/session info fpp invoice list [--status] [--client-id] [--page] [--page-size] [--json] fpp invoice create --client-id --invoice-number --amount --due-date [--currency] [--source-system] [--external-id] [--json] fpp invoice show <invoice-id> [--json] fpp invoice set-status <invoice-id> <status> [--json] fpp escalation list [--json] Active escalations, grouped by stage fpp escalation status <invoice-id> [--json] Current stage + full history fpp escalation advance <invoice-id> [--json] Preview the next stage's AI-drafted email (does not send or persist) fpp client list [--risk-level] [--search] [--page] [--page-size] [--json] fpp client show <client-id> [--json] fpp client risk <client-id> [--json] Compute/refresh the AI risk score
fpp login fpp invoice list --status overdue --json | jq '.[] | {id, invoiceNumber, daysPastDue}' fpp client risk <client-id> --json | jq '.level'
--statusoninvoice listacceptsdisputed,overdue,paid,pending,written_off. Full flag reference for any command:fpp <command> --help. Full install, config, and auth walkthrough:packages/cli/README.md.
Interactive OpenAPI athttp://localhost:8000/docs. Verified against the router source directly:
GET /health Liveness probe GET /health/ready Readiness (DB) GET /api/v1/clients List POST /api/v1/clients Create GET /api/v1/clients/{client_id} Detail PUT /api/v1/clients/{client_id} Update DELETE /api/v1/clients/{client_id} Delete GET /api/v1/invoices List POST /api/v1/invoices Create (manual) GET /api/v1/invoices/{invoice_id} Detail PATCH /api/v1/invoices/{invoice_id}/status Update status GET /api/v1/escalations Active escalations POST /api/v1/escalations/{invoice_id}/draft AI-draft next escalation email (preview only) GET /api/v1/escalations/{invoice_id}/history Full history POST /api/v1/legal/demand-letter Generate demand letter POST /api/v1/legal/demand-letter/stream Generate + stream (SSE) GET /api/v1/evidence/{invoice_id} Evidence items POST /api/v1/evidence/{invoice_id}/upload Manual upload DELETE /api/v1/evidence/{item_id} Remove POST /api/v1/risk/score AI risk score, structured JSON GET /api/v1/analytics/overview Dashboard totals
Every non-freelancer-payment-protectionrow below is sourced from each vendor's own docs/help center, checked in August 2026.
The honest read: FreshBooks and HoneyBook are stronger at the mechanical, rule-based reminder they already do well. HubSpot's June 2026 Breeze beta is the closest thing to a competing risk-scoring feature on this list and is worth watching. Nobody here drafts a jurisdiction-referenced demand letter or streams AI generation into the UI; that's the actual gap this project fills, not "full collection automation," which none of these, including this project, deliver end to end yet.
System diagram (what's actually implemented)
graph TB subgraph "Frontend: Next.js 14" A[App Router Pages] B[TanStack Query Cache] C[Framer Motion UI] D[Supabase Auth Client] end subgraph "Backend: FastAPI, Python 3.12" E[FastAPI App Factory] F[JWT Middleware] G[slowapi Rate Limiter] H["Routers: 8 domains"] I[Services: business logic only] end subgraph "AI: Claude Sonnet 4.6" J[packages/legal_ai/client.py] K[Demand Letter: streaming SSE] L[Escalation Email: structured draft] M[Risk Scorer: JSON output] end subgraph "Data Layer" T[(Supabase PostgreSQL + RLS)] U[Supabase Storage] W[(SQLite Dev DB)] end A --> E D --> T B --> E E --> F --> G --> H --> I I --> J J --> K J --> L J --> M I --> T & U
Celery and Redis are declared dependencies (requirements.txt) with no worker code in the repository today: noapps/workers/directory exists, and there is no scheduled job that advances an invoice's stage automatically. SeeWhat's Not Implemented Yet.
Legal document drafting usespython-docx/WeasyPrintin the code paths that are wired up for it, and the Anthropic Python SDK is the reference implementation. The Python ecosystem is also where contract-analysis tooling (NLTK, spaCy) would live for a future dispute-analysis feature.
Why centralize all Claude calls in one file
packages/legal_ai/client.py(called fromapps/api/app/services/ai_service.py) is the only place the Anthropic SDK is imported. Model version, retries, and the sync-SDK/async-FastAPI bridge live there, so upgrading the model is a one-file change.
Why Pydantic Settings with fail-fast validation
settings = Settings()runs at import time. IfANTHROPIC_API_KEYis absent, the app raises before serving a request rather than degrading silently. The tradeoff: the settings model is strict about unrecognized fields too, which is the root cause of one of the two.env.exampleissues in the FAQ below.
Every data-returning command also takes--jsonfor structured output an agent or script can parse directly:
freelancer-payment-protection-cliships a Model Context Protocol (MCP) server, so an agent (Claude Desktop, Claude Code, or any other MCP client) can call the same commands above (invoice list,client risk,escalation status, ...) as tool calls instead of shelling out to the CLI directly.
pip install "freelancer-payment-protection-cli[mcp]"
Claude Desktop config(claude_desktop_config.json):
{ "mcpServers": { "freelancer-payment-protection": { "command": "fpp-mcp" } } }
The server exposes one tool,run, that shells out to the installedfppbinary with the given argument list and returns its output as structured JSON when possible — everyfppsubcommand is reachable through it, not just a hand-picked subset. Example call:run(args=["client", "risk", "<client-id>", "--json"])returns the same 0-100 risk score, factor breakdown, and AI reasoning thatfpp client risk <client-id> --jsonprints to a terminal.
Being direct about this because the architecture diagrams and dependency list overstate it otherwise:
- No background worker or scheduler.celeryandredisare pinned inrequirements.txt, but noapps/workers/code exists in the repository. Nothing advances an invoice's escalation stage automatically or on a timer.
- No minimum-wait-time enforcement.escalation_service.py'sget_next_stage()is a plain ordered lookup with no date/timedelta check anywhere in the call path. Any authenticated caller can request a draft for the next stage regardless of how long the invoice has been overdue; the endpoint also never writes the new stage back to the invoice.
- No FreshBooks/QuickBooks/Wave sync.packages/integrations/__init__.pyis an empty file. Invoices are created through the API/CLI, not synced from an accounting tool.
- No production PDF/DOCX export yet.doc_gen_service.py's docstring says it plainly: dev builds save the drafted letter as a.txtfile; thepython-docx/WeasyPrint production path is not wired up.
- No evidence ZIP export.The evidence router supports list/upload/delete only.
None of this is secret. It's what running the code shows. The parts that are real (AI drafting, risk scoring with reasoning, streaming, the CLI) are described above with specifics, not adjectives.
What is this, and what's the actual differentiator versus FreshBooks or HoneyBook?Both of those handle sending an invoice and reminding a client on a fixed schedule. Neither drafts a jurisdiction-referenced legal demand letter or scores a client's payment risk with an AI-generated reasoning trail. This project does both, backed by a real Claude API call you can see inpackages/legal_ai/andapps/api/app/services/, not a canned template swap.
Is this open source? Can I fork it or use the code in my own project?Yes. The repository is MIT licensed: fork it, modify it, or embed the code in your own project, subject only to the standard MIT terms inLICENSE(keep the copyright/permission notice). Thefreelancer-payment-protection-clipackage on PyPI/npm is installable and runnable as-is under the same license.
What platforms does the CLI support?Python 3.10–3.13 on Linux, macOS, or Windows, installed viapip,uvx, orpipx. The npm package (freelancer-payment-protection-clion npm) is a thin wrapper that shells out touvxorpipxat runtime rather than bundling a platform binary; it needs one of those two onPATH. Running the full backend/frontend stack needs Python 3.12.x specifically; 3.13/3.14 aren't supported by the current dependency pins.
How is this different from HubSpot's new Breeze Invoice Prioritization feature?Breeze (Revenue Hub, public beta as of June 2026) ranks a HubSpot user's overdue invoices by risk, age, and customer value, closer to a sort order than a score.fpp client riskreturns a 0–100 score with a named-factor breakdown and a written reasoning paragraph per client, works standalone without adopting the rest of HubSpot's CRM, and pairs with jurisdiction-referenced demand-letter drafting that HubSpot doesn't offer. Worth revisiting as Breeze comes out of beta.
I followed the Quick Start exactly anduvicorn app.main:app --reloadcrashed on startup. Is that a bug?Yes, a real one in the shippedapps/api/.env.example. Two of its default values don't surviveSettings()'s validation:ALLOWED_ORIGINS=http://localhost:3000needs to be a JSON array (["http://localhost:3000"]) because the field is typedlist[str], andDATABASE_URL=sqlite:///./dev.dbisn't a field theSettingsmodel declares at all, so it fails withExtra inputs are not permitted. Fix both lines in your.env(or just delete theDATABASE_URLline;apps/api/app/database.pyalready defaults to that same SQLite path independently) and the server boots. Confirmed by running the documented steps in a clean clone.
Doesfpp escalation advanceactually send the email or move the invoice forward?No. It calls/api/v1/escalations/{id}/draft, which returns an AI-drafted preview only. The backend has no endpoint today that persists a stage change or sends the email. SeeWhat's Not Implemented Yet.
What happens if I don't have anANTHROPIC_API_KEYset?The app still starts once the two.envfixes above are applied, but the AI routes behave differently:client riskfalls back to a deterministic heuristic score (documented inrisk_service.py), whileescalation advanceand the demand-letter endpoints return a 503 with no fallback.
Can I use this for a real client engagement today?For the CLI against your own self-hosted backend and Supabase project, yes. The MIT license also permits using or embedding this in a real client engagement or your own product; seeLicensefor the exact terms.
GitHub Issues are open for bug reports and feature requests. Pull requests are welcome; open an issue first for anything non-trivial so the approach can be agreed on before you put in the work. Reach out viagithub.com/RudrenduPaulwith questions.
Built by Rudrendu Paul and Sourav Nandy · Developed withClaude Code
Bridge Town is an MCP-native, git-versioned financial modeling platform for FP&A teams and finance leaders. AI agents use Bridge Town tools to create projects, write Python model files, run models in isolated cloud sandboxes, query data, write outputs to Google Sheets, create dashboards, branch scenarios, and collaborate with teammates.
The Capital.com MCP Server lets your AI assistant talk to your trading account directly. Market data, position checks, trade previews – all in plain language, without leaving your AI tool.
Coinrule Agentic Trading MCP enables investors to create, backtest, execute, and manage trading agents through natural language across stocks, crypto and ETFs
Invest with Claude and other AI assistants
Australian Consumer Data Right Product Data
Remote MCP server for historical crypto & prediction-market data: search ~500K instruments, live market stats (OHLC, turnover, spreads, depth, slippage) and tick-data purchase. Keyless for catalog & stats; optional OAuth for account tools. Endpoint: https://cryptostruct.com/mcp
Cross-border debt collection from your AI assistant: check cases, get pricing, submit new cases.
Read-only MCP server for your Evibe investment portfolio + live market data (holdings, performance, dividends, benchmarks, screeners). Works with Claude & ChatGPT.
Financial and quantitative modeling engine for AI agents. Typed, named, deterministic.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
