repo-context-mcp

repo-context-mcp

Universal MCP server that analyzes any codebase and provides structured context to AI assistants. Dynamic, accurate, and token-efficient.

What's New in v1.8.0

• Bug fix: diff-aware 0L — modified files added to hotfiles now show real line counts instead of 0L.
• section="modified" in get_project_context — dedicated section for git-modified files only (no mixing with oversized).
• depth=1 in read_file_outline — top-level symbols only. Reduces ~450 tokens to ~80 tokens on complex files.
• Multi-name search_symbol — search multiple symbols at once: "handleDelete,handleEdit".
• Fuzzy match indicator in search_symbol — results now show ~ci (case-insensitive), ~sub (substring), ~fuzzy tags. Header shows (fuzzy — no exact match found) when no exact match exists.
• max_files=-1 default limit in search_in_project — when showing all files, max_results defaults to 5 per file (was 30) to avoid token budget blowup. Override with explicit max_results.

See CHANGELOG.md for previous versions.

Quick Setup

Automatic (recommended)

npm install -g repo-context-mcp

# Run the interactive setup wizard
repo-context-setup

The wizard will:

• Detect installed AI tools (Claude Desktop, Cursor, Windsurf, VS Code, Cline, Zed, OpenCode, Codex, Antigravity)
• Let you select which ones to configure
• Safely merge repo-context into their config files (backup created)
• Show a summary of changes

# Alternative: use the --setup flag
repo-context-mcp --setup

# Check current config status (non-interactive)
repo-context-setup --status

Manual Setup

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json / ~/.cursor/mcp.json):

{
	"mcpServers": {
		"repo-context": {
			"command": "npx",
			"args": ["repo-context-mcp"]
		}
	}
}

VS Code (~/Library/Application Support/Code/User/mcp.json on macOS, %APPDATA%\Code\User\mcp.json on Windows):

{
	"servers": {
		"repo-context": {
			"type": "stdio",
			"command": "npx",
			"args": ["repo-context-mcp"]
		}
	}
}

Usage

Tools (12 exposed — optimized for minimal token overhead)

# ─── Project Context ───
get_project_context                                # Full context (default: compact)
get_project_context { "format": "ultra" }          # Ultra-efficient (~165 tokens)
get_project_context { "section": "stack" }         # Specific section only
get_project_context { "section": "endpoints" }     # Sections: stack|structure|endpoints|models|status|hotfiles|modified|imports|annotations
get_project_context { "section": "modified" }      # Git-modified files only (v1.8.0)
get_project_context { "force_refresh": true }      # Force re-analysis

# ─── Smart File Reading (v1.5.2) ───
read_file { "file": "src/server.ts" }              # Smart: full if <200L, outline if >200L
read_file { "file": "src/server.ts", "start_line": 100, "end_line": 150 }  # Range
read_file_outline { "file": "src/server.ts" }                    # Outline: all symbols + line ranges
read_file_outline { "file": "src/server.ts", "depth": 1 }       # Top-level only (~80t vs ~450t) (v1.8.0)
read_file_symbol { "file": "src/server.ts", "symbol": "createServer" }     # Fuzzy match

# ─── Search (v1.5.2+) ───
search_in_file { "file": "src/server.ts", "pattern": "TODO" }                       # In-file search
search_in_file { "file": "src/server.ts", "pattern": "TODO", "context_lines": 3 }   # With context

search_in_project { "pattern": "handleRoute" }                                       # 1-line summary: total matches + top 10 hottest files
search_in_project { "pattern": "export", "file_pattern": "*.tsx" }                  # Filter by glob
search_in_project { "pattern": "TODO", "max_files": 5 }                             # Code detail for top 5 files (sorted: code before docs)
search_in_project { "pattern": "TODO", "max_files": 5, "context_lines": 2 }         # Detail with context (overlapping ranges merged automatically)
search_in_project { "pattern": "TODO", "max_files": 5, "max_results": 10 }          # Max 10 matches per file
# max_files=-1 defaults to 5 matches/file to avoid token blowup (v1.8.0) — override with max_results

