repo-lens-mcp

Why Use This?

The problem: You're working in your frontend repo and need to find a backend API endpoint. Or you're debugging and need to find where a function is defined across your monorepo. With Claude Code, you can search the current repository, but what about your other local projects?

The solution: Repo Lens lets you declare your repositories once in a YAML config file — or search any directory ad-hoc — and search across all of them simultaneously using AST-based structural search. Find the exact function signature, class definition, or API route you need without leaving your current context.

Use Cases

• Frontend + Backend development: Search backend API routes while working in your frontend repo
• PHP + JS/TS projects: Find PHP classes, traits, and interfaces alongside TypeScript types
• Microservices architecture: Find function definitions across multiple services
• Monorepo navigation: Search across packages without switching directories
• Code exploration: Understand how different projects in your ecosystem connect

Quickstart

npx repo-lens-mcp

Key Features

AST-Based Intelligence

Unlike grep-style text search, Repo Lens uses **ast-grep** (written in Rust) to parse code into Abstract Syntax Trees:

• Structural accuracy: Distinguish between `class User` and `const User`
• Export awareness: Find only exported functions, or include private ones
• Signature extraction: Get full function signatures, not just names

Zero-Friction Search

Search any directory instantly with the `paths` parameter — no configuration required:

• Pass directory paths directly to any search tool
• Declare persistent repos in `repolens.yaml` with aliases for repeated use
• Mix both: registered repos + ad-hoc paths in the same query

Multi-Repository Search

Declare your repositories once and search them all at once:

• Static YAML config — declare once, search always
• Filter by repository alias or search all
• Results include repository context

API Route Discovery

Map all API endpoints across Express, NestJS, Fastify, and Laravel projects. Find that `/users/:id` endpoint in seconds.

Installation

Claude Desktop / VS Code (Recommended)

Add this to your `claude_desktop_config.json` (or VS Code MCP settings):

{
  "mcpServers": {
    "repo-lens": {
      "command": "npx",
      "args": ["-y", "repo-lens-mcp", "--config", "/home/user/repolens.yaml"]
    }
  }
}

Restart Claude, and you're ready to go.

Local Development

git clone https://github.com/YohannHommet/repo-lens-mcp.git
cd repo-lens-mcp
pnpm install
pnpm build
pnpm dev

Configuration

Config File (`repolens.yaml`)

Create a YAML config file declaring your repositories:

# repolens.yaml
repositories:
  - path: ~/projects/backend-api
    alias: backend
  - path: ~/projects/frontend-app
    alias: frontend
  - path: ~/projects/shared-lib

`~` is expanded to your home directory automatically.

Config Path Resolution

1. `--config ` CLI argument (explicit — fails if file not found)

2. Default: `~/.config/repo-lens-mcp/repolens.yaml` (graceful — returns empty if not found, ad-hoc paths still work)

Environment Variables

Example:

{
  "env": {
    "MCP_LOG_LEVEL": "debug"
  }
}

Capabilities

Repository Listing (1 tool)

Symbol Search (3 tools)

AST-based structural search powered by ast-grep. Supports JavaScript/TypeScript and PHP (classes, traits, interfaces, enums, functions, methods, constants):

All search tools accept:

• `paths` — Ad-hoc directory paths to search (comma-separated, no registration needed)
• `repoFilter` — Filter registered repositories by alias

API Route Discovery (1 tool)

Usage Examples

1. Search Any Directory (No Configuration)

> "Find all functions starting with 'handle' in my backend"

repolens_find_functions(paths: "/home/user/projects/backend", name: "handle*")

2. List Configured Repos

> "What repos are available?"

repolens_list_repositories()

3. Find an API Endpoint

> "Find the Express route that handles POST requests to /login"

repolens_find_api_routes(repoFilter: "backend", method: "POST", pathPattern: "/login")

4. Find a Specific Class

> "Where is the UserService class defined?"

repolens_find_classes(name: "UserService")

What About Text Search / File Operations?

Repo Lens focuses on multi-repository AST-based search. For text search and file operations within your current repository, use Claude Code's built-in tools (Grep, Read, Glob) which are optimized for single-repo use.

This separation keeps Repo Lens fast and focused on what it does best: cross-repository structural code intelligence.

License

AGPL-3.0

This software is free to use. If you modify and distribute it (or run it as a network service), you must share your source code under the same license.

Built with care by Yohann Hommet