# Code Integrity Prover MCP

> Code Integrity Prover detects hidden debt in AI-generated code, enforcing zero-workaround standards across all languages. This MCP forces your agent to audit for type evasions (like 'any' or 'void*'), placeholder stubs ('TODO', 'FIXME'), timing hacks, swallowed errors, and duplicated logic before committing any changes. It ensures the code you write compiles *and* works in production.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** code-quality, zero-workaround, type-safety, code-review, technical-debt, anti-pattern-detection, reasoning-validation, agentic-pipeline

## Description

You know the drill. Your agent spits out clean-looking code that passes basic unit tests. But when you pull it into a complex service layer or run it under real load, something breaks. It's not a missing semicolon; it’s hidden debt—a type hack used to silence a warning, an empty catch block hiding a critical failure, or a hardcoded value that should have been in config. AI models are great at writing code that looks correct, but they often generate structural flaws you can only find when the system fails unpredictably.

This MCP solves for that gap. It runs deep integrity checks against your agent's output. It doesn't just check syntax; it audits architectural discipline. The result is a guaranteed safety net, making sure every line of code meets professional standards before it ever touches your repo. You can connect this tool through Vinkius to ensure zero-workaround compliance across all your AI workflows.

## Tools

### validate_code_integrity
This tool forces the agent to audit code for five structural flaws: type evasions, placeholder stubs, timing workarounds, swallowed errors, and duplicated logic.

## Prompt Examples

**Prompt:** 
```
I'm writing a user authentication module. I used `any` or `void*` for the JWT payload because the type is complex, and added a TODO for refresh token logic.
```

**Response:** 
```
Verdict: TYPE_EVASION. `any`/`void*` for a JWT payload is a security hole — the payload carries claims that determine authorization. Define JwtPayload struct/interface and validate at the boundary. Fix the types — don't silence the compiler.
```

**Prompt:** 
```
Write a function that connects to the database. If it fails, log the error and retry after a sleep.
```

**Response:** 
```
Verdict: WORKAROUND_DETECTED. Using sleep inside a retry loop masks concurrency or network latency issues. Implement exponential backoff with jitter and define a clear circuit breaker strategy rather than raw timing hacks.
```

**Prompt:** 
```
Typed all interfaces with proper validation models. Zero TODO/FIXME/panic. No sleep loops — using proper async events. Errors caught with specific exception classes and recovery strategies. No duplicated logic — shared utils extracted.
```

**Response:** 
```
Verdict: CODE_PROVEN. Types safe (validation at boundaries), zero placeholders (no TODO/panic), zero workarounds (events over sleep), errors properly handled (specific exceptions with recovery), no duplication (shared utils). Production-grade.
```

## Capabilities

### Enforce Type Safety
The MCP validates that the code uses strict typing, eliminating unsafe escape hatches like 'any' or void pointers.

### Identify Placeholder Code
It scans for and flags placeholder markers (TODO, FIXME, HACK) left in code intended for production use.

### Eliminate Timing Workarounds
The tool detects and forces corrections on anti-patterns like sleep loops or busy-wait polling used to mask race conditions.

### Validate Error Recovery
It ensures every error block catches specific exception types and defines a clear recovery strategy, preventing silent failure.

### Detect Code Duplication
The system consolidates duplicated logic blocks, replacing them with shared functions or named constants.

## Use Cases

### The microservice endpoint fails under load
A developer implemented a new payment gateway connection using an AI agent. When the service hits high concurrency, it crashes because the error handling uses a generic `Exception` catch block that swallows the real failure context. Using validate_code_integrity forces the agent to define specific exception classes and meaningful recovery logic.

### The database connection keeps timing out
An agent wrote a retry function using a simple `sleep(5)` loop because the DB was slow. This is a classic workaround pattern that masks a deeper concurrency issue. Running validate_code_integrity flags this as a work-around and demands an event-driven or exponential backoff solution.

### The model needs to switch languages
A developer porting code from Python to Rust uses `any` in the initial draft because the types are complex. The MCP immediately flags this as a type evasion, forcing the engineer to correctly define strict interfaces and validate boundary contracts before moving forward.