# grep replacement (v1.6.6) — all files matching glob, grouped + sorted, respects .gitignore
search_in_project { "pattern": "useState", "file_pattern": "*.ts", "max_files": -1 }
search_in_project { "pattern": "invokeLambda", "file_pattern": "*.tsx", "max_files": -1, "context_lines": 2 }

# exclude docs/markdown from results (v1.7.0)
search_in_project { "pattern": "handleRoute", "exclude_pattern": "*.md" }
search_in_project { "pattern": "TODO", "exclude_pattern": "*.md,docs/**", "max_files": 5 }

# ─── Global Symbol Search (v1.7.0+) ───
search_symbol { "name": "createServer" }                                      # Find symbol across project (fuzzy)
search_symbol { "name": "User", "type": "interface" }                         # Filter by type
search_symbol { "name": "handle", "exported_only": true }                     # Only exported symbols
search_symbol { "name": "handleDelete,handleEdit" }                           # Multi-name search (v1.8.0)

# ─── File Listing (v1.5.2) ───
list_files                                          # Project root
list_files { "path": "src", "pattern": "*.ts" }     # Filtered

# ─── Annotations ───
annotate { "action": "list" }
annotate { "action": "add", "category": "businessRules", "text": "..." }
annotate { "action": "remove", "category": "gotchas", "index": 0 }

# ─── Diagnostics (v1.6.1) ───
get_diagnostics                                     # Auto-detects language, runs checker, returns ONLY fatal errors

# ─── Docs ───
generate_project_docs                               # Force regenerate .repo-context/

Resources (Zero Token Cost!)

MCP Resources are automatically available to AI - no tool call needed:

Resource	Description
repo://context/summary	~50 token summary
repo://context/full	Complete compact context
repo://context/stack	Languages & frameworks
repo://context/structure	Folders & entry points
repo://context/api	API endpoints
repo://context/models	Data models
repo://context/hotfiles	Complex/oversized files
repo://context/annotations	Business rules & gotchas
repo://context/imports	Internal dependency graph
repo://context/outlines	All file outlines (symbols + lines)
repo://context.json	Full JSON (programmatic)

Output Formats

Minimal (~50 tokens)

my-app:typescript+nextjs [src/app/components/lib] entry:src/index.ts

Ultra (~165 tokens)

my-app|typescript|nextjs
[src:45(⚠page.tsx:1200L) app:20 components:15 lib:8]
→src/index.ts,src/app/page.tsx
API(12):G:/api/users P:/api/auth
M(5):User,Post,Comment
⚠3hot|hub:store/index.ts(←12)|rules:2|gotchas:1
[docs|test:25|docker|ci:github]

Compact (~350 tokens) - Default

# my-app (typescript)
A modern web application

Stack: typescript, Next.js, React, pnpm
Deps: next, react, prisma, zod

Structure:
  src/ (45) - Source code ⚠page.tsx:1200L
  app/ (20) - Next.js app router
  components/ (15) - UI components
Entry: src/index.ts, src/app/page.tsx

API (12):
  GET /api/users → src/app/api/users/route.ts:5
  POST /api/auth → src/app/api/auth/route.ts:10

Models (5):
  User (model): id, email, name...
  Post (model): id, title, content...

⚠ Hot Files (3):
  src/app/page.tsx (1200L) - oversized
  src/store/index.ts (800L) - oversized,high-imports

Import hubs: store/index.ts(←12), utils/api.ts(←9)
Orphans: legacy/parser.ts, utils/deprecated.ts

📋 Business Rules:
  - Schedules: ≥1min separation
⚠ Gotchas:
  - page.tsx: 1200+ lines, read by sections

Status: tests:25 | docker | ci:github | todos:3

Zero-Token Auto-Docs (v1.3.0)

On startup, the MCP generates a .repo-context/ directory with rich markdown docs:

