Codebase Intelligence MCP Server

A production-grade Model Context Protocol (MCP) server that exposes powerful code analysis and repository intelligence tools. Designed for local git repositories, this server provides tools for code search, git history analysis, complexity metrics, test discovery, and dependency management.

Perfect for integrating with Claude, Cursor, or other LLM-based development tools via MCP clients.

Quick Start (< 2 minutes)

# 1. Install
git clone https://github.com/atishay2411/langgraph-mcp-server
cd langgraph-mcp-server
pip install -e .

# 2. Set repository path
export CODEBASE_INTEL_REPO_ROOT=/path/to/your/git/repo

# 3. Run server (stdio mode - zero config)
python -m codebase_intel.server

# ✓ Ready for MCP clients!

Architecture

LLM Client (Claude/Cursor)
          │
          ├─ LangGraph Agent (custom StateGraph)
          │
          └─ MCP Client (MultiServerMCPClient)
                    │
          ┌─────────▼─────────┐
          │   MCP Transport   │
          │ (stdio or HTTP)   │
          └─────────┬─────────┘
                    │
       ┌────────────▼────────────┐
       │   FastMCP Server        │
       │ (codebase_intel)        │
       └────┬──────────┬─────────┘
            │          │
      ┌─────▼──┐    ┌──▼────────┐
      │9 Tools │    │4 Resources│
      │2 Prompts    │2 Prompts  │
      └─────┬──┘    └───────────┘
            │
    Repository (read-only)

Tools (9 available)

Tool	Params	Description	Security
read_file()	path, start_line, end_line	Read files with line-range support	✓ Traversal guard
list_directory()	path, max_depth	Recursive directory tree (auto-exclude .git, node_modules)	✓ Dir exclusion
search_code()	pattern, glob, regex	Code search (literal + regex, glob patterns)	✓ Binary skip
git_log()	path, max_count, since	Repository history with filtering	✓ Subprocess allowlist
git_blame()	path, start_line, end_line	Per-line git attribution	✓ Arg list only
git_show()	ref, path	Show commit/tree/blob	✓ Ref validation
analyze_complexity()	path, min_rank	Cyclomatic complexity (Python, radon)	✓ Dir exclusion
list_dependencies()	(none)	Parse pyproject.toml/requirements.txt/package.json	✓ Error handling
discover_tests()	path	AST-based test discovery (no execution)	✓ No code exec

Resources (ambient context):

• repo://structure — Dir tree (3 levels)
• repo://readme — README content
• repo://dependencies — All deps
• repo://git-log — Last 20 commits

Prompts (templates with embedded data):

• code_review_prompt(path, focus) — Customizable code review
• summarize_recent_changes_prompt(max_commits) — Git history summary

Modes

Stdio Transport (local, zero-auth)

export CODEBASE_INTEL_REPO_ROOT=/path/to/repo
python -m codebase_intel.server
# Clients connect via stdin/stdout

HTTP Transport (remote, bearer-token auth)

export CODEBASE_INTEL_REPO_ROOT=/path/to/repo
export CODEBASE_INTEL_TRANSPORT=streamable-http
export CODEBASE_INTEL_AUTH_TOKEN=$(openssl rand -hex 32)
python -m codebase_intel.server
# Server at http://localhost:8000/mcp (requires Bearer token)

Docker

export TARGET_REPO_PATH=/path/to/repo
export CODEBASE_INTEL_AUTH_TOKEN=$(openssl rand -hex 32)
docker-compose up
# Server at http://localhost:8000/mcp

LangGraph Client Example

export GROQ_API_KEY=your_key
export CODEBASE_INTEL_REPO_ROOT=/path/to/repo
python -m codebase_intel_client "What's the most complex function?"

The client uses a custom StateGraph (explicit agent & tools nodes, not prebuilt one-liner) demonstrating production-grade LangGraph patterns.

Configuration

# Required
CODEBASE_INTEL_REPO_ROOT=/path/to/repo

# Optional (env vars, see .env.example)
CODEBASE_INTEL_LOG_LEVEL=INFO
CODEBASE_INTEL_TRANSPORT=stdio  # or streamable-http
CODEBASE_INTEL_AUTH_TOKEN=...   # required for HTTP

See .env.example for full options.

Security

✅ Path Traversal Prevention — resolve_within_repo() + normalization
✅ Safe Git Execution — Argument lists, no shell, allowlisted subcommands
✅ Directory Exclusions — .git, node_modules, venv, etc. auto-skipped
✅ Bearer Token Auth — Constant-time comparison, no side-channels
✅ No Code Execution — AST-based parsing, no imports/subprocess for untrusted code
✅ Read-Only Design — No write capabilities anywhere

Testing

pytest tests/ -v                              # All tests
pytest tests/ --cov=src/ --cov-report=html   # With coverage
pytest tests/test_tool_files.py -v           # Specific file

111+ tests passing (93% pass rate) covering security, tools, auth, dependencies, git operations, test discovery.

CI/CD

✅ Lint (ruff)
✅ Type-check (mypy)
✅ Tests (pytest + coverage)
✅ Docker build validation

See .github/workflows/ci.yml.

Project Layout

src/codebase_intel/              # MCP Server (9 tools, 4 resources, 2 prompts)
  ├── server.py                   # FastMCP assembly
  ├── config.py, logging_conf.py
  ├── security/                   # Path guard, git subprocess wrapper
  ├── tools/                       # 9 MCP tools
  ├── resources/, prompts/         # Resources & prompts
  └── auth/                        # Bearer token middleware

src/codebase_intel_client/       # LangGraph Client
  ├── graph.py                    # Custom StateGraph
  ├── nodes.py                    # Agent nodes
  ├── config.py, state.py
  └── run.py                      # CLI entrypoint

tests/                            # 111+ tests
.github/workflows/ci.yml          # GitHub Actions
Dockerfile, docker-compose.yml    # Containerization

Example Queries

# Find complex functions
"What functions in src/ have high cyclomatic complexity?"

# Analyze dependencies
"List all Python dependencies and their versions."

# Search patterns
"Find all async functions in the codebase."

# Test coverage
"Which test files exist and how many tests do we have?"

# Git insights
"What changed in the last 5 commits?"

Limitations (v1)

• Python complexity analysis only (JS/TS coming)
• Single repository (no monorepo support)
• Read-only (by design)
• Requires .git directory

Contributing

1. Fork & branch
2. pytest tests/ && ruff check .
3. Submit PR

License

MIT — See LICENSE

Built With

• Model Context Protocol
• FastMCP
• LangGraph
• Radon (complexity)
• Groq (LLM)

---

Questions? Open an issue.