MCP 服务器

Codebase Intelligence MCP Server

A production-grade MCP server for local git repositories that provides tools for code search, git history analysis, complexity metrics, test discovery, and dependency management.

README

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?"