convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
kioie

DriftGuard

kioie/driftguard

Detecte drift de schema JSON em APIs e MCPs antes das integrações quebrarem

Ver no GitHub
BomPluginScore · de 0 a 100

MCP 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/driftguard

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
v0.3.4
Issues abertas
9
Contribuidores
3

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

CI

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
GoalTest locally, integrate with agentsProduction 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

ToolAPI keyPurpose
compare_jsonNoLocal before/after JSON schema diff
parse_mcp_configNoPreview watch URLs from mcp.json (no create)
hosted_infoNoOffline vs hosted matrix, trial/pricing links
explain_driftNoRemediation hints for breaking changes
register_watchProContinuous monitoring
check_watchProImmediate check
list_watchesProList watches
list_drift_eventsProDrift history
suggest_watchesProImport mcp.json + optional create
assert_coverageProCI 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


  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

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

DocUse
SYSTEM_PROMPT.mdTool matrix, decision flow, config
docs/CI.mdVersion-pinned CI paths (Actions, npx, assert)
AGENTS.mdEditing this repo
docs/QUICKSTART.mdSetup 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.

Ver o original no GitHub

Bom para

Relacionados