ci-guard-mcp

One local audit engine. A CLI, a GitHub Action, and four MCP tools.

Catch risky GitHub workflows, undocumented environment variables, possible credentials, and conflicting dependency configuration before merging. Audits are deterministic, read-only, and run without sending source code to a service. Two runtime dependencies: yaml and ignore.

Run locally

Requires Node.js 20 or later. Git is required for index scans and tracked-file selection.

# Run directly with npx:
npx ci-guard-mcp scan . --fail-on warn
npx ci-guard-mcp scan . --sandbox
npx ci-guard-mcp scan . --no-git
npx ci-guard-mcp scan . --format json
npx ci-guard-mcp scan . --format sarif > findings.sarif
npx ci-guard-mcp scan . --auditor workflows --auditor lockfile
npx ci-guard-mcp scan . --auditor secrets --staged
npx ci-guard-mcp scan . --auditor secrets --include-ignored

# Or from a local source checkout:
npm ci --ignore-scripts
npm run build
node dist/cli.js scan .

Exit codes: 0 below threshold, 1 findings at or above threshold, 2 invalid arguments, configuration or I/O failure. --fail-on error is the default; warn also fails on warnings. Informational findings never fail a scan. Output formats are text, json, sarif, and github. --root PATH is equivalent to the positional scan directory. --include-ignored audits tracked files even when they match .gitignore rules (for example, a .env committed before .gitignore was added). --help lists every flag.

Staged mode is intentionally limited to secrets: it reads entire changed index blobs, including renamed/added files, so unstaged edits cannot conceal a staged credential. It applies ignore rules from the index and skips deletions, symlinks and submodules. Other audits need the repository-wide context and cannot be combined with --staged.

GitHub Action

After this repository is published, use a reviewed full commit SHA in place of FULL_COMMIT_SHA:

name: Repository audit
on: [push, pull_request]
permissions:
  contents: read
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: carelessdept/ci-guard-mcp@FULL_COMMIT_SHA
        id: guard
        with:
          path: .
          fail-on: warn

Inputs: path (default .), fail-on (error or warn, default error). Outputs: errors, warnings, findings as decimal counts. Outputs and the Markdown job summary are written before the finding threshold is evaluated. Findings become escaped workflow annotations; a failed audit exits the action with status 1. Operational failure exits 2 and does not claim complete counts.

This composite action installs its locked build dependencies with lifecycle scripts disabled into a runner-temp directory and runs the compiled CLI. It requires npm registry access, Bash, and a runner compatible with actions/setup-node@v4. The scanned repository's dependencies and scripts are never installed or executed. The self-audit workflow runs the local action and verifies its outputs. Run the CLI separately with --format sarif when uploading to a code-scanning service; the action itself does not upload reports or request write permissions.

MCP server

The stdio server uses newline-delimited JSON-RPC 2.0, negotiates MCP versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05, and implements initialization, ping, too

... View full README on GitHub