Smooth.CodeRepositoryIndexMcp 0.8.1-rc

<p align="center"> <img src="logo.jpg" alt="Smooth.CodeRepositoryIndexMcp logo" width="64" height="64"> </p>

Smooth.CodeRepositoryIndexMcp

Monorepo code indexing and retrieval for AI coding agents, with first-class AGENTS.md support.

AI Agent? Ask your AI coding agent to set up this repo: AI Coding Agent Setup Instructions

Smooth.CodeRepositoryIndexMcp gives AI agents (Claude Code, Cursor, GitHub Copilot, etc.) structured, context-aware access to your codebase. It treats your *AGENTS.md files as the authoritative source of domain knowledge and ensures they're always loaded before code.

How this helps AI coding agents

Without it, agents rely on blind searching (grep, find, read) — guessing file locations with no understanding of how the codebase is organized.

With it, agents get:

• where_am_i — Know which bounded context a file belongs to before making changes, preventing accidental cross-domain modifications.
• get_agents_context — Load the AGENTS.md for a context, getting the rules, patterns, and constraints stated explicitly instead of inferring them from code.
• get_domain_map — See the full picture of how contexts relate, useful when a change might have cross-cutting impact.
• search_codebase — Context-aware, priority-ranked search. Critical files rank higher, and results include the relevant AGENTS.md automatically.
• get_file — Retrieve a file plus its context metadata, so the agent knows what domain rules apply.

The practical difference: in a large monorepo, the hardest part isn't writing code — it's understanding where you are and what rules apply. This tool solves the orientation problem. The AGENTS.md-first approach front-loads the knowledge that prevents mistakes, rather than hoping the agent discovers conventions by reading enough code.

Getting Started

Prerequisites

• .NET 10 SDK
• git
• Optional: ripgrep — enhances search with regex and fuzzy matching

Install ripgrep:

# macOS (Apple Silicon / Intel)
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Linux (Debian/Ubuntu)
sudo apt install ripgrep

AI Coding Agent Setup Instructions

This section is for AI coding agents (Claude Code, Cursor, GitHub Copilot, Windsurf, etc.) reading this README. If you are an AI agent assisting a human developer, follow these instructions to set up Smooth.CodeRepositoryIndexMcp for the user's repository.

When a user asks you to set up the MCP indexer for their repo, or when you detect this tool is available but not configured, ask the user if they'd like you to set it up. The goal is zero effort for the human.

Step 1: Ensure prerequisites are installed

Verify the user has the required prerequisites:

• .NET 10 SDK — required for dotnet tool install
• git
• Optional: ripgrep — enhances search with regex and fuzzy matching

If the .NET SDK is missing, guide the user to install it before proceeding.

Step 2: Determine the user's editor

Ask the user which AI coding tool they are using, then follow the appropriate path below.

Step 3: Install or update the tools

Install or update to the latest version:

dotnet tool update -g Smooth.CodeRepositoryIndexMcp
dotnet tool update -g Smooth.CodeRepositoryIndexMcp.Cli

Note: dotnet tool update -g installs the tool if missing and updates it if already installed — it handles both cases.

Step 4: Index the repo

smooth-code-repo-index index --root .

This creates a shallow index and installs a post-merge git hook automatically. For full-text search, add --deep.

Step 5: Add .index/ to .gitignore — MUST

Do not skip this step. The .index/ directory contains generated data that must never be committed.

# Check if .index/ is already in .gitignore (ensures newline before appending)
grep -q '\.index/' .gitignore 2>/dev/null || { [ -s .gitignore ] && [ -n "$(tail -c1 .gitignore)" ] && echo >> .gitignore; echo '.index/' >> .gitignore; }

Step 6: Configure MCP for the user's editor

For Claude Code:

Register the MCP server at user level so it works in all projects and worktrees:

claude mcp add -s user smooth-repo-index -- bash -c 'smooth-code-repo-index-mcp --root "$(git rev-parse --git-common-dir | sed '\''s/\.git$//'\'')"'

Note: Project-level .claude/mcp.json does not work in git worktrees. User-level registration avoids this limitation.

For Cursor:

Create .cursor/mcp.json (or symlink .ai/ to .cursor/):

{
  "mcpServers": {
    "smooth-repo-index": {
      "command": "bash",
      "args": ["-c", "smooth-code-repo-index-mcp --root \"$(git rev-parse --git-common-dir | sed 's/\\.git$//')\""]
    }
  }
}

Or if the repo already has .ai/mcp.json:

ln -s .ai .cursor

For HTTP-only editors (GitHub Copilot, or any editor without stdio MCP support):

These editors need the API server running over HTTP. Detect the available container runtime, then help the user set up Compose:

# Detect container runtime
docker --version 2>/dev/null && RUNTIME=docker || { podman --version 2>/dev/null && RUNTIME=podman; }

Podman users: All docker and docker compose commands below work identically with podman and podman compose. Substitute accordingly.

1. Create .docker/.env from the example:

WORKSPACE_PATH=./workspace
REPO1_PATH=/absolute/path/to/this/repo

2. Create .docker/repos.yaml:

repos:
  this-repo:
    path: /repos/repo1

3. Start the API server:

$RUNTIME compose -f .docker/docker-compose.yaml up -d api

4. Configure the editor to point at http://localhost:5224.

Adding more repos later: To index additional repositories, add volume mounts in docker-compose.yaml, update repos.yaml with the new alias/path, and restart the container (docker compose restart api).

Step 7: Add MCP usage instructions to the target repo's CLAUDE.md — MUST

Do not skip this step. Without these instructions, the AI agent won't use the MCP tools and will fall back to grep/find.

