Back to Browse

Lucidshark MCP Server

Developer ToolsUse Caution4.4MCP RegistryLocal
Free

Server data from the Official MCP Registry

Local code quality and security scanner: lint, types, SAST, SCA, tests, coverage.

About

Local code quality and security scanner: lint, types, SAST, SCA, tests, coverage.

Security Report

4.4
Use Caution4.4High Risk

LucidShark is a local code-quality and security scanner whose visible code shows no data exfiltration, hardcoded secrets, or unsafe shell construction, and its network and process permissions fit its purpose. The main concern is the self-updater, which downloads and applies binary updates automatically and verifies them only against a SHA256SUMS file from the same release, so a compromised release could pass verification. The truncated view also leaves the MCP/status HTTP endpoint's authentication and bind address unverified. Supply chain analysis found 9 known vulnerabilities in dependencies (0 critical, 2 high severity). Package verification found 1 issue.

12 files analyzed · 13 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

process_spawn

Check that this permission is expected for this type of plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "lucidshark": {
      "command": "uvx",
      "args": [
        "lucidshark==0.10.0"
      ]
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

LucidShark

CI codecov License

Ship AI-generated code without the fear

AI writes code → LucidShark checks → AI fixes → repeat

The quality gate for agentic engineering. As AI agents increasingly write production code, LucidShark ensures high standards through automated, comprehensive quality checks - no manual code review bottlenecks.

Why LucidShark

  • Local-first - No server, no SaaS account. Runs on your machine and in CI with the same results.

  • Configuration-as-code - lucidshark.yml lives in your repo. Same rules for everyone, changes go through code review.

  • AI-native - MCP integration with Claude Code, Cursor and Windsurf, plus a lint hook for Aider. Structured feedback that AI agents can act on directly.

  • Unified pipeline - Linting, type checking, formatting, security (SAST/SCA/IaC), tests, coverage, and duplication detection in one tool. Stop configuring 5+ separate tools.

  • Open source & extensible - Apache 2.0 licensed. Add your own tools via the plugin system.

Quick Start

# 1. Install LucidShark
curl -fsSL https://raw.githubusercontent.com/toniantunovi/lucidshark/main/install.sh | bash

# 2. Configure Claude Code and generate lucidshark.yml
#    (--cursor, --windsurf, --aider or --all-tools select other AI tools)
./lucidshark init

# 3. Restart your AI tool. To tailor the generated config, ask it:
#    "Autoconfigure LucidShark for this project"

That's it! init detects your languages and writes a lucidshark.yml with every supported tool enabled. Autoconfigure has your AI assistant analyze the codebase, ask you a few questions, and refine that configuration.

Installation Options

MethodCommandUsageNotes
Install Script (Linux/macOS)curl -fsSL .../install.sh | bash./lucidsharkRecommended, installs to current directory, self-updates
ManualDownload from Releases./lucidsharkPre-built binaries for Linux and macOS
pippip install lucidsharklucidsharkRequires Python 3.10+
uvxuvx lucidsharkuvx lucidsharkRun without installing

Important: The install script and the release binaries create a project-local ./lucidshark file; use ./lucidshark to run the project-specific version. With pip or uvx, the command is lucidshark. The examples below use ./lucidshark.

Verified Downloads

Nothing LucidShark installs runs unverified:

  • The LucidShark binary. Every release publishes a SHA256SUMS file and a signed build provenance attestation. The install script checks the binary against SHA256SUMS before making it executable and aborts on mismatch. The self-updater does the same before staging an update, and checks the hash again before applying it. SHA256SUMS comes from the same release as the binary, so it catches corrupted or tampered transfers. The attestation is what proves a binary was built by this repository's release workflow. To verify a manual download:

    shasum -a 256 -c SHA256SUMS --ignore-missing     # or: sha256sum -c SHA256SUMS --ignore-missing
    gh attestation verify lucidshark-linux-amd64 --repo toniantunovi/lucidshark
    
  • Scanner and tool binaries (Trivy, OpenGrep, Checkov, gosec, PMD, Checkstyle, SpotBugs, ktlint, detekt, duplo). Each download is checked against a SHA-256 pinned inside LucidShark for that exact version, asset and platform (checksums.py). A mismatch, or a URL with no pin, is refused before anything is written to disk. The pins are generated by scripts/update_tool_checksums.py, which cross-checks each hash against the digest GitHub recorded when the asset was uploaded.

Running Scans

./lucidshark scan --all             # Run all quality checks
./lucidshark scan --linting         # Run specific domains
./lucidshark scan --linting --fix   # Auto-fix linting issues
./lucidshark scan --all --dry-run   # Preview what would be scanned

Scan domains: --linting, --type-checking, --formatting, --sast, --sca, --iac, --container, --testing, --coverage, --duplication. With no domain flag, scan runs only the security domains enabled in lucidshark.yml.

Incremental Scanning

By default, LucidShark scans only uncommitted changes (staged, unstaged, untracked files):

# Default: scan only changed files (no extra flags needed)
./lucidshark scan --linting --type-checking

# Full project scan
./lucidshark scan --all --all-files

# PR/CI: filter results to files changed since a branch
./lucidshark scan --all --base-branch origin/main

See Incremental Scanning for threshold scopes, CI integration, and advanced usage.

Note: LucidShark runs in strict mode by default - all configured tools must run successfully. If a configured tool isn't installed, the scan stops up front (exit code 3) with install hints. If a tool is skipped for a missing prerequisite or fails while running, the scan fails with a HIGH severity issue and fix suggestions. A tool with no applicable files is skipped without failing. Security tools (trivy, opengrep, gosec, checkov), duplo, PMD, Checkstyle, SpotBugs, ktlint, and detekt are downloaded automatically.

Example Output

When issues are found:

$ ./lucidshark scan --linting --type-checking --sast --format summary
Total issues: 4

By severity:
  HIGH: 1
  MEDIUM: 2
  LOW: 1

By domain:
  SAST: 1 issues
  LINTING: 2 issues
  TYPE_CHECKING: 1 issues

Scan duration: 1243ms
Project: /path/to/project

When everything passes:

$ ./lucidshark scan --linting --type-checking --format summary
Total issues: 0

By domain:
  LINTING: PASS
  TYPE_CHECKING: PASS

Scan duration: 812ms
Project: /path/to/project

Output is JSON by default. Use --format summary for the overview above, --format table for a per-issue breakdown, --format ai for AI agents, or --format sarif for code-scanning tools.

Diagnostics

Check your LucidShark setup with the doctor command:

./lucidshark doctor

This checks:

  • Configuration file presence and validity
  • Tool availability (security scanners, linters, type checkers)
  • Python environment compatibility
  • Git repository status
  • MCP integration (Claude Code)

AI Tool Setup

init configures Claude Code by default. Tool flags select other tools instead and combine freely (add --claude-code to keep Claude Code alongside them); --all-tools configures all of them. --dry-run, --force and --remove apply to every selected tool, and shared files (CLAUDE.md, CONVENTIONS.md, .aider.conf.yml, MCP JSON files) are merged, not overwritten (an MCP JSON file that can't be parsed is replaced). Every run also writes lucidshark.yml unless it already exists or --no-config is given.

ToolCommandWhat it writes
Claude Code./lucidshark init.mcp.json, .claude/skills/lucidshark/SKILL.md, .claude/CLAUDE.md section, .claude/settings.json hook
Cursor./lucidshark init --cursor.cursor/mcp.json, .cursor/rules/lucidshark.mdc (always applied)
Windsurf./lucidshark init --windsurf.windsurf/rules/lucidshark.md (trigger: always_on); prints an MCP snippet with absolute paths to merge into ~/.codeium/windsurf/mcp_config.json (or .devin/mcp_config.json in Devin Desktop). init writes neither file
Aider./lucidshark init --aider.aider.conf.yml keys lint-cmd (LucidShark on every edited file), auto-lint, read: [CONVENTIONS.md], plus a CONVENTIONS.md section. Aider has no MCP support
All of the above./lucidshark init --all-tools

Restart your AI tool after running init to activate.

Any other MCP client can run the server directly with lucidshark serve --mcp .. Or tell your agent:

Add the LucidShark MCP server so you can test your own output before committing.

Supported Languages

LucidShark supports 14 programming languages with full tool coverage:

LanguagesWhat's Included
Python, TypeScript, JavaScript, Java, Kotlin, Rust, Go, C#, C, C++, Scala, Swift, Ruby, PHPLinting, type checking, formatting, testing, coverage, security, duplication

Two gaps: Java has no formatter, and plain JavaScript has no type checker (TypeScript uses tsc).

For detailed per-language tool coverage, configuration examples, and detection info, see the Language Reference.

What It Checks

DomainToolsWhat It Catches
LintingRuff, ESLint, Biome, Clippy, Checkstyle, PMD, ktlint, golangci-lint, dotnet format, clang-tidy, Scalafix, SwiftLint, RuboCop, phpcsStyle issues, code smells, bug detection
FormattingRuff Format, Prettier, ktlint, rustfmt, gofmt, dotnet format, clang-format, Scalafmt, SwiftFormat, RuboCop Format, PHP-CS-FixerCode formatting, whitespace style
Type Checkingmypy, Pyright, TypeScript (tsc), SpotBugs (managed), detekt, cargo check, go vet, dotnet build, cppcheck, scalac, Swift compiler, Sorbet, PHPStanType errors, static analysis bugs
Security (SAST)OpenGrep, gosec (Go)Code vulnerabilities
Security (SCA)TrivyDependency vulnerabilities
Security (IaC)CheckovInfrastructure misconfigurations
Security (Container)TrivyContainer image vulnerabilities
Testingpytest, Jest, Vitest, Mocha, Karma (Angular), Playwright (E2E), Maven/Gradle (JUnit), cargo test, go test, dotnet test, CTest, sbt test, swift test, RSpec, PHPUnitTest failures
Coveragecoverage.py, Istanbul, Vitest, JaCoCo, Tarpaulin, go cover, dotnet coverage, gcov/lcov, Scoverage, llvm-cov, SimpleCov, PHPUnit CloverCoverage gaps
DuplicationDuploCode clones, duplicate blocks

All results are normalized to a common format.

Quality Overview

Track quality trends over time with a git-committed quality dashboard - no server or SaaS required.

./lucidshark scan --all --all-files && ./lucidshark overview --update

This creates QUALITY.md at your repo root showing:

  • Health score (0-10) with visual bar
  • Domain status table with trends
  • Issues breakdown by severity
  • Top files by issue count
  • Test coverage
  • Historical trend chart

Add to your CI pipeline to auto-update on merge to main. See docs/help.md for configuration options.

Configuration

LucidShark auto-detects your project. For custom settings, create lucidshark.yml:

version: 1
pipeline:
  linting:
    enabled: true
    tools: [{ name: ruff }]
  type_checking:
    enabled: true
    tools: [{ name: mypy, strict: true }]
  formatting:
    enabled: true
    tools: [{ name: ruff_format }]
  security:
    enabled: true
    tools:
      - { name: trivy, domains: [sca, container] }
      - { name: opengrep, domains: [sast] }
      - { name: gosec, domains: [sast] }   # Go-specific SAST (auto-detected)
  testing:
    enabled: true
    command: "make test"            # Optional: custom command overrides plugin-based runner
    post_command: "make clean"      # Optional: runs after tests complete
    tools: [{ name: pytest }]
  coverage:
    enabled: true
    threshold: 80
    tools: [{ name: coverage_py }]
  duplication:
    enabled: true
    threshold: 10.0
fail_on:
  linting: error
  security: high
  testing: any
ignore_issues:
  - rule_id: CVE-2021-3807
    reason: "Not exploitable in our context"
    expires: 2027-06-01
exclude: ["**/node_modules/**", "**/.venv/**"]

See docs/help.md for the full configuration reference.

CLI Reference

CommandDescription
./lucidshark scan --allRun all quality checks
./lucidshark scan --linting --fixLint and auto-fix
./lucidshark scan --formatting --fixFormat and auto-fix
./lucidshark overview --updateGenerate/update QUALITY.md
./lucidshark initConfigure AI tool integration (Claude Code by default; --cursor, --windsurf, --aider, --all-tools) and generate lucidshark.yml (skip with --no-config)
./lucidshark doctorCheck setup and environment health
./lucidshark validateValidate lucidshark.yml

For the full CLI reference, all scan flags, output formats, and exit codes, see docs/help.md.

Development

To build LucidShark from source:

git clone https://github.com/toniantunovi/lucidshark.git
cd lucidshark

# Install Python dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Build the binary
pyinstaller lucidshark.spec

# The binary will be in the dist/ directory
./dist/lucidshark --version

Documentation

License

Apache 2.0

Reviews

No reviews yet

Be the first to review this server!