# Speclock

> AI Constraint Engine — enforces CLAUDE.md, .cursorrules, AGENTS.md rules as laws. 51 MCP tools, 991 tests. Official MCP Registry. npx speclock protect

- **Type:** MCP server
- **Install:** `agentstack add mcp-sgroy10-speclock`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sgroy10](https://agentstack.voostack.com/s/sgroy10)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sgroy10](https://github.com/sgroy10)
- **Source:** https://github.com/sgroy10/speclock
- **Website:** https://sgroy10.github.io/speclock/

## Install

```sh
agentstack add mcp-sgroy10-speclock
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Your AI keeps breaking things you told it not to touch.SpecLock makes it stop.

  
  
  
  

  
  
  

  
  
  

  
  
  
  

Browse all badge variants at sgroy10.github.io/speclock/badge.html · or run speclock badge in your terminal.

  Website · npm · Saves Wall · Smithery · GitHub

Developed by Sandeep Roy · Free & Open Source (MIT License)

---

## Quick Start

```bash
npx speclock protect              # Install in your project (creates CLAUDE.md if missing)
speclock mcp install claude-code  # Wire up MCP for Claude Code (or cursor, windsurf, cline, codex)
speclock doctor                   # Verify everything is set up correctly
```

That's it. Your AI now has rules it can't ignore. Default mode is WARN (loud warnings, no blocks). Opt in to hard enforcement with `speclock protect --strict`.

## What's New in v5.7.0

- **The Saves Wall** — publish a save to a public, indexable page with `speclock wins --publish` (opt-in). Each gets a shareable URL with a rich social card, and a live "🔒 blocked by speclock · N" badge counts every published block. Browse them at [/saves](https://speclock-mcp-production.up.railway.app/saves).

## What's New in v5.6.1

- **`speclock wins`** — a shareable "Save Receipt" of everything SpecLock blocked your AI from doing. Screenshot-ready and screenshot-worthy.
- **`speclock wrapped`** — a Spotify-Wrapped-style recap of your saves, all-time and monthly (alias: `speclock recap`).
- **Dynamic "🔒 N violations blocked" README badge** — a new live badge variant that shows the real number of violations SpecLock has blocked for you. Add it with `speclock badge`.
- **Default WARN mode** — no more false-positive blocks. Loud warnings instead. Opt in to strict with `--strict` or `SPECLOCK_STRICT=1`.
- **`speclock mcp install `** — autoinstaller for Claude Code, Cursor, Windsurf, Cline, Codex. No more hand-editing JSON.
- **Greenfield support** — `speclock protect` in fresh projects auto-creates CLAUDE.md with safe defaults.
- **`speclock doctor`** — health check verifying installation, git hook, rule files, and MCP integration. Prints exact fix commands for any issues.

## What is SpecLock?

**SpecLock is an AI constraint engine that enforces your project rules across every AI coding session.** Your AI keeps breaking things you told it not to touch — SpecLock makes it stop.

## Commands Reference

```bash
speclock protect                      # Install pre-commit hook + extract locks from rule files
speclock protect --strict             # Hard enforcement mode (blocks violations)
speclock doctor                       # Health check — verifies install, hooks, rules, MCP
speclock mcp install          # Wire up MCP server (claude-code, cursor, windsurf, cline, codex)
speclock check "action description"   # Test if an action would conflict with locks
speclock add-lock "rule"              # Add a new lock
speclock list-locks                   # Show all locks
speclock enforce hard|advisory        # Change enforcement mode
speclock wins                         # Shareable "Save Receipt" of what SpecLock blocked (screenshot it!)
speclock wins --publish               # Publish your latest save to the public Saves Wall (opt-in)
speclock wrapped                      # Spotify-Wrapped-style recap of your saves (alias: recap)
```

Full command reference: `npx speclock help`

---

```
You:    "Never touch the auth system"
AI:     🔒 Locked.

         ... 5 sessions later ...

You:    "Add social login to the login page"
AI:     ⚠️  BLOCKED — violates lock "Never touch the auth system"
        Matched: auth → authentication (synonym), login → auth (concept)
        Confidence: 100%
        Should I find another approach?
```

**100/100 on Claude's independent test suite. 1043 tests across 24 suites. 0 false positives. 15.7ms per check.**

## The Problem

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.

```
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)
- **"streamline checkout"** = modify payment flow (synonym + concept mapping)
- **"temporarily disable logging"** = disable logging (temporal evasion detection)
- **"Update UI and also drop the users table"** = hidden violation (compound splitter)

And it knows what's safe:
- **"Enable audit logging"** when the lock says "Never *disable* audit logging" → **no conflict** (intent alignment)

## Quick Start by Platform

### Bolt.new / Aider / Any npm Platform
```bash
npx speclock setup --goal "Build my app" --template nextjs
```
Creates `SPECLOCK.md`, injects rules into `package.json`, generates `.speclock/context/latest.md`. The AI reads these automatically.

### Claude Code
Add to `.mcp.json`:
```json
{
  "mcpServers": {
    "speclock": {
      "command": "npx",
      "args": ["-y", "speclock", "serve", "--project", "."]
    }
  }
}
```

