# Codebase Intelligence MCP Server

![CI](https://github.com/atishay2411/langgraph-mcp-server/actions/workflows/ci.yml/badge.svg)
![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)

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)

```bash
# 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)
```bash
export CODEBASE_INTEL_REPO_ROOT=/path/to/repo
python -m codebase_intel.server
# Clients connect via stdin/stdout
```

### HTTP Transport (remote, bearer-token auth)
```bash
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
```bash
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

```bash
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

```bash
# 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

```bash
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

```bash
# 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](LICENSE)

## Built With

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP](https://github.com/jlowin/fastmcp)
- [LangGraph](https://github.com/langchain-ai/langgraph)
- [Radon](https://radon.readthedocs.io/) (complexity)
- [Groq](https://groq.com/) (LLM)

---

**Questions?** Open an [issue](https://github.com/atishay2411/langgraph-mcp-server/issues).