Skip to main content
Glama

ArchGuard MCP — Architecture Drift, Zero-Downtime SQL & Distributed Systems Verifier

Official MCP Registry (active): io.github.yashwant938/arch-guard-mc@1.0.0
Live Remote MCP Endpoint (Streamable HTTP · Zero Auth): https://arch-guard-mcp.yashwant938.workers.dev/mcp
Live Interactive Explorer: https://arch-guard-mcp.yashwant938.workers.dev

ArchGuard is a zero-dependency Model Context Protocol (MCP 2025-03-26) server, Agent Skills suite, and installable Plugin built from scratch to eliminate the three biggest blind spots of AI coding agents:

  1. Silent Architectural & Production Reliability Drift — Coding agents introduce circular imports, N+1 DB loops, outbound HTTP calls without timeouts, unbounded in-memory Map caches, check-then-act race conditions, and missing idempotency keys.

  2. Table-Locking SQL Migrations — Agents write CREATE INDEX (blocking writes), DROP/RENAME COLUMN (breaking rolling pods), ADD COLUMN NOT NULL without defaults, and ALTER COLUMN TYPE rewrites instead of safe 3-phase Expand-Contract migrations.

  3. Hallucinated Distributed-Systems Math — LLMs routinely get bytes-to-TB, bits-to-Gbps, shard bottlenecks, Dynamo/Raft quorums, consistent hashing skew, and Jeff Dean fanout tail-latency amplification (1 - (1 - p)^K) wrong.

