MCP setup

The Model Context Protocol (MCP) lets compatible host applications discover tools exposed by local processes. CodeGuard is a deterministic local analysis tool provider; it does not use or provide an AI model.

Start the server

Build the local checkout, then start a server scoped to an explicit root:

npm run build
node dist/cli/index.js mcp --root /absolute/path/to/project

After installing codeguard-local@beta globally, run codeguard mcp --root . from the project directory. The root is canonicalized and defines the instance's filesystem boundary. Each separate server instance is scoped to its own root. The server uses stdio: stdin/stdout carry MCP protocol messages, and diagnostics are written to stderr.

Tools

• analyze_project: fresh whole-project analysis with summary, analyzer statuses, bounded diagnostics, and optional remediation suggestions.
• analyze_file: analyze one project-relative TS/TSX/JS/JSX file with project context; returns diagnostics located in that file.
• get_project_info: project name/root, type, language, frameworks, enabled analyzers, configuration status, and source-file count.
• get_diagnostics: fresh analysis with severity filtering and bounded pagination.
• get_security_issues: configured SEC001–SEC005 findings, framed as potential issues for review; reports disabled configuration explicitly.
• get_architecture_issues: configured ARCH001–ARCH002 findings; reports disabled configuration explicitly.

Collections are bounded, no analysis result cache is used, and file-level output excludes diagnostics located in other files. See Security.

Prompts

CodeGuard also registers two MCP prompt templates. They are plain instructions that guide a compatible AI client in using the tools above; they contain no source code and no credential values.

• review_project (optional focus: all, typescript, javascript, security, or architecture): asks the assistant to gather project info, run the analysis, order findings by severity, separate confirmed compiler errors from potential security warnings, and propose practical remediation.
• explain_diagnostics (required code such as TS2322 or SEC001; optional project-relative filePath): asks the assistant to explain the code, the likely cause, and a safe remediation, and to state uncertainty.

Prompt arguments are validated: codes may contain only letters, digits, ., _, and -, and file paths must be relative and stay inside the project. The prompts tell the assistant that diagnostics are deterministic CodeGuard results rather than AI-generated analysis and that no automatic fix is available. CodeGuard itself has no AI model, makes no AI API calls, and needs no API key. Your connected AI client may apply its own data-handling policies to the diagnostics it receives.

Typical AI-assisted workflow: run the review_project prompt, read the findings, then run explain_diagnostics for a specific code you want clarified. Apply any change yourself or approve it explicitly in your client; CodeGuard never edits files.

VS Code

Install the beta globally with npm install -g codeguard-local@beta. Add the following to .vscode/mcp.json, merging with any existing servers entries:

{
  "servers": {
    "codeguard": {
      "type": "stdio",
      "command": "codeguard",
      "args": [
        "mcp",
        "--root",
        "${workspaceFolder}"
      ]
    }
  }
}

Start the server from VS Code's MCP controls and verify that all six tools appear. In GitHub Copilot Agent Mode, ask it to use analyze_project or another CodeGuard tool for the workspace.

Codex

Install the beta globally with npm install -g codeguard-local@beta, then configure ~/.codex/config.toml:

[mcp_servers.codeguard]
command = "codeguard"
args = ["mcp", "--root", "<project-root>"]

Replace <project-root> with the project directory on the local machine. Keep the root explicit so the server's access boundary is clear.

MCP Inspector

Install the beta globally, then run the Inspector with the installed executable:

npx @modelcontextprotocol/inspector codeguard mcp --root .

In the Inspector, confirm initialization, list tools, call get_project_info, then call analyze_project on a fixture with a known diagnostic.

Troubleshooting

If the connection closes, confirm Node.js 24+, build output exists, --root names an accessible directory, and the host is launching a stdio process without extra stdout banners. If tools are missing, restart the server after rebuilding and inspect stderr. On VS Code, PATH may differ from an interactive shell; use an explicit Node executable path if the host cannot resolve node. More help is in Troubleshooting.