Work context, packaged for LLMs

UCP is an open format that turns a sprawling issue thread into a small, verifiable package your agent can load: facts, decisions, conflicts, hashed sources.

Try in browser Run the server Read the spec

microsoft/vscode#519 · 596 comments over ten years

raw thread~18,500 tokens

ucp package~1,200 tokens

15× smaller, with decisions, conflicts and provenance intact.

Install

Run the whole toolchain as one self-hosted service, or pick the piece you need.

One container: REST API on /v1, MCP over Streamable HTTP on /mcp.

docker run --rm -p 8080:8080 -e GITHUB_TOKEN=ghp_yourtoken \
  ghcr.io/ucpcore/ucp-server:latest

Same server, no Docker. The PyPI package is ucpcore-server; the command is ucp-server.

uvx --from ucpcore-server ucp-server

The CLI generator, the stdio MCP server, and the Python library.

pip install ucp-gen # ucp-gen github owner/repo#42, ucp-gen jira KEY-1

pip install ucp-mcp # serve packages to agents over stdio

pip install pyucp # import ucp: models, validation, rendering

Types, validation and canonical rendering for TypeScript.

npm install @ucpcore/core

Generate a package from a real issue

By default no LLM is involved: the structure alone carries the facts, decisions and timeline. Decorations go to stderr; stdout stays pure JSON, so piping is always safe.

Works on any public GitHub issue or Jira ticket. Every claim cites its sources; every source carries a sha256 hash. The output validates against the schema before it is written.

ucp-genzsh

$ ucp-gen github pallets/flask#5961 -o task.ucp.json✓ pallets/flask#5961 — issue + 4 comments + 1 linked PRs✓ valid ucp-core package — 6 sources, sha256-hashed📦 wrote task.ucp.json├── Flask 3.1.3 test breaks after Werkzeug update…├── claims 7 must-know├── decisions 1 (1 accepted)├── coverage truncated=false├── sources 6└── tokens ~713 rendered$

Connect Cursor or Claude Code in 60 seconds

MCP is the pipe. UCP is what flows through it. Start the server, point your agent at it, done.

Start the server

Generates and caches packages on demand.

docker run --rm -p 8080:8080 \
  -e GITHUB_TOKEN=ghp_yourtoken \
  ghcr.io/ucpcore/ucp-server:latest

Add it to mcp.json

Cursor and Claude Code speak Streamable HTTP natively.

{
  "mcpServers": {
    "ucp": { "url": "http://localhost:8080/mcp" }
  }
}

Your agent now has generate_context, list_contexts, get_context, get_context_markdown, and submit_usage_receipt. Ask it to load context for owner/repo#123 or PROJ-123. Prefer plain HTTP? The same server exposes POST /v1/generate and POST /v1/receipt.

Deploying beyond localhost? Set UCP_SERVER_API_KEY and send it as a Bearer header — see the MCP reference.

Close the loop with Usage Receipts

Most context formats are one-way: producer ships a package, the agent reads it, and nobody learns what actually helped. UCP adds a Usage Receipt — a small JSON object that records which claims were cited, which were ignored, and how the task ended. The reference server uses that signal to warm-rank the next package for your team.

Step 1

Generate

Server assembles a UCP with ranked must_know

Step 2

Agent works

Cursor, Sidebar, or any MCP client uses cited claims

Step 3

Submit receipt

Claim ids only — no claim text, privacy-safe

Step 4

Warm rank

Cited claims gain salience; noise drops

Step 5

Next package

Same task, sharper ordering for your team

Package · must_know before receipt

mk-1 HMAC-SHA256 required for webhooks .82 · graph

mk-2 Redis idempotency keys (team debate) .71 · producer

mk-3 Legacy v1 keys sunset Aug 1 .65 · recency

cited mk-1, mk-3 — used in the fix

ignored mk-2 — not relevant this sprint

usage-receipt.json §4.12

{
  "receipt_version": "0.1.0",
  "package_id": "urn:uuid:7f9c…",
  "consumer": { "type": "mcp" },
  "claims_cited": ["mk-1", "mk-3"],
  "claims_ignored": ["mk-2"],
  "gaps_needed": ["rate-limit docs"],
  "outcome": "task_completed"
}

Next package warm ranking

mk-1

.94

mk-3

.88

mk-2

.52

Salience delta

mk-1

+12%

mk-2

−19%

MCP: submit_usage_receipt · REST: POST /v1/receipt Example receipt → SPEC §4.12 →

Measured on real issues

Same token estimator on both sides (~4 chars/token). "Raw thread" is the text you would otherwise paste into the model: title, body, comments, linked-PR bodies.

Issue	Comments	Raw thread	UCP
microsoft/vscode#519	first 200 of 596	~18,500	~1,200
rust-lang/rust#158622	12	~4,450	~1,450
pallets/flask#5961	4	~800	~700
pallets/flask#5948	0	~500	~330

The win grows with thread size: a decade-long discussion collapses ~15× while keeping decisions, conflicts and provenance. On small issues the token count is similar, but the package is still structured, hashed and audience-aware. Reproduce with tools/benchmark_context.py; generated with ucp-gen 0.3.1, 2026-07-06.

What --llm adds

One call to any OpenAI-compatible endpoint extracts what exists only in prose. Guarantees hold: the package stays schema-valid, hallucinated citations are dropped, and if the endpoint is down you get the structural package with a warning.

conflict

On vscode#519, the enriched package records the dispute over whether Electron or VS Code's hard-coded styles are to blame, both positions citing specific hashed comments.

decision [rejected]

The request is not on the roadmap. Stated only in prose across a decade of comments, invisible to every structured GitHub field.

What's inside a package

One JSON document. Every consumer, human or model, gets the same predictable sections.

{ "summary": { … }, // what is going on, with cited sources "must_know": [ … ], // facts, each with a salience score "decisions": [ … ], // what was decided, when, with status "conflicts": [ … ], // contradictions, kept visible instead of merged "context_diff": { … }, // what changed since your last visit "coverage": { … }, // truncated honesty on partial fetch "sources": { … }, // every claim cites sources; each sha256-hashed "profiles": ["ucp-core", "ucp-verified"] // expects a Usage Receipt (§4.12) }

A canonical rendering algorithm turns any package into a deterministic prompt. Under a token budget, salience defines the truncation order (each claim MAY carry salience_method: producer, graph, ranking, or llm). Sources carry content_hash (sha256); consumers revalidate with since + context_diff when the upstream changes. A claim without sources is schema-invalid.