Wraps the fpp CLI as a single generic MCP tool for freelancer client payment-risk checks.
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
Manual Client & Custom JSON ConfigExpand JSON ▾
Client Config & Setup
Choose your client or environment
Target File:
💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.
Documentation Overview
freelancer-payment-protection
Full tech stack badges
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 by Rudrendu Paul & Sourav Nandy
Note on the license: this project is MIT licensed. Copyright is held by Rudrendu Paul and Sourav Nandy. See License below for full terms.
Install the CLI
That installs fpp, a typed command-line client for the FastAPI backend below (invoices, escalations, client risk scoring, --json on every data command). It talks to a freelancer-payment-protection API instance you run yourself. See Run the full stack locally to stand one up, or point FPP_API_URL at one that's already running.
Table of Contents
- 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
What This Is
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. See What's Not Implemented Yet for 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.
Features
| Capability | What's actually implemented |
|---|---|
| AI escalation drafting | Five ordered stages (polite_reminder → firm_notice → final_warning → legal_demand → legal_action). POST /api/v1/escalations/{id}/draft asks Claude for the next stage's subject/body/tone/confidence score. It's a preview: the endpoint doesn't send the email or persist the stage change (apps/api/app/services/escalation_service.py). |
| Jurisdiction-referenced demand letters | Claude drafts a letter for a jurisdiction string you supply. Four jurisdictions (California, New York, England & Wales, Ontario) have a dedicated template file under legal-templates/; any other jurisdiction still gets a draft, formatted from the model's general knowledge rather than a hard-coded template. Every letter carries a fixed AI-disclaimer paragraph. Streams to the UI over SSE via a threading.Thread → queue.Queue → asyncio.run_in_executor bridge (apps/api/app/services/ai_service.py), verified real and not just a UI-only typewriter effect. |
| Client risk scoring | POST /api/v1/risk/score returns a 0–100 score, a level (low/medium/high/critical), and a factors array. The prompt asks Claude to weigh 7 named factors (industry payment culture, payment-terms length, historical delay, contract quality, invoice size, geography, outstanding-balance ratio) and return its reasoning. If the Claude call fails, risk_service.py falls back to a deterministic heuristic score rather than erroring. Rate-limited to 30 requests/minute. |
| Evidence locker | Manual upload of PDF/PNG/JPEG/.eml/plain-text files (25MB cap), listed and deletable per invoice, backed by Supabase Storage in production. There's no drag-and-drop auto-capture and no ZIP export endpoint today. Uploads happen one file at a time via POST /api/v1/evidence/{invoice_id}/upload. |
CLI (fpp) | Every data-returning command supports --json. Persistent login against Supabase's own password-grant endpoint, cached to ~/.config/freelancer-payment-protection-cli/credentials.json (mode 600), transparent refresh. Published on PyPI and npm as freelancer-payment-protection-cli. |
| Security controls | Row Level Security on every Postgres table (packages/db/migrations/versions/002_rls_policies.sql), Supabase JWT auth with no local bypass, slowapi rate limiting (10/min on the AI-drafting routes, 30/min on risk scoring, 100/min global), CodeQL on every PR, pip-audit + pnpm audit dependency scanning, and TruffleHog secret scanning in CI. |
Run the full stack locally
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 at pip install for one of the pinned backend dependencies).
[!WARNING] Requires Python 3.12.x specifically. 3.13 and 3.14 are not yet supported.
Related MCP Servers
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about Freelancer Payment Protection
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/freelancer-payment-protection)HTML Embed
<a href="https://allmcps.com/mcp/freelancer-payment-protection"><img src="https://allmcps.com/api/badge/freelancer-payment-protection?style=directory" alt="Freelancer Payment Protection on AllMCPs" /></a>Technical Specs & Signals
CategoryDeveloper Tools
27Quality signal: Emerging · 27/100How this signal is calculated ▾
Server availabilityNot measured
Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.
Verified ownership8/20
Documentation & tools11/30
Adoption & activity1/15
Community engagement0/10
A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.
Own this project?
This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.
Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.
Claim & get free dofollowShare & Embed
Add our SVG badge (dark/light directory styles) or embeddable widget to your site.