DriftGuard
kioie/driftguard
Detecte drift de schema JSON em APIs e MCPs antes das integrações quebrarem
Ver no GitHubMCP server que detecta mudanças em schemas JSON de APIs e integrações antes que quebrem sua aplicação. Oferece comparação local offline de schemas, integração com agentes Claude/Cursor e monitoramento contínuo opcional via serviço gerenciado.
Instalação
npx convez-ai kioie/driftguard1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Comparar schemas JSON antes e depois em CI/CD
- Monitorar mudanças em APIs externas continuamente
- Validar compatibilidade de integração de agentes IA
- Alertar sobre breaking changes em dependências
Veredito

Ferramenta focada e bem pensada para detectar schema drift em integrações críticas. O modelo open-core (cliente OSS + serviço gerenciado) é honesto e permite começar sem custo. Essencial para times que gerenciam múltiplas APIs e agentes IA em produção.
README
A tradução para o português deste README ainda está na fila.
DriftGuard
Catch schema drift before your integrations break.
Open-source local JSON schema diff + MCP client for developers and AI agents. Continuous API/MCP monitoring, alerts, and history run on hosted DriftGuard Pro/Team.
Not full self-host: this repo is the client layer (diff + MCP connector). The monitoring pipeline is a managed service — see OPEN_CORE.md.
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 · GitLab — docs/GITLAB_CI.md · GitHub Marketplace path — docs/GITHUB_MARKETPLACE.md
Quick start
git clone https://github.com/kioie/driftguard
cd driftguard && npm ci && npm run build
CLI
npm run check -- diff '{"id":1,"email":"a@b.com"}' '{"id":1}'
# exit 1 if breaking changes
MCP server (Cursor, Claude, Windsurf)
See docs/QUICKSTART.md and examples/mcp-client-config.json.
{
"mcpServers": {
"driftguard": {
"command": "node",
"args": ["/absolute/path/to/driftguard/dist/mcp/server.js"]
}
}
}
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 SYSTEM_PROMPT.md for when-to-use guidance.
CI integration
Pin the client version and follow the hook → preview → trial → gate funnel:
# 1. Hook (free)
- uses: kioie/driftguard/.github/actions/drift-diff@v0.3.2
with:
before: '{"id":1}'
after: '{"id":1,"name":"x"}'
# 2. Preview (free — links to console, non-blocking)
- uses: kioie/driftguard/.github/actions/drift-coverage-preview@v0.3.2
with:
files-json: '[{"path":"mcp.json","content":"..."}]'
# 3. Gate (Pro API key — blocks until all deps watched)
- uses: kioie/driftguard/.github/actions/drift-coverage@v0.3.2
with:
api-key: ${{ secrets.DRIFTGUARD_API_KEY }}
files-json: '...'
Full model: docs/CI.md
- Try offline —
compare_json,parse_mcp_configin Cursor (no signup) - Start trial — driftguard.org/start (full Pro on one endpoint)
- Add API key — set
DRIFTGUARD_API_KEYin MCP env → monitoring tools unlock - Team — pricing for more watches, audit export, SSO
Optional: override hosted URL with DRIFTGUARD_API (default: https://driftguard.org). Non-default values also 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/ # Quick start, discovery
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 |
|---|---|
| SYSTEM_PROMPT.md | Tool matrix, decision flow, config |
| docs/CI.md | Version-pinned CI paths (Actions, npx, assert) |
| AGENTS.md | Editing this repo |
| docs/QUICKSTART.md | Setup steps |
Call MCP tool hosted_info at runtime for current URLs and capability matrix.
Design
Brand kit: docs/DESIGN.md
Contributing
CONTRIBUTING.md — public client only.
License
MIT — LICENSE. Applies to this repository only; hosted service is separate.