DEV Community

Toni Antunovic
Toni Antunovic

Posted on • Originally published at lucidshark.com

How to Set Up Automated Quality Gates for Claude Code with MCP

#claudecode #qualitygates #mcp #aitools

This article was originally published on LucidShark Blog.

You have Claude Code open, an MCP server running, and a codebase that keeps growing. Every time an AI agent touches a file, you trust that the output is good. But "good" to an AI means "it compiled and passed the tests you asked about." Structural rot, complexity creep, and style drift accumulate silently until your next painful sprint review.

The fix is not more code review. The fix is wiring a deterministic quality gate directly into the Claude Code workflow so every AI-generated or AI-modified file gets analyzed before it can reach your commit history. This tutorial shows you exactly how to do that with LucidShark and MCP.

Why AI Coding Agents Need a Quality Gate at the Seam

Claude Code is an agentic tool. It does not just suggest changes, it makes them. When you ask it to implement a feature or refactor a module, it will write files, run commands, and iterate. The feedback loop it relies on is functional: does the code compile, do the tests pass, does the output match the spec?

None of those signals measure structural quality. A function with a cyclomatic complexity of 28 passes every test. A module with 340 lines of duplicated logic compiles cleanly. A file with zero branch coverage in a critical error path merges without protest. The AI completed the task by its own definition of "done," which is a very different definition than your team's.

⚠️ Warning: AI coding agents optimize for the feedback they receive. If your only feedback signals are "compile success" and "test pass," you will get code that compiles and passes tests. You will not automatically get code that is maintainable, well-covered, or architecturally sound.

The MCP (Model Context Protocol) integration point is the seam where you can intercept this. Before Claude Code finalizes a change, or immediately after it produces output, you can invoke a local quality analysis tool and surface the results back into the agent's context. The agent can then fix issues before you ever see them.

What LucidShark Measures and Why It Matters Here

LucidShark is a local-first static analysis tool designed specifically for AI-assisted development workflows. It runs entirely on your machine, sends no data externally, and produces structured JSON output that MCP can consume. The checks it runs cover the gaps that AI agents leave open:

  • Cyclomatic complexity: Flags functions that have branched beyond the point where a human can reason about them, even if they work correctly today.

  • Code duplication: Detects copy-paste patterns that AI agents produce when they do not have enough context to extract shared logic.

  • Test coverage mapping: Shows which lines, branches, and paths your test suite does not exercise, so you can see what "100% tests passing" actually means in coverage terms.

  • Dependency risk scoring: Checks your package manifest against known vulnerability data and flags packages with suspicious or unlicensed provenance.

  • SAST (Static Application Security Testing): Identifies injection patterns, hardcoded credentials, and unsafe API usage in generated code.

  • Style and lint conformance: Enforces your project's rules so AI output does not drift from team conventions over time.

📝 Note: LucidShark's local-first design is not just a privacy choice. It means the tool can be invoked inside MCP tool calls with no network latency, no API rate limits, and no dependency on external service availability. Quality checks happen at the speed of your local disk.

Setting Up the MCP Server

LucidShark ships with a built-in MCP server mode. When you start it in this mode, it exposes a set of tools that Claude Code can call during an agentic session. The tools wrap the same analysis engine as the CLI, but they return structured results designed for an AI to read and act on.

Step 1: Install LucidShark 

npm install -g lucidshark
Enter fullscreen mode Exit fullscreen mode

Verify the installation:

lucidshark --version
lucidshark doctor
Enter fullscreen mode Exit fullscreen mode

The doctor command checks that your local environment has the required analysis dependencies (ESLint runtime, coverage tooling, and the LucidShark rule engine). Fix any warnings it surfaces before proceeding.

Step 2: Initialize a project configuration

Run this in the root of the repository you want to gate:

lucidshark init
Enter fullscreen mode Exit fullscreen mode

This creates a lucidshark.config.json file. The defaults are sensible for most TypeScript or JavaScript projects. The key settings to review for an AI-assisted project:

{
  "complexity": {
    "maxCyclomatic": 10,
    "maxCognitive": 15
  },
  "coverage": {
    "minLineCoverage": 70,
    "minBranchCoverage": 60,
    "failOnUncoveredCriticalPaths": true
  },
  "duplication": {
    "minTokens": 50,
    "maxDuplicationRatio": 0.05
  },
  "sast": {
    "enabled": true,
    "blockOnHighSeverity": true
  },
  "mcp": {
    "enabled": true,
    "port": 7878,
    "returnStructuredJson": true
  }
}
Enter fullscreen mode Exit fullscreen mode

📝 Note: Set maxCyclomatic lower than you think you need. AI agents frequently produce functions in the 15 to 25 complexity range because they solve the immediate problem without decomposing it. A threshold of 10 creates useful pressure to keep generated code readable.

Step 3: Start the MCP server 

lucidshark mcp --project /path/to/your/repo
Enter fullscreen mode Exit fullscreen mode

You should see output like:

LucidShark MCP server running on stdio
Project root: /path/to/your/repo
Tools registered: analyze_file, analyze_diff, check_coverage, scan_dependencies, run_sast
Ready for connections.
Enter fullscreen mode Exit fullscreen mode

Step 4: Register the MCP server with Claude Code

Open or create your Claude Code MCP configuration file. On macOS and Linux it lives at ~/.claude/mcp_settings.json. Add the LucidShark server entry:

