mcp-judge

Unpublished public-release candidate. See PUBLIC_RELEASE.md for license information, privacy boundaries, verification and known limitations.

English | 한국어 | 日本語 | 中文

A source-neutral message-triage MCP. It classifies incoming messages into a small, bounded set of action categories with a fast model, then routes each one: dismiss noise, notify what needs you, and (optionally) auto-register clear calendar events. You bring your own source, notifier, and calendar through small adapter interfaces.

It answers "does this need me to act?" — not the open-ended "is this useful?" — so it stays a filter, not a second inbox.

Why

A plain keyword/regex filter can miss action items that have no date token ("can you take this?", "please reply"). Model-based classification is an alternative; accuracy and cost depend on the selected provider and have not been benchmarked here.

Install

pip install -e .            # core (MCP + Claude CLI backend, no API key)
pip install -e ".[anthropic]"   # optional: Anthropic SDK backend
pip install -e ".[dev]"         # tests + lint

The default backend drives a logged-in Claude CLI (claude -p) — no API key to manage. Set backend: "anthropic" in config to use the Anthropic SDK with ANTHROPIC_API_KEY instead.

Quickstart (model service required; may incur charges)

mcp-judge --source examples/demo.jsonl

This reads a JSONL file source, classifies each line, prints notifications for action items, and dismisses the rest. State is stored in a local SQLite DB (judge.sqlite3).

This is not an offline demo: it invokes the configured model backend. A CLI login does not make inference free. Messages and context are sent to that provider. For offline checks with synthetic models, use the tests instead; see PUBLIC_RELEASE.md.

Configuration

A JSON file (see config.example.json), passed with --config:

Presets

A preset is pure data: the category list, which categories are action (notify-worthy), which notify even when unsure (fail-safe), which may auto-register to a calendar, and the model instructions. schedule-en and schedule-ko ship built in; add your own in mcp_judge/config.py.

MCP server

MCP_JUDGE_CONFIG=./config.json mcp-judge-server

Tools: judge_ingest(source, item_id, text, context?), judge_pending(limit?), judge_get(item_id, source?), judge_health(). The server records verdicts and sends notifications inline when a notifier is configured.

Identity and upgrades

Items are unique by (source, item_id). judge_get without source remains compatible for unique IDs; ambiguous IDs return ambiguous_item_id rather than selecting an arbitrary record. Store get/resolve accept keyword source and raise AmbiguousItemError for ambiguous unqualified IDs.

Opening an old database migrates its single-column primary key transactionally, preserving message text, status, verdict, notification and creation time. Back up your database before upgrading; old versions cannot safely use the migrated schema. New calendar idempotency keys are JSON arrays [source, item_id], not bare IDs. Existing registered records remain terminal and are not replayed. Custom calendar adapters must accept the new key format; historical external keys are not rewritten.

Bring your own adapters

The engine depends only on three Protocols in mcp_judge/adapters.py:

• Source — items() yields {item_id, text, context?}.
• Notifier — send(text) -> delivery_id.
• Calendar — create_event(title, date, time, idempotency_key) -> id (idempotent).

FileSource and StdoutNotifier are included as runnable demos, plus a built-in TelegramNotifier (set channels.notifier: "telegram" with your own bot token/token_env and chat_id — no extra infra). Implement the Protocols to wire any other source, notifier, or calendar.

License

MIT, Copyright (c) 2026 Bum-Boo. The owner confirmed rights to the code and samples and approved this notice.

Note: the ko/ja/zh translations are machine-made and not yet native-reviewed.