Driftguard

DriftGuard

[](https://github.com/Drift-Guard/driftguard/actions/workflows/ci.yml)

Catch API and schema changes before your integrations break.

> Start hosted trial (no credit card): driftguard.org/start — full Pro on one endpoint, ~2 minutes. > 10-min MCP drift lab: Dev.to tutorial · ToolSchema Kit

DriftGuard compares JSON contracts locally (free CLI and MCP client) and runs scheduled checks with alerts when you need always-on API contract monitoring and contract observability on hosted Pro/Team.

Use schema drift CI (compare_json, GitHub Actions) before merge; use hosted watches when you need MCP tool catalog drift detection in production.

> Not full self-host: this repo is the client layer (diff + MCP connector). The monitoring pipeline is a managed service — see [OPENCORE.md](OPENCORE.md).

Not to be confused with

Many projects share the name DriftGuard. This repo (Drift-Guard/driftguard) is API and MCP schema drift monitoring — canonical product: driftguard.org.

• npm driftguard — UI linter (sjamcox), not schema drift.
• npm driftguard-mcp — conversation-drift MCP (jschoemaker), not contract monitoring.
• getdriftguard — API schema CLI under npm user driftguard; different vendor and scope.
• GitHub orgs / ML libs — assorted driftguard repos (GitOps, Python ML, etc.); verify Drift-Guard/driftguard or driftguard.org before integrating.

See [docs/DISCOVERY.md](docs/DISCOVERY.md) and [docs/npm-org-chase.md](docs/npm-org-chase.md) for the @drift-guard scoped npm publish path.

---

Why this repo?

| | This repo (OSS client) | Hosted DriftGuard | |---|---|---| | Goal | Test locally, integrate with agents | Production monitoring | | Diff JSON schemas | ✅ CLI + MCP | ✅ + history | | Parse mcp.json preview | ✅ offline | ✅ + auto-import | | Continuous checks | ❌ | ✅ cron + queues | | MCP tools/list polling | ❌ | ✅ | | Alerts & console | ❌ | ✅ |

Use the OSS client to try and integrate. Upgrade when you need always-on monitoring.

CI: one-file starter — [examples/workflows/driftguard-starter.yml](examples/workflows/driftguard-starter.yml) · GitLab — [docs/GITLABCI.md](docs/GITLABCI.md) · GitHub Marketplace path — [docs/GITHUBMARKETPLACE.md](docs/GITHUBMARKETPLACE.md)

---

Quick start

npx @drift-guard/driftguard@latest version
npx @drift-guard/driftguard@latest diff '{"id":1,"email":"a@b.com"}' '{"id":1}'
# exit 1 if breaking changes

Until @drift-guard is on npm, clone and build — see [docs/QUICKSTART.md](docs/QUICKSTART.md#1-install).

CLI

Same commands as above; from a local clone use npm run check -- diff … after npm run build.

MCP server (Cursor, Claude, Windsurf)

See [docs/QUICKSTART.md](docs/QUICKSTART.md), [examples/mcp-client-config.json](examples/mcp-client-config.json), and [examples/AGENTS-snippet.md](examples/AGENTS-snippet.md) for consumer repos.

From a local clone (after npm run build):

{
  "mcpServers": {
    "driftguard": {
      "command": "node",
      "args": ["/absolute/path/to/driftguard/dist/mcp/server.js"]
    }
  }
}

Or via npx (no clone — copy from [examples/mcp-client-config.json](examples/mcp-client-config.json)):

{
  "mcpServers": {
    "driftguard": {
      "command": "npx",
      "args": ["-y", "@drift-guard/driftguard@0.3.3", "mcp"]
    }
  }
}

Add "DRIFTGUARD_API_KEY": "dg_…" under env for monitoring tools.

---

MCP tools

| Tool | API key | Purpose | |------|---------|---------| | compare_json | No | Local before/after JSON schema diff | | parse_mcp_config | No | Preview watch URLs from mcp.json (no create) | | hosted_info | No | Offline vs hosted matrix, trial/pricing links | | explain_drift | No | Remediation hints for breaking changes | | register_watch | Pro | Continuous monitoring | | check_watch | Pro | Immediate check | | list_watches | Pro | List watches | | list_drift_events | Pro | Drift history | | suggest_watches | Pro | Import mcp.json + optional create | | assert_coverage | Pro | CI gate — deps must be watched |

Agents: read [SYSTEMPROMPT.md](SYSTEMPROMPT.md) for when-to-use guidance.

---

CI integration

Pin the client version and follow the hook → preview → trial → gate funnel:

# 1. Hook (free)
- uses: Drift-Guard/driftguard/.github/actions/drift-diff@v0.3.3
  with:
    before: '{"id":1}'
    after: '{"id":1,"name":"x"}'

# 2. Preview (free — links to console, non-blocking)
- uses: Drift-Guard/driftguard/.github/actions/drift-coverage-preview@v0.3.3
  with:
    files-json: '[{"path":"mcp.json","content":"..."}]'

# 3. Gate (Pro API key — blocks until all deps watched)
- uses: Drift-Guard/driftguard/.github/actions/drift-coverage@v0.3.3
  with:
    api-key: ${{ secrets.DRIFTGUARD_API_KEY }}
    files-json: '...'

Full model: [docs/CI.md](docs/CI.md)

---

1. Try offline — compare_json, parse_mcp_config in Cursor (no signup)
2. Start trial — driftguard.org/start (full Pro on one endpoint)
3. Add API key — set DRIFTGUARD_API_KEY in MCP env → monitoring tools unlock
4. Team — pricing for more watches, audit export, SSO

Advanced (rare): override hosted URL with DRIFTGUARD_API (default https://driftguard.org). Non-default values require DRIFTGUARD_ALLOW_CUSTOM_API=1 — otherwise the client pins to the official host so a malicious MCP config cannot exfiltrate your API key.

---

Project structure

src/core/          # Schema inference + diff (MIT)
src/cli/           # driftguard diff | mcp
src/mcp/           # MCP server (local + hosted proxy)
examples/          # MCP client config template
docs/              # Documentation hub, quick start, reference
AGENTS.md          # Agent contribution guide
SYSTEM_PROMPT.md   # Agent tool reference
server.json        # MCP Registry metadata
OPEN_CORE.md       # Public vs hosted boundary

---

For AI agents

| Doc | Use | |-----|-----| | [docs/README.md](docs/README.md) | Documentation hub — pillars, OSS vs hosted, nav | | [SYSTEMPROMPT.md](SYSTEMPROMPT.md) | Tool matrix, decision flow, config | | [docs/getting-started.md](docs/getting-started.md) | Progressive onboarding funnel | | [docs/reference/](docs/reference/README.md) | MCP + CLI reference index | | [docs/CI.md](docs/CI.md) | Version-pinned CI paths (Actions, npx, assert) | | [AGENTS.md](AGENTS.md) | Editing this repo | | [docs/QUICKSTART.md](docs/QUICKSTART.md) | Setup steps |

Call MCP tool hosted_info at runtime for current URLs and capability matrix.

---

Design

Brand kit: [docs/DESIGN.md](docs/DESIGN.md)

Contributing

[CONTRIBUTING.md](CONTRIBUTING.md) — public client only.

License

MIT — [LICENSE](LICENSE). Applies to this repository only; hosted service is separate.

Source & license

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

• Author: Drift-Guard
• Source: Drift-Guard/driftguard
• License: MIT

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