MCP 服务器

DevInsight MCP

Enables Claude to inspect, analyze, and grade local Git repositories with tools for stats, TODO scanning, git history, large file detection, health scores, and tech stack fingerprinting.

README

DevInsight MCP

A lightweight Model Context Protocol (MCP) server that gives Claude the ability to inspect, analyze, and grade local Git repositories.

Built with Anthropic's official Python MCP SDK, DevInsight demonstrates all three MCP primitives — Tools, Resources, and Prompts — through practical developer workflows: language stats, TODO tracking, git history, large-file detection, an overall repo health score, and technology-stack fingerprinting.

Demo

DevInsight demo

A live session driving the DevInsight tools against this very repository — repo stats, TODO scan, and large-file detection.

✨ Features

📊 Repository statistics — languages, file counts, line counts
📝 Scan projects for TODO, FIXME, HACK, and XXX
📜 Summarize recent Git commits (author, date, message, +/- lines)
📁 Detect oversized source files that are due for a refactor
🩺 Score overall repository health (README/LICENSE/tests/git, TODO density, file size) with concrete recommendations
🧰 Fingerprint a project's tech stack — languages, frameworks, databases, package managers, CI/CD, deployment
🌳 Browse repositories through an MCP Resource
🤖 Review and prioritize TODOs using an MCP Prompt

Scanning automatically skips noise: .git, .github, node_modules, virtualenvs, build/cache directories, lock files, and binary assets — see Repository Scanning below.

Why DevInsight?

Developers spend a surprising amount of time manually inspecting repositories:

searching for TODOs
checking Git history
counting files
finding oversized modules
judging whether a project is in good shape before diving in

DevInsight exposes these tasks as MCP tools so Claude can perform them for you, directly in conversation.

Instead of manually searching your project, you can simply ask:

"Summarize the last 10 commits."

"Find every TODO and tell me which ones are most important."

"Which files are becoming too large?"

"How healthy is this repo, and what should I fix first?"

"What's the tech stack of this project?"

Installation

Clone the repository

git clone https://github.com/AzamHosseinian/devinsight-mcp.git
cd devinsight-mcp

Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate

Windows:

.venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

Try it with the MCP Inspector

The easiest way to test the server standalone is with the official MCP Inspector:

mcp dev server.py

The Inspector lets you invoke every Tool, inspect Resources, test Prompts, and debug raw responses — all in the browser, no client app required.

Claude Desktop Setup

Add DevInsight to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "devinsight": {
      "command": "/absolute/path/to/devinsight-mcp/.venv/bin/python3",
      "args": [
        "/absolute/path/to/devinsight-mcp/server.py"
      ]
    }
  }
}

Using the virtual environment's Python interpreter (rather than a bare python) ensures Claude Desktop finds the mcp package regardless of what's active in your shell.

Fully quit and reopen Claude Desktop afterwards — it only reads this file on startup. Then try:

Use repo_stats on ~/projects/my-app

Review all TODOs in this repository.

Available Tools

Primitive	Name	Purpose
Tool	`repo_stats`	Language and line-count breakdown
Tool	`find_todos`	Find TODO / FIXME / HACK / XXX comments
Tool	`git_log_summary`	Summarize recent Git activity
Tool	`find_large_files`	Detect files exceeding a configurable size
Tool	`repo_health`	Overall 0-100 health score with recommendations
Tool	`tech_stack`	Detect languages, frameworks, databases, package managers, CI/CD, deployment
Resource	`repo://tree/{path}`	Render the repository tree
Prompt	`review_todos`	Ask Claude to prioritize TODOs

Usage examples

repo_stats(path="~/projects/my-app")
→ { "total_files": 142, "total_lines": 18734,
    "by_extension": { ".ts": {...}, ".tsx": {...}, ... } }

find_todos(path=".", max_results=50)
→ [ { "file": "src/api.ts", "line_number": 42,
      "tag": "TODO", "text": "handle retry backoff" }, ... ]

git_log_summary(path=".", count=5)
→ { "commits": [ { "hash": "a1b2c3d4", "author": "...", 
      "date": "2026-07-10", "message": "...", 
      "insertions": 12, "deletions": 3 }, ... ] }

find_large_files(path=".", threshold_lines=300)
→ [ { "file": "src/legacy/parser.py", "lines": 812 }, ... ]

repo_health(path=".")
→ { "score": 78,
    "checks": { "has_git": true, "has_readme": true,
                "has_license": true, "has_tests": false },
    "recommendations": [ "Add a test suite ..." ] }

tech_stack(path=".")
→ { "languages": ["Python"], "frameworks": ["FastAPI"],
    "databases": ["PostgreSQL"], "package_managers": ["pip"],
    "ci_cd": ["GitHub Actions"], "deployment": ["Docker"] }

Repository Scanning

Statistics tools (repo_stats, find_todos, find_large_files, repo_health) walk the repo while pruning directories as they go — ignored subtrees are never descended into.

Ignored directories: .git, .github, node_modules, venv, .venv, env, __pycache__, dist, build, .next, .nuxt, .svelte-kit, .idea, .vscode, target, coverage, htmlcov, .pytest_cache, .mypy_cache, .cache

Excluded from statistics: lock files (package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock, Cargo.lock, Gemfile.lock, composer.lock, uv.lock, bun.lockb) and binary assets (.png, .jpg, .jpeg, .gif, .pdf, .zip, .exe, .dll) — these are real project content, but noise in line/size stats.

tech_stack looks at these same files directly, since a lock file's mere presence is a useful package-manager signal.

Architecture

               Claude Desktop
                      │
                      ▼
             DevInsight MCP Server
                      │
      ┌───────────────┼───────────────┐
      ▼               ▼               ▼
 Git Repository   File System     Git History

Project Structure

devinsight-mcp/
├── server.py
├── requirements.txt
├── pyproject.toml
├── README.md
├── docs/
│   ├── demo.gif
│   ├── demo.tape
│   └── demo_cli.py
└── .gitignore