Checkride MCP Server

Checkride is a Model Context Protocol (MCP) server that serves as a fast, local "CI pre-flight" validation sidecar for AI coding agents.

Once Checkride is connected in Cursor, Claude Desktop, or Antigravity, it runs as an invisible local validation sidecar — the AI agent calls its tools to test code changes locally instead of guessing whether code is ready to commit.

Features

• Fast Pre-Flight Pipeline: Runs test suite, type checker, and linter concurrently.

• Smart SHA-256 Caching: Instant sub-10ms responses ([CACHED < 10ms]) on unchanged codebases.

• Git & Staged-Files Intelligence: Run targeted validations and safety checks on modified or staged Git files only.

• Pre-Commit Git Hooks: Easily install local .git/hooks/pre-commit to validate code automatically before manual commits.

• Docker Sandboxing: Optional containerized execution ("sandbox": "docker") to isolate process execution.

• Dependency Security Auditing: Runs package security audits (npm audit, cargo audit, pip-audit) to detect vulnerabilities introduced by AI agents.

• AI Fix Generator: Analyzes errors and type mismatches to return prompt-ready remediation hints and code snippets.

• Visual Report Exporter: Exports Markdown (.checkride/summary.md) and HTML (.checkride/report.html) validation summaries.

• Git Safety Guard Scanner: Detects leftover conflict markers (<<<<<<<), leaked API secrets/keys, and debug statements (console.log, debugger, breakpoint()).

• Auto-Detection & Monorepo Support: Auto-detects package managers (pnpm, yarn, bun, npm), monorepos (Turbo, pnpm workspaces, Lerna), and languages (TypeScript, JavaScript, Python, Rust, Go).

• Configurable Sidecar: Customize commands, timeouts per check, excludes, git safety severity, and custom build steps via .checkriderc.json.

Related MCP server: FlowCheck MCP Server

What "Connected" Means

Cursor / AI Assistants start Checkride in the background via:

{
  "mcpServers": {
    "checkride": {
      "command": "npx",
      "args": ["-y", "checkride-mcp"]
    }
  }
}

When you chat in your IDE, the agent can invoke 10 MCP tools. Those tools read your .checkriderc.json and run the exact same commands as your CI (pytest, ruff, tsc, test suite, web build).

You don't open Checkride as a desktop app — it operates as invisible infrastructure that the AI agent uses autonomously.

Typical Agent Workflow

flowchart LR
  A[You ask agent to change code] --> B[Agent edits files]
  B --> C[Agent calls Checkride MCP]
  C --> D{Passed?}
  D -->|Yes| E[Agent says ready / offers commit]
  D -->|No| F[Agent reads errors and fixes]
  F --> C

1. You ask for a change

Example: "Add a field to the incident API and update the web page."

2. Agent implements the change

Edits files across your codebase.

3. Agent validates with Checkride (automatic or on request)

Common tool calls:

4. Agent fixes or confirms

• Failed: Agent reads Checkride error output, fixes the code, and re-runs checks.

• Passed: Agent informs you that the codebase is clean and ready to commit.

What You Can Say in Chat

You don't need exact tool names — plain language prompts trigger the tools automatically:

"Run checkride on my staged changes"
"Run full pre-flight checks before I commit"
"Did my API changes pass tests and lint?"
"Check for secrets or debug logs in what I changed"

MCP vs CLI vs Git Hook

Exposed MCP Tools

Example Session

You:   Add an unlock button to the admin users page.

Agent: [edits src/components/admin.tsx...]
       [calls run_staged_checks]
       → lint/typecheck on changed files
       → git safety on staged files

Agent: Staged checks passed. Ready to commit.

You:   Run full checks to be sure.

Agent: [calls run_checks]
       → test suite + ruff + tsc + build
       → all passed!

If tests fail:

Agent: [calls run_tests] → 2 failures
       [calls suggest_fixes] → hints for each failure
       [fixes code]
       [calls run_tests again] → passed

Important Details

1. Checkride validates, you commit: Checkride executes local checks — it never commits or pushes code without your explicit action.

2. Uses your local environment: Command execution runs using local node_modules, Python virtualenv, or Docker container.

3. MCP integration: MCP runs inside Cursor/AGY/Claude. Terminal commits without the editor utilize the CLI or Git hooks (init-hooks).

4. Reload Cursor: After adding Checkride to .cursor/mcp.json or settings, reload the window so the server connects under Settings → MCP.

Configuration (.checkriderc.json)

Checkride automatically looks for .checkriderc.json, .checkriderc, or checkride.config.json in the root of your project directory:

{
  "sandbox": "docker",
  "docker_image": "node:20-alpine",
  "git_safety": {
    "severity": "warn",
    "ignore_patterns": ["test/"]
  },
  "timeouts": {
    "test": 60000,
    "typecheck": 60000,
    "lint": 30000,
    "security": 60000,
    "default": 60000
  },
  "commands": {
    "test": "pnpm test",
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "security": "npm audit --json",
    "custom": [
      {
        "name": "Format Check",
        "command": "prettier --check .",
        "timeout": 15000
      }
    ]
  },
  "exclude": ["node_modules", "dist", "build", ".git"],
  "env": {
    "CI": "true"
  }
}

Installing Git Pre-Commit Hook

Install local .git/hooks/pre-commit to automatically run Checkride checks before any manual git commit:

npx checkride-mcp init-hooks

Or run staged checks manually from your terminal:

npx checkride-mcp check --staged

Connecting to AI Agents

1. Claude Desktop Config (claude_desktop_config.json)

{
  "mcpServers": {
    "checkride": {
      "command": "npx",
      "args": ["-y", "checkride-mcp"]
    }
  }
}

2. Cursor / Antigravity / Claude Code Config

{
  "mcpServers": {
    "checkride": {
      "command": "npx",
      "args": ["-y", "checkride-mcp"]
    }
  }
}

License

MIT © Siqah