Skip to main content

DevInsight MCP

License: MIT PyPI Python 3.10+ MCP Tests

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

Install from PyPI (easiest)

pip install devinsight-mcp
devinsight-mcp        # runs the server over stdio

Or run it without installing, using uv:

uvx devinsight-mcp

From source (development)

Clone the repository

git clone https://github.com/AzalHoseinian/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

Run the tests

pip install pytest
python -m pytest -q

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

Easiest (uses uvx):

{
  "mcpServers": {
    "devinsight": {
      "command": "uvx",
      "args": ["devinsight-mcp"]
    }
  }
}

From a clone:

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

If you installed the command with pip install . or pip install devinsight-mcp, you can point Claude Desktop at it instead:

{
  "mcpServers": {
    "devinsight": {
      "command": "/absolute/path/to/devinsight-mcp/.venv/bin/devinsight-mcp"
    }
  }
}

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

or

Review all TODOs in this repository.


Security notes

DevInsight is read-only: it never writes, deletes or executes anything from the repositories it scans. The only external command it runs is git log with a fixed argument list.

It can, however, read any path you give it that your user account can read, so only connect it to clients you trust. It does not follow symlinked directories when drawing the tree, and it skips lock files and binaries in statistics.


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/
├── devinsight_mcp.py      # implementation (installed as the `devinsight-mcp` command)
├── server.py              # thin launcher for `mcp dev server.py`
├── tests/
├── .github/workflows/test.yml
├── pytest.ini
├── requirements.txt
├── pyproject.toml
├── README.md
├── docs/
│   ├── demo.gif
│   ├── demo.tape
│   └── demo_cli.py
└── .gitignore

Roadmap

  • Repository statistics
  • TODO scanner
  • Git history summaries
  • Large file detection
  • Repository tree resource
  • TODO review prompt
  • Overall repo health score
  • Tech stack detection
  • Test suite and CI
  • Optional allowlist of readable root directories
  • Lint summary tool
  • GitHub Issues integration
  • Dependency vulnerability analysis
  • Pull request insights

Tech Stack

  • Python
  • Anthropic MCP Python SDK
  • Git
  • Claude Desktop
  • Model Context Protocol (MCP)

Contributing

Contributions, suggestions, and feedback are welcome.

If you'd like to improve DevInsight, feel free to open an issue or submit a pull request.


License

MIT — see LICENSE.

Metadata

Release files for devinsight-mcp 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for devinsight-mcp 1.0.2
File Size Uploaded Provenance Actions
devinsight_mcp-1.0.2.tar.gz 14.2 kB Without provenance Details for devinsight_mcp-1.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for devinsight-mcp 1.0.2
File Interpreter ABI Platform Actions
devinsight_mcp-1.0.2-py3-none-any.whl Python 3 none any Details for devinsight_mcp-1.0.2-py3-none-any.whl

Total release size: 28.1 kB

Release files / devinsight_mcp-1.0.2.tar.gz

Download URL devinsight_mcp-1.0.2.tar.gz
Size 14.2 kB
Tags Source
SHA-256 checksum
How to use checksums
01ff5454ec0452d83d0598880aa42a88c551e62b7f84cb800c9310ac7c98df9c
BLAKE2b-256 checksum
How to use checksums
4fef5b4d9167d77838740aba5e50d1b1c3ad02dd689d8713c4bb4eee073b1d09
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.7

Release files / devinsight_mcp-1.0.2-py3-none-any.whl

Download URL devinsight_mcp-1.0.2-py3-none-any.whl
Size 13.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3dca9b820a572d3bcbfc8a375fb6d24d5bad8dd70508fe0572f0b8f7f4376709
BLAKE2b-256 checksum
How to use checksums
2af04a85d78ea39c883967baf5d0cd7f6246879c8ce6e94d2c79541bcad065e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.7

Security for devinsight-mcp 1.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page