intent-gate MCP server

intent-gate

English | 简体中文

Stop AI coding agents from guessing.

Complex business requirements. A thin or sloppy PRD. No legacy code to reference. That is exactly where coding agents start inventing: "happy path only, no failure flow", "idempotency with no server-side design" — gaps get silently filled with plausible-looking guesses, and you find out far too late.

intent-gate moves intent alignment before coding, into the requirement-analysis stage: a PRD goes through an intent-confidence gate → gaps are resolved through a three-level funnel → the output is technically annotated Mermaid contracts (state machines / sequence diagrams / decision tables) → a mechanical lint gate must reach zero CRITICAL → only then is coding allowed to begin.

It runs as an MCP server (stdio subprocess) — plug-and-play with Claude Code and other MCP clients. No daemon, no credentials, zero config — full workflow out of the box.

Where it sits in a vibe-coding workflow

intent-gate owns exactly one stage of the pipeline, the requirement-analysis stage:

PRD ──▶ [ intent-gate: confidence gate → intent alignment → Mermaid contracts ]
          ──▶ summary.md (every edge technically annotated, lint CRITICAL = 0)
          ──▶ coding agent (Claude Code / Cursor / any agent) ──▶ tests ──▶ ship

The leverage is asymmetric: if the contracts land well, the coding stage is a free win — every edge, step and rule already has a home, so any competent agent can implement the spec. That is why intent-gate deliberately does NOT touch coding, review or deployment: downstream agents are interchangeable; the input contract is not.

Dual-layer intent alignment

The diagram is the instrument, not a deliverable. Layer 1 (reading): sweep the PRD text for explicit ambiguities. Layer 2 (drawing): hard-draw draft diagrams in the FIRST turn — every node/edge that can't be drawn yet becomes a TBDn placeholder, never a guess (every edge is a forced decision). Placeholders route by kind: technical gaps go to code evidence, business gaps go to a structured human question — and may only be cleared by code evidence or a human ruling. A placeholder left in a delivered diagram is a lint CRITICAL (L13).

A real run: the smart-locker drop-off page

What one real requirement looks like after a full intent-gate pass.

The requirement, in one sentence:

"A smart-locker drop-off page — show the shipment details, allow changing the locker size, scan and drop the parcel. Must be duplicate-proof, expiry-proof, and masked."

That's it. Exactly where a coding agent starts guessing.

What happened along the way:

1. Reading layer: the text sweep flagged the explicit gaps (expiry? slot-size rules?) straight from the PRD.
2. Drawing layer: the analyzer hard-drew the state machine in the first turn — and stalled at "submit": what about failure? Should duplicate protection live on the server or the frontend? Each un-drawable edge became a TBDn placeholder instead of a guess.
3. 🔴 Red-light questions were asked one at a time (≥3 mutually exclusive options): "How do you guard against double-submit on rapid clicks / re-scan?"
4. You ruled: "Server-side Redisson lock, wait 10s / lease 300s" → your words were logged verbatim → injected into the state-machine edge and decision-table BR-01.
5. A mechanical lint gate ran before delivery: CRITICAL = 0 or it does not ship — and any leftover placeholder would itself be a CRITICAL.

The output: a technically annotated Mermaid contract (full state machine):