Add the exact markdown block below verbatim to the CLAUDE.md (or AGENTS.md) of the repo you are enabling this for — not the smooth-code-repo-index-mcp project itself. If the user has a root CLAUDE.md that applies across all their projects (e.g. ~/source/CLAUDE.md), add it there so all repos benefit automatically. Do not paraphrase, summarize, or rewrite it:

## Codebase Navigation (MCP) — Non-Negotiable

When the `smooth-repo-index` MCP tools are available, they are the **primary and required** code discovery method. Do NOT use Grep, Glob, find, rg, or grep for searching code — use the MCP tools.

| Task | Use | Do NOT use |
|:-----|:----|:-----------|
| Search code | `search_codebase` | Grep, rg, grep, find |
| Identify context | `where_am_i` | Manual path inspection |
| Load context | `get_agents_context` | Read on AGENTS.md files |
| Understand repo structure | `get_domain_map` | Glob + manual scanning |
| Read file with metadata | `get_file` | Read (unless MCP unavailable) |

Only fall back to Grep/Glob/Read if the MCP server is not connected or a tool call fails.

Step 8: Verify

After setup, confirm the MCP server is working by using one of its tools (e.g., get_domain_map or where_am_i). If connected, report success to the user. If not, check that the dotnet tools are on PATH and the editor has reloaded its MCP configuration.

Updating

To update the tools to the latest version:

dotnet tool update -g Smooth.CodeRepositoryIndexMcp
dotnet tool update -g Smooth.CodeRepositoryIndexMcp.Cli

For the HTTP/API server (Docker/Podman):

docker pull ghcr.io/generik0/smooth-code-repo-index-mcp:latest
docker compose -f .docker/docker-compose.yaml up -d api

The MCP server rebuilds all indexes on startup, so no manual re-indexing is needed after updating.

Uninstalling

To fully remove Smooth.CodeRepositoryIndexMcp from a repo:

1. Remove the git hook: rm .git/hooks/post-merge
2. Remove the index directory: rm -rf .index/
3. Remove the .index/ entry from .gitignore
4. Remove MCP registration:
   • Claude Code: claude mcp remove -s user smooth-repo-index
   • Cursor: delete .cursor/mcp.json (or the symlink)
   • HTTP/API: stop the container (docker compose -f .docker/docker-compose.yaml down)
5. Optionally uninstall the tools: dotnet tool uninstall -g Smooth.CodeRepositoryIndexMcp && dotnet tool uninstall -g Smooth.CodeRepositoryIndexMcp.Cli

Note: Uninstalling the dotnet tools does not remove the post-merge hook or .index/ directory from repos where they were installed. Clean those up manually per steps 1–3.

Summary for the AI agent

When the user says "set up the indexer" or you see this repo's tools are available:

1. Ask: "Would you like me to set up Smooth.CodeRepositoryIndexMcp for this repo? I'll install the tools, index the codebase, and configure your editor's MCP connection."
2. Verify prerequisites (.NET 10 SDK, git)
3. Detect the editor from context (which agent is running)
4. If HTTP transport needed: detect container runtime (docker --version → fallback podman --version)
5. Install or update tools to latest version
6. Run smooth-code-repo-index index --root .
7. MUST: Add .index/ to .gitignore — generated data must never be committed
8. Write the appropriate MCP config file
9. MUST: Add MCP usage instructions to the target repo's CLAUDE.md (not the smooth-repo-index-mcp project) — without this, the agent won't use the MCP tools. If a root CLAUDE.md exists that covers all projects, prefer that.
10. Verify the connection works

The human should not need to do anything manually.

AI agents: STOP here. The sections below are for human developers setting up manually. Do not execute these steps — use the AI setup instructions above instead.

Human Setup Instructions

For manual setup (install, index, editor config, CLI usage, container runtime, uninstalling), see Human Setup Guide.

MCP Tools

When running as an MCP server (stdio or HTTP), five tools are exposed:

All tools accept an optional repo parameter for multi-repo mode. When a --scope is set on the server, tools default to that repo.

CLI Reference

Common Flags

Contributing

For local development setup, running tests, publishing binaries, code standards, and AI DevEx configuration, see Contributing Guide.

How It Works

Startup: The MCP server deletes existing indexes and rebuilds fresh on every startup, ensuring the index always reflects the current state of each repo.

Shallow index (default): Discovers all files and *AGENTS.md files, maps every path to a bounded context, generates a domain map and repo map, caches AGENTS.md content for instant retrieval. Completes in seconds.

Deep index (opt-in): Runs shallow first, then chunks all source files using line-based structural splitting, indexes them into Lucene.NET for full-text search with compound identifier splitting (PascalCase, camelCase, snake_case), assigns priority tiers, computes fan-in scores for structural importance, and detects cross-context boundaries.

AGENTS.md first: Every retrieval operation loads the relevant AGENTS.md before any code. AGENTS.md content is never trimmed from the context budget (20% protected allocation).

Multi-repo: A single MCP server indexes and serves multiple repos. Each repo is fully independent — separate SQLite DB, separate context map, separate AGENTS.md cache. Cross-repo search iterates all repos and labels results with the repo alias.

Architecture Decision Records

Configuration

Place .indexconfig.yaml at your repo root. All fields are optional — sensible defaults are applied. Sensitive paths (secrets/, credentials/, .ssh/) are always excluded.

Search Quality Reports

Measured against expert-verified ground truth on a ~500k LOC enterprise monorepo.

License

MIT — see LICENSE.

This project includes third-party dependencies under the Apache License 2.0. See THIRD-PARTY-NOTICES.md for details.