your-project/
├── .repo-context/
│   ├── ARCHITECTURE.md     ← Stack, frameworks, deps, patterns
│   ├── COMPONENTS.md       ← Folders, entry points, hot files, endpoints
│   ├── MODELS.md           ← All data models with fields
│   ├── IMPORTS.md          ← Hub files, orphans, mermaid diagram
│   ├── OUTLINES.md         ← All symbols with line ranges (v1.5.0)
│   └── STATUS.md           ← TODOs, CI/CD, Docker, annotations

The AI reads these files naturally — 0 MCP token cost. A file watcher keeps them updated automatically when you change code (5s debounce).

Hot Files Detection (v1.2.0)

Automatically identifies problematic files based on:

Criterion	Threshold	Why it matters
Lines of code	> 300	File too large to navigate easily
Import count	> 15	High coupling
Export count	> 20	Too many responsibilities
TODO density	> 3	Concentrated tech debt

Import Graph (v1.2.0)

Analyzes internal import/require statements to build a dependency map:

• Hub files: Most-imported files (core of the system)
• Orphan files: Files nobody imports (possible dead code)
• Mermaid output: Visual diagram with get_project_imports { "format": "mermaid" }

Annotations (v1.2.0)

Manage project knowledge via MCP tools — no manual file editing needed:

# Add a business rule
add_annotation { "category": "businessRules", "text": "Orders require payment before shipping" }

# Add a gotcha
add_annotation { "category": "gotchas", "text": "UserService.ts has 2000+ lines, read by sections" }

# List all with indices
list_annotations

# Remove by index
remove_annotation { "category": "gotchas", "index": 0 }

Annotations are persisted in .repo-context-notes.json and included in all context formats.

Smart Caching

• In-memory: 30s TTL for repeated calls
• Disk cache: 1h TTL with file hash validation
• Auto-invalidate: When config files change (package.json, etc.)

The cache file .repo-context.json is stored in your project root. Add to .gitignore.

Supported Languages

Language	Deps	Endpoints	Models
TypeScript/JS	package.json	Express, Fastify, Hono, NestJS, Next.js	Interfaces, Types, Classes
Python	requirements.txt, pyproject.toml	FastAPI, Flask, Django	Pydantic, Dataclasses
Rust	Cargo.toml	Actix, Axum, Rocket	Structs, Enums
Go	go.mod	Gin, Echo, Fiber	Structs
Java/Kotlin	pom.xml, build.gradle	Spring	Classes, Records
PHP	composer.json	Laravel, Symfony	Classes
Ruby	Gemfile	Rails, Sinatra	ActiveRecord
C#/.NET	.csproj	ASP.NET	Classes, Records
Swift	Package.swift	Vapor	Structs, Classes
Dart	pubspec.yaml	-	Classes

Analysis Includes

• Tech Stack: Languages, frameworks, dependencies, package manager
• Structure: Folders with descriptions, entry points, config files, largest file per folder
• API Endpoints: REST routes, GraphQL operations
• Data Models: Interfaces, types, schemas, database models
• Architecture: MVC, Clean Architecture, Serverless, etc.
• Status: TODOs, tests, CI/CD, Docker
• Hot Files: Oversized, high-import, TODO-dense files
• Import Graph: Hub files, orphan files, dependency map
• Annotations: Business rules, gotchas, warnings (managed via MCP)

Environment Variables

Variable	Description	Default
REPO_CONTEXT_ROOT	Project root override	process.cwd()

Contributing

git clone https://github.com/anomalyco/repo-context-mcp
cd repo-context-mcp
npm install
npm run build

Adding Language Support

• src/detectors/language.ts - Language detection
• src/detectors/endpoints.ts - Endpoint patterns
• src/detectors/models.ts - Model patterns

Adding Detectors

• src/detectors/hotfiles.ts - Hot file thresholds
• src/detectors/imports.ts - Import graph patterns
• src/detectors/annotations.ts - Annotation manager

License

MIT

Use less tokens. Know more. Ship faster.