stateDiagram-v2
    direction LR
    [*] --> DROP_CONFIRM: 进入寄件确认页 (DB_QUERY_SHIPMENT, LOCKER_ROUTING_QUERY)
    DROP_CONFIRM --> SLOT_OPTIONS_LOADING: 请求可用柜格 (IOT_GET_FREE_SLOTS)
    SLOT_OPTIONS_LOADING --> DROP_CONFIRM: 获取成功 (RETURN_SLOT_LIST)
    SLOT_OPTIONS_LOADING --> DROP_CONFIRM: 获取失败 (RETURN_ERROR, SIZE_EDIT_DISABLED)
    DROP_CONFIRM --> SLOT_ROUTING: 修改柜型或站点 (DB_INSERT_SHIPMENT_SLOT, DB_UPDATE_SHIPMENT)
    SLOT_ROUTING --> DROP_CONFIRM: 路由成功 (DB_UPDATE_SHIPMENT_SLOT, RETURN_NEW_FEE)
    SLOT_ROUTING --> DROP_CONFIRM: 路由失败 (RETURN_ERROR, ROLLBACK_OR_KEEP_ORIGIN)
    DROP_CONFIRM --> EXPIRED: 扫码时效超时 (RETURN_ERROR_CODE, GUIDE_RESCAN)
    EXPIRED --> [*]: 引导回首页 (FRONTEND_NAVIGATE)
    DROP_CONFIRM --> SUBMITTING: 点击确认投递 (REDIS_LOCK_SUBMIT, IOT_UNLOCK_COMMAND)
    SUBMITTING --> STEP_QUERY: 提交成功 (DB_UPDATE_SHIPMENT, QUERY_CURRENT_STEP)
    SUBMITTING --> DROP_CONFIRM: 提交失败 (RELEASE_LOCK, RETURN_ERROR)
    SUBMITTING --> TERMINATE: 开柜指令失败 (DB_UPDATE_DROP_STATUS_TERMINATE)
    STEP_QUERY --> LOADING: DropStep=awaitingDrop (RETURN_NEXT_STEP)
    STEP_QUERY --> IDENTITY_CHECK: DropStep=identityCheck (RETURN_NEXT_STEP)
    STEP_QUERY --> PAY_CHANNEL: DropStep=payChannel (RETURN_NEXT_STEP)
    STEP_QUERY --> QUERY_PROGRESS: DropStep=queryProgress (RETURN_NEXT_STEP)
    STEP_QUERY --> DROP_CONFIRM: DropStep=dropConfirm (STAY_ON_PAGE)
    LOADING --> SUCCESS: 跳转下一步 (FRONTEND_NAVIGATE)
    IDENTITY_CHECK --> SUCCESS: 跳转下一步 (FRONTEND_NAVIGATE)
    PAY_CHANNEL --> SUCCESS: 跳转下一步 (FRONTEND_NAVIGATE)
    QUERY_PROGRESS --> SUCCESS: 跳转下一步 (FRONTEND_NAVIGATE)
    SUCCESS --> [*]: 投递流程结束 (END)
    TERMINATE --> [*]: 运单终止 (END)

Every edge carries a mandatory technical-action annotation — the edge DROP_CONFIRM --> SUBMITTING reads (REDIS_LOCK_SUBMIT, IOT_UNLOCK_COMMAND). What the coding agent receives is a spec, not an illustration.

Decision table (rule logic forced into a matrix — no "happy path only" survival):

Rule	Condition	Action	Failure branch
BR-01	Submit: lock LOCK:dropoff:submit:{shipmentId} conflict	Redisson lock serializes, concurrent submits rejected	Lock conflict → error code DUPLICATE_SUBMIT
BR-07	Scan deadline scanExpireTime	5-minute double check: page countdown + server-side fallback on submit	Expired → SCAN_EXPIRED, guide re-scan

The full contract: 10 business rules (BR-01..BR-10) + 3 sequence diagrams + an intent-injection mapping table (15 Q&A rounds, every answer on record).

The mechanical lint gate (pre-delivery self-check report):

summary_lint: CRITICAL 0 / 2 findings total (all MINOR, human-review class)

• [MINOR][L3] state STEP_QUERY has 5 outgoing edges — confirm triggers are distinguishable
• [MINOR][L3] state SUBMITTING has 3 outgoing edges — confirm triggers are distinguishable

With CRITICAL > 0 the contract refuses to ship and coding refuses to start — this is checked by code, not self-reported by the model.

