Skip to main content
Glama

@codapult/guard

CI Fixtures npm License: MIT Node.js >=20.19 TypeScript MCP Registry MCPSafe codapult-guard MCP server – quality and maintenance score on Glama

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 ─────────────────────────────────────→ Database

Guard 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 init

Review 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 off

verify 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 codex

Supported 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.

GitHub PR checks

Trusted PR verification

The Guard check must come from a protected workflow source, including for fork PRs.

Trusted PR setup

Merge queue

Your repository merges through a GitHub merge queue.

Merge queue setup

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

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 tools
codapult_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

    A4/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Architectural 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 impact
      3
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Real-time architecture governance tool that enforces Clean Architecture, DDD, SOLID, TDD, and Security rules across 8 languages using 11 specialized agents.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Guardrails for AI coding agents that enforces rules via compliance receipts, blocking destructive actions and syncing rules across all AI tools.
      24
      145 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enforces AST-based architectural guardrails on AI-generated code, blocking writes that violate maintainability, security, or complexity rules and prompting immediate refactoring.
      2
      MIT