# Checkride MCP Server

<p align="center">
  <img src="./assets/logo.jpg" alt="Checkride Logo" width="220" />
</p>

**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`.

---

## What "Connected" Means

Cursor / AI Assistants start Checkride in the background via:

```json
{
  "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

```mermaid
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:

| Tool | When it's used | What it runs |
|---|---|---|
| **`run_staged_checks`** | Before commit — only changed files | Git safety scan + linter on staged files |
| **`run_checks`** | Full pre-flight check | `pytest` + `ruff` + `tsc` + custom build steps |
| **`run_tests`** | After backend/API edits | Executed test suite |
| **`run_lint`** | After code edits | Configured linter (`eslint`, `ruff`, `clippy`) |
| **`run_typecheck`** | After TS/React edits | `tsc --noEmit` or `mypy` |
| **`check_git_safety`** | Before commit | Conflict markers, secrets, debug logs |
| **`suggest_fixes`** | When something fails | Parses errors → prompt fix hints for agent |
| **`get_check_status`** | Quick recap | Last run result without re-running |

### 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:

```text
"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

| Method | Who runs it | Best for |
|---|---|---|
| **MCP (Connected)** | AI Agent during chat | Continuous validation while pair-programming |
| **`npx checkride-mcp check --staged`** | You in terminal | Quick check before manual `git commit` |
| **`npx checkride-mcp check --full`** | You in terminal | Full CI mirror locally |
| **`npx checkride-mcp init-hooks`** | Git automatically | Block bad commits even outside Cursor/IDE |

---

## Exposed MCP Tools

| Tool Name | Description | Parameters | Output Schema |
| --- | --- | --- | --- |
| `run_checks` | Run full validation pipeline with smart SHA-256 caching (<10ms on unchanged code) | `project_path` *(string, optional)*, `bypass_cache` *(boolean, optional)* | `{ passed, results: { test, typecheck, lint, custom }, summary, cached }` |
| `run_staged_checks` | Run targeted checks on modified/staged Git files | `project_path` *(string, optional)* | `{ passed, staged_files, safety, lint, summary }` |
| `check_git_safety` | Scan files for conflict markers, leaked secrets, and debug logs | `project_path` *(string, optional)*, `files` *(string[], optional)* | `{ passed, issues: [{ type, file, line, content, description }], scanned_files, summary }` |
| `run_security_audit` | Run dependency vulnerability security audits | `project_path` *(string, optional)* | `{ passed, vulnerabilities: { critical, high, moderate, low, total }, issues: [{ package, severity, title, url, fix_available }], summary }` |
| `suggest_fixes` | Generate AI prompt hints for fixing test failures & TS errors | `project_path` *(string, optional)* | `{ count, suggestions: [{ category, file, line, issue, hint, prompt_snippet }], summary }` |
| `export_report` | Export visual Markdown/HTML reports to `.checkride/` | `project_path` *(string, optional)*, `format` *("markdown" \| "html", optional)* | `{ file_path, format, content, summary }` |
| `run_tests` | Run only the test suite | `project_path` *(string, optional)*, `test_pattern` *(string, optional)* | `{ passed, output, failed_tests: string[] }` |
| `run_typecheck` | Run type checking (`tsc`, `mypy`, `cargo check`, `go vet`) | `project_path` *(string, optional)* | `{ passed, output, errors: string[] }` |
| `run_lint` | Run code linter (`eslint`, `biome`, `ruff`, `clippy`) | `project_path` *(string, optional)*, `fix` *(boolean, optional)* | `{ passed, output, issues: number }` |
| `get_check_status` | Retrieve status of the last check run | *None* | `{ last_run, passed, summary, results }` |

---

## Example Session

```text
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:

```text
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:

```json
{
  "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`:

```bash
npx checkride-mcp init-hooks
```

Or run staged checks manually from your terminal:

```bash
npx checkride-mcp check --staged
```

---

## Connecting to AI Agents

### 1. Claude Desktop Config (`claude_desktop_config.json`)

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

### 2. Cursor / Antigravity / Claude Code Config

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

---

## License

MIT © [Siqah](https://github.com/siqah)