com.welancePublished by welance.comOfficial publisherv1.14.1Updated Oct 29, 2026
Free bar for digital product briefs: your model judges, open rules and code score it.
The publisher's own server: welance/directory
Free remote MCP server that scores digital product briefs against an open, versioned ruleset, using your assistant's own model to judge.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/com.welance%2Fperfect-brief/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"brief-bar": {
"type": "http",
"url": "https://briefs.welance.com/mcp"
}
}
}briefs.welance.com)Eight languages, no build step, no tracking. Same origin serves the pages and the API.
Scores a digital product brief against an open, versioned ruleset. The score says how good a brief is; a separate gate says whether it may publish. An LLM only ever judges (server-side, key never leaves the box); deterministic code owns every number, the gate, and the decision.
The product target is a brief that makes expectations explicit and open to discussion, so client and supplier can understand whether and how to work together before committing. See the product decision and audit of current rule coverage. The audit identifies proposed improvements; it does not change current scoring.
This repo is the service. The ruleset + engine live inside it as an
installable package (brief_bar/) so they can later be split into their own
OSS repo and consumed here as a pinned dependency — the seam is already drawn.
Without an API key the service runs mock-only (instant keyword engine,
fully deterministic) — enough to develop against and to run the whole test
suite. Add the key to unlock the llm judge and /v1/suggest.
The console can import PDF, UTF-8 TXT and Markdown documents up to 10 MB
(10,000,000 bytes). Text extraction runs locally using the vendored
PDF.js display API and worker; the original
file is not uploaded. Review the extracted text before explicitly scoring with
AI. Imported-document scoring sets no_cache: true.
The API's separate text limit defaults to 1,000,000 characters
(PB_REQUEST_MAX_CHARS). Existing environment overrides still apply. Provider
context limits may be lower; a successful import does not guarantee that every
model can judge the document. Text is never silently truncated or summarised.
PDF extraction is limited to 1,000 pages and 60 seconds; pages without extractable
text, password-protected PDFs and malformed files are refused. Run OCR or remove
blank pages before import when needed. There is no multipart/file storage API.
POST /v1/score
The ruleset_version is your audit trail: it pins exactly which bar judged a
brief, and every verdict carries a verbatim quote from the brief as evidence —
inspectable by a human long after any particular model is gone. (The mock
judge is reproducible forever; the LLM judge runs at temperature 0 and is
cached by (ruleset_version, model, brief), but temperature 0 is not a
determinism guarantee across provider updates — the quotes are the part of
the trail that never expires.)
Welance uses OpenRouter (PB_OPENROUTER_API_KEY). Publish scoring runs on
deepseek/deepseek-v4-pro; interactive suggestion generation runs on
google/gemini-3.1-flash-lite. Self-hosters may
still configure the optional direct-Anthropic adapter, but it is not part of
the Welance deployment. With OpenRouter, requests may pick a
model from the server's allowlist (PB_OPENROUTER_MODELS, exact
vendor-prefixed slugs, comma-separated); anything else is rejected with 422.
The resolved model is returned in every score for a reproducible audit trail.
Suggestion generation may use a lower-latency model selected by
PB_SUGGEST_MODEL. Single-rule suggestions are editable human choices and
default to one generation call; set PB_SUGGEST_VERIFY=true to restore a
second LLM review. The authoritative score and the multi-gap repair loop keep
their verification behavior. Suggestion responses name their verifier model
when one ran.
The service reuses its OpenRouter connection pool and applies separate bounded
output ceilings (PB_SUGGEST_MAX_TOKENS, PB_SUGGEST_ALL_MAX_TOKENS, and
PB_VERIFIER_MAX_TOKENS) because short suggestion JSON does not need the
judge's larger allowance. Successful service-funded suggestions are cached;
BYOK calls always bypass that shared cache.
The judge normally asks for all fourteen verdicts in one provider call.
PB_JUDGE_BATCH_SIZE=5 instead runs deterministic 5/5/4 rule batches with at
most PB_JUDGE_CONCURRENCY=3 calls in flight, then merges them before the same
deterministic aggregation. It is an operational latency option, not a scoring
mode: any incomplete or failed batch refuses the entire score. Keep it at its
default 0 until the live make test-llm-batching comparison has passed for
the deployed model.
Bring your own key: send X-LLM-Key: <your OpenRouter key> and the call runs
on your key — any valid OpenRouter model slug is allowed unless this deployment
sets PB_BYOK_MODELS (you pay), used per request, never stored or logged. BYOK
scoring deliberately bypasses the shared
verdict cache, so the supplied key always funds a fresh call. Use a spend-capped
key. The console exposes this as an optional field in live mode.
Sending a key to somebody else's server deserves more than that paragraph.
Every line that touches it, where it provably is not, and the honest limits are
at briefs.welance.com/security.html;
the claim is enforced by tests/test_byok_leak.py, which fails if the key ever
reaches a log, a cache write, or a response.
Other endpoints:
POST /v1/suggest {brief, rule_id, locale, model?} → tailored fixes for one gap (LLM).POST /v1/suggest/all {brief, rule_ids?, locale, model?} → one fix per failing gap; omit rule_ids to auto-detect (LLM).GET /v1/rules → the full catalogue (id, title, weight, gate, criteria, references) for the directory UI.GET /v1/models → the enabled judge models (default + available) for a model picker.GET /v1/healthz → service release, ruleset version, engine + LLM availability.GET / → the interactive console.Suggestion responses include X-PB-Generation-Ms, X-PB-Verification-Ms,
X-PB-Cached, X-PB-Cache-Ms, X-PB-Model, and the standard Server-Timing header, so callers
can distinguish model latency from network/UI latency without exposing prompts
or document contents. /v1/healthz also reports whether the optional Redis
cache/rate-limit store is currently connected.
https://briefs.welance.com/mcp is a free remote MCP server (Streamable HTTP,
stateless JSON). No model of ours runs. Your assistant's own model judges
the brief with the service judge's own prompt; the bar's code validates those
verdicts and does the arithmetic with the same engine as /v1/score.
Also as prompts (score_with_your_model — the whole workflow, gate first —
judge_brief, improve_brief, brief_template) and resources
(perfect-brief://rules, …/template, …/judge-prompt, …/verdict-schema).
The same contract is plain HTTP at /v1/byo/* (see /docs).
Advisory, never authority. An aggregated result is tagged
evaluation_source: "client", authoritative: false, with the ruleset version,
evidence errors and pattern conflicts, and a Find a team on welance/directory →
link (PB_DIRECTORY_URL). It cannot authorise publication: the
welance/directory scores every brief itself on /v1/score.
Claude (claude.ai, Desktop): Settings → Connectors → Add custom connector →
https://briefs.welance.com/mcp. Claude Code:
ChatGPT: Settings → Apps & Connectors → Advanced → enable developer mode →
Create → URL https://briefs.welance.com/mcp, no authentication
(availability depends on the plan).
Cursor (~/.cursor/mcp.json or .cursor/mcp.json):
VS Code (.vscode/mcp.json, or MCP: Add Server… → HTTP):
Local (stdio) — same tools, for any client that runs commands:
Protocol: revisions 2024-11-05 → 2025-11-25 negotiate through initialize
(an unknown one is answered with 2025-11-25); the stateless 2026-07-28
envelope (server/discover) is served too. JSON-RPC batches are refused with
400. No session, no event stream.
The older connector whose score_brief/suggest_fixes spend the service
judge lives at /mcp-hosted, off unless PB_MCP_HOSTED_ENABLED=true, and
then under the same per-address limits. A draft Official MCP Registry entry
is in registry/.
welance.com/directory consumes itThe directory is a pure consumer. It renders the verdict; it holds no scoring logic:
Score as the user types (debounced) and on submit. otto.welance.com calls the
same endpoint server-to-server when it needs to persist a verdict.
(brief, ruleset_version).
There is no database. Redis holds only an ephemeral verdict cache + rate-limit
counters, and the service degrades gracefully if Redis is down.brief_bar/ is an installable package with its
own version and CI corpus. Today it's vendored here; extracting it to
welance/brief-bar and pinning a tag is a lift-and-shift, no code change.clear-title, problem-defined, budget-floor, anonymised),
not a quiet penalty on the number.Architecture decisions with real stakes are recorded as ADRs in
docs/decisions/:
The image is a stateless HTTP service on :8000 with a /v1/healthz liveness
probe — a standard Deployment + Service + Ingress, plus a small Redis
(a cache, so a single replica or a managed instance is fine). Set PB_* via a
Secret/ConfigMap; lock PB_CORS_ORIGINS to the directory's origin. Scale the
API horizontally; the cache is shared through Redis.
The API accepts text, not uploads: brief is one bounded string. The Directory
may read supported PDF, DOCX and text-family documents locally in the browser
and include their extracted text as untrusted context. Original bytes, images
and arbitrary binaries are not sent to this service, stored by it, or published
as attachments. Multipart publication to Directus is a separate Directory flow.
The bundled console defaults to the mock judge (offline, instant). Its live
mode calls this service's /v1/score and /v1/suggest; provider credentials
stay server-side unless a caller explicitly supplies a per-request BYOK key.
Source: README.md at commit a07438d
Read the brief rules
Read the bar before judging anything. Free; no model runs. Returns the live catalogue with its version: every rule's id, title, criteria (what the judge reads), weight, gate role, policy context and how to pass it, plus the arithmetic — status scores, confidence threshold, accept threshold, bands, the gate and which policy contexts can be turned off. The number of rules is whatever the live catalogue says.
Takes no parameters.
Get a brief template
A brief template built from the live rules, with the inputs each section needs. Use it to start a brief from nothing, or to see which section a gap belongs in. Markdown, one section per rule, gate rules marked; write in any language.
Takes no parameters.
Get the judge prompt
The judge prompt and verdict JSON Schema, for YOUR model to answer. Free. This is the service judge's own prompt, word for word, so your model grades against the same bar. Pass the brief to get it embedded, or leave it empty for a template with a {{BRIEF}} placeholder. Answer the prompt with your own model (temperature 0 if you can), return only the JSON array it asks for, and send that array with the brief and the returned ruleset_version to aggregate_verdicts. welance runs no model for this.
briefGet an improvement prompt
A working order for improving a brief with your own model, gate first. Pass the verdicts you already have (the JSON array from your model) to target the failing rules in weight order; without them the prompt walks every rule. The prompt keeps the author's voice and forbids invented scores and facts. Nothing is generated here: your model does the writing.
briefrequiredverdictsdirectory_contextRun deterministic checks
Deterministic checks only — semantic coverage is INCOMPLETE. Never a score. Finds what a pattern can find for certain: emails, URLs and phone numbers (which block anonymisation), a stated budget and timeline, personal-data cues without a compliance cue, unfilled placeholders, the title line and labelled sections. It does not judge meaning: company or person names, a vague problem or an unmeasurable goal pass straight through. Use it as a quick pre-flight, then judge with get_judge_prompt and aggregate_verdicts.
briefrequireddirectory_contextScore from your verdicts
Turn your model's verdicts into the bar's score, gate and decision. Advisory. Validates the verdicts against the live ruleset (every rule exactly once, valid status and confidence, the version you judged at) and against the brief (each quote must be copied verbatim), then aggregates them with the same engine that scores on the service: same verdicts, same number. Any error means no score — fix and resend. The result is tagged evaluation_source "client" and authoritative false: your model wrote the verdicts, so it is advice, never a welance score, and it cannot authorise publication on the welance/directory (the directory scores every brief itself). Say so when you report it. Fix gate.missing first. directory_context false drops the directory-only policy rules.
briefrequiredverdictsrequiredruleset_versionrequireddirectory_contextBar status
Which ruleset version is live, and what this free surface can do. Confirms the mode (bring your own model, zero provider calls, no fallback to welance's model) and the tools available.
Takes no parameters.
100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
brief_bar/ the open ruleset + deterministic engine (the OSS core) rules/*.yaml 14 rules, weights sum to 100, ★ = gate requirement scoring.yaml the €10k floor, the 4-requirement gate (anonymised is directory-context, deactivatable), the bands score.py weighted average + gate + decision (no model here) judge.py MockJudge (keyword, offline) + LLMJudge protocol llm.py batched-judge & suggestion prompts (versioned with rules) fixtures/*.yaml labelled briefs = the regression corpus / CI immune systemapp/ the FastAPI service main.py routes, rate limit, CORS; mounts site/ at / scorer.py mock/LLM orchestration + Redis verdict cachesite/ THE public pages: landing, console, rules — served both by GitHub Pages and by the service itself (one surface)CLAUDE.md · PLAN.md bootstrap + phased mission for an agentic coding sessionGOVERNANCE.md · CONTRIBUTING.md · CODEOWNERS · LICENSE the open-bar machinery (MIT)docker-compose.yml api + redis (the only stateful dependency: ephemeral cache)cp .env.example .env # add a spend-capped PB_OPENROUTER_API_KEYmake up # docker compose up --build -d (api + redis)make health # GET /v1/healthzopen http://localhost:8000 # the console (mock judge works with no key){ "brief": "…", "locale": "it", "judge": "mock" } // judge: "mock" | "llm"{ "score": 92.0, "band": "Directory-ready", "decision": "blocked", "decision_label": "Blocked — hard requirements unmet", "gate": { "passed": false, "missing": ["anonymised"] }, "verdicts": [ { "rule_id": "anonymised", "status": "fail", "confidence": 0.8, "quote": "Stripe … [email protected]", "note": "identifying info present", "weight": 8, "severity": "high", "gate": "pass" }, … ], "review_required": false, "low_confidence": [], "ruleset_version": "1.0.0+83107baec655", "engine": "[email protected]+83107baec655", "judge": "mock", "cached": false }claude mcp add --transport http perfect-brief https://briefs.welance.com/mcp{ "mcpServers": { "perfect-brief": { "url": "https://briefs.welance.com/mcp" } } }{ "servers": { "perfect-brief": { "type": "http", "url": "https://briefs.welance.com/mcp" } } }{ "mcpServers": { "perfect-brief": { "command": "uvx", "args": ["--from", "git+https://github.com/welance/perfect-brief#subdirectory=mcp-server", "perfect-brief-mcp"] } } }const res = await fetch("https://briefs.welance.com/v1/score", { method: "POST", headers: { "content-type": "application/json", "x-api-key": KEY }, body: JSON.stringify({ brief, locale, judge: "llm" }),}).then(r => r.json());// res.decision drives publish/blocked/with-reservation; res.gate.missing lists why.// persist res together with res.ruleset_version for a reproducible audit trail.pip install -e ".[dev]"make test # fixture corpus + API tests, all on the deterministic mock judgemake lint # ruffmake typecheck # mypymake dev # uvicorn --reload on :8000