Referee

Alexa reminders remember "when?". Referee remembers "what you agreed".

Comment

Inspiration

Diving deep into cybersecurity—spending my nights tackling TryHackMe modules and working with the CyberYoddha club at college—taught me that the most dangerous vulnerabilities usually stem from unvalidated inputs.

I started noticing this exact same vulnerability in everyday life, specifically in informal handshake deals. Whether it was splitting a Swiggy Instamart grocery order, covering a friend's Yulu ride, or managing shared costs on a daily Delhi Metro commute, the agreements were always painfully vague.

Someone would say, "I lent Aman 1.5k, he'll pay Friday," but which Friday? Cash or UPI?

This social ambiguity is the equivalent of an open port. That realization inspired Referee—an automated, voice-first Model Context Protocol (MCP) server that acts as a strict firewall against vague terms, forcing exactness before a deal is locked.

What it does

Referee is a self-hosted MCP server that transforms vague, spoken money deals into exact, trackable terms.

It captures the details of an informal agreement, identifies fuzzy amounts or relative deadlines, and asks sharp clarifying questions to remove the ambiguity. Once the terms are verified, it locks them into an append-only event log, tracks subsequent payments, and yields a neutral, deterministic verdict.

How I built it

  • Core Server: Built using Python 3.11+ and the official MCP Python SDK, utilizing the Streamable HTTP transport.
  • Vagueness Detection: Developed vagueterms, a deterministic, pure-Python rules engine that relies on keyword heuristics to spot ambiguity, ensuring predictability and preventing hallucinations.
  • State Management: Used SQLite with an append-only event architecture, ensuring original terms are never overwritten and amendments are fully tracked.

Challenges I ran into

The most significant hurdle was accurately extracting intent from complex statements. Conversational phrasing is messy, and our initial deterministic regex parser struggled with mixed pronouns and multi-clause sentences, proving that parsing complex statements is a massive bottleneck for voice-first financial tools.

Managing state context across multi-turn conversations was difficult, as users frequently triggered context-switching commands that conflicted with active slot-filling flows.

Accomplishments that I'm proud of

  • Creating a strict separation of concerns where the parser only extracts data, while a fully deterministic vagueness detector handles decision-making without hallucinating.
  • Successfully publishing vagueterms as a standalone open-source Python package.
  • Implementing a tamper-evident event architecture that maintains a perfectly honest history of every deal.

What I learned

  • Natural language agreements rarely match exact slot values; users say "sounds good" instead of confirming a date, requiring flexible heuristics.
  • The architecture must strictly isolate data extraction from rules logic to remain trustworthy.

What's next for Referee

Because complex statements remain our biggest parsing challenge, we plan to integrate Amazon Bedrock, specifically an Amazon Nova model, to parse intricate conversational sentences directly into structured JSON term sheets.

We will retain the current regex engine as a zero-cost deterministic fallback to ensure the app functions even when offline or without cloud access.

Built With

Share this project:

Updates

Submission history