### Cursor / Windsurf / Cline
Same config — add to `.cursor/mcp.json` or equivalent.

### Lovable (No Install)
1. Go to **Settings → Connectors → New MCP server**
2. Enter URL: `https://speclock-mcp-production.up.railway.app/mcp`
3. Paste [project instructions](SPECLOCK-INSTRUCTIONS.md) into Knowledge

---

## Why SpecLock Over Alternatives?

| | Claude Memory | Mem0 | `.cursorrules` | **SpecLock** |
|---|:---:|:---:|:---:|:---:|
| Remembers context | Yes | Yes | Manual | **Yes** |
| **Blocks the AI from breaking things** | No | No | No | **Yes** |
| **Semantic conflict detection** | No | No | No | **100/100 score, 0% FP** |
| **Tamper-proof audit trail** | No | No | No | **HMAC-SHA256 chain** |
| **Hard enforcement (AI cannot proceed)** | No | No | No | **Yes** |
| **SOC 2 / HIPAA compliance exports** | No | No | No | **Yes** |
| **Encrypted storage (AES-256-GCM)** | No | No | No | **Yes** |
| **RBAC + API key auth** | No | No | No | **4 roles** |
| **Policy-as-Code DSL** | No | No | No | **YAML rules** |
| Works on Bolt.new, Lovable, etc. | No | No | No | **Yes** |

**Other tools remember. SpecLock enforces.**

---

## Semantic Engine

Not keyword matching — **real semantic analysis** with Gemini Flash hybrid for universal domain coverage. Scored **100/100** on Claude's independent adversarial test battery (7 suites, including false positives, question framing, patch gateway, and diff analysis).

CategoryDetectionExample
Direct violations100%"Delete the auth module" vs lock "Never modify auth"
Euphemistic attacks100%"Clean up old patient data" = deletion
Temporal evasion100%"Temporarily disable MFA" = disable MFA
Dilution attacks100%Violation buried in multi-part request
Compound sentences100%"Update UI and also drop users table"
Synonym substitution100%"Sunset the API" = remove the API
Payment brand names (11 gateways)100%"Add Razorpay" / "Implement PayU" vs "Must use Stripe"
Salary/payroll cross-vocab100%"Optimize salary" vs "Payroll records locked"
Safety system bypass100%"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:

```
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  "JIRA-1234: approved by CTO"` (logged to audit trail)
- **Auto-escalation** — lock overridden 3+ times → auto-flags for review

---

## Enterprise Security

### API Key Auth + RBAC

```bash
speclock auth create-key --role developer --name "CI Bot"
# → sk_speclock_a1b2c3... (shown once, stored as SHA-256 hash)
```

| Role | Read | Write Locks | Override | Admin |
|------|:---:|:---:|:---:|:---:|
| `viewer` | Yes | — | — | — |
| `developer` | Yes | — | With reason | — |
| `architect` | Yes | Yes | Yes | — |
| `admin` | Yes | Yes | Yes | Yes |

### AES-256-GCM Encryption

```bash
export SPECLOCK_ENCRYPTION_KEY="your-secret"
speclock encrypt   # Encrypts brain.json + events.log at rest
```

PBKDF2 key derivation (100K iterations). Authenticated encryption. **HIPAA 2026 compliant.**

### HMAC Audit Chain

Every event gets an HMAC-SHA256 hash chained to the previous event. Modify anything — the chain breaks.

```bash
$ speclock audit-verify

✓ Audit chain VALID — 247 events, 0 broken links, no tampering detected.
```

### Compliance Exports

```bash
speclock export --format soc2    # SOC 2 Type II report (JSON)
speclock export --format hipaa   # HIPAA PHI protection report
speclock export --format csv     # All events for auditor spreadsheets
```

---

## Policy-as-Code

Declarative YAML rules for organization-wide enforcement:

```yaml
# .speclock/policy.yml
rules:
  - name: "HIPAA PHI Protection"
    match:
      files: ["**/patient/**", "**/medical/**"]
      actions: [delete, modify, export]
    enforce: block
    severity: critical

  - name: "No direct DB mutations"
    match:
      files: ["**/models/**"]
      actions: [delete]
    enforce: warn
    severity: high
```

Import and export policies between projects. Share constraint templates across your organization.

---

## REST API v2

Real-time constraint checking, patch review, and autonomous systems:

```bash
# Patch Gateway (v5.1)
POST /api/v2/gateway/review        { description, files, useLLM }

# AI Patch Firewall (v5.2)
POST /api/v2/gateway/review-diff   { description, files, diff, options }
POST /api/v2/gateway/parse-diff    { diff }

# Typed constraint checking
POST /api/v2/check-typed    { metric, value, entity }
POST /api/v2/check-batch    { checks: [...] }

# SSE streaming (real-time violations)
GET  /api/v2/stream

# Spec Compiler
POST /api/v2/compiler/compile  { text, autoApply }

# Code Graph
GET  /api/v2/graph/blast-radius?file=src/core/memory.js
GET  /api/v2/graph/lock-map
POST /api/v2/graph/build
```

