{
  "markdown": "# MCP Guardian\n\n**A safety layer between your AI assistant and the tools it uses.**\n\n[![npm version](https://img.shields.io/npm/v/@mcp-guardian/server)](https://www.npmjs.com/package/@mcp-guardian/server)\n[![npm downloads](https://img.shields.io/npm/dm/@mcp-guardian/server)](https://www.npmjs.com/package/@mcp-guardian/server)\n[![Socket Badge](https://badge.socket.dev/npm/package/@mcp-guardian/server/4.1.8)](https://badge.socket.dev/npm/package/@mcp-guardian/server/4.1.8)\n[![Website](https://img.shields.io/badge/Website-mcp--guardian--cloud.vercel.app-0070f3)](https://mcp-guardian-cloud.vercel.app/)\n[![mcp-guardian MCP server](https://glama.ai/mcp/servers/rudraneel93/mcp-guardian/badges/score.svg)](https://glama.ai/mcp/servers/rudraneel93/mcp-guardian)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org/)\n[![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.25-green)](https://github.com/modelcontextprotocol/typescript-sdk)\n[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)\n[![CI](https://github.com/rudraneel93/mcp-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/rudraneel93/mcp-guardian/actions/workflows/ci.yml)\n\n**Version 4.1.8** · [Website](https://mcp-guardian-cloud.vercel.app) · [npm](https://www.npmjs.com/package/@mcp-guardian/server) · [Install & troubleshooting](docs/INSTALL.md) · [Changelog](CHANGELOG.md)\n\n### What's new in 4.1.8\n\n- **Incident policy workflow** — Enterprise AI investigation drawer can generate, preview, accept, or reject blocking rules from incidents\n- **npm publish hardening** — ordered publish script with registry dep resolution checks and clean-install verification before server goes live\n- **Dashboard stability** — fix React hooks ordering in Security/Health panels that caused error #310 on load\n\n### What's new in 4.1.7\n\n- **Active Rules controls** — Security → Policy now includes list/search, soft disable/enable, and hard delete operations synced to YAML\n- **Policy runtime semantics** — `enabled: false` is honored across rule strategies with backward-compatible defaults\n- **Policy mutation APIs** — cloud + local dashboard endpoints for list/toggle/delete with updated README guidance\n\n### What's new in 4.1.6\n\n- **`mcp-guardian start`** — one command for proxy + web dashboard on port 4000 (local dev defaults)\n- **`mcp-guardian setup`** — one-shot install for git clones (`pnpm install`, build, dashboard SPA)\n- **npm tarball** — prebuilt dashboard UI (`deploy/dashboard-spa/out/`) built at publish time\n- **Install guide** — expanded troubleshooting in README and [docs/INSTALL.md](docs/INSTALL.md)\n\n### What's new in 4.1.5\n\n- **npm install** — fixes broken `@mcp-guardian/server@4.1.4` registry manifest (`workspace:` deps). Use **4.1.5+**.\n\n### What's new in 4.1.4\n\n- **`mcp-guardian onboard` from global npm** — resolves the installed package root (not `cwd`); writes `guardian-configs/` under your current directory; ships `scripts/guardian-proxy.sh` and `policy-audit.yaml` in the npm tarball\n\n### What's new in 4.1.3\n\n**npm install fix** — registry manifest now matches published tarballs (`^4.1.3` semver deps, not `workspace:`). Use `@mcp-guardian/server@4.1.3` or later. Publish via `./scripts/publish-npm-all.sh` (server/CLI ship from `.tgz` so metadata stays correct).\n\n### What's new in 4.1.1\n\n**npm install hygiene** — fixes supply-chain scanner findings from 4.1.0:\n\n- Published tarballs no longer include `postinstall` or other lifecycle scripts\n- `workspace:` dependencies are rewritten to semver (`^4.1.1`) at pack time\n- Publish **all** packages via `./scripts/publish-npm-all.sh` (core → plugin-sdk → server → cli)\n\n### What's new in 4.1.0\n\n**Industry roadmap plan compliance** — runtime verification and dashboard wiring for all eleven fleet-wide modules (A1–C5, B1–B3):\n\n- **`guardian roadmap audit`** — CLI + `GET /api/agentic/plan-compliance/audit` verify every shipped module; exit 0 when production-ready\n- **Dashboard Agentic AI panels** — PlanCompliance, Reputation, ZeroTrust, FederatedLearning, Observatory mesh sync, SandboxWizard captured-traffic scorecard, ChainGraph (A1)\n- **Protection home strip** — roadmap compliance score on the main Protection tab with link to Agentic AI\n- **A1 ONNX graph path** — optional fleet chain classifier via `GUARDIAN_FLEET_GRAPH_ONNX_MODEL`\n- **B3 MPC-lite masking** — pairwise-masked federated gradients (`GUARDIAN_FEDERATED_MPC`)\n- **B2/B1 mesh relays** — observatory and reputation mesh publish/pull; dev stub via `GUARDIAN_OBSERVATORY_STUB`\n- **Docs & env** — `guardian roadmap *` commands documented; production env vars in `.env.example`\n\nRun `guardian roadmap audit --json` or open **Agentic AI → Overview** in the dashboard to confirm 100% compliance.\n\n### What's new in 4.0.0\n\n**Industry-standard MCP protection** — Guardian moves from per-call filtering to fleet-wide, cross-agent security:\n\n- **MTX v1** — open threat exchange format (`@mcp-guardian/mtx`) + cloud hub\n- **Guardian Certified MCP** — HMAC attestation, persistent registry, verification API\n- **Multi-step attack chains** — collusion detector + session-chain graph with proxy enforcement\n- **Capability graph & intent binding** — tool/resource graph and session intent allowlists\n- **Agent reputation ledger** — persistent scores with proxy enforcement\n- **Dynamic sandbox tiers** — shadow / redact / allow with RL-ready persistence\n- **Protocol fuzzer** — expanded corpus with real block validation and cert gates\n- **Policy simulator** — `/api/policy/simulate` + `ab_test_policy` MCP tool\n- **Incident playbooks & AI investigator** — webhook/isolate executors; Threat Lab–linked investigations\n- **Compliance evidence runner** — live policy + audit wired to SOC2/HIPAA/PCI/FedRAMP/ISO mappings\n- **guardian-bench** — `mcp-guardian bench` CLI + public leaderboard\n\nSee [CHANGELOG.md](CHANGELOG.md) for 3.4.1 production hardening (JWKS refresh, payload limits, SIEM on all block paths, audit retention).\n\n**Roadmap (shipped in 4.0):** Semantic policy translator with approval flows, config provenance chain, STRIDE/LINDDUN threat modeling, behavioral biometrics, cross-MCP attack chains with SIEM export, digital twin sandbox, zero-trust SPIFFE scoring, decentralized reputation network, ecosystem observatory, insurance risk quantification + PDF export, and federated threat detection — [docs/AGENTIC_ROADMAP.md](docs/AGENTIC_ROADMAP.md).\n\n### Fleet mandate for CISO buyers\n\nGuardian v4 is designed as a **fleet-wide control plane**, not a single-proxy filter:\n\n- **Mandatory policy provenance** — every YAML change is hash-chained, signed, and exportable to SIEM/auditors\n- **Human-in-the-loop policy approval** — NL drafts must pass simulation + explicit approval before apply\n- **Cross-agent attack chain detection** — session graphs span servers; alerts export as CEF for Splunk/Datadog\n- **SPIFFE/mTLS identity** — zero-trust composite scores include workload identity from SPIFFE SVIDs\n- **Cloud observatory + reputation mesh** — anonymized fleet telemetry and server reputation consensus via MCP Guardian Cloud\n- **Insurance-ready risk reports** — ALE quantification with underwriter PDF export for cyber insurance workflows\n\n---\n\n## What problem does this solve?\n\nModern AI assistants (Claude, Cursor, Cline, and others) can connect to **tools** — read files, run commands, query databases, post to Slack, and more. Those connections often use a standard called **MCP** (Model Context Protocol).\n\nThat power is useful, but risky:\n\n- The AI might read files it should not see.\n- It might run shell commands or delete data by mistake or because of a malicious prompt.\n- Secrets can leak through tool arguments.\n- API costs can spike without you noticing.\n\n**MCP Guardian sits in the middle.** Every tool request goes through Guardian first. Guardian checks your rules, blocks bad requests, logs what happened, and can show you a live dashboard — **before** anything reaches your real tools.\n\n```\nYour AI assistant\n       │\n       ▼\n  MCP Guardian  ← reads your rules, blocks bad calls, keeps a log\n       │\n       ▼\n  Your real tools (files, GitHub, database, …)\n```\n\n---\n\n## How it works (step by step)\n\n1. **You install Guardian** and point it at your existing MCP setup (or run `mcp-guardian onboard` to do this automatically).\n2. **Guardian wraps your tool servers** so the AI talks to Guardian instead of talking to them directly.\n3. When the AI tries to use a tool, Guardian receives the request first.\n4. Guardian compares the request to your **policy** (a simple rules file you control).\n5. If the request is allowed, Guardian forwards it to the real tool and returns the result.\n6. If the request breaks a rule, Guardian **blocks it** and tells the AI it was denied — the real tool never runs.\n7. Every allow and block is saved to a local database so you can review history and see charts on the dashboard.\n\nYou stay in control: Guardian does not silently change your rules unless you approve it (for example when reviewing Threat Lab suggestions).\n\n---\n\n## Architecture\n\nThis section shows how MCP Guardian is wired together: what runs where, how a tool call flows through governance, and how optional Pro pipelines connect to the proxy.\n\n**In this section:** [System overview](#system-overview) · [Tool call path](#tool-call-path-tools_call) · [Transports](#transports) · [Agentic AI](#agentic-ai-integration) · [Dashboard](#dashboard-and-observability) · [Pro pipelines](#pro-pipeline-architecture) · [Learning loop](#continuous-improvement-loop)\n\n### System overview\n\nWhen you run **`mcp-guardian start`** or `pnpm dashboard:proxy`, one Node process typically hosts the **policy proxy**, the **dashboard API**, and (optionally) **agentic services**. All components share the same audit database (`MCP_GUARDIAN_DB_PATH`, default `~/.mcp-guardian/history.db`).\n\n```mermaid\nflowchart TB\n  subgraph clients [AI clients]\n    Cursor[Cursor / Cline / Claude]\n  end\n\n  subgraph guardian [MCP Guardian process]\n    Proxy[Proxy layer\\nstdio HTTP SSE WS streamable]\n  Policy[PolicyEngine\\nYAML + hot reload]\n  Agentic[Agentic container\\noptional hooks]\n  DashboardAPI[Dashboard REST + WebSocket]\n  end\n\n  subgraph storage [Persistence]\n    SQLite[(history.db)]\n    SIEM[SIEM exporters\\noptional]\n  end\n\n  Upstream[Upstream MCP servers\\nfilesystem GitHub etc]\n\n  Cursor --> Proxy\n  Proxy --> Policy\n  Proxy --> Agentic\n  Policy --> Proxy\n  Agentic --> Proxy\n  Proxy --> Upstream\n  Upstream --> Proxy\n  Proxy --> SQLite\n  Proxy --> SIEM\n  DashboardAPI --> SQLite\n  clients -.-> DashboardAPI\n```\n\n| Component | Role | Main code |\n|-----------|------|-----------|\n| **Proxy layer** | Intercepts JSON-RPC; enforces policy on every `tools/call` | [`src/proxy/`](src/proxy/) |\n| **Policy engine** | Evaluates YAML rules, rate limits, RBAC, patterns | [`src/policy/`](src/policy/) |\n| **History DB** | Stores allow/block audit, tokens, cost | [`src/database/history-db.ts`](src/database/history-db.ts) |\n| **Dashboard** | Local UI + REST API over the same DB | [`deploy/dashboard-spa/`](deploy/dashboard-spa/), [`src/utils/dashboard-server.ts`](src/utils/dashboard-server.ts) |\n| **Agentic** | Smart features (injection scan, policy gen, trust, etc.) | [`src/agentic/`](src/agentic/) |\n\nEnterprise deployments may add **Redis** (rate limits, DPoP, circuit-breaker sync) and **PostgreSQL** instead of SQLite — see [ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md).\n\n### Tool call path (`tools/call`)\n\nEvery dangerous decision happens **before** the real MCP server runs. If Guardian blocks a call, the upstream tool never receives it.\n\n```mermaid\nsequenceDiagram\n  participant Client as AI client\n  participant Transport as Proxy transport\n  participant PreGuard as Pre-forward guard\n  participant Policy as PolicyEngine\n  participant Semantic as Semantic gate\n  participant Upstream as Upstream MCP\n  participant Audit as Audit queue\n  participant SIEM as SIEM log\n\n  Client->>Transport: tools/call JSON-RPC\n  Transport->>PreGuard: checkExpandedPayload + agentic hooks\n  alt blocked at pre-guard\n    PreGuard-->>Client: JSON-RPC error -32001\n    PreGuard->>Audit: denied record\n    PreGuard->>SIEM: tool_blocked\n  else allowed\n    PreGuard->>Policy: evaluateAsync context\n    alt policy block\n      Policy-->>Client: JSON-RPC error\n      Policy->>Audit: denied record\n      Policy->>SIEM: tool_blocked\n    else policy pass\n      Policy->>Semantic: sync semantic request gate\n      alt semantic block\n        Semantic-->>Client: JSON-RPC error\n        Semantic->>Audit: denied record\n        Semantic->>SIEM: tool_blocked\n      else forward\n        Semantic->>Upstream: forward request\n        Upstream-->>Transport: tool result\n        Transport->>Transport: response DLP gate\n        Transport-->>Client: JSON-RPC result\n        Transport->>Audit: allow record\n      end\n    end\n  end\n```\n\n**Integration details:**\n\n1. **Pre-forward guard** ([`src/proxy/tool-call-pre-guard.ts`](src/proxy/tool-call-pre-guard.ts)) — caps expanded argument size and runs agentic pre-hooks (prompt injection, etc.) on all transports.\n2. **Policy** ([`src/policy/policy-engine.ts`](src/policy/policy-engine.ts)) — your YAML rules; rate-limit counters survive hot-reload via [`src/policy/rate-limit-store.ts`](src/policy/rate-limit-store.ts).\n3. **Semantic gate** ([`src/proxy/proxy-post-policy-gates.ts`](src/proxy/proxy-post-policy-gates.ts)) — optional LLM/heuristic check on arguments before forward.\n4. **Audit** — [`persistCallRecord`](src/utils/call-record-cost.ts) → async [`audit-write-queue`](src/database/audit-write-queue.ts) → SQLite; blocks also emit [`StructuredLogger.logBlocked`](src/utils/structured-logger.ts) for SIEM.\n\n### Transports\n\nGuardian implements the same governance stack on every MCP transport your IDE might use:\n\n| Transport | Entry module | `tools/call` governance |\n|-----------|--------------|-------------------------|\n| **stdio** | [`src/proxy/proxy-server.ts`](src/proxy/proxy-server.ts) | Full pipeline (default for wrapped configs) |\n| **HTTP** | [`src/proxy/http-proxy-server.ts`](src/proxy/http-proxy-server.ts) | Full + pre-forward guard |\n| **SSE** | [`src/proxy/sse-proxy-server.ts`](src/proxy/sse-proxy-server.ts) | Full + pre-forward guard |\n| **WebSocket** | [`src/proxy/websocket-proxy-server.ts`](src/proxy/websocket-proxy-server.ts) | Full + pre-forward guard |\n| **Streamable HTTP** | [`src/proxy/streamable-http-proxy-server.ts`](src/proxy/streamable-http-proxy-server.ts) | Full + pre-forward guard |\n\nRun `mcp-guardian onboard` so client configs point at Guardian-wrapped servers. If an IDE connects to an MCP server **around** Guardian (common with raw SSE URLs), calls are **untracked** — metrics and logs will show `sse_untracked`.\n\n### Agentic AI integration\n\nAgentic features are optional modules loaded at boot ([`src/container.ts`](src/container.ts)). They do not replace your YAML policy; they add observation, scoring, and recommendations.\n\n```mermaid\nflowchart TB\n  subgraph mcp [MCP surface]\n    Tools[MCP tools in src/index.ts]\n  end\n\n  subgraph container [DI container]\n    Core[agentic/core.ts\\npipeline scheduler telemetry]\n    Features[Feature modules\\npolicy gen injection trust mesh]\n  end\n\n  subgraph runtime [Runtime integration]\n    Hooks[proxy-integration.ts\\npre/post call hooks]\n    PreGuard[tool-call-pre-guard.ts]\n  end\n\n  subgraph ui [Dashboard]\n    API[agentic-dashboard-summary.ts]\n    Workspace[Agentic AI workspace SPA]\n  end\n\n  DB[(agentic tables\\nmigration 011)]\n\n  Tools --> Core\n  Core --> Features\n  PreGuard --> Hooks\n  Hooks --> Features\n  API --> DB\n  Workspace --> API\n  Hooks --> DB\n```\n\n| Integration point | What happens |\n|-------------------|--------------|\n| **Every `tools/call`** | [`runAgenticPreForwardHooks`](src/agentic/proxy-integration.ts) can block or sanitize arguments when agentic mode is on |\n| **MCP tools** | ~35 agentic tools registered in [`src/index.ts`](src/index.ts) for automation and dashboard actions |\n| **Modules** | 40+ agentic modules in [`src/agentic/`](src/agentic/) (prediction, policy-gen, mesh, collusion, reputation, etc.) |\n| **Dashboard** | **Agentic AI** workspace reads [`/api/agentic/*`](src/utils/agentic-dashboard-summary.ts) summaries |\n| **Database** | Agentic state in [`011-agentic-tables.sql`](src/database/migrations/011-agentic-tables.sql) |\n\nModule-level detail: [docs/AGENTIC_ARCHITECTURE.md](docs/AGENTIC_ARCHITECTURE.md) · Shipped features: [docs/AGENTIC_FEATURES.md](docs/AGENTIC_FEATURES.md) · **Roadmap:** [docs/AGENTIC_ROADMAP.md](docs/AGENTIC_ROADMAP.md).\n\n### Dashboard and observability\n\n```mermaid\nflowchart LR\n  Proxy[Proxy writes] --> DB[(history.db)]\n  DB --> REST[Dashboard REST API]\n  REST --> SPA[Next.js SPA\\nProtection Activity Agentic]\n  REST --> WS[WebSocket push\\nGUARDIAN_WS_ENABLED]\n  Proxy --> Prom[Prometheus metrics\\noptional]\n  Proxy --> SIEM[SIEM exporters\\nMCP_GUARDIAN_SIEM_ENABLED]\n```\n\nThe dashboard is not a separate database — it reads the same `call_records` the proxy writes. Set `MCP_GUARDIAN_DB_PATH` consistently when running `pnpm real-life:filesystem` or other tests so charts match proxy traffic.\n\n### Pro pipeline architecture\n\nThese Pro workflows run **alongside** the live proxy. They consume audit data, swarm reports, and LLM output to improve detection — they do not sit in the hot path of every tool call.\n\n#### Security Swarm\n\nAutomated red-team loop: generate attacks, run the harness, detect bypasses, feed learning.\n\n![Security Swarm architecture — scout, harness, bypass detection, and learning feedback](docs/assets/security-swarm-architecture.png)\n\n- **What it does:** Runs scripted steps (build, corpus eval, parity, harness) and records bypasses when policy allows an attack that should be blocked.\n- **How it connects:** Reads/writes under `reports/security-swarm/`; bypasses and proposals can inform Threat Lab and runtime attack-learning.\n- **Run:** `pnpm security-swarm` (Pro license in production).\n\n#### Threat Lab (LLM discovery)\n\nHuman-reviewed LLM proposals for new attack fixtures and policy ideas.\n\n![Threat Lab architecture — Ollama discovery, validation, and candidate manifest](docs/assets/llm-threat-discovery-architecture.png)\n\n- **What it does:** Collects signals (bypasses, semantic TPs, ThreatIntel), asks a local LLM for new corpus candidates, validates them, writes `threat-lab-candidates.json` for **you to accept**.\n- **How it connects:** Outputs feed the adversarial harness and optional policy-applier after review — nothing is applied silently.\n- **Run:** `pnpm security-swarm:threat-lab` (requires Ollama). See [THREAT_LAB.md](docs/THREAT_LAB.md).\n\n#### Auto Threat Research\n\nBackground LLM research when the proxy blocks suspicious traffic; writes validated `adv-*.json` fixtures.\n\n![Auto Threat Research architecture — queued detections to auto corpus fixtures](docs/assets/auto-threat-research-architecture.png)\n\n- **What it does:** Debounces block events, classifies attack types, writes harness fixtures when validation passes (dedupe + rate caps).\n- **How it connects:** Uses the same auto-corpus writer as Threat Lab when both `GUARDIAN_THREAT_RESEARCH_AUTO` and `SWARM_THREAT_RESEARCH_AUTO` are enabled.\n- **Run:** Enable env flags on the proxy host; or trigger from dashboard **Threat Discovery**.\n\n### Continuous improvement loop\n\n```mermaid\nflowchart LR\n  Live[Live proxy blocks] --> Audit[(history.db)]\n  Live --> Learn[Attack learning]\n  Swarm[Security Swarm] --> Bypasses[bypasses.json]\n  Bypasses --> ThreatLab[Threat Lab]\n  ThreatLab --> Harness[adversarial harness]\n  AutoResearch[Auto Threat Research] --> Fixtures[adv fixtures]\n  Fixtures --> Harness\n  Harness --> Policy[Policy YAML updates]\n  Policy --> Live\n```\n\nDeep dive: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n---\n\n## Features explained\n\nBelow is what each major capability does, in plain language.\n\n### Policy proxy (the core)\n\n**What it is:** A filter on every tool call.\n\n**How it works:** You write rules in a YAML file (see [The policy file](#the-policy-file) below). Rules can allow specific tools, deny dangerous ones, limit how often tools run, cap token usage, and match patterns in arguments (for example “block if the path contains `../`”). When you change the file, Guardian can reload rules without restarting.\n\n**Why it matters:** This is your main line of defense — fast, predictable, and fully under your control.\n\n---\n\n### Attack blocking (built into the default policy)\n\n**What it is:** Hundreds of pre-written checks for common abuse.\n\n**How it works:** Before a call reaches your server, Guardian looks for things like shell commands hidden in arguments, path traversal (`../etc/passwd`), SQL injection patterns, attempts to exfiltrate secrets, suspicious URLs, and Unicode tricks that hide malicious text. If a pattern matches, the call is blocked and logged.\n\n**Why it matters:** Many real-world attacks look like normal tool calls; these checks catch a large class of them without an AI model.\n\n---\n\n### Cost tracking\n\n**What it is:** A running tally of how much your tool usage costs.\n\n**How it works:** Guardian estimates tokens and dollar cost per call (using model pricing when available). You can set budgets and see burn rate over time in the dashboard.\n\n**Why it matters:** Runaway agents or loops can get expensive; you see it early.\n\n---\n\n### Health monitoring\n\n**What it is:** A health check for each connected MCP server.\n\n**How it works:** Guardian tracks success rate, latency, and whether a server is responding. If a server keeps failing, a circuit breaker can stop hammering it.\n\n**Why it matters:** You notice broken or flaky integrations before users complain.\n\n---\n\n### Live audit log\n\n**What it is:** A permanent record of what was allowed and what was blocked.\n\n**How it works:** Each decision is stored in a local SQLite database (default: `~/.mcp-guardian/history.db`). The dashboard reads this database to show tables, charts, and filters.\n\n**Why it matters:** Security and debugging need a clear trail — who tried what, when, and why it was blocked.\n\n---\n\n### Package scanning (CVE and typo-squat)\n\n**What it is:** A check on MCP packages before you trust them.\n\n**How it works:** Guardian can scan installed or configured packages for known security issues (CVEs) and names that look like famous packages but are slightly misspelled (typo-squatting).\n\n**Why it matters:** Supply-chain attacks often arrive as “almost the right” package name.\n\n---\n\n### Adversarial harness (offline tests)\n\n**What it is:** A large automated test suite that fires attack-like requests at your policy **without** a live AI.\n\n**How it works:** Run `pnpm harness` from the repo. It replays 800+ fixtures and reports what would be blocked or allowed.\n\n**Why it matters:** You can change rules and immediately see if you broke legitimate use or left a hole open.\n\n---\n\n### Real-life scenarios (live tests)\n\n**What it is:** A short or long run of real attack traffic against a real filesystem MCP server through Guardian.\n\n**How it works:** Commands like `pnpm real-life:filesystem` drive the official filesystem server with path traversal, injection, and similar tests while the proxy is running. Results show up in the dashboard if you use the same database path.\n\n**Why it matters:** Offline tests are fast; live tests prove the full path (proxy → policy → log → UI) works.\n\n---\n\n## Agentic AI features (version 4.1)\n\nThese are **smart assistants inside Guardian** that watch, score, and recommend — they do not replace your policy unless you choose to apply a suggestion.\n\n### Shipped today\n\n| Feature | What it does for you |\n|--------|----------------------|\n| **Threat prediction** | Scores how risky each MCP server is and suggests hardening before something breaks. |\n| **Policy generation** | Watches normal tool use, then drafts a tight “only what you actually need” policy you can review. |\n| **Prompt injection detection** | Scans tool arguments for text meant to hijack another AI (heuristic + optional LLM). |\n| **Threat mesh (MTX)** | Opt-in anonymized attack-pattern sharing; `@mcp-guardian/mtx` open exchange format. |\n| **Honeypots** | Deploys fake decoy servers; probes trigger alerts. |\n| **Supply chain checks** | Publisher verification, dependency confusion, typo-squat detection, SBOM export. |\n| **Compliance mapping** | Maps posture to SOC 2, HIPAA, PCI-DSS, FedRAMP, ISO 27001 with evidence runner. |\n| **Drift detection** | Notices when a server’s tools or behavior change unexpectedly. |\n| **Red team & protocol fuzzer** | Curated and mutated attacks; expanded fuzz corpus with cert gates. |\n| **Trust protocol & Guardian score** | Agent-to-agent negotiation plus local trust scoring. |\n| **Collusion & attack chains** | Multi-step pattern detection across agents/tools (session-chain graph). |\n| **Capability graph & intent binding** | Maps tool/resource relationships; session intent allowlists. |\n| **Agent reputation** | Persistent reputation ledger with proxy enforcement. |\n| **Sandbox tiers** | Dynamic shadow / redact / allow per tool or server. |\n| **Guardian Certified MCP** | HMAC-signed server attestation and verification tiers. |\n| **Policy simulator** | Preview policy impact before deploy (`ab_test_policy`, REST simulate API). |\n| **Incident playbooks & investigator** | Automated playbook steps; AI incident investigation in the dashboard. |\n| **MCP lifecycle guard** | Session-gated access to `tools/list`, `resources/read`, `prompts/get`. |\n| **Response DLP** | Scans upstream tool responses and streaming output for secrets. |\n| **RL tuning** | Contextual bandits and Thompson sampling for threshold optimization. |\n\n**Dashboard:** Open **Agentic AI** in the web UI for overview charts, trust scores, audit tables, and admin tools. See [Agentic Features Guide](docs/AGENTIC_FEATURES.md).\n\n### Industry-standard roadmap (shipped in 4.0)\n\nGuardian’s industry-standard layer delivers **cross-server, cross-agent, systemic** protection — what enterprise CISOs need to mandate Guardian fleet-wide. All eleven capabilities shipped in v4.0:\n\n| Tier | Features | Theme |\n|------|----------|--------|\n| **1 — Paradigm** | A1 Cross-MCP attack chain detection · A2 Digital twin & policy sandbox · A3 Agent behavioral biometrics | See the forest, not just the trees |\n| **2 — Ecosystem** | B1 Decentralized reputation network · B2 Ecosystem health observatory · B3 Federated threat detection | Network effects across deployments |\n| **3 — Enterprise** | C1 Config provenance chain · C2 Threat modeling as code (STRIDE/LINDDUN) · C3 Zero-trust continuous verification · C4 Insurance risk quantification · C5 Semantic policy translator | Compliance, CFO, and business stakeholders |\n\n**Build order (12 months):** Phase 1 (C5, C1, C2, A3) → Phase 2 (A1, A2, C3) → Phase 3 (B1, B2, C4) → Phase 4 research (B3).\n\nFull detail, foundations already in code, and differentiation rationale: **[docs/AGENTIC_ROADMAP.md](docs/AGENTIC_ROADMAP.md)**.\n\n**Verify compliance:** Run `guardian roadmap audit` (or `--json` for machine-readable output). The dashboard **Agentic AI → Overview** tab shows the same runtime audit via **Industry Roadmap Compliance**. Additional CLI utilities: `guardian roadmap fleet-graph-train`, `federated-export|import`, `observatory-sync`, `reputation-sync`. See [Agentic Quickstart](docs/AGENTIC_QUICKSTART.md#industry-roadmap-cli).\n\n**Production env vars** (optional): fleet chain blocking (`GUARDIAN_FLEET_CHAIN_BLOCK_CONFIDENCE`), multi-region Redis (`GUARDIAN_FLEET_REGION`), observatory relay or dev stub (`GUARDIAN_OBSERVATORY_RELAY_URL`, `GUARDIAN_OBSERVATORY_STUB`), federated learning (`GUARDIAN_FEDERATED_LEARNING`, `GUARDIAN_FEDERATED_MPC`), ONNX graph model (`GUARDIAN_FLEET_GRAPH_ONNX_MODEL`). Full list in [`.env.example`](.env.example).\n\n---\n\n## The web dashboard\n\n**What it is:** A local website (default [http://localhost:4000](http://localhost:4000)) that shows what Guardian is doing.\n\n**How it works:** When you run **`mcp-guardian start`** (or `pnpm dashboard:proxy` from a git clone), the same process serves the dashboard and the API. The UI reads real data from your history database — not fake demo numbers.\n\n**Main areas:**\n\n| Area | What you see |\n|------|----------------|\n| **Protection** | Overall status and plain-English analysis of your setup. |\n| **Activity** | Audit log of allowed and blocked calls. |\n| **Threats** | Active threats and quarantine actions. |\n| **Security** | Security score and trends. |\n| **Operations** | Traffic, errors, and cost charts over time. |\n| **Agentic AI** | Autonomous features: trust, threats, policy, operations, audit, and tools. Industry roadmap panels (A1–C5, B1–B3) live here — plan compliance audit on **Overview**. |\n| **Settings** | Servers, policy, and setup checklist. |\n\n**Tip:** If charts say “no traffic in this time window,” widen the **Time window** dropdown (for example **Last 7 days**). Short windows only show very recent calls.\n\n---\n\n## Security Swarm (Pro)\n\n**What it is:** A team of automated testers that keep trying to break your policy the way an attacker would.\n\n**How it works:**\n\n- One track **generates and runs attacks**, checks for bypasses, and writes reports.\n- Another track **learns from real blocks** on your proxy and improves detection over time.\n- The two tracks feed each other so tests get better as your deployment sees real traffic.\n\n**Why it matters:** Your policy is only as strong as the attacks you have tested against; the swarm expands that set continuously.\n\nRun: `pnpm security-swarm` (license required in production). Architecture diagram: [Architecture § Pro pipeline](#pro-pipeline-architecture) above.\n\n---\n\n## Threat Lab (Pro)\n\n**What it is:** Uses a local AI model to **propose** new attack patterns and rule ideas based on what Guardian has seen.\n\n**How it works:**\n\n1. Collects signals from recent blocks, CVE data, and swarm findings.\n2. The model suggests new test cases and possible policy lines.\n3. Automated checks validate proposals.\n4. **You review and approve** — nothing is applied automatically.\n\nRun: `pnpm security-swarm:threat-lab` (needs Ollama or another configured LLM). See [THREAT_LAB.md](docs/THREAT_LAB.md).\n\n---\n\n## Auto Threat Research (Pro)\n\n**What it is:** Background research when something interesting is blocked.\n\n**How it works:** When the proxy blocks a suspicious call, events can be queued, grouped, and analyzed by an LLM to classify the attack type and add it to your research corpus. **It does not change your live policy by itself** — it builds knowledge for you to use later.\n\nEnable with `GUARDIAN_THREAT_RESEARCH_AUTO=true` when licensed.\n\n---\n\n## Guardian Autopilot (Pro)\n\n**What it is:** One-command setup: wrap MCP configs, start the proxy, turn on the dashboard, and optional background services (digests, learning).\n\n**How it works:**\n\n```bash\npnpm autopilot:init -- --apply\npnpm autopilot:start\n```\n\nSee [AUTOPILOT.md](docs/AUTOPILOT.md).\n\n---\n\n## Free vs Pro\n\n| | **Free (community)** | **Pro** |\n|---|---------------------|--------|\n| Policy proxy and YAML rules | Yes | Yes |\n| Attack blocking, audit log, cost tracking | Yes | Yes |\n| Harness and real-life scenarios | Yes | Yes |\n| Full enterprise dashboard | Limited / dev bypass | Yes |\n| Security Swarm, Threat Lab, Autopilot | No | Yes |\n| Fleet, SSO, Kubernetes, PostgreSQL | No | Yes |\n\nLocal development can use `GUARDIAN_CI_BYPASS_LICENSE=true` with `pnpm dashboard:proxy`. Production Pro needs a license — [PRO_SETUP.md](docs/PRO_SETUP.md).\n\n---\n\n## Getting started — install, clone, and run\n\nThis section walks through every path to a working Guardian: **npm install** for day-to-day use, **git clone** for development, and **`mcp-guardian start`** (or `pnpm dashboard:proxy` from the repo) to run the **proxy + web dashboard** together on port **4000**.\n\n> **npm note:** `mcp-guardian start`, `setup`, and `onboard --start` ship in **4.1.6** on GitHub. If `mcp-guardian start` is missing from help, your global install is older than 4.1.6 — use [git clone + build](#clone-and-set-up-for-development) below, or `npm install -g @mcp-guardian/server@4.1.6` once published. Full fixes: [docs/INSTALL.md](docs/INSTALL.md).\n\n### What you need\n\n| Requirement | Notes |\n|-------------|--------|\n| **Node.js 18+** | Required by `@mcp-guardian/server` |\n| **npm** | For global install or running the published CLI |\n| **pnpm** | Only if you develop from a git clone (`pnpm install`, `pnpm build`) |\n| **Git** | Only for clone-from-source workflow |\n| **Ollama** (optional) | Local LLM at `http://127.0.0.1:11434` for semantic detection, Threat Lab, and Auto Threat Research in dev |\n\n---\n\n### Install from npm (recommended for users)\n\nInstall the published server package. Pin **4.1.5+** — older 4.1.1–4.1.4 releases had broken `workspace:` metadata on npm. **4.1.6** adds `start` / `setup` (see GitHub `master` or npm once published).\n\n```bash\n# Global CLI (mcp-guardian command on your PATH)\nnpm install -g @mcp-guardian/server@latest\n\n# Or install in a project directory\nnpm install @mcp-guardian/server@latest\n```\n\nVerify the CLI and install health:\n\n```bash\nmcp-guardian --version\nmcp-guardian doctor\n```\n\n**What you get:** compiled `dist/`, default policy templates, prebuilt dashboard static files (`deploy/dashboard-spa/out/` in 4.1.6+), and the `mcp-guardian` CLI (`start`, `onboard`, `proxy`, `analyze`, `doctor`, etc.).\n\n**Recommended flow after install:**\n\n```bash\nmcp-guardian onboard --apply\nmcp-guardian start\n```\n\nOpen **http://localhost:4000**. Or combine: `mcp-guardian onboard --apply --start` (4.1.6+).\n\n**Manual proxy (advanced)** — only if you need custom env vars without `start`:\n\n```bash\nexport DASHBOARD_ENABLED=true\nexport DASHBOARD_AUTH_DISABLED=true\nexport GUARDIAN_CI_BYPASS_LICENSE=true\nexport MCP_GUARDIAN_DB_PATH=\"$HOME/.mcp-guardian/history.db\"\nmcp-guardian proxy --config guardian-configs/filesystem.json --policy policy-audit.yaml\n```\n\n---\n\n### Clone and set up for development\n\nUse this when you want the full repo: dashboard SPA, agentic modules, tests, Security Swarm, and `pnpm` scripts.\n\n```bash\ngit clone https://github.com/rudraneel93/mcp-guardian.git\ncd mcp-guardian\n\n# Install workspace dependencies (pnpm is required for the monorepo)\ncorepack enable\npnpm install\n\n# Copy optional environment overrides\ncp .env.example .env\n# Edit .env if you need NVD keys, LLM URLs, custom DB path, etc.\n\n# Compile TypeScript + workspace packages + dashboard SPA (first time)\npnpm build\npnpm setup\n# setup = pnpm install (if needed) + build + scripts/build-dashboard-spa.sh\n# Alternative: pnpm dashboard:build\n```\n\n**One-liner after clone** (install + build everything):\n\n```bash\ngit clone https://github.com/rudraneel93/mcp-guardian.git && cd mcp-guardian && pnpm install && pnpm build && pnpm setup\n```\n\n**Run from the repo without a global install:**\n\n```bash\nnode dist/cli.js start\n# or after linking: npm link && mcp-guardian start\n```\n\n---\n\n### Configure environment\n\nGuardian reads environment variables at startup. For local development, defaults in `scripts/start-dashboard-proxy.sh` are usually enough.\n\n```bash\ncp .env.example .env\n```\n\n| Variable | Purpose | Default (dev) |\n|----------|---------|----------------|\n| `MCP_GUARDIAN_DB_PATH` | SQLite audit/history DB | `~/.mcp-guardian/history.db` |\n| `DASHBOARD_ENABLED` | REST API + web UI | `true` when using `mcp-guardian start` or `dashboard:proxy` |\n| `DASHBOARD_PORT` | Dashboard URL port | `4000` |\n| `DASHBOARD_AUTH_DISABLED` | Skip login on localhost | `true` in dev script |\n| `GUARDIAN_CI_BYPASS_LICENSE` | Unlock Pro dashboard features locally | `true` in dev script |\n| `GUARDIAN_LLM_ENABLED` | Semantic / AI features | `true` in dev script |\n| `OLLAMA_BASE_URL` | Local LLM endpoint | `http://127.0.0.1:11434` |\n| `GUARDIAN_WS_ENABLED` | Live WebSocket metrics | `true` |\n\nExample — use a repo-local database so tests and dashboard share the same file:\n\n```bash\nexport MCP_GUARDIAN_DB_PATH=\"$PWD/reports/local-history.db\"\nmkdir -p \"$(dirname \"$MCP_GUARDIAN_DB_PATH\")\"\n```\n\nFull reference: [`.env.example`](.env.example).\n\n---\n\n### Start the dashboard and proxy (recommended)\n\n**Primary command (npm global or git clone, 4.1.6+):**\n\n```bash\nmcp-guardian start\n```\n\nSets local defaults (`DASHBOARD_ENABLED`, `MCP_GUARDIAN_DB_PATH=~/.mcp-guardian/history.db`, license bypass for localhost), picks a single-server `guardian-configs/*.json` (or onboard `configsDir`), and runs proxy + API + UI.\n\n**Custom config or policy:**\n\n```bash\nmcp-guardian start --config guardian-configs/filesystem.json --policy default-policy.yaml\nmcp-guardian start --build-dashboard   # git clone: build SPA if out/ missing\n```\n\n**From the repo (dev script, same stack + extra dev env):**\n\n```bash\npnpm dashboard:proxy\n# or: pnpm dashboard:proxy -- guardian-configs/filesystem.json default-policy.yaml\n```\n\n**What this does:**\n\n1. Rebuilds `dist/` if dashboard-related sources changed (dev script only)  \n2. Builds the dashboard SPA (`deploy/dashboard-spa/out/`) if missing  \n3. Picks a single-server MCP config unless you pass `--config`  \n4. Starts **one Node process** that runs:\n   - the **MCP proxy** (stdio to your upstream MCP server),\n   - the **dashboard REST API**,\n   - the **static web UI** at [http://localhost:4000/](http://localhost:4000/),\n   - optional **agentic** schedulers and WebSocket push.\n\n**Expected console output:**\n\n```\n[dashboard-proxy] DB: /Users/you/.mcp-guardian/history.db\n[dashboard-proxy] Dashboard: http://localhost:4000/\n[dashboard-proxy] Config: guardian-configs/filesystem.json  Policy: default-policy.yaml  Mode: block\n```\n\nOpen the browser → **Protection**, **Activity**, **Agentic AI**, etc. If charts are empty, widen the time window (e.g. **Last 7 days**) or generate traffic (next section).\n\n**Stop:** `Ctrl+C` in the terminal. If port 4000 is stuck: `lsof -ti :4000 | xargs kill`.\n\n---\n\n### Dashboard UI development (hot reload)\n\nWhen editing React panels under `deploy/dashboard-spa/`, run the SPA dev server separately:\n\n```bash\n# Terminal 1 — proxy + API (backend)\npnpm dashboard:proxy\n\n# Terminal 2 — Next.js dev server for the SPA (frontend hot reload)\npnpm dashboard:dev\n```\n\nFor SOC-style split API + UI: `pnpm soc:full` (API on 4040, SPA dev server — see `package.json`).\n\n---\n\n### Easiest path: onboard (wrap your AI client)\n\nAfter **npm global install** (4.1.6+), let Guardian find and wrap MCP configs for Cursor, Claude Desktop, Cline, and Windsurf:\n\n```bash\nmcp-guardian onboard --apply\nmcp-guardian start\n```\n\n`--apply` patches your live IDE MCP JSON (with backup). Restart your AI client so traffic flows through Guardian.\n\n**If you see “No MCP config found for client auto”:**\n\n- Install and configure an IDE with MCP first (Cursor, Cline, Claude Desktop, or Windsurf), **or**\n- Pass a client: `mcp-guardian onboard --client cursor --apply`, **or**\n- Pass a config file: `mcp-guardian onboard --config /path/to/mcp.json --apply`, **or**\n- Skip onboard and start with a repo example: `mcp-guardian start --config guardian-configs/filesystem.json`\n\n**Common config paths (macOS):**\n\n| Client | Config file |\n|--------|-------------|\n| Cline | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |\n| Cursor | `~/.cursor/mcp.json` |\n| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n\nFrom a **git clone** (before/after build):\n\n```bash\npnpm build\npnpm onboard -- --client auto --apply\n# or: node dist/cli.js onboard --apply\n```\n\n---\n\n### Run proxy without `start` (advanced)\n\nPrefer **`mcp-guardian start`** — it sets the same env vars automatically. Use `proxy` directly only when you need full control:\n\n```bash\nexport DASHBOARD_ENABLED=true\nexport DASHBOARD_PORT=4000\nexport MCP_GUARDIAN_DB_PATH=\"$HOME/.mcp-guardian/history.db\"\nmcp-guardian proxy --config guardian-configs/filesystem.json --policy default-policy.yaml --blocking-mode block\n```\n\n**From repo:**\n\n```bash\nnode dist/cli.js proxy --config guardian-configs/filesystem.json --policy default-policy.yaml\n```\n\nWithout `DASHBOARD_ENABLED`, you get proxy-only (no web UI). Logs still go to `MCP_GUARDIAN_DB_PATH`.\n\n---\n\n### Generate test traffic and verify\n\nWith **`mcp-guardian start`** or `pnpm dashboard:proxy` running in one terminal:\n\n```bash\n# Same DB as the proxy (important for dashboard charts)\nexport MCP_GUARDIAN_DB_PATH=\"${MCP_GUARDIAN_DB_PATH:-$HOME/.mcp-guardian/history.db}\"\n\n# Short live attack smoke test against the official filesystem MCP server\npnpm real-life:filesystem\n\n# Offline policy matrix (no live MCP server required)\npnpm harness\n\n# Plain-English summary of current posture\npnpm analyze\n\n# Industry roadmap module audit (CLI)\nnode dist/cli.js roadmap audit\n# or after global install: mcp-guardian roadmap audit\n```\n\nRefresh **http://localhost:4000/** → **Activity** / **Protection** should show new events.\n\nDetails: [scenarios/real-life/README.md](scenarios/real-life/README.md).\n\n---\n\n### Guardian Autopilot (one-command fleet setup)\n\nWraps configs, starts proxy, dashboard, and optional background jobs:\n\n```bash\npnpm autopilot:init -- --apply\npnpm autopilot:start\npnpm autopilot:status\n```\n\nSee [docs/PRO_SETUP.md](docs/PRO_SETUP.md) for production licensing (local dev uses `GUARDIAN_CI_BYPASS_LICENSE=true` with `mcp-guardian start` or `pnpm dashboard:proxy`).\n\n---\n\n### Web dashboard — what you will see\n\n| Tab / area | Purpose |\n|------------|---------|\n| **Protection** | Overall status, roadmap compliance strip (v4.1+) |\n| **Activity** | Audit log of allowed and blocked `tools/call` |\n| **Threats** | Active threats, quarantine, fleet chain graph (A1) |\n| **Security** | Score, trends, and **Policy Studio** with Active Rules controls |\n| **Operations** | Traffic, errors, cost charts |\n| **Agentic AI** | Trust, policy gen, observatory, federated learning, plan compliance audit |\n| **Settings** | Servers, policy, setup checklist |\n\nThe dashboard reads the **same SQLite DB** as the proxy (`MCP_GUARDIAN_DB_PATH`). It is not a separate demo dataset.\n\nIn **Security → Policy**, you can now manage rules without hand-editing YAML:\n\n- **Active Rules list** with search/filter\n- **Soft disable/enable** (writes `enabled: false/true` on the rule)\n- **Hard delete** (removes the rule from `policy.rules[]`)\n- Editor stays in sync with structured actions so YAML remains source-of-truth\n\nAgentic features: [docs/AGENTIC_QUICKSTART.md](docs/AGENTIC_QUICKSTART.md) · [docs/AGENTIC_FEATURES.md](docs/AGENTIC_FEATURES.md).\n\n---\n\n### Command reference\n\n| Command | What it does |\n|---------|----------------|\n| `npm install -g @mcp-guardian/server@latest` | Install published CLI |\n| `mcp-guardian start` | **Proxy + dashboard on :4000** (recommended, 4.1.6+) |\n| `mcp-guardian onboard --apply` | Auto-wrap MCP client configs |\n| `mcp-guardian onboard --apply --start` | Onboard then start (4.1.6+) |\n| `mcp-guardian setup` | Dev: `pnpm install` + build + dashboard SPA |\n| `mcp-guardian doctor` | Validate install, DB, SPA, config |\n| `mcp-guardian proxy --policy …` | Manual proxy (add `--config`) |\n| `pnpm install && pnpm build` | Dev: install + compile monorepo |\n| `pnpm setup` / `pnpm dashboard:build` | Dev: build dashboard SPA |\n| `pnpm dashboard:proxy` | Dev: proxy + API + UI (repo script) |\n| `pnpm dashboard:dev` | Dev: SPA hot reload (with proxy running) |\n| `pnpm real-life:filesystem` | Live MCP attack smoke test |\n| `pnpm harness` | Offline adversarial policy matrix |\n| `pnpm analyze` | Plain-English security summary |\n| `pnpm security-swarm` | Pro: continuous adversarial testing |\n| `pnpm autopilot:init` / `autopilot:start` | Pro: wrap + start full stack |\n| `mcp-guardian roadmap audit` | Verify industry roadmap modules (A1–C5) |\n\n---\n\n### Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| **`mcp-guardian start` not in help** | Global install is older than **4.1.6**. `git pull && pnpm build && node dist/cli.js start`, or `npm install -g @mcp-guardian/server@latest` when 4.1.6 is on npm |\n| **`unknown option --start`** | Same — upgrade to 4.1.6 or run `onboard --apply` then `start` separately |\n| **`InstallError` / `workspace:` on npm** | Use `@mcp-guardian/server@4.1.5+`, not 4.1.1–4.1.4; `npm cache clean --force` then reinstall |\n| **`ETARGET` / No matching version for `@mcp-guardian/core`** | Publish chain incomplete — maintainers run `./scripts/publish-npm-all.sh` |\n| **`next: command not found`** (dashboard build) | npm: reinstall package (prebuilt `out/` in 4.1.6). Git: `mcp-guardian setup` or `cd deploy/dashboard-spa && npm install && npm run build` |\n| **`benchmark-report.json` missing`** | `git pull` — seed file must exist under `deploy/dashboard-spa/app/data/` |\n| **`pnpm dashboard:proxy` not found** | Run from **repo root**, or use **`mcp-guardian start`** globally |\n| **No MCP config found** | `mcp-guardian onboard --apply` or `mcp-guardian start --config guardian-configs/filesystem.json` |\n| **Database disk I/O error** | Stop proxy; `rm -f ~/.mcp-guardian/history.db-wal history.db-shm history.db.pid`; `mcp-guardian start` |\n| **Empty dashboard charts** | Same `MCP_GUARDIAN_DB_PATH` as proxy; widen time window; `pnpm real-life:filesystem` |\n| **Port 4000 in use** | `lsof -ti :4000 \\| xargs kill` or `DASHBOARD_PORT=4001 mcp-guardian start` |\n| **`better-sqlite3` errors** (pnpm 10) | `pnpm approve-builds` → allow better-sqlite3 → `pnpm install` |\n| **Ollama warning on start** | Optional — `ollama serve` for semantic / Threat Lab |\n| **Pro features locked** | Production: [PRO_SETUP.md](docs/PRO_SETUP.md). Dev: use `mcp-guardian start` |\n| **BundlePhobia / Socket badge** | Server package is Node-only; use [@mcp-guardian/core](https://bundlephobia.com/package/@mcp-guardian/core) for size analysis |\n\n**Step-by-step fixes:** [docs/INSTALL.md](docs/INSTALL.md) · [SECURITY.md](SECURITY.md) · [docs/REAL_WORLD_INTEGRATION.md](docs/REAL_WORLD_INTEGRATION.md) (multi-server proxies).\n\n---\n\n## Quick start (summary)\n\n**From npm:**\n\n```bash\nnpm install -g @mcp-guardian/server@latest\nmcp-guardian onboard --apply\nmcp-guardian start    # → http://localhost:4000/\n```\n\n**From git:**\n\n```bash\ngit clone https://github.com/rudraneel93/mcp-guardian.git && cd mcp-guardian\npnpm install && pnpm build && pnpm setup\nmcp-guardian start\n```\n\nSee **[Getting started — install, clone, and run](#getting-started--install-clone-and-run)** and **[docs/INSTALL.md](docs/INSTALL.md)** for the full walkthrough and troubleshooting.\n\n---\n\n## The policy file\n\nRules live in `default-policy.yaml` (or a path you set). Example:\n\n```yaml\nversion: '1.0'\npolicy:\n  mode: block\n  default_action: block\n\n  rules:\n    - name: allow-safe-tools\n      description: Only allow read-only tools\n      action: block\n      tools:\n        allow:\n          - read_file\n          - list_directory\n          - search\n\n    - name: block-shell-commands\n      description: Never let the AI run shell commands\n      action: block\n      tools:\n        deny:\n          - bash\n          - execute_command\n          - eval\n\n    - name: rate-limit\n      description: Max 60 tool calls per minute\n      action: block\n      maxCallsPerMinute: 60\n```\n\nThe bundled default policy already blocks many common attack patterns. You can extend it or start from templates in `policy-templates/`. Full reference: [POLICY.md](docs/POLICY.md).\n\n---\n\n## Settings you might change\n\n| Variable | Plain meaning |\n|----------|----------------|\n| `MCP_GUARDIAN_POLICY` | Path to your rules file |\n| `MCP_GUARDIAN_DB_PATH` | Where call history is stored (share this between proxy and test runners) |\n| `MCP_GUARDIAN_RETENTION_DAYS` | How long to keep audit rows (default 30) |\n| `MCP_GUARDIAN_MAX_PAYLOAD_BYTES` | Max raw JSON-RPC message size (default 10MB) |\n| `GUARDIAN_MAX_EXPANDED_PAYLOAD_BYTES` | Max serialized tool-argument size after decode (default 50MB) |\n| `GUARDIAN_JWKS_REFRESH_MS` | How often to refresh OIDC JWKS (default 5 minutes) |\n| `GUARDIAN_STRICT_ALLOWLIST_RBAC` | Require RBAC on `tools.allow` policy rules |\n| `GUARDIAN_HEALTH_PROBE_INTERVAL_MS` | Periodic MCP health probes (0 = disabled) |\n| `GUARDIAN_SHUTDOWN_GRACE_MS` | Wait for in-flight calls on shutdown (default 30s) |\n| `GUARDIAN_DB_ENCRYPTION_KEY` | Encrypt sensitive audit fields at rest |\n| `GUARDIAN_DB_ENCRYPT_AUDIT_ARGS` | Also encrypt redacted argument snippets in audit (`true` + key above) |\n| `MCP_GUARDIAN_SIEM_ENABLED` | Export block/audit events to Splunk, Datadog, webhooks, etc. |\n| `DASHBOARD_PORT` | Dashboard port (default `4000`) |\n| `GUARDIAN_DAILY_BUDGET_USD` | Daily spend alert threshold |\n| `GUARDIAN_LLM_PROVIDER` / `OLLAMA_BASE_URL` | Local AI for semantic checks and Threat Lab |\n| `GUARDIAN_CI_BYPASS_LICENSE` | Local dev only: use dashboard without Pro license |\n\nMore: [ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md) for teams, Redis, and multiple servers.\n\n---\n\n## Supported AI clients\n\nGuardian can auto-discover and wrap configs for:\n\n- **Cline** (VS Code)\n- **Claude Desktop**\n- **Cursor**\n- **Windsurf**\n\nOr pass any MCP config: `mcp-guardian proxy --config path/to/config.json`.\n\n---\n\n## Documentation map\n\n| Topic | Document |\n|-------|----------|\n| **Installation & troubleshooting** | [docs/INSTALL.md](docs/INSTALL.md) |\n| Agentic AI (shipped) | [docs/AGENTIC_FEATURES.md](docs/AGENTIC_FEATURES.md) |\n| Agentic AI roadmap | [docs/AGENTIC_ROADMAP.md](docs/AGENTIC_ROADMAP.md) |\n| Agentic architecture | [docs/AGENTIC_ARCHITECTURE.md](docs/AGENTIC_ARCHITECTURE.md) |\n| MTX threat exchange | [docs/MTX_SPEC.md](docs/MTX_SPEC.md) |\n| MCP security reference | [docs/MCP_SECURITY_REFERENCE.md](docs/MCP_SECURITY_REFERENCE.md) |\n| Autopilot | [docs/AUTOPILOT.md](docs/AUTOPILOT.md) |\n| Pro license | [docs/PRO_SETUP.md](docs/PRO_SETUP.md) |\n| Policy reference | [docs/POLICY.md](docs/POLICY.md) |\n| Enterprise deploy | [docs/ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md) |\n| Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |\n| Release history | [CHANGELOG.md](CHANGELOG.md) |\n\n---\n\n## License\n\n**Community features** (proxy, policy, scanning, harness, real-life scenarios) are **MIT** — see [LICENSE](LICENSE) and [COMMUNITY_SCOPE.md](COMMUNITY_SCOPE.md).\n\n**Pro features** require a license in production: [mcp-guardian-cloud.vercel.app](https://mcp-guardian-cloud.vercel.app). See [LICENSE-PRO](LICENSE-PRO).\n",
  "bytes": 50386,
  "sha": "6f5d809afc645a020d69c5557872bbf6c1c63a40e2eeb124ca5fbf4bb706f642",
  "repo_slug": "rudraneel93/mcp-guardian",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rudraneel93_mcp_guardian_9a36b6a9/readme"
}