---

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 <path> 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

Variable	Default	Description
MCP_LOG_LEVEL	info	Log level: debug, info, warn, error

Example:

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

---

Capabilities

Repository Listing (1 tool)

Tool	Description
repolens_list_repositories	List all configured repositories (read-only)

Symbol Search (3 tools)

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

Tool	Description
repolens_find_functions	Find function/method definitions in JS/TS and PHP (supports wildcards like handle*)
repolens_find_classes	Find class definitions (also finds PHP traits)
repolens_find_types	Find interfaces and type aliases (PHP: interfaces only)

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)

Tool	Description
repolens_find_api_routes	Map API endpoints across Express, NestJS, Fastify, Laravel

---

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