Detailed Analysis
Constraint-mcp v2, developed by Christopher Anandaraj, extends a previously released Model Context Protocol (MCP) server that enforces software architectural rules on Claude Code at the tool level rather than the prompt level. The original version used abstract syntax tree (AST) analysis to intercept file-write operations — Claude must call `check_write()` before writing any file — and block writes that violate structural rules such as import restrictions between modules. Version 2 addresses the core limitation of that approach: AST analysis can only detect what code explicitly imports, not what it semantically does. An AI agent could write raw SQL inside an API handler using only local variables, passing every structural check while still violating the intended architecture. The new release introduces a semantic enforcement layer with three rule types: Domain Coherence (ensuring a file's content is relevant to its module's declared purpose), Semantic Coupling Bans (blocking files from being semantically close to domains they should not touch), and Semantic Drift Detection (embedding a baseline on first write and flagging subsequent modifications that stray too far, preventing gradual scope creep).
The technical implementation relies on fastembed with the BAAI/bge-small-en-v1.5 embedding model, a 384-dimension, approximately 22-megabyte model that runs entirely on CPU with roughly 20-millisecond inference time per check. Critically, it requires no external API key and makes no network calls, keeping enforcement entirely local. Violations are non-blocking by default, surfacing as warnings in the agent's context so developers can observe behavior and calibrate thresholds before enabling strict mode via the `CONSTRAINT_MCP_SEMANTIC_STRICT=true` environment variable. The system is backward compatible, meaning repositories without a Semantic Constraints section in their specification file behave identically to v1 behavior.
The significance of this project lies in a fundamental tension that has emerged as AI coding agents become more capable: the more autonomously an agent operates, the more it can produce code that is locally correct but architecturally incoherent. Prompt-level instructions — telling Claude "do not write database logic in the API layer" — are advisory and can be overridden, forgotten across long context windows, or circumvented by an agent that finds a technically compliant path to a problematic outcome. Constraint-mcp relocates enforcement to the tool call itself, making the architectural rule a hard constraint on the agent's action surface rather than a soft instruction in its context. The semantic layer extends this from structural correctness to intentional correctness, which is a meaningful escalation in the kind of guarantees a developer can make about agentic output.
This development connects to a broader trend in AI tooling around what might be called "agentic governance" — the set of mechanisms by which human-defined constraints remain effective even as AI agents are granted greater autonomy over consequential tasks. As Claude Code and similar agentic coding tools see wider deployment in professional software development contexts, the gap between what an agent is instructed to do and what it can be verified to have done becomes a genuine engineering concern. Projects like constraint-mcp represent a practitioner-driven response to that concern, emerging from direct experience with agentic coding workflows rather than from AI labs themselves. The choice to use lightweight, offline-capable embeddings rather than a hosted model reflects a design philosophy oriented toward production viability — latency, cost, and data-privacy constraints all favor local inference at the file-write boundary.
The threshold-tuning problem the author raises is a real and underappreciated challenge. Semantic similarity scores are not universal constants; a threshold that correctly flags SQL logic in an authentication module might also incorrectly flag legitimate references to session storage or token validation depending on how the embedding model spaces those concepts. The progressive disclosure model — warnings first, strict mode opt-in — is an appropriate response to this uncertainty, but it also means the system's enforcement strength is directly proportional to the effort a team invests in calibrating it to their specific codebase's domain vocabulary. Whether the community develops shared threshold conventions for common architectural patterns, or whether the tool remains highly bespoke to each project, will likely determine how broadly it gets adopted beyond early enthusiasts in the Claude Code ecosystem.
Read original article →