codapult-guard
OfficialCodapult Guard is a local-first MCP server for architecture guardrails in JavaScript/TypeScript projects, helping discover, approve, verify, audit, and review project-specific boundaries and policies.
Initialize or refresh the project model and persist discovered architecture facts.
Recommend the next bounded workflow action and return structured project context.
Generate evidence-backed architecture rule and contract proposals, then record approval or rejection.
Run fast changed-file checks, full repository audits, and configured completion gates including lint/typecheck/test/build plus Guard policy checks.
Prepare bounded AI-review packets with diffs, context, contracts, and findings.
Trace likely impact of changed files through the dependency graph.
Explain active Guard rules or contracts by ID.
List and manage owner-attributed, time-limited waivers for exact finding fingerprints.
Audit governance provenance, policy bindings, and verification evidence reachability.
Provides GitHub Actions workflow presets and setup guidance for Guard checks, including standard PR checks, trusted PR verification, and merge-queue workflows.
@codapult/guard
Architecture guardrails for AI-assisted development
Codapult Guard helps teams preserve the architecture that makes their project work as it changes. It maps a JavaScript or TypeScript codebase, lets the team approve project-specific boundaries, and checks future changes locally and in CI. AI agents can use the same project context and verification results as developers.
Catch project-specific regressions
A type checker can confirm that code is valid TypeScript. It cannot know that this project requires client components to stay away from persistence modules. Once the team approves that boundary, Guard can detect a violating import in changed files and show which rule was triggered.
Project boundary: Client → Server Action → Service → Repository → Database
Possible regression: Client ─────────────────────────────────────→ DatabaseGuard discovers the architecture in the repository; it does not prescribe one universal structure or activate proposed rules without approval.
Related MCP server: Guardian MCP Toolkit
Get started
Requirements: Node.js >=20.19 and a JavaScript or TypeScript project.
# pnpm
pnpm add -D @codapult/guard
pnpm exec codapult-guard init
# npm
npm install --save-dev @codapult/guard
npx codapult-guard initReview the generated project model, proposed rules, contracts, and baseline under
.codapult/guard/ before relying on the results. Then run Guard's architecture checks:
pnpm exec codapult-guard verify --no-project-checks --tools offverify can run your configured project checks and detected adapters. The flags above limit this
run to Guard's built-in checks. With npm, run npx codapult-guard verify --no-project-checks --tools off.
See the complete guide for initialization and daily workflows.
Use Guard with an AI agent
Install a managed instruction block for your agent so it knows when to load Guard context and run verification:
pnpm exec codapult-guard install-agent codexSupported hosts and MCP setup are in the AI-agent integration guide and host integration guides.
The MCP server uses host-managed local stdio, with no network listener or application-level authentication. The host and operating system control process access and workspace permissions; see the security model.
Choose a GitHub setup
Choose a preset from the existing workflow templates and follow only the hosting steps for that level of protection. Most projects can start with standard PR checks.
Preset | Use it when | Guide |
PR checks | You want Guard findings and a required check on ordinary pull requests. | |
Trusted PR verification | The Guard check must come from a protected workflow source, including for fork PRs. | |
Merge queue | Your repository merges through a GitHub merge queue. |
If you are unsure, use PR checks first. It is useful CI feedback, but its workflow lives in the project being checked and can be changed by a pull request. Choose trusted verification when the check itself must be protected from that change.
What Guard does
Learns project-specific structure, dependencies, boundaries, and existing findings.
Checks approved architecture rules and contracts without imposing a universal architecture.
Shows change impact and prepares bounded, redacted context for AI review.
Runs configured project checks and adapters when enabled; it does not replace them.
Produces deterministic CLI, JSON, and SARIF results for local use and CI.
Guard is local-first and does not call an LLM. The AI host owns model access, edits, and its repair loop. Guard complements TypeScript, ESLint or Biome, tests, SAST, and dependency scanners; it does not replace them.
Documentation
GitHub setup presets — choose and configure the CI level you need.
Complete Guard guide — commands, policy, results, security, and advanced workflows.
AI-agent integration — managed instructions and MCP workflow.
Host integrations — Codex, Cursor, Claude Code, Copilot, Gemini CLI, and generic MCP clients.
Policy mutation controls — approval and protected policy behavior.
Extensions — adapters, output formats, and integration boundaries.
For contributors
Maintainer checks and project fixture coverage are documented in the fixture guide and release guide.
More from Codapult
Starting a SaaS from scratch? Codapult is a production-ready Next.js SaaS foundation built for AI-assisted development, with modular architecture, built-in AI, MCP context, and source code under your control.
License
MIT. See LICENSE.
Available Tools
14 toolscodapult_guard_analyzeRefresh Guard ModelA
Rediscover the repository and persist its current project facts and snapshots. Use after repository changes when codapult_guard_next_action returns needs-refresh or needs-setup; this does not change Guard rules, contracts, or baseline. Returns the new revision and discovery metrics.
Inputs: root, confirm, no_wait, wait_ms.
codapult_guard_auditGuard AuditA
Scan the entire current repository against active Guard rules, including findings normally hidden by the baseline, and validate policy contracts. Use for a full health review; unlike codapult_guard_check, this is not limited to changed files. Returns findings, contract issues, counts, and overall status.
Inputs: root.
codapult_guard_checkGuard CheckA
Run active architecture rules and contract validation, returning structured findings and status. Use for a fast deterministic policy check: changed_only=true focuses on changed files and respects the baseline; false scans the full project. Omitted uses the scanner default. For a full audit that ignores baseline suppression, use codapult_guard_audit.
Inputs: root, changed_only.
codapult_guard_contextGuard ContextA
Read the project model, architecture insights, conventions, active policy, proposals, baseline, waivers, and completion-gate settings in one structured response. Works before Guard initialization. Use refresh=true (default) for current repository state; refresh=false prefers persisted snapshots and is useful when inspecting the last saved model.
Inputs: root, refresh.
codapult_guard_explainExplain Guard PolicyA
Look up one active Guard rule or contract by ID and return its definition, evidence, guidance, and suggested next steps. Use when a check reports a rule ID or when deciding how to comply. For a finding-specific explanation, inspect the finding from codapult_guard_check or codapult_guard_audit as well.
Inputs: id (required), root.
codapult_guard_governanceGuard Governance AuditB
Inspect proposal and approval provenance metadata, policy bindings, and whether retained verification evidence is reachable from decisions. Use for a governance trail audit; output describes declared metadata and does not authenticate identities or verify signatures.
Inputs: root.
codapult_guard_impactGuard Impact AnalysisA
Trace the likely project impact of one or more file paths through the discovered dependency graph, including dependents, routes, capabilities, contracts, and graph paths. Use before changing a file to understand downstream areas to inspect. This is repository analysis, not a policy pass/fail check; returns structured impact details.
Inputs: files (required), root.
codapult_guard_initInitialize GuardA
Create the initial Guard policy, project model, and supporting artifacts for a repository that has not been initialized. Existing Guard state is preserved by default. Use force only to replace existing state after reviewing the consequences; the result reports initialization findings.
Inputs: root, force, confirm, no_wait, +1 more.
codapult_guard_next_actionGuard Next ActionA
Choose the next bounded step in the Guard workflow without writing project files. Call at task start or after a step: it checks setup, stale project facts/proposals, changed-file findings, and policy contracts, then returns an action such as init, analyze, policy review, repair, or verify with the reason.
Inputs: root.
codapult_guard_proposal_decideDecide Guard ProposalsA
Record an explicit approval or rejection for the selected current proposals. Approval activates the selected rules/contracts in Guard policy; rejection records the decision without activation. Stale proposals cannot be decided, and protected approval policy may require a non-MCP reviewer. Returns the decision and affected IDs.
Inputs: ids (required), decision (required), root, confirm.
codapult_guard_proposeGuard ProposalsA
Generate evidence-backed candidate architecture rules and contracts from the current project model. Use to review possible policy after setup or structural changes; proposals are never activated automatically. The result includes evidence, questions, freshness, and persistence status. Persisted proposals still require an explicit decision with codapult_guard_proposal_decide.
Inputs: root, confirm, persist.
codapult_guard_reviewPrepare Guard ReviewA
Build a bounded packet for an AI semantic reviewer containing the diff, project context, active contracts, and deterministic Guard findings. Use after coding and before verification. The result needs human/agent review; it is not itself an approval or verification. Set base for PR comparisons and requirement to focus the review.
Inputs: base, root, requirement, changed_only, +1 more.
codapult_guard_verifyGuard VerifyA
Run the configured completion gate: selected project checks plus Guard architecture and policy checks, returning structured results. Use after implementation and semantic review; this executes project commands but does not edit source. Defaults come from agent.json where omitted. Pass requirement to bind verification to the task and increment iteration on each retry.
Inputs: root, tools, checks, strict, +7 more.
codapult_guard_waiversGuard WaiversA
List or manage owner-attributed, time-limited exceptions tied to exact active finding fingerprints. Use list to inspect current waivers; add requires fingerprint, owner, expiry, and reason; renew/remove require waiver id and reason. Every mutation requires confirm=true and may be restricted by protected approval policy. Adding a waiver does not change the underlying rule.
Inputs: id, root, issue, owner, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
The tools cover distinct workflow stages, and descriptions explicitly contrast check vs audit vs verify vs review. Some overlap remains among policy-checking and orchestration tools such as next_action, check, audit, verify, and review, but boundaries are mostly clear.
All names share the codapult_guard_ prefix and snake_case formatting, which is highly consistent. However, suffixes mix verbs and nouns such as analyze, context, proposal_decide, and waivers, so it is not a pure verb_noun pattern.
Fourteen tools is within the well-scoped range for a multi-stage governance workflow. Each tool maps to a distinct lifecycle operation, and the set does not feel bloated for the apparent domain.
The surface covers initialization, discovery, context inspection, proposal and decision handling, checks, audit, semantic review, verification, waivers, governance, impact analysis, explanation, and next-action orchestration. No obvious lifecycle gap is apparent; even replacement is handled through init with force.
Maintenance
Related MCP Connectors
Guardrails for LLM output: pass / fail / review verdicts and one recommended action. Hosted or npm.
Enforces architectural invariants and code quality rules inside your AI agent's edit loop.
AgentGuard — 20-tool AI safety MCP: policy preflight, risk scoring, audit logging, rate limits.
Governed behavior for AI applications and coding agents: define, evaluate, release and inspect.
Related MCP Servers
- AlicenseCqualityDmaintenanceArchitectural Gatekeeper for AI coding. Prevents "tunnel vision" bugs by forcing the AI to verify dependencies (via AST parsing) before editing files. Supports JavaScript & TypeScript. Blocks unsafe edits until the AI proves it understands the impact3Apache 2.0
- FlicenseNot gradedqualityCmaintenanceReal-time architecture governance tool that enforces Clean Architecture, DDD, SOLID, TDD, and Security rules across 8 languages using 11 specialized agents.-
- AlicenseAqualityCmaintenanceGuardrails for AI coding agents that enforces rules via compliance receipts, blocking destructive actions and syncing rules across all AI tools.24145 npm1MIT
- AlicenseAqualityDmaintenanceEnforces AST-based architectural guardrails on AI-generated code, blocking writes that violate maintainability, security, or complexity rules and prompting immediate refactoring.2MIT