Code Guardian MCP server

code-guardian

mcp-name: io.github.LuminariSoftwares/code-guardian

One command that tells you three things about any repo, without running it:

• Safe: is it safe to run?
• Works: will it work?
• Complete: does it have what it needs?

Each is a score out of 100 (higher is better), combined into an Overall score and an A–F grade. Scores come only from deterministic checks with fixed weights: same repo, same version, same output, every time. On top of that:

against a small goal contract.

• Orphan code: functions, classes and modules nothing reachable from the project's entry points uses, judged

what it broke, what to fix next, and whether the scan itself can be trusted (see The verify loop).

• An optional plain-English explanation from a local model, which never adds, removes or rescores a finding.
• A verify loop for AI-assisted changes: run it before and after every change to learn what the change fixed,

It parses the code (ast for Python; json, tomllib and configparser for manifests; regular expressions for secrets) and never executes, imports or installs it. A scan makes no network calls. Python 3.11+, standard library only. Status: 0.3.1 is the current release. The fourth guardian, next to stack-guardian, context-guardian and tool-guardian.

Install

pip install code-guardian-mcp

The distribution is code-guardian-mcp (code-guardian on PyPI is someone else's project); the commands are code-guardian and code-guardian-mcp. To run the MCP server without installing anything: uvx code-guardian-mcp mcp.

From a clone (for the tests):

git clone https://github.com/LuminariSoftwares/code-guardian.git
cd code-guardian
python -m venv .venv
.venv\Scripts\activate          # Windows;  macOS/Linux: source .venv/bin/activate
pip install -e . pytest
python -m pytest -q

30-second example

tests/fixtures/riskyrepo is a small project that trips every scanner. Its key-shaped strings are never stored in the repository; tests/makerisky.py adds them to a copy at test time:

python tests/make_risky.py risky_repo
code-guardian scan risky_repo

Real output:

code-guardian 0.3.1  scan of risky
files: 7 Python, 3 manifests, 2 other (0 skipped, 0 excluded by the goal file)
status: COMPLETE

  Safe       0/100  is it safe to run?           -237
  Works     85/100  will it work?                -15
  Complete  35/100  does it have what it needs?  -65
  Overall   33/100  grade F  (a Safe check is FAIL (exec.shell, obfuscation, secret.key, tls.off): the grade is at most D)

biggest deductions:
  -60  Safe     secret.key FAIL          x3   at deploy/id_rsa:1, risky/settings.py:1, risky/settings.py:2
  -40  Safe     obfuscation FAIL         x1   at risky/loader.py:7
  -30  Safe     exec.shell FAIL          x1   at risky/runner.py:7
  -25  Safe     tls.off FAIL             x1   at risky/network.py:11
  -23  Safe     install.hook WARN        x3   at package.json:5, setup.py:5, setup.py:14

Shortened. The full README is on GitHub.