---

## 51 MCP Tools

Memory — goal, locks, decisions, notes, deploy facts

| Tool | What it does |
|------|-------------|
| `speclock_init` | Initialize SpecLock in project |
| `speclock_get_context` | Full context pack (the key tool) |
| `speclock_set_goal` | Set project goal |
| `speclock_add_lock` | Add constraint + auto-guard files |
| `speclock_remove_lock` | Soft-delete a lock |
| `speclock_add_decision` | Record architectural decision |
| `speclock_add_note` | Add pinned note |
| `speclock_set_deploy_facts` | Record deploy config |

Enforcement — conflict detection, hard blocking, overrides

| Tool | What it does |
|------|-------------|
| `speclock_check_conflict` | Semantic conflict check against all locks |
| `speclock_set_enforcement` | Switch advisory/hard mode |
| `speclock_override_lock` | Override with reason (audit logged) |
| `speclock_override_history` | View override audit trail |
| `speclock_semantic_audit` | Analyze git diff against locks |
| `speclock_detect_drift` | Scan for constraint violations |
| `speclock_audit` | Audit staged files pre-commit |

Tracking & Sessions — changes, events, session continuity

| Tool | What it does |
|------|-------------|
| `speclock_session_briefing` | Start session + full briefing |
| `speclock_session_summary` | End session + record summary |
| `speclock_log_change` | Log a change with files |
| `speclock_get_changes` | Recent tracked changes |
| `speclock_get_events` | Full event log (filterable) |
| `speclock_checkpoint` | Git tag for rollback |
| `speclock_repo_status` | Branch, commit, diff summary |

Intelligence — suggestions, health, templates, reports

| Tool | What it does |
|------|-------------|
| `speclock_suggest_locks` | AI-powered lock suggestions |
| `speclock_health` | Health score + multi-agent timeline |
| `speclock_apply_template` | Apply constraint template |
| `speclock_report` | Violation stats + most tested locks |

Enterprise — audit, compliance, policy, telemetry

| Tool | What it does |
|------|-------------|
| `speclock_verify_audit` | Verify HMAC chain integrity |
| `speclock_export_compliance` | SOC 2 / HIPAA / CSV reports |
| `speclock_policy_evaluate` | Evaluate policy rules |
| `speclock_policy_manage` | CRUD for policy rules |
| `speclock_telemetry` | Opt-in usage analytics |

Typed Constraints — numerical, range, state, temporal (v5.0)

| Tool | What it does |
|------|-------------|
| `speclock_add_typed_lock` | Add typed constraint (numerical/range/state/temporal) |
| `speclock_check_typed` | Check proposed values against typed constraints |
| `speclock_list_typed_locks` | List all typed constraints |
| `speclock_update_threshold` | Update typed lock thresholds |

Spec Compiler & Code Graph — NL→constraints, dependency analysis (v5.0)

| Tool | What it does |
|------|-------------|
| `speclock_compile_spec` | Compile natural language into structured constraints |
| `speclock_build_graph` | Build/refresh code dependency graph |
| `speclock_blast_radius` | Calculate blast radius of file changes |
| `speclock_map_locks` | Map locks to actual code files |

Patch Gateway & AI Patch Firewall — change review, diff analysis (v5.1/v5.2)

| Tool | What it does |
|------|-------------|
| `speclock_review_patch` | ALLOW/WARN/BLOCK verdict for proposed changes |
| `speclock_review_patch_diff` | Diff-native review with signal scoring + unified verdict |
| `speclock_parse_diff` | Parse unified diff into structured changes (debug/inspect) |

Universal Rules Sync & Incident Replay — cross-tool sync, session replay (v5.3)

| Tool | What it does |
|------|-------------|
| `speclock_sync_rules` | Sync constraints to Cursor, Claude, Copilot, Windsurf, Gemini, Aider, AGENTS.md |
| `speclock_list_sync_formats` | List all available sync formats |
| `speclock_replay` | Replay a session's activity — what AI tried and what was caught |
| `speclock_list_sessions` | List available sessions for replay |
| `speclock_drift_score` | 0-100 project integrity metric — how much AI deviated from intent |
| `speclock_coverage` | Lock Coverage Audit — find unprotected code areas |
| `speclock_strengthen` | Grade locks and suggest stronger versions |

---

## CLI

```bash
# Setup
speclock setup --goal "Build my app" --template nextjs

# Constraints
speclock lock "Never modify auth files" --tags auth,security
speclock lock remove 
speclock check "Add social login"              # Test before doing

# Enforcement
speclock enforce hard                          # Block violations
speclock override  "JIRA-1234"         # Override with reason

# Audit & Compliance
speclock audit-verify                          # Verify HMAC chain
speclock

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sgroy10](https://github.com/sgroy10)
- **Source:** [sgroy10/speclock](https://github.com/sgroy10/speclock)
- **License:** MIT
- **Homepage:** https://sgroy10.github.io/speclock/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sgroy10-speclock
- Seller: https://agentstack.voostack.com/s/sgroy10
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.