ArchGuard replaces guesswork with deterministic static analysis, graph algorithms (Tarjan's SCC), mathematical proofs, and live edge simulations.


Quick Connect (Works in Antigravity, Claude Code, Cursor, Windsurf, Codex)

Option A — Hosted Remote MCP (Instant, Zero Install)

Add to your mcp_config.json / .cursor/mcp.json / Claude MCP config:

{
  "mcpServers": {
    "arch-guard": {
      "url": "https://arch-guard-mcp.yashwant938.workers.dev/mcp"
    }
  }
}

Option B — Local Stdio MCP (Unlocks Full Local Repository Scanning)

{
  "mcpServers": {
    "arch-guard-local": {
      "command": "node",
      "args": ["/absolute/path/to/arch-guard-mc/bin/arch-guard-mcp.mjs"]
    }
  }
}

Option C — Standalone CLI / CI Gate

# Audit any codebase locally (exits 1 if CRITICAL findings exist)
node bin/cli.mjs audit .

# Guard a SQL migration before deploy
node bin/cli.mjs migrate migrations/004_orders.sql postgres

# Print deterministic capacity math for Big Tech presets
node bin/cli.mjs capacity uber

Related MCP server: boilerforge

MCP Primitives Implemented (Tools + Resources + Prompts)

7 Deterministic MCP Tools

Tool

Transport

What It Computes

audit_codebase_architecture

Local stdio

Walks a repo on disk → builds multi-language import graph → runs Tarjan's $O(V+E)$ SCC for circular deps → computes Robert C. Martin $C_a / C_e / I$ coupling → runs 12 reliability/security/SOLID rules → outputs 0–100 health score + Mermaid dependency graph

audit_code_snippet

Remote & Local

Runs the exact same Tarjan SCC + 12-rule architecture auditor on any set of files passed over Remote HTTP

check_migration_safety

Remote & Local

Audits PostgreSQL / MySQL / SQLite DDL for lock levels (ACCESS EXCLUSIVE, SHARE) and rolling-deploy breaks (MIG-001–MIG-008), generating an actionable 3-phase Expand-Contract plan

estimate_system_capacity

Remote & Local

Exact Write/Read QPS, peak QPS, cache-adjusted DB QPS, N-year raw & replicated storage, ingress/egress Gbps, Redis RAM, dominant shard bottleneck, and Little's Law concurrency (tinyurl, twitter, whatsapp, uber, youtube, stripe, or custom)

simulate_quorum_and_tail_latency

Remote & Local

Proves Dynamo W + R > N, split-brain write safety W > N/2, Raft odd-cluster fault tolerance, and Jeff Dean tail-latency amplification $1 - (1 - p)^K$ with hedged-request comparison

simulate_consistent_hashing

Remote & Local

Real FNV-1a 32-bit hash ring simulation measuring exact load skew (min/max/std-dev) and key remap % on scale-out vs naive modulo hashing

recommend_architecture

Remote & Local

Maps workload traits (consistency, R/W ratio, contention, real-time need, latency SLO) to a Staff-level stack + matching Big Tech In-The-Wild case studies (Shopify, Slack, Figma, Meta, Stripe)

4 MCP Resources (resources/list, resources/read)

  • arch-guard://cheatsheet/latency-numbers — Jeff Dean latency ladder & powers of 2

  • arch-guard://cheatsheet/core-patterns — 6 Core System Design Patterns Matrix

  • arch-guard://cheatsheet/expand-contract — Zero-Downtime SQL Migration Playbook

  • arch-guard://cheatsheet/interview-rubrics — Microsoft (L60–L65), Google, Amazon & Meta hiring rubrics

3 MCP Prompts (prompts/list, prompts/get)

  • staff-architecture-review — End-to-end codebase reliability & structural review workflow

  • zero-downtime-migration-plan — DDL safety check + 3-phase Expand-Contract rewrite

  • system-design-interview-sim — Calibrated 45-minute Staff HLD/LLD mock interview


Bundled Agent Skills & Plugin

This repository is also a ready-to-install Agent Plugin (plugin.json + mcp_config.json + rules/AGENTS.md) containing 3 progressive-disclosure skills:


Architecture Overview

arch-guard-mcp/
├── bin/
│   ├── arch-guard-mcp.mjs      # Local stdio MCP server (Node >= 20, zero deps)
│   └── cli.mjs                 # Standalone CI/developer CLI
├── src/
│   ├── engines/
│   │   ├── codebaseAuditor.mjs # Multi-lang import graph, Tarjan SCC, Ca/Ce/I, 12 smell rules
│   │   ├── fsScanner.mjs       # Local repository walker
│   │   ├── migrationGuardian.mjs # PostgreSQL/MySQL/SQLite Expand-Contract DDL guardian
│   │   ├── capacityMath.mjs    # Exact QPS, storage, bandwidth, shards & Little's Law
│   │   ├── distributedSim.mjs  # Dynamo/Raft quorum, tail latency, FNV-1a consistent hashing
│   │   └── architectureAdvisor.mjs # Staff-level blueprint advisor & cheatsheet resources
│   └── mcp/
│       └── protocol.mjs        # Transport-agnostic MCP 2025-03-26 JSON-RPC 2.0 dispatcher
├── worker/
│   └── index.mjs               # Cloudflare Workers Remote Streamable HTTP MCP (/mcp, /health, /)
├── skills/                     # 3 cross-agent progressive-disclosure SKILL.md workflows
├── rules/AGENTS.md             # Always-on plugin safety rules
├── tests/                      # Engine unit tests + stdio & HTTP end-to-end MCP tests
├── plugin.json                 # Antigravity / agent plugin manifest
└── wrangler.jsonc              # Cloudflare Workers deployment config

Development & Verification

# Run full unit + stdio MCP + Streamable HTTP Worker tests
npm test

# Self-audit ArchGuard's own source code
npm run audit:self

# Build zero-dependency Cloudflare Worker bundle (dist/worker.mjs)
npm run build:worker

# Package Agensi-ready SKILL.md ZIP (dist/arch-guard-backend-verifier.zip)
npm run package:agensi

Registry & Marketplace Metadata Included

Related project: System Design Complete Guide (Interactive HLD & LLD Atlas)

Available Tools

7 tools
audit_codebase_architectureAInspect

Scan a local repository directory on disk to detect circular module dependencies (Tarjan SCC), coupling/instability hotspots (Ca/Ce/I), layer boundary violations, and 12 production reliability/security/SOLID anti-patterns (N+1 queries in loops, missing HTTP timeouts, unbounded caches, check-then-act races, SQL/command injection, God modules). Outputs a 0-100 health score and Mermaid dependency graph.

Inputs: directoryPath (required), maxFiles, maxFileLines.

audit_code_snippetAInspect

Analyze one or more source files for circular module dependencies (Tarjan SCC), coupling/instability metrics (Ca/Ce/I), and 12 production reliability/security/SOLID anti-patterns (N+1 loops, missing HTTP timeouts, unbounded caches, check-then-act races, missing idempotency keys, SQL/command injection, God classes). Returns a 0-100 health score, prioritized findings, and Mermaid dependency graph.

Inputs: files (required), maxFileLines.

check_migration_safetyBInspect

Audit a SQL migration (PostgreSQL, MySQL, or SQLite) for production table locks, rolling-deployment breaking changes (DROP/RENAME COLUMN, blocking CREATE INDEX, ADD COLUMN NOT NULL without DEFAULT, ALTER COLUMN TYPE rewrite, unvalidated constraints, missing lock_timeout), and auto-generate a safe 3-phase Expand-Contract deployment plan.

Inputs: sql (required), dialect.

estimate_system_capacityAInspect

Compute exact back-of-the-envelope distributed systems capacity math: avg & peak Write/Read QPS, cache-adjusted DB QPS, N-year raw & replicated storage, peak ingress/egress Gbps, Redis RAM sizing, primary shard count + dominant bottleneck, and Little’s Law peak concurrency. Supports Big Tech presets (tinyurl, twitter, whatsapp, uber, youtube, stripe) or custom numbers.

Inputs: dau, preset, avgLatencyMs, avgReadBytes, +8 more.

recommend_architectureBInspect

Generate a Staff-level distributed system architecture blueprint (primary database, caching & stampede control, contention strategy, messaging/CDC, real-time transport, reliability guardrails, and matching Big Tech In-The-Wild case studies) from concrete workload traits.

Inputs: dataModel, scaleTier, consistency, latencySloMs, +3 more.

simulate_consistent_hashingAInspect

Run a deterministic FNV-1a 32-bit consistent hashing ring simulation to measure exact shard load skew (min/max/std-dev) and key remapping percentage when scaling out by 1 node compared against naive modulo hashing.

Inputs: nodeCount, sampleKeys, virtualNodes.

simulate_quorum_and_tail_latencyAInspect

Verify Dynamo quorum consistency (W + R > N, split-brain write safety W > N/2), Raft consensus fault tolerance, and Jeff Dean tail-latency amplification (1 - (1 - p)^K) across parallel microservice fanout calls with hedged-request comparison.

Inputs: readQuorum, fanoutCount, writeQuorum, singleNodeP50Ms, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation3/5

    audit_code_snippet and audit_codebase_architecture are nearly identical in function: both detect Tarjan SCC cycles, Ca/Ce/I coupling, the same 12 anti-patterns, and emit a 0-100 health score plus a Mermaid graph. The only differentiator is 'files vs repo directory', which is easy to misselect. The remaining tools (quorum/latency sim, hashing sim, migration audit, capacity math, architecture recommendation) are reasonably distinct, though simulate_quorum_and_tail_latency vs estimate_system_capacity both touch performance math.

    Naming Consistency5/5

    Every tool follows a consistent snake_case verb_noun pattern (simulate_*, audit_*, check_*, estimate_*, recommend_*). Verbs are semantically meaningful and predictable, and no camelCase or stylistic mixing appears.

    Tool Count5/5

    Seven tools is well within the ideal 3-15 range and each maps to a coherent phase of architecture review (analyze, simulate, audit, recommend). No filler or trivially redundant entries beyond the audit pair.

    Completeness4/5

    The surface covers architecture recommendation, capacity math, consistency/hashing simulation, code quality audit, and migration safety, which is strong lifecycle coverage for an advisory server. Minor gaps exist: no cost/cloud-spend estimation, no API/schema design analysis, and no runtime observability or SLO review, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers