lidar_harness_mcp

# LiDAR Harness MCP **Incremental Validation Engine — As a pluggable MCP middleware for Claude Code, OpenCode, and other code agents.** Inspired by PGO (Pose Graph Optimization) in SLAM, LiDAR Harness provides a four-layer validation architecture, ensuring the quality of agent-generated code without increasing the context burden per round. ## Core Concepts Most code agents work by re-running `tsc` / `lint` after each code modification, injecting **all** errors back into the context. This wastes tokens in tasks with over 10 rounds. LiDAR Harness's PGO (Pose Graph Optimization) engine adopts an **incremental mechanism**: ``` Initial: tsc --noEmit → 7 errors found → All injected Round 2: 3 errors fixed → 4 known, 0 new → Not injected, agent not interrupted Round 3: 1 new error introduced → Only inject this 1 new error ... ``` **Effect**: Context occupancy reduced by 60-80%, agent not repeatedly interrupted by known errors. ## Features | Tool | Purpose | Typical Timing | |------|---------|-----------------| | `harness_init` | Initialize project, auto-detect typecheck/lint commands, establish baseline | Once per session | | `harness_classify` | Determine if task is "simple" (Q&A) or "complex" (coding) | After user message | | `harness_pgo` | **Incremental check** — Only return new typecheck/lint errors | After each code modification | | `harness_review` | Multi-perspective code review (security scan, correctness, style) | Every 3 rounds | | `harness_reset` | Reset PGO state | When switching tasks | ### Architecture ``` Model completes a turn (modifies code) │ ▼ ┌──────────────────────┐ │ Layer 0: Gate │ ─── Simple tasks (Q&A/explanation) → Skip subsequent validation └────────┬─────────────┘ ▼ ┌──────────────────────┐ │ Layer 2: PGO │ ─── typecheck + lint, incremental injection (core functionality) └────────┬─────────────┘ ▼ ┌──────────────────────┐ │ Layer 3: MultiReview │ ─── Security/correctness/style (every 3 rounds) └──────────────────────┘ ``` ## Quick Start ### Prerequisites - Node.js >= 18 - An MCP client (Claude Code, OpenCode, or any MCP-compatible tool) ### Installation ```bash git clone https://github.com/bernardleex526-png/lidar_harness_mcp.git cd lidar_harness_mcp npm install npm run build ``` ### Integration with Claude Code Add to project `.claude/settings.local.json`: ```json { "mcpServers": { "lidar-harness": { "command": "node", "args": ["/path/to/lidar_harness_mcp/dist/index.js"] } } } ``` Restart Claude Code, and 5 tools will be available. ### Integration with OpenCode OpenCode also supports MCP Server, with similar configuration. Add to OpenCode's MCP configuration: ```json { "mcpServers": { "lidar-harness": { "command": "node", "args": ["/path/to/lidar_harness_mcp/dist/index.js"] } } } ``` ### Direct Testing MCP Server communicates via stdio, and can be tested with JSON: ```bash # List tools echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js # Initialize project echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"harness_init","arguments":{"cwd":"/your/project","taskMessage":"fix the build"}}}' | node dist/index.js ``` ## Example Workflow ### Typical Usage in Claude Code ``` User: Refactor this module Claude: [Calls harness_init, detects tsc and lint] Claude: [Completes task, calls harness_pgo] Claude: → Compilation passes, no new errors Claude: Refactoring complete. User: Add an API endpoint Claude: [Modifies code, calls harness_pgo] Claude: → 2 new type errors found, need to be fixed Claude: [Fixes errors, calls harness_pgo again] Claude: → 0 new errors, compilation passes ``` ### Cyclic Detection (Optional) PGO also has a monotonic convergence guarantee: - `shownErrors` set only increases - Only shows new errors unseen by the agent in each round - Stops when `unseenSigs.length === 0`, mathematically guaranteed to converge ## Supported Languages | Language | Detection File | Default Command | |----------|----------------|-----------------| | TypeScript | `tsconfig.json` | `npx tsc --noEmit`, `npm run lint` (if lint script exists) | | Go | `go.mod` | `go vet ./...` | | Rust | `Cargo.toml` | `cargo check` | | Java (Maven) | `pom.xml` | `mvn compile -q` | | Java (Gradle) | `build.gradle` | `gradle build -q` | Arbitrary verification commands can also be manually passed. ## Project Structure ``` lidar-harness-mcp/ ├── src/ │ ├── index.ts # MCP Server entry, tool registration │ └── harness/ │ ├── pgo.ts # PGO incremental validation engine │ ├── review.ts # Multi-perspective code review │ └── gate.ts # Complexity gating ├── package.json ├── tsconfig.json └── README.md ``` Zero runtime dependencies (except `@modelcontextprotocol/sdk`). ## License MIT