Codebase Health Agent MCP

A multi-agent AI system that audits any code repository and produces a clean, styled health report (Markdown + PDF). Point it at a project folder, and three specialized agents coordinate to scan the structure, review the code, and write the report.

Built with LangGraph, the Model Context Protocol (MCP), and Google Gemini.

---

✨ What it does

You give it a path to a codebase. It inspects the project across several dimensions and hands you a report:

• Structure — file counts, languages, and which key files are present/missing (README, tests, requirements, .gitignore).
• Git activity — total commits, last commit, contributors, and change hotspots.
• Code review — real issues grouped by severity (HIGH / MEDIUM / LOW), each with a location, the problem, and a suggested fix.
• Verdict — a plain-English summary, a health score (0–10), and the top 3 fixes.

The code review works at two levels:

Level	How	Catches
Level 2 — Static analysis	Runs ruff, bandit, radon	Style issues, security flaws (hardcoded secrets, eval), complexity
Level 3 — LLM reasoning	The Analyst agent reads the code	Things linters can't catch: inefficient logic (e.g. O(n²) loops), fragile logic, missing edge cases, poor design

---

🏗️ Architecture

A StateGraph orchestrator (fixed pipeline) coordinates three specialized ReAct agents, each with its own MCP tools:

                 USER: "audit /path/to/project"
                              │
                    ┌─────────▼──────────┐
                    │   StateGraph        │   (dumb orchestrator; fixed order)
                    │   orchestrator      │   holds shared AuditState
                    └─────────┬──────────┘
       START → SCANNER → ANALYST → REPORTER → END
                  │          │          │
             file_system  code_analysis  file_system
             + git_tools   + read_file   (write + PDF)
             (MCP server)  (MCP server)  (MCP server)

  Each agent is a create_agent (ReAct) that thinks and calls its own tools.
  Shared state (AuditState) flows through the nodes.

• Orchestrator = StateGraph — pure wiring, no LLM. The order is always scanner → analyst → reporter, so a deterministic graph is used (not an LLM router).
• Each node = a ReAct agent (langchain.agents.create_agent) that decides how to do its own job using its own filtered set of MCP tools.
• State passing — the Scanner's findings reach the Analyst (and both reach the Reporter) through a shared, typed AuditState.

The three MCP servers (tool layer)

Server	Tools	Used by
file_system	read_file, write_file (auto-PDF), append_file, list_files, walk_directory	Scanner, Analyst, Reporter
code_analysis	run_complexity (radon), run_security (bandit), run_lint (ruff)	Analyst
git_tools	git_summary, recent_commits, most_changed_files	Scanner

---

📁 Project structure

codebase_health_agent/
├── agent.py              # CLI entry point
├── graph.py             # StateGraph orchestrator: MCP setup, nodes, wiring
├── state.py             # AuditState (typed shared state)
├── config.py            # Model + agent system prompts
├── parsing.py           # Extracts health score + structured issues from text
├── test_health_agent.py # Unit tests (stdlib unittest)
├── requirements.txt
├── agents/
│   ├── scanner.py       # build_scanner(tools)
│   ├── analyst.py       # build_analyst(tools)
│   └── reporter.py      # build_reporter(tools)
├── servers/             # MCP servers (run as subprocesses over stdio)
│   ├── file_system.py   # file I/O + styled Markdown→PDF generator
│   ├── code_analysis.py # radon / bandit / ruff wrappers
│   └── git_tools.py     # git history inspection
└── reports/             # generated reports (.md + .pdf)

---

🚀 Setup

1. Install dependencies

pip install -r requirements.txt

Requires the code-analysis CLI tools (ruff, bandit, radon), the agent stack (langgraph, langchain, langchain-google-genai, mcp, langchain-mcp-adapters), and fpdf2 for PDF output.

2. Add your API key

Create a .env file in the project root:

GOOGLE_API_KEY=your_gemini_api_key_here

Get a free key from Google AI Studio.

The model is set in config.py (gemini-flash-lite-latest by default). The design is model-agnostic — you can swap in any LangChain chat model (e.g. Groq) by changing only config.py.

---

▶️ Usage

Run from the project root, passing the path to the repo you want to audit:

python3 agent.py /path/to/some/project

If the path has spaces, quote it:

python3 agent.py "/path/with spaces/my-project"

Output is written to reports/<project-name>-health-report.md and a styled .pdf.

Example report (excerpt)

Health 5.5/10 | 5 Python files | 2 High, 2 Medium, 1 Low | Tests: None

## Code Review
### HIGH
- servers/file_system.py:184 — Unsanitized paths allow directory traversal — resolve against a safe root
### MEDIUM
- agent.py:41 — Hardcoded "python3" breaks on Windows — use sys.executable

---

🧪 Tests

Pure logic (parsing, PDF generation, graph wiring) is covered by unit tests — no API calls needed:

python3 -m unittest test_health_agent -v

---

🛠️ How it was built

This project demonstrates several concepts:

• Multi-agent supervision — a fixed StateGraph coordinating specialized agents.
• MCP (Model Context Protocol) — tools exposed by standalone servers, connected to agents via langchain-mcp-adapters.
• Tool filtering — each agent only receives the tools relevant to its role.
• Robust parsing — free-text LLM output is parsed into a typed score + issue list, with a normalizer that handles both string and structured (block-list) model responses.
• Model portability — swapping providers touches only one file.

---

⚠️ Notes & limitations

• Free-tier model quotas (Gemini/Groq) can rate-limit large repos; tool outputs and file reads are capped to stay within budget. A paid tier removes this constraint.
• Code analysis currently targets Python projects (uses ruff/bandit/radon).
• The report is a summary, not an exhaustive audit — it surfaces the highest-impact issues.

---

📜 License

MIT — free to use and modify.