Same requirement without intent-gate (observed in our control run): the agent would front-end-disable the submit button instead of designing a server-side distributed lock, hardcode a success page instead of routing by queryCurrentStep, and never model the EXPIRED state at all. The guessing space is structurally compressed, not politely discouraged.

Measured against a peer plugin

Same PRD (a deliberately vague withdrawal-confirmation page), same project, same model, same human answering: intent-gate vs a peer intent-alignment plugin, plus a two-round independent red-blue review of the intent-gate output.

• 3.5× the questions (35 vs 10) — 31% of them surfaced only through self-review and the adversarial rounds, including 6 failure edges that no amount of PRD reading reveals
• The peer landed a real hit too: a terminology-vs-ruling conflict that intent-gate missed across 24 questions — the two detection surfaces complement each other; neither replaces the other
• The sobering part: 24 questions resolved, mechanical lint green, self-declared "no open issues" — and the red-blue review still found 6 CRITICAL defects (one would have let any user void someone else's order). Self-attestation is not evidence; independent review is not optional
• Cost: ≈11% extra input tokens for the MCP machinery

Setup, isolation protocol, token metering and round-by-round findings (Chinese): summary · full report

Where to put your PRD

intent-gate accepts UTF-8 text files or .docx (the dominant format for business requirements). Three ways to hand one over:

Way	Example	Notes
Absolute path	analyze D:\docs\locker-dropoff.docx	Most reliable; readable from anywhere
Relative path	analyze docs/locker-dropoff.md	Resolved against the project root (HG_WORKSPACE_ROOT, defaults to the startup directory)
Conversation attachment	Drag the file into the chat; have the agent persist it first	Attachments are conversation content to the host, not a path — the agent must write them to disk before handing over a path

Supported formats:

• ✅ UTF-8 text: .md / .txt / .csv / .json and similar
• ✅ .docx: native support — mammoth is a core dependency (installed automatically; tables become Markdown tables); if markitdown already exists in your environment (e.g. for another document MCP), it is reused for enhanced extraction
• ❌ Legacy .doc / .pdf / .xlsx and other binaries: convert first — Word「Save As → .docx or Plain Text (.txt)」, PDF export/save-as text

Errors carry the next step: missing file, binary format, and encoding failures each return a distinct message telling you what to do.

Using it: what to say

Once installed, you drive it with plain language. This table is the whole manual:

You say	Who picks it up	What happens
"分析这个需求 / analyze this PRD"（贴文档或指文件）	🔴 Red team（requirement-alignment）	Reads the playbook first, runs the Step 0 confidence check, then asks you structured questions (≥3 options + "other"), one gap at a time
"画个状态机 / 生成 DDL"	🔴 Red team	Same entry — pattern routing decides which diagrams your requirement actually needs
"继续"（中断后/新会话）	🔴 Red team	Resumes from the on-disk ledger (.harness/requests/{feature}/_review/) — no session memory needed
回答它的提问："1"，或 "4 余额不足一律拒绝"	the funnel	Answer logged verbatim → injected into the diagrams → settled with a precise landing point
"红蓝对抗 / blue-team review" —— 另开新会话说	🔵 Blue team（red-blue-review）	Independent adversarial review of the delivered summary: R1–R9 checks → findings with verdict PASS / FAIL-可整改 / FAIL-重做
"按 findings 整改"（回到红军的会话里说）	🔴 Red team revision discipline	Each finding settled into revision-log.md with a real landing point, lint re-runs to zero CRITICAL; anything conflicting with your earlier rulings comes back to you for a decision
什么都不说，直接让它写代码	compact routing Hook + contract-coding	The agent reads the landed summary.md contract before coding; blocked or lint-CRITICAL contracts refuse to be coded against

Two rules worth remembering:

• Answer its questions seriously — every answer becomes part of the contract your coding agent will execute against.
• The blue team needs a fresh session — reviewing in the same session degrades adversarial review into self-check. Deliver with the red team, then open a new conversation and say "红蓝对抗".

Core mechanisms

Intent-confidence gate (Step 0): assess the light status before analyzing any requirement. Until 🔴 core-logic gaps are eliminated, the report status must be blocked, the first task in any breakdown is forced to be [BLOCKER], and downstream coding is forbidden from starting.

Three-level alignment funnel (Step 0.5) — cost decreases level by level, fully non-blocking throughout:

① Code-grounded verification: technical gaps are checked against the code first;
  a unique ground truth is recorded directly, zero interpersonal cost
② AI-disclosed inference: registered with an explicit evidence chain, batch-confirmed
  by a human at session end (pure inference is forbidden on money-critical main flows)
③ Human ruling: structured-option questions (≥3 mutually exclusive options + "other"),
  one question at a time

Mechanical enforcement (enforced by MCP tools, not by prompt self-discipline):

• Once a gap is registered it is physically persisted to pending-questions.md; until every box is ticked you don't get intent_aligned_ready;
• resolve_question mechanically rejects an empty landing point — every injected intent must be precise down to a state-machine edge, a sequence-diagram step, or a decision-table rule number; if no landing point is found, closing the question is forbidden and it must be asked again;
• Landing-point anchors may not be handwritten — the draft_mapping script locates real section/rule/step numbers;
• Pre-delivery lint_summary mechanical self-check (L0–L8: unparseable state machine (blind-guard) / missing terminal state / dead states / misplaced anchors / BR references / table read-write matrix…), CRITICALs must reach zero before delivery.

Why confidence is read off artifacts

The obvious challenge: "Claude Code can already generate Mermaid diagrams — even generate code — why do I need your MCP?"

Answer: a model drawing a diagram is not intent alignment. Intent confidence is not the model's self-assessment — it is the closure state of artifacts.

Asking a model to rate "how sure are you" is a dead channel: verbal confidence barely correlates with actual correctness (it's post-hoc rationalization, not a reading); token-level logprobs can't reach semantic-layer uncertainty ("should there be an intermediate state after a refund?") and the API doesn't expose them anyway. So this system never asks the model for a score — it makes the model produce, and reads the confidence off the artifacts.

Drawing diagrams (state machines / sequence diagrams / decision tables) is a measuring instrument, not a means of expression: what natural language can fudge, formalization cannot — "after the refund is processed, it's done" is one sentence, but in a state machine you must answer whether REFUNDING has an outgoing edge, where it points, and on what trigger. Every edge is a forced discrete decision; vague intent is invisible in prose but a hole on an edge.

The difference between "Claude Code drawing it" and "the intent-gate host drawing it": after Claude Code draws, nobody verifies — intent gaps stay on the diagram as-is; after intent-gate draws, the output must pass lint, every gap goes through alignment, and a human rules on each one — every cell of the artifact is closed.

Gaps come in four kinds, each with its own detector — "can't draw it" is only layer one:

Layer	Mechanism	What it catches
① Forced formalization	Draw the diagram; mark wherever you can't	Perceived gaps — the model knows it doesn't know
② Taxonomy sweep	An eleven-category ambiguity checklist (exception paths / rollback / condition combinations / field semantics / idempotency & privilege / terminology…)	Semi-silent gaps — the model won't stall on its own, but sweeping element-by-element with the checklist exposes them
③ Mechanical lint	L1 no successful terminal state / L2 dead states / L6 table has no writes…	Fully silent gaps — places the model filled in without any awareness; enforced by code, zero reliance on self-discipline
④ Blue-team independent review	Independent session + information diet (optional skill)	Systematic blind spots of the author's attention — layers ①–③ are the same pair of eyes; this one swaps in a fresh pair

So a 🟢 green light doesn't mean "the model feels confident" — it means "every edge of the state machine is grounded, all nine minefields swept, lint CRITICALs at zero, and a human has ruled on every gap." Confidence is a property of the graph, not of the model. Drawing is the instrument, lint is the calibrator, human rulings are the reference source.

Optional add-ons

• Red-blue adversarial review (red-blue-review skill): after a complex requirement's summary is delivered, optionally open an independent session — the blue team reads only the artifacts, not the red team's reasoning (information diet), runs the R1–R9 checks, and produces findings that drive a gated rectification loop. approved comes via exactly two paths — a blue-team PASS or a direct human ruling; the red team never self-grants. Circuit breaker: at most 2 rounds, still FAIL → ESCALATE to a human.
• DingTalk group consensus channel (sister project intent-gate-service, a standalone MCP service): business gaps belong to business people, technical gaps to technical people — funnel level ③ can post to a DingTalk group @ the right role; replies land in the inbox via callback. The real value of the group channel is the paper trail: answers carry a staffId and the original wording and are publicly visible — no objection in the group ≈ consensus. The main plugin defaults to the single channel, zero config.
• Contract-driven coding (contract-coding skill): an addendum layer for the coding phase — when a requirement's contract exists (.harness/requests/{feature}/summary.md), code is generated FROM the mermaid contract (every edge/rule maps to an implementation anchor), and drift stops the line: the contract gets amended first, then the code follows. It layers on top of your own coding skills / superpowers and never replaces them — your project keeps full ownership of HOW to write code; this skill only owns contract fidelity.

Environment requirements

Item	Requirement	Notes
Python	≥ 3.11	python.org; pipx/uv manage an isolated environment
Package manager	pipx or uv	Install pipx / Install uv
OS	Windows / macOS / Linux	On Windows, the plugin's SessionStart injection needs Git Bash (skipped silently when missing; everything else keeps working)
MCP client	Any MCP-capable client	Claude Code / Cursor / VS Code / DeepSeek Harness / Kimi Code etc.; full plugin support (skills/hooks) is Claude Code + DeepSeek Harness (install --target dsh) + Kimi Code (install --target kimi-code)

Dependencies (installed automatically — nothing manual):

Package	Purpose
mcp>=1.10,<2.0	MCP protocol (FastMCP 1.x)
pydantic>=2.6 / pydantic-settings>=2.2	Configuration & validation
mammoth>=1.11	.docx parsing engine (only dependency is cobble, pure Python, no onnxruntime)

Optional enhancement: if markitdown is already in your environment (e.g. installed for another document MCP), it is reused automatically for finer table/merged-cell extraction; otherwise mammoth handles it.

Quick start (Claude Code — two steps)

# 1) Install the MCP server — the enforcement half (tools, ledger, lint gates)
#    .docx is natively supported: mammoth is a core dependency, installed
#    automatically with the package — no extra required
pipx install intent-gate-mcp
# or: uv tool install intent-gate-mcp

# 2) Install the plugin — skills + hooks, auto-registers the MCP server
claude plugin marketplace add baixinghao/intent-gate
claude plugin install intent-gate@baixinghao-plugins

Restart your session. Done — the Hook injects only a compact router and the MCP tools are live; full Skills and the playbook load on demand.

⚠️ Step 1 is not optional. The plugin's skills are discipline; the MCP server is enforcement. A plugin-only install (no intent-gate command on PATH) leaves you with good advice and zero mechanical gates — no question ledger, no lint, no delivery blocking. The SessionStart hook self-checks at every session start: if the server is missing, your agent will tell you to run step 1.

Environment variables

Variable	Default	Description
HG_WORKSPACE_ROOT	. (startup directory)	Project root (where .harness lives); relative PRD paths resolve against it
HG_LOG_LEVEL	INFO	Log level (DEBUG / INFO / WARNING / ERROR)
HG_CHANNEL	single	Intent-alignment channel; only single (dialog fallback) is supported — the DingTalk group channel lives in the sister project intent-gate-service

Every variable has a default — zero config to use; copy .env.example to .env only when you want to adjust.