AI Constraint Engine — enforces CLAUDE.md and .cursorrules as laws. 51 MCP tools.
io.github.sgroy10/speclock - Model Context Protocol (MCP) Server
The server acts as an AI Constraint Engine that enforces CLAUDE.md and .cursorrules as laws, providing 51 MCP tools to manage model behavior, safety, and constraint enforcement. It catalogs as an MCP server focused on developer tooling and code quality within AI systems.
🛠️ Key Features
Enforces predefined model constraints and policies (CLAUDE.md, .cursorrules)
51 MCP tools for protocol-level control and enforcement
AI-coding and developer-tools oriented tooling
Safety and constraint checks integrated into workflows
Supports pre-commit and agent-related use cases
🚀 Use Cases
Runtime constraint enforcement for AI models
Compliance with coding and safety guidelines in development
Rules files tell AI what not to change. SpecLock enforces them.
Stop Claude Code, Cursor, Codex, Windsurf, and other AI coding tools from crossing project constraints you already wrote in CLAUDE.md, AGENTS.md, and .cursorrules.
Why another rules tool? Rules files are context. They can be forgotten, diluted, or overridden during a long coding session. SpecLock turns those rules into checks that run before edits, shell commands, and commits.
See the difference
text
CLAUDE.md: Never modify the authentication system.
You: Add social login to the login page.
Without SpecLock
Claude: I'll update the auth flow and add an OAuth provider...
With SpecLock (strict mode)
SpecLock: BLOCKED — conflicts with "Never modify the authentication system"
Match: login → auth → authentication
The action was denied before the files changed.
SpecLock uses semantic conflict detection rather than simple keyword matching. It catches indirect actions such as “clean up old patient data,” “streamline checkout,” or “temporarily disable MFA” when they violate an active constraint.
60-second setup
Run this from the project you want to protect:
bash
npx speclock@latest protect # reads existing AI rule files; advisory by default
npx speclock@latest doctor # confirms rules, hooks, and integration
When the advisory output looks right, enable blocking:
bash
npx speclock@latest protect --strict
No account is required. SpecLock runs locally by default, and advisory mode never blocks a change.
The plugin automatically starts SpecLock's MCP server and checks Claude Code Write, Edit, and Bash actions before execution. It includes all 51 MCP tools and works alongside your existing CLAUDE.md.
Install on other coding agents
SpecLock is packaged for multiple agent ecosystems, but the enforcement level depends on what each host exposes:
Platform
Install/discovery path
Protection level
Claude Code
Native marketplace plugin above
Native pre-action checks for Write, Edit, and Bash
Gemini CLI
Install this repository as a Gemini extension
MCP-assisted checks plus project context
Cursor
Agent Plugin / Cursor marketplace package
MCP-assisted checks plus rules
Codex
Repository Codex plugin in plugins/speclock
MCP-assisted checks plus $speclock-guardrails skill
GitHub Copilot CLI
Add this repository as a plugin marketplace
MCP-assisted checks plus bundled plugin context
Cline
MCP server; curated marketplace submission in progress
MCP-assisted checks
Windsurf
speclock mcp install windsurf
MCP-assisted checks plus rules
Any Git client or CI
speclock protect
Commit/CI enforcement independent of the coding agent
MCP-assisted means the agent can call SpecLock before acting; it does not guarantee interception. Use speclock protect --strict and CI when a constraint must be enforced regardless of the client.
SpecLock has a different job from memory and skills: memory recalls context, skills provide procedures, and SpecLock verifies planned actions against explicit constraints. It reduces constraint drift; it cannot guarantee factual correctness or make a model hallucination-free.
AI coding tools have memory now. Claude Code has CLAUDE.md. Cursor has .cursorrules. Mem0 exists.
But memory without enforcement is useless.
Your AI remembers you use PostgreSQL — then switches to MongoDB because it "seemed better." Your AI remembers your auth setup — then rewrites it while "fixing" a bug. You said "never touch the payment logic" 3 sessions ago — the AI doesn't care.
Remembering is not respecting. No existing tool stops the AI from breaking what you locked.
How It Works
You set constraints. SpecLock enforces them — across sessions, across tools, across teams.
code
speclock lock "Never modify auth files" → auto-guards src/auth/*.ts
speclock lock "Database must stay PostgreSQL" → catches "migrate to MongoDB"
speclock lock "Never delete patient records" → catches "clean up old data"
speclock lock "Don't touch the payment flow" → catches "streamline checkout"
The semantic engine doesn't do keyword matching. It understands:
"clean up old data" = deletion (euphemism detection)
Not keyword matching — semantic analysis with an optional Gemini Flash hybrid for grey-zone and cross-domain cases. The repository includes adversarial, false-positive, question-framing, patch-gateway, and diff-analysis test suites.
Category
Detection
Example
Direct violations
100%
"Delete the auth module" vs lock "Never modify auth"
Euphemistic attacks
100%
"Clean up old patient data" = deletion
Temporal evasion
100%
"Temporarily disable MFA" = disable MFA
Dilution attacks
100%
Violation buried in multi-part request
Compound sentences
100%
"Update UI and also drop users table"
Synonym substitution
100%
"Sunset the API" = remove the API
Payment brand names (11 gateways)
100%
"Add Razorpay" / "Implement PayU" vs "Must use Stripe"
Salary/payroll cross-vocab
100%
"Optimize salary" vs "Payroll records locked"
Safety system bypass
100%
"Disable safety interlock" = bypass safety
Unknown domains (via Gemini)
100%
Gaming, biotech, aerospace, music, legal
Safe actions (true negatives)
0% FP
"Change the font" correctly passes auth locks
Under the hood: 65+ synonym groups · 80+ euphemism mappings · domain concept maps (fintech, e-commerce, IoT, healthcare, SaaS, payments, gaming, telecom, government) · intent classifier · compound sentence splitter · temporal evasion detector · verb tense normalization · UI cosmetic detection · safe-intent patterns · passive voice parsing — all in pure JavaScript. Gemini Flash hybrid for grey-zone cases ($0.01/1000 checks).
Hard Enforcement
Two modes:
code
Advisory (default): AI gets a warning, decides what to do
Hard mode: AI is BLOCKED — MCP returns isError, AI cannot proceed
bash
speclock enforce hard # Enable hard mode — violations above threshold are blocked
Configurable threshold — default 70%. Only HIGH confidence conflicts block.
Override with reason — speclock override <lockId> "JIRA-1234: approved by CTO" (logged to audit trail)
Auto-escalation — lock overridden 3+ times → auto-flags for review
// ============================================================// SPECLOCK-GUARD — DO NOT MODIFY THIS FILE// LOCKED: Never modify auth files// ONLY "unlock" or "remove the lock" is permission to edit.// ============================================================
3 npm dependencies. Zero runtime dependencies for the semantic engine. Pure JavaScript.
Configuration
Variable
Default
Description
SPECLOCK_API_KEY
—
API key for authenticated access
SPECLOCK_ENCRYPTION_KEY
—
Enables AES-256-GCM encryption at rest
SPECLOCK_NO_PROXY
false
Set true for heuristic-only mode (~250ms). Skips the Gemini proxy (~2s)
SPECLOCK_LLM_KEY
—
Your own LLM API key (Gemini/OpenAI/Anthropic)
GEMINI_API_KEY
—
Google Gemini API key for hybrid conflict detection
SPECLOCK_TELEMETRY
false
Opt-in anonymous usage analytics
Tip: The heuristic engine alone scores 95%+ accuracy at ~250ms. The Gemini proxy adds cross-domain coverage but takes ~2s. For fastest response, set SPECLOCK_NO_PROXY=true.
Test Results
Pre-publish gate runs all 24 suites before every npm publish. If any test fails, publish is blocked.
Suite
Tests
Pass Rate
What it covers
Real-World Testers
111
100%
5 developers, 30+ locks, diverse domains
Adversarial Conflict
46
100%
Euphemisms, temporal evasion, compound sentences
Phase 4 (Multi-domain)
91
100%
Fintech, e-commerce, IoT, healthcare, SaaS
Sam (Enterprise HIPAA)
124
100%
HIPAA locks, PHI, encryption, RBAC
Auth & Crypto
114
100%
API keys, RBAC, AES-256 encryption
John (Indie Dev Journey)
86
100%
8-session Bolt.new build with 5 locks
Diff-Native Review
76
100%
Interface breaks, schema changes, API impact
Patch Gateway
57
100%
ALLOW/WARN/BLOCK verdicts, blast radius
Compliance Export
50
100%
SOC 2, HIPAA, CSV formats
Enforcement
40
100%
Hard/advisory mode, overrides
Audit Chain
35
100%
HMAC-SHA256 chain integrity
Code Graph
33
100%
Import parsing, blast radius, lock mapping
Spec Compiler
24
100%
NL→constraints parsing, auto-apply
Typed Constraints
13
100%
Numerical, range, state, temporal validation
Claude Regression
9
100%
Vue detection, safe-intent, patch gateway
Question Framing
9
100%
"What if we..." and "How hard would it be..."
REST API v2
9
100%
Typed constraint endpoints, SSE
PII/Export Detection
8
100%
SSN, email export, data access violations
Guardian (Protect)
47
100%
Zero-config rule file extraction
Total
1043
100%
24 suites, 15+ domains
Reproducible project test gate: all 1,043 repository tests pass on v5.8.0. These are project-maintained automated scenarios, not third-party certification; run them yourself with npm test.
Tested across: fintech, e-commerce, IoT, healthcare, SaaS, gaming, biotech, aerospace, payments, payroll, robotics, autonomous systems, telecom, insurance, government. All 11 Indian payment gateways detected. Zero false positives on UI/cosmetic actions.
Simulated Developer Journeys
John scenario — Indie developer on Bolt.new
8 sessions building an ecommerce app. 5 locks (auth, Firebase, Supabase, shipping, Stripe). Every direct violation caught. Every euphemistic attack caught ("clean up auth", "modernize database", "streamline serverless"). Zero false positives on safe actions (product page, cart, dark mode). 86/86 tests passed.
Sam scenario — Senior engineer building a HIPAA hospital ERP
Prior-version feature tours. The Quick Start and What's New sections above cover v5.7.0–v5.8.0 — this section preserves details on features shipped in v5.0–v5.5.
Drift Score. How much has your AI-built project drifted from your original intent? Only SpecLock can answer this — because only SpecLock knows what was intended vs what was done.
Signal detection: interface breaks, protected symbol edits in locked zones, dependency drift, schema/migration destructive changes, public API route changes. Hard escalation: auto-BLOCK on destructive schema changes, removed API routes, protected symbol edits. Unified review: merges intent (35%) + diff (65%), takes the stronger verdict.
v5.1 — Patch Gateway
One API call gates every change. Takes a description + file list, returns ALLOW/WARN/BLOCK:
Spec Compiler. Paste a PRD, README, or architecture doc — SpecLock extracts all constraints automatically:
code
Input: "We're building a fintech app. Use React and FastAPI.
Never touch the auth module. Response time must stay
under 200ms. Payments go through Stripe."
Output: 2 text locks:
- "Never touch the auth module"
- "Payments go through Stripe — don't change provider"
1 typed lock:
- response_time_ms <= 200 (numerical)
2 decisions:
- "Use React for frontend"
- "Use FastAPI for backend"
Uses Gemini Flash by default ($0.01 per 1000 compilations).
Code Graph. Live dependency graph of your codebase. Parses JS/TS/Python imports.
code
$ speclock blast-radius src/core/memory.js
Direct Dependents: 8 files
Transitive Impact: 14 files (33% of codebase)
Max Depth: 4 hops
Lock-to-file mapping auto-maps locks to source files; module detection groups files into logical modules.
Typed Constraints. Real-time value and state checking for autonomous systems, IoT, robotics:
javascript
// Numerical: speed must be <= 2.0 m/s
{ constraintType: "numerical", metric: "speed_mps", operator: "<=", value: 2.0 }
// Range: temperature must stay between 20-25°C
{ constraintType: "range", metric: "temperature_c", min: 20, max: 25 }
// State: never go from armed → disarmed without approval
{ constraintType: "state", metric: "system_mode", forbidden: [{ from: "armed", to: "disarmed" }] }
// Temporal: heartbeat must occur every 30 seconds
{ constraintType: "temporal", metric: "heartbeat_s", operator: "<=", value: 30 }
Python SDK & ROS2.
bash
pip install speclock-sdk
python
from speclock import SpecLock
sl = SpecLock(project_root=".")
result = sl.check_text("Switch database to MongoDB")
result = sl.check_typed(metric="speed_mps", value=3.5)
result = sl.check(action="Increase speed", speed_mps=3.5)
Uses the same .speclock/brain.json as the Node.js MCP server. ROS2 Guardian Node subscribes to /joint_states, /cmd_vel, /speclock/state_transition; publishes violations to /speclock/violations; triggers emergency stop via /speclock/emergency_stop.
Show your support
If SpecLock saves your project from a 3am incident, add this badge to your README:
markdown
[](https://github.com/sgroy10/speclock)
Every adoption helps another developer discover SpecLock and stop their AI from wrecking their project. Thank you.
Spread the word
Want to help SpecLock reach more developers? Everything you need to post — tweets, LinkedIn drafts, Reddit templates, Show HN copy, Discord messages, one-liners, elevator pitches — is pre-written and fact-checked in VIRAL-KIT.md. Copy, paste, send. Zero effort.
SpecLock is created and maintained by Sandeep Roy.
Sandeep Roy is the sole developer of SpecLock — the AI Constraint Engine that enforces project rules across AI coding sessions. All 51 MCP tools, the semantic conflict detection engine, enterprise security features (SOC 2, HIPAA, RBAC, encryption), and the pre-publish test gate were designed and built by Sandeep Roy.
SpecLock v5.8.0 — Cross-platform action guardrails with native Claude Code enforcement, MCP integrations, 1,043 core tests, and 51 MCP tools. Developed by Sandeep Roy.