Jev CodeGuard
Supports OpenAI Codex agents with command safety evaluation, diff verification, and security auditing through the MCP server.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Jev CodeGuard (jev-codeguard) — Command Firewall, AST Security Auditor & Diff Verifier for AI Coding Agents
Stop AI coding agents from running destructive shell commands, shipping security bugs, or wasting thousands of tokens grading their own code.
Jev CodeGuard (jev-codeguard) is an open-source Model Context Protocol (MCP) server, PreToolUse CLI hook firewall, and real-time local monitoring dashboard built specifically for Claude Code, OpenAI Codex, Cursor, Windsurf, and Google Antigravity (Gemini).
How does
jev-codeguarddiffer from generic Jev MCP wrappers (likejev-mcp)?
While minimal wrappers expose raw/v1/jevjudgment calls,jev-codeguardis a full coding-agent safety, static-analysis & verification runtime: it combines local AST & Rust linters (ts-morph,oxlint,ruff,codegraph), anti-gaming prose command detection, 9 OWASP/AppSec skill rubrics with lazySKILL.mdescalation, zero-token localgit diffverification, a deterministicPreToolUsehook firewall (jev-gate), and a live local SSE Radar Portal (http://127.0.0.1:4399) with persistent per-repo Project Brain memory.
It pairs your frontier System-2 coding agent with TypeSafe AI's Jev (~150ms calibrated probability engine at $0.042 / 1M input tokens, free output) and local open-source static/AST engines (ts-morph, oxlint, ruff, codegraph) to deliver five concrete superpowers:
🛡️ Pre-Execution Command Firewall (
jev_guard_action&jev-gate): Evaluates literal shell commands for blast radius, destructiveness, and secret exfiltration before execution — automatically rejecting English prose summaries so agents cannot disguise risky commands.🔍 Zero-Token Local Git Diff Verifier (
jev_verify_diff): Reads staged, unstaged, and untracked changes directly from disk (zero agent tokens spent echoing diffs), enriches them with AST symbol skeletons, callers, and linter diagnostics, and flags regressions before commit.🔒 Skill-Backed Security & Quality Auditor (
jev_audit_code): Checks 9 OWASP/AppSec vectors + architecture + 60fps GSAP animation rules in ~150ms, lazily injecting remediation excerpts from your localSKILL.mdlibrary only when a risk crossesP >= 0.55.✂️ Context Pruner & Workflow Router (
jev_prune_context&jev_route_task): Scores up to 100 candidate files/skills in a single ~150ms parallel pass so noisy files never pollute your agent's context window.📡 Live Bilingual (
EN | VI) Radar Portal (http://127.0.0.1:4399): Zero-dependency local SSE dashboard showing every agent check, probability bar, latency, cost, and 1-click Project Brain override rules.
mcp-jev là lớp Tường lửa bảo vệ (Guardrail Firewall), Kiểm toán bảo mật AST và Trạm giám sát trực tiếp dành cho các AI Coding Agent (Claude Code, OpenAI Codex, Cursor, Windsurf, Antigravity / Gemini):
Chặn lệnh nguy hiểm trước khi chạy (
jev_guard_action/jev-gate): Chấm xác suất an toàn trong ~150ms, tự động phát hiện và từ chối nếu Agent cố tình mô tả văn xuôi thay vì đưa câu lệnh thật.Chấm điểm
git difftốn 0 token của Agent (jev_verify_diff): Tự đọc code thay đổi dưới local (kể cả file mới chưagit add), kết hợp phân tích AST (ts-morph, Pythonast), linter (oxlint,ruff) và đồ thị phụ thuộc (codegraph) để bắt lỗi bảo mật/regression trước khi báo cáo xong việc.Audit bảo mật không làm phình ngữ cảnh (
jev_audit_code): Chỉ trích xuất quy tắc sửa lỗi từ bộSKILL.mdcục bộ khi phát hiện rủi ro vượt ngưỡng (P >= 0.55).Dashboard trực tiếp
http://127.0.0.1:4399(Song ngữEN | VI): Theo dõi thời gian thực mọi câu hỏi & phán quyết của các Agent ở nhiều cửa sổ terminal và dạy lại quy tắc riêng cho từng dự án (Project Brain).
Why mcp-jev?
Bottleneck in Standard Agent Workflows | How |
Uncalibrated Self-Grading: Frontier LLMs rationalize risky commands or incomplete diffs when grading their own work. | External RLCD Probabilities: Returns mathematically calibrated probabilities ( |
Prose Gaming on Command Guards: Agents often describe "Read-only safe git check" instead of passing the literal command they intend to run. | Literal Command-Shape Gate ( |
Autopilot Guardrail Bypass: After a guard returns | Opt-In Autopilot + 15-Min Escalation Lock: |
Blind Diff Reviews on Large Repos: Truncated diffs miss surrounding functions, imported types, callers, and syntax errors. | Deep Project Brain + Hybrid AST Engine: Locally enriches evaluations with |
Context Window Bloat: Loading security & framework guidelines ( | Lazy Skill Escalation: |
Zero Multi-Agent Visibility: Hard to see what Codex, Claude, and Gemini are deciding across terminals. | Live Radar Portal ( |
Related MCP server: AegisMCP
Architecture
flowchart TB
subgraph Agents["System-2 Coding Agents"]
CC["Claude Code"]
CX["OpenAI Codex"]
AG["Antigravity / Gemini"]
CU["Cursor / Windsurf"]
end
subgraph MCPJev["mcp-jev (Local Node.js Server & CLI)"]
direction TB
Hook["Mode B: jev-gate PreToolUse Firewall\n(Exit 0 ALLOW | Ask | Exit 2 BLOCK)"]
Tools["Mode A: 9 MCP Tools\n(guard_action, verify_diff, audit_code,\nautopilot_decide, prune_context, route_task, ...)"]
Enricher["Deep Context & Hybrid Open-Source Engine\n• ts-morph + Python AST Skeletons\n• Oxlint (Rust JS/TS) + Ruff (Rust Python/Bandit)\n• CodeGraph Affected Tests & Callers\n• Workspace Boundary & Secret Redaction"]
Brain["Persistent Project Brain\n~/.mcp-jev/projects/<workspace>.json"]
Policy["Frozen Calibrated Policy Engine (JEV_POLICY)\n• Prose Command Detector\n• 15-min Cross-Process Guard Escalation Lock\n• Lazy Local SKILL.md Escalation"]
Ledger["Atomic Rotated Event Ledger\n~/.mcp-jev/events.jsonl (5 MiB cap)"]
Radar["Live Radar Portal (SSE)\nhttp://localhost:4399"]
end
JevAPI["TypeSafe AI Jev API\nPOST /v1/jev (~150ms RLCD)"]
Agents -->|MCP stdio| Tools
CC -->|PreToolUse Hook| Hook
Tools --> Enricher
Hook --> Enricher
Enricher <--> Brain
Enricher -->|SHA-256 Cached| JevAPI
JevAPI --> Policy
Policy --> Ledger
Ledger <-->|Real-Time SSE + Human Feedback| Radar
Radar -->|Teach Override Rules| BrainQuickstart
1. Prerequisites
Node.js
>= 20.0.0A TypeSafe AI Jev API Key (
jev_live_...) from typesafe.ai(Optional Open-Source Analyzers):
oxlintandts-morphare bundled out of the box vianpm install.Install
ruff(pip install ruff) to enable Rust-powered Python + Bandit (S) static security checks.Install
@colbymchenry/codegraph(npm install -g @colbymchenry/codegraph) to enable Tree-sitter dependency graph & affected-test discovery.
2. Install, Build & Configure
# Option A: Install globally from npm (once published)
npm install -g jev-codeguard
jev-codeguard setup --api-key jev_live_your_key_here
# Option B: Clone and build from source
git clone https://github.com/undowhai113/jev-codeguard.git
cd jev-codeguard
npm install
npm run build
node dist/src/cli/index.js setup --api-key jev_live_your_key_hereRun the test suite (46 unit, calibration, concurrency, and security boundary tests):
npm testConnecting Your Coding Agents
Replace /absolute/path/to/jev-codeguard below with the path printed by node dist/src/cli/index.js setup.
(If you saved your key via setup --api-key, jev-codeguard automatically reads ~/.mcp-jev/config.json so you don't need to hardcode JEV_API_KEY in every IDE config!)
1. Claude Code (~/.claude.json + Optional Zero-Trust Hook)
Add jev-codeguard via CLI or ~/.claude.json:
claude mcp add jev-codeguard -- node /absolute/path/to/jev-codeguard/dist/src/cli/index.js serveOptional — Deterministic PreToolUse Firewall (.claude/settings.json):
Intercepts Bash, Write, and Edit calls before execution, even if the agent forgets to call an MCP tool:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Write|Edit",
"hooks": [
{
"type": "command",
"command": "node \"/absolute/path/to/jev-codeguard/dist/src/cli/index.js\" gate"
}
]
}
]
}
}2. OpenAI Codex (~/.codex/config.toml)
[mcp_servers.jev-codeguard]
command = "node"
args = ["/absolute/path/to/jev-codeguard/dist/src/cli/index.js", "serve"]3. Google Antigravity (~/.gemini/antigravity/mcp_config.json)
(Automatically registered if ~/.gemini/antigravity/mcp_config.json exists when you run setup)
{
"mcpServers": {
"jev-codeguard": {
"command": "node",
"args": ["/absolute/path/to/jev-codeguard/dist/src/cli/index.js", "serve"],
"env": {
"JEV_SKILLS_DIR": "/Users/you/.gemini/config/skills"
}
}
}
}4. Cursor / Windsurf (~/.cursor/mcp.json)
{
"mcpServers": {
"jev-codeguard": {
"command": "node",
"args": ["/absolute/path/to/jev-codeguard/dist/src/cli/index.js", "serve"]
}
}
}Complete Reference: 9 MCP Tools
1. jev_guard_action — Literal Pre-Execution Command Firewall
Evaluates P(safe), P(destructive), P(secret_or_net_risk), and blast_radius (1..5) before an agent executes a shell command or external mutation.
Anti-Gaming Prose Detector: Requires the verbatim executable command in
exact_command(e.g.git push --force origin main) and human intent incontext. If an agent passes a prose summary ("Push only reviewed docs safely"),jev_guard_actionimmediately returnsASK_USERwithout calling the API.Returns:
ALLOW,ASK_USER, orBLOCKwith concrete reasons and remediation steps.
2. jev_verify_diff — Deep Context & Hybrid AST Diff Gate
Collects git diff HEAD locally (zero agent prompt tokens wasted echoing diffs) and enriches it with:
Spec-to-Diff Alignment Matrix: Maps numbered/bulleted spec requirements against touched files & symbols.
Hybrid AST & Static Linter Probe: Runs
ts-morphAST skeleton extraction, Pythonast,oxlint(Rust JS/TS),ruff(Rust Python + Bandit security), andcodegraphaffected-test lookup.Cross-File Context: Extracts enclosing post-edit function scopes, imported interfaces/types, unmodified reverse dependents, and companion test suites.
Calibrated Verdict: Only elevated
security_risk >= 0.50orbug_risk >= 0.45triggersBLOCK. Uncertain spec alignment (P(fulfills_spec) < 0.68) or missing test coverage (P >= 0.65) returnsASK_USER([WARNING]) so agents report uncertainty honestly instead of rewriting the spec to game the gate.
3. jev_audit_code — Skill-Backed Security, Architecture & GSAP Auditor
Scores code snippets, files, or the local git diff across 9 OWASP/AppSec vectors (unvalidated_input, broken_authz_or_idor, injection_sql_cmd_path, xss_or_unsafe_html, ssrf_or_open_redirect, csrf_or_cookie_flaw, secrets_or_env_leak, cache_or_state_leak, dos_or_unbounded_resource) + deep-module architecture + 60fps GSAP animation vectors (when React/Vue/GSAP is detected).
Auto-Detected Stacks:
nextjs,express,react,vue,frontend,fastapi,django,flask,golang,gsap,general.Lazy Skill Escalation: Only security vectors can
BLOCK; GSAP and architecture vectors surface non-blocking advisory guidance with targeted excerpts from your localSKILL.mdlibrary (~/.gemini/config/skills,~/.claude/skills,~/.agents/skills, orJEV_SKILLS_DIR).
4. jev_autopilot_decide — Opt-In Human-Proxy Technical Recommender
Evaluates multiple-choice technical trade-offs (library choice, transaction strategy, module seam) against developer engineering standards.
Safe by Default (
ASK_HUMAN): UnlessJEV_AUTOPILOT=1is explicitly enabled in the server environment,jev_autopilot_decidealways returnsmode: "ASK_HUMAN"together with Jev's calibrated recommendation (selectedOption) so the user stays in control.Anti-Bypass Lock: Even when
JEV_AUTOPILOT=1is enabled,jev_autopilot_deciderefuses to auto-proceed (escalationReason: "recent_guard_escalation") within 15 minutes of anyjev_guard_actionASK_USERorBLOCKin the same workspace (tracked both in-memory and across separate agent processes via~/.mcp-jev/events.jsonl), and enforces a hard floor ofmin_confidence >= 0.65.
5. jev_prune_context — Out-of-Context Parallel File/Skill Filter
Scores up to 100 candidate { id, summary } items against a task description in one ~150ms parallel request, returning only candidates with P(relevant) >= threshold (default 0.60). Keeps irrelevant files out of your System-2 context window.
6. jev_classify_batch — High-Throughput Parallel Triage
Classifies up to 100 items (logs, lint errors, PR comments, issue tickets) into custom criteria categories in a single API call.
7. jev_route_task — Multi-Agent Workflow & Model Tier Router
Recommends optimal execution strategy (direct_edit, tdd_red_green, parallel_subagents, brainstorm_spec_first, deep_bug_diagnosis), model tier (fast_lightweight, balanced_coding, deep_reasoning_flagship), complexity (1..5), and whether security or UI/UX skills should be loaded.
8. jev_decide — Raw Multi-Question System-1 Battery
Direct access to Jev's native noul ($P \in [0, 1]$), choice, and score (1..5) primitives for custom agent workflows.
9. jev_stats — Session Telemetry & Cost Tracker
Returns total calls, SHA-256 cache hits, average latency (ms), token usage, and cumulative USD cost.
Live Radar Portal (http://localhost:4399) & Project Brain
Whenever mcp-jev serve runs (or when you launch npx mcp-jev dashboard), a lightweight local dashboard starts on http://127.0.0.1:4399:
Real-Time Multi-Agent Stream (SSE): Watch Claude, Codex, Gemini, and CLI hooks evaluate commands, diffs, and audits live in one unified feed.
Open-Source Engine Badges: Inspect
ts-morph,oxlint,ruff, andcodegraphdiagnostics attached to each diff/audit event.Human-in-the-Loop Project Brain (
~/.mcp-jev/projects/<workspace>.json): Click Override / Teach Rule on any event card to save persistent project-specific rules (FALSE_POSITIVE_OVERRIDEorCUSTOM_RULE) that are automatically injected into future Jev evaluations for that repository.
Calibrated Policy Thresholds (JEV_POLICY)
All gate thresholds live in one frozen module (src/core/policy-config.ts), calibrated against 330+ real multi-agent events:
Gate | Verdict | Calibrated Rule |
|
|
|
|
| Literal command shape AND |
|
|
|
|
| Clean of blockers, but |
|
| At least one security vector |
|
| Requires |
CLI Reference
# Start MCP stdio server (also ensures Live Radar Portal is up on 127.0.0.1:4399)
mcp-jev serve
# Launch standalone Live Radar Portal on a custom port
mcp-jev dashboard --port 4399
# Save API key (~/.mcp-jev/config.json, mode 0600), install SKILL.md, print IDE configs
mcp-jev setup --api-key jev_live_your_key_here
# Run Zero-Trust PreToolUse Hook Firewall (reads Claude/Cursor JSON from stdin or flags)
jev-gate --command "rm -rf dist && npm run build"
jev-gate --file src/api/route.ts
# Run Skill-Backed Security & Quality Audit on a file or current local git diff
mcp-jev audit --file src/mcp/server.ts
# Run Zero-Token Local Git Diff Verification against a specification
mcp-jev verify-diff --spec "Add rate limiting and input validation to /api/login"
# Run Human-Proxy Technical Recommender from terminal
mcp-jev autopilot --question "Which lock strategy?" \
--opt prisma_tx="Optimistic check inside Prisma $transaction" \
--opt redis_lock="External Redis Redlock cluster"Environment Variables
Variable | Default | Description |
|
| TypeSafe AI API key ( |
|
| Set to |
| Auto-detected | Custom path to local |
|
|
|
|
| Custom path for the cross-process event ledger (auto-rotates to |
|
| Byte threshold before atomic lockfile-guarded rotation of |
| Parent of | Path-delimited ( |
|
| Custom Jev API endpoint override. |
Security & Privacy Model
Zero Shell Interpolation (
shell: false): All child processes (git,oxlint,ruff,codegraph,python) are invoked viaexecFileSync/spawnargument arrays withshell: falseacross Windows, macOS, and Linux — eliminatingcmd.exeand/bin/shmetacharacter injection.Workspace Path Traversal & Secret Blocklist:
jev_audit_codeandextractReferencedDocsAndFilesenforce canonicalrealpathSyncworkspace boundaries (isWithinWorkspaceBoundary) and automatically block sensitive files (.env,.env.*,*.pem,*.key,*.p12,id_rsa,credentials.json,~/.ssh/*,~/.mcp-jev/config.json) from ever being read or sent to the Jev API.Hardened Local Dashboard (
127.0.0.1Only): The Radar Portal binds strictly to127.0.0.1, enforcesContent-Security-Policy,X-Frame-Options: DENY,Hostheader DNS-rebinding checks,OriginCSRF validation on state-mutating endpoints,64 KBbody caps, and25max SSE client caps.Restricted Credential Permissions:
mcp-jev setupcreates~/.mcp-jevwith0700and writesconfig.jsonwith0600permissions; API keys are never echoed in tool responses or event logs.What Leaves Your Machine: When a Jev tool is called, bounded state snippets (command string, budgeted git diff, or audited file content) are sent over HTTPS (
TLS) tohttps://api.typesafe.ai/v1/jev. Local telemetry, Project Brain rules, and rotated event logs (~/.mcp-jev/events.jsonl) stay100%on your machine.
Project Structure
mcp-jev/
├── src/
│ ├── core/
│ │ ├── jev-client.ts # HTTPS client, SHA-256 TTL cache, retries, ~/.mcp-jev/config.json loader
│ │ ├── policy-config.ts # Frozen JEV_POLICY thresholds (single source of truth)
│ │ ├── policy-engine.ts # Calibrated command/diff/autopilot gates + 15-min guard escalation lock
│ │ ├── command-shape.ts # Literal command vs. prose detector (strips quotes, heredocs, comments)
│ │ ├── context-enricher.ts # Project Brain DNA, spec matrix, callers, contracts, boundary/secret guards
│ │ ├── hybrid-ast-engine.ts # ts-morph + Python AST, Oxlint, Ruff, and CodeGraph integration
│ │ ├── skill-auditor.ts # 10+ OWASP/Architecture/GSAP vectors + Lazy SKILL.md Escalation
│ │ ├── git-collector.ts # Zero-token local git diff collector & multi-file proportional budgeter
│ │ ├── event-log.ts # Multi-process atomic O_APPEND ledger, 5 MiB rotation & tail reader
│ │ ├── presets.ts # Prompt/question battery builders
│ │ ├── cache.ts # Deterministic SHA-256 in-memory cache
│ │ └── telemetry.ts # Session latency, cache hit & USD cost aggregator
│ ├── mcp/
│ │ └── server.ts # 9 MCP tools registered over StdioServerTransport
│ ├── dashboard/
│ │ └── server.ts # Live Radar Portal (127.0.0.1:4399, SSE + Project Brain rule editor)
│ └── cli/
│ ├── index.ts # `mcp-jev` & `jev-gate` CLI entrypoints
│ ├── hook-runner.ts # Zero-Trust PreToolUse hook runner (Claude Code / Cursor)
│ └── setup.ts # Interactive config writer & companion skill installer
├── skills/
│ └── jev-system-one/SKILL.md # Companion agent workflow instructions
└── tests/ # 11 test suites (calibration, concurrency, security & AST engines)Contributing & Security
Contributing Guide: See CONTRIBUTING.md for local setup, architecture map, and PR calibration rules.
Security Policy: See SECURITY.md for trust boundaries and private vulnerability disclosure.
Release History: See CHANGELOG.md.
License
Released under the MIT License.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
The WAF for agents. Pattern-based + heuristic firewall scans prompts, RAG documents, tool argume...
See, price, and control every tool call your AI agents make: policy checks, cost, and audit tools.
Deterministic runtime safety for AI agents: scan PII, gate tool actions, verify LLM output.
Real-time MCP & A2A prompt-injection, jailbreak, and tool-schema poisoning firewall for AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceLocal zero-trust permission gateway for AI agents. Enforces policy-based tool authorization, human approvals, scoped permissions, and cryptographically verifiable audit logs.4128 PyPI5Apache 2.0
- FlicenseNot gradedqualityDmaintenanceA local-first security gateway and visual dashboard for AI agents that enforces cost caps, blocks prompt injections, and requires approval for dangerous actions.3-
- AlicenseAqualityCmaintenanceEnables AI coding agents to avoid irreversible mistakes by intercepting risky deletions, overwrites, and commands before execution, applying path, pattern, and blast-radius safeguards with quarantine backups.315 npmMIT
- AlicenseNot gradedqualityBmaintenanceA local proxy in front of any MCP server for developers on Claude Code or Cursor: see every tool call your agent makes, hold the risky ones for your approval, and keep a secret-redacted journal that is tamper-evident with an external anchor.65 npm1Apache 2.0