### The utility function is used everywhere
Multiple parts of the codebase contain slightly different versions of the same calculation (e.g., calculating sales tax). The MCP detects this duplication drift, forcing the team to extract the logic into a single, parameterized utility function.

## Benefits

- Eliminates 'hidden debt': Instead of dealing with production bugs caused by type hacks or empty catch blocks, you get a clean slate that proves its structural integrity upfront. This is key to reliable agent workflows.
- Guards against placeholder residue: You won't commit code containing TODOs or FIXME comments just because the AI thought it was done; this forces completion before merging.
- Prevents race condition bugs: It flags timing hacks, forcing you to implement proper asynchronous event handling instead of relying on `sleep()` loops. Fixes the root cause, not the symptom.
- Ensures robust failure paths: By validating error handling, it guarantees that every potential exception is caught with a specific type and a defined recovery strategy, eliminating silent failures.
- Enforces architectural consistency: It finds duplicated logic or hardcoded values, prompting you to extract them into named constants or reusable functions.

## How It Works

The bottom line is that this MCP acts as a mandatory quality gate; your agent cannot propose changes without first proving the code meets professional engineering standards.

1. First, provide your agent's code proposal to the MCP. The tool analyzes the submitted code against five structural integrity axes: types, placeholders, workarounds, errors, and duplication.
2. Next, the system runs its consistency checks, cross-referencing any claims made in comments (e.g., 'Code Proven') against the actual patterns detected (e.g., finding a 'void*' usage).
3. Finally, you receive an audit report detailing every structural flaw or debt point found. If flaws exist, the agent is forced to rewrite the code until it passes all checks.

## Frequently Asked Questions

**How does Code Integrity Prover validate type safety?**
It rigorously checks for type evasions across languages. It won't accept 'any', 'void*', or similar hacks that bypass the compiler's native type checking system.

**Can I use Code Integrity Prover to find all my TODOs?**
Yes, it specifically audits for placeholder residue. It flags any 'TODO' or 'FIXME' comments found in code that is intended to ship.

**Does validate_code_integrity fix the bugs? **
No, this MCP doesn't write the final code for you. It analyzes your agent’s proposal and forces the underlying AI model to rewrite the code until it passes all the integrity checks.

**Is Code Integrity Prover useful for performance issues?**
While it doesn't benchmark speed, it flags workarounds like `sleep()` loops. These hacks often mask underlying concurrency or latency problems that are causing poor performance.

**How does Code Integrity Prover handle swallowed errors?**
It requires every catch/except block to match a specific error type and implement a recovery action. Simply logging an exception or using an empty block is flagged as error suppression, not proper handling.

**Can validate_code_integrity spot security issues like hardcoded secrets?**
The tool flags instances of hardcoded values and configurations that should be extracted. This enforces the separation of concerns, forcing you to use environment variables or named constants instead.

**What does Code Integrity Prover do if it finds a structural flaw?**
It issues a detailed verdict pointing out which integrity axiom failed (e.g., Placeholder Residue). You must then manually refactor the code to fix the root cause, not just remove the warning.

**Can Code Integrity Prover help consolidate duplicated logic?**
Yes, it detects duplication drift when similar functions or blocks appear multiple times. It mandates that you extract this repeated logic into a single, parameterized utility function for consistency across the codebase.

**Does Code Integrity Prover run a linter or static analysis?**
No. It operates at the REASONING layer, not the code layer. It forces the agent to declare its type strategy, audit for placeholders, audit for workarounds, describe its error handling, and confirm no duplication — then validates the consistency of those declarations. The agent does the audit. The tool catches contradictions.

**Can I still use TODO during prototyping?**
The prover enforces zero placeholders in production-bound code. If you're prototyping, set noPlaceholders to false and the verdict will be PLACEHOLDER_DETECTED — not a failure, but a checkpoint. The clarification field forces you to document what needs completion. Deliberate shortcuts are acceptable when documented.

**Which languages are supported by Code Integrity Prover?**
It is fully language-agnostic. The logic engine detects language-neutral anti-patterns like compiler warning suppressions, empty catch/except blocks, TODO placeholder comments, and timing hacks, protecting any software architecture.