{
  "mcpServers": {
    "lucidshark": {
      "command": "lucidshark",
      "args": ["mcp", "--project", "/path/to/your/repo"],
      "env": {}
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Restart Claude Code. In the next session, the LucidShark tools will be available in the tool list. You can verify with /tools in the Claude Code terminal, which should show the lucidshark.* namespace.

Using the Quality Gate in Practice

Once the MCP server is registered, you can instruct Claude Code to use it explicitly, or you can set up a CLAUDE.md rule that makes quality checks automatic.

Option A: Explicit invocation in your prompt

When you ask Claude Code to implement something, append a quality requirement:

Implement the user notification service in src/services/notifications.ts.
After writing the file, run lucidshark.analyze_file on it and fix any issues
with complexity above 10, any SAST high-severity findings, and any duplication
above 5%. Do not consider the task done until the quality gate passes.
Enter fullscreen mode Exit fullscreen mode

Claude Code will write the file, call the MCP tool, read the structured JSON results, and iterate on the code until the checks pass. You see the final version, not the intermediate drafts.

Option B: Automatic enforcement via CLAUDE.md

Create or update the CLAUDE.md file in your project root. This file provides persistent instructions that Claude Code reads at the start of every session:

# Quality Gate Rules

After writing or modifying any source file, you MUST call lucidshark.analyze_file
on the changed path before moving to the next task.

If the result contains:
- complexity violations: refactor the function into smaller units
- SAST high-severity findings: fix them immediately, do not proceed
- duplication above threshold: extract shared logic into a utility
- coverage gaps on critical paths: add tests before finishing

Do not mark a task complete if the quality gate has unresolved findings.
Report the final gate status in your summary.
Enter fullscreen mode Exit fullscreen mode

⚠️ Warning: Do not skip the CLAUDE.md rule if you are running overnight or long-running agentic sessions. Without a persistent quality gate instruction, the agent will revert to its default "task complete when functional" behavior after context pressure builds up. The CLAUDE.md anchor keeps the constraint visible across the full session.

Checking a diff before commit

LucidShark also exposes an analyze_diff tool that takes a unified diff string and returns quality findings scoped to the changed lines only. This is useful in a pre-commit hook or in a Claude Code workflow that processes a staged diff:

git diff --staged | lucidshark analyze-diff --stdin
Enter fullscreen mode Exit fullscreen mode

Or via MCP in a Claude Code prompt:

Before committing, run lucidshark.analyze_diff on the staged changes.
If there are any blocking findings, fix them first.
Enter fullscreen mode Exit fullscreen mode

Reading the Quality Gate Output

When LucidShark runs through MCP, it returns JSON that Claude Code can parse and act on. Here is a representative output from analyze_file:

{
  "file": "src/services/notifications.ts",
  "passed": false,
  "findings": [
    {
      "rule": "complexity/cyclomatic",
      "severity": "warning",
      "location": "sendBatchNotification:47",
      "message": "Function cyclomatic complexity is 14, threshold is 10",
      "suggestion": "Extract the retry logic into a separate function"
    },
    {
      "rule": "sast/hardcoded-secret",
      "severity": "high",
      "location": "line 12",
      "message": "Potential hardcoded API key: NOTIF_KEY = 'sk-...'",
      "suggestion": "Move to environment variable or secrets manager"
    }
  ],
  "metrics": {
    "linesOfCode": 187,
    "cyclomaticComplexity": { "max": 14, "avg": 4.2 },
    "duplicationRatio": 0.02,
    "coverageEstimate": null
  },
  "gate": "FAIL"
}
Enter fullscreen mode Exit fullscreen mode

Claude Code receives this as a tool result, reads the findings array, and uses the suggestion fields to guide its fixes. The loop runs until gate returns PASS.

LucidShark in the Full AI Development Workflow

The MCP integration is one piece of a broader quality workflow. LucidShark also fits at two other points that matter for AI-heavy teams:

  • Pre-commit hooks: Run lucidshark analyze --staged to block commits with high-severity SAST findings or complexity violations above your threshold. This catches issues that slipped through the MCP loop.

  • CI/CD pipeline: Run lucidshark analyze --ci to generate a machine-readable report as part of your build. This gives you a project-wide quality trend over time, not just per-file spot checks.

  • IDE integration: The LucidShark VS Code extension surfaces findings inline as you review AI-generated code, so you see the same metrics Claude Code sees during generation.

The design principle is consistency: the same rules, the same thresholds, the same engine, at every stage. An AI agent cannot produce code that passes the MCP gate but fails CI, because they run the same checks. That consistency is what makes the gate trustworthy rather than advisory.

📝 Note: LucidShark is open source under the Apache 2.0 license. You can read the rule engine, add custom rules specific to your codebase, and contribute upstream. There is no telemetry, no cloud dependency, and no paid tier for the core quality gate functionality.

The result of wiring all of this together is a development loop where AI agents produce code that meets your standards automatically, not code that you have to audit and manually fix after the fact. Claude Code becomes a collaborator that enforces the same quality bar you hold your human contributors to, because it has the same information and the same gates in its workflow.

✅ Try LucidShark: Install via npm (npm install -g lucidshark), run lucidshark analyze in your repo, and get your first quality report in under 60 seconds. Runs entirely local, no data leaves your machine, and integrates with Claude Code via MCP. lucidshark.com

Top comments (0)