Enforces architectural boundaries and provides project context for AI coding agents in JavaScript and TypeScript codebases.
Also known as codapult/codapult-guard, codapult-guard, @codapult/guard
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- 3,407
- Latest version
- 0.14.1
- Last commit
- Nov 10, 2026
- License
- MIT
What is Guard MCP?
Guard enforces architectural boundaries and provides project context for AI coding agents in JavaScript and TypeScript codebases.
Summary generated from the project's README
About Guard MCP server
Maintaining architectural integrity in JavaScript and TypeScript codebases is what guard enables for development teams. It maps your specific project structure to identify dependencies and boundaries, allowing you to approve custom rules that prevent illegal imports or structural regressions. Unlike standard type checkers, it understands project-specific requirements, such as keeping client components separate from persistence modules.
Developers use this tool locally or within CI environments like GitHub using presets for pull requests or merge queues. The MCP server operates via host-managed local stdio, meaning it requires no network listener or application-level authentication. It works alongside existing tools like ESLint, Biome, or TypeScript rather than replacing them. To integrate with an AI agent, you can use the install-agent command to provide the necessary context for verification.
By providing deterministic CLI, JSON, and SARIF results, it ensures that AI coding agents receive the same architectural context and verification findings as human developers. This helps prevent agents from introducing changes that violate your established project contracts.
What you can do with it
- 1Prevent architectural regressionsAsk the AI to check if a new import violates the established project boundaries.
- 2Provide architectural context to agentsGive an AI agent the project structure and approved rules so it follows your specific design patterns.
- 3Automate pull request reviewsSet up automated checks to ensure every pull request adheres to your architectural contracts.
- 4Analyze change impactUse the tool to understand how a code change affects the existing project structure.
Written from the project's README. Every use case is checked against a quote from it.
How to install Guard MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Guard MCP in Claude Code
$ claude mcp add codapult-guard -- npx -y @codapult/guardInstall Guard MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"codapult-guard": {
"command": "npx",
"args": [
"-y",
"@codapult/guard"
]
}
}
}Install Guard MCP in VS Code
.vscode/mcp.json
{
"servers": {
"codapult-guard": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codapult/guard"
]
}
}
}Install Guard MCP in VS Code CLI
$ code --add-mcp '{"name":"codapult-guard","type":"stdio","command":"npx","args":["-y","@codapult/guard"]}'Install Guard MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"codapult-guard": {
"command": "npx",
"args": [
"-y",
"@codapult/guard"
]
}
}
}Install Guard MCP in Codex
$ codex mcp add codapult-guard -- npx -y @codapult/guardInstall Guard MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.codapult-guard] command = "npx" args = ["-y", "@codapult/guard"]
Install Guard MCP in Gemini CLI
$ gemini mcp add -s user codapult-guard npx -- -y @codapult/guardInstall Guard MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"codapult-guard": {
"command": "npx",
"args": [
"-y",
"@codapult/guard"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablecodapult/codapult-guard is public and reachablegithub.com/codapult/codapult-guard ↗Pass
- Package names this repository as its source@codapult/guard names codapult/codapult-guard as sourcenpmjs.com/package/@codapult/guard ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @codapult/guardnpmjs.com/package/@codapult/guard/v/0.14.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/codapult/codapult-guard ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @codapult/guardPass
- No critical advisory in the package or its dependencies115 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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 ─────────────────────────────────────→ Database
Guard discovers the architecture in the repository; it does not prescribe one universal structure or activate proposed rules without approval.
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
- 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.
Guard MCP questions
How do I add Guard MCP to Claude Code?
Run claude mcp add codapult-guard -- npx -y @codapult/guard in your terminal. Add --scope user to make it available in every project.
How do I add Guard MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does Guard prevent architectural regressions?
It allows teams to approve project-specific boundaries and detects violating imports in changed files when a rule is triggered.
Does Guard use an LLM to check code?
No, Guard is local-first and does not call an LLM; the AI host is responsible for model access and edits.
What are the system requirements for Guard?
You need Node.js version 20.19 or higher and a JavaScript or TypeScript project.
How does the MCP server handle authentication?
The MCP server uses host-managed local stdio and does not use network listeners or application-level authentication.