Intent Engineering MCP server

intent-engineering

intent-engineering is an MCP server that exposes three tools — auditintentspec, generateintentspecscaffold, and assessretrofit_level — letting any MCP-aware client (Claude Desktop, Cursor, Anti-Gravity) review, scaffold, and triage agent intent specs against a 9-section unified template synthesized from production-agent research.

Most agent failures aren't reasoning failures — they're intent failures. The spec is vague, the stop rules are missing, the outcome is an activity disguised as a state. This server makes that gap auditable from inside the harness the agent already runs in. The full reasoning, the rejected alternatives, and what would break in v0 live in docs/EXPLANATION.md.

The trust surface, up front

• It audits itself, and it has now published a wrong number and a wrong correction of that number. Graded whole on 2026-08-29, the canonical skill scores 23/25 with zero anti-patterns. This page claimed 14/25 for one day, a retraction measured on the first 10,000 characters of a 32,356-character file. The original figure was right; the retraction was the error, and the same blind spot produced both. The full measurement table is in Dogfood result.
• Read-only by design. No tool writes files. The retrofit tool recommends; it does not apply.
• File reads are guarded. An early version would read any path you handed it, which made /etc/passwd a real disclosure bug. Every disk read now routes through one guard: extension allowlist, symlink resolution, root confinement, and a size cap.
• The build refuses common failure modes. SDK pinned to the stable v1.x line, a prepublishOnly guard that fails the build on any console.log in src/, and a changelog rule: no scope change without written approval before code.
• Limitations are named, not hidden. Stdio only, opinionated heading parser with its alias table documented, and the honest boundary that the mapper recognizes equivalent intent but does not invent it.

Why this exists

Problem

Engineering teams treat AI agents like reliable coworkers, but agents fail silently when given underspecified intent. The cost is shipped features that solve the wrong problem — and the failure mode is invisible until production. PMs feel this pain twice: once writing the spec, and again when an agent confidently delivers something off-target. There's no shared protocol for "audit this spec before an agent runs on it."

Solution

A Model Context Protocol server that exposes three tools any MCP-aware client (Claude Desktop, Cursor, etc.) can call: auditintentspec audits a spec against a 25-item rubric, generateintentspecscaffold scaffolds new specs by kind, assessretrofit_level retrofits older docs. Published to npm as @swins/intent-engineering-mcp and to the official MCP registry as com.seanwinslow/intent-engineering via DNS-verified namespace.

Tradeoffs and Decisions

• TypeScript over Python: the MCP TS SDK has the deepest client coverage (Claude Desktop, Cursor) — at the cost of locking out the Python-native data science crowd.
• stdio transport over HTTP: zero-infra v0, but couples the server to a process-bound client. v1 will add SSE for cloud agents.
• DNS-verified namespace (com.seanwinslow/) over GitHub-handle namespace**: locks the brand surface to a domain I control; required a separate Ed25519 keypair + apex TXT record, which is more upfront friction than mcp-publisher login github.

What I Learned

The MCP protocol is essentially a contract for "I am a tool an LLM can call without me writing a wrapper." Once that landed, the server became a thin protocol adapter over an existing skill — and the OPTIONAL-fields pattern I'd developed on a separate knowledge-graph project translated directly.

Shortened. The full README is on GitHub.