Smooth.CodeRepositoryIndexMcp 0.9.0-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. *AGENTS.md files are treated as first-class citizens — the authoritative source of domain knowledge, always loaded before any code, and never trimmed from the context budget. In a monorepo, they are the primary mechanism for helping agents understand the what: what this bounded context does, what rules apply, and what decisions have already been made.

Table of Contents

• How this helps AI coding agents
• Writing your AGENTS.md files
• Getting Started
  • Prerequisites
  • AI Coding Agent Setup Instructions
  • Human Setup Guide
• MCP Tools
  • MCP Tools Reference
• CLI Reference
• Contributing
• How It Works, Architecture Decisions & Search Quality
• License

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.

Writing your *AGENTS.md files

The tool's quality is directly proportional to the quality of your *AGENTS.md files. The recommended approach is to create localized *AGENTS.md files at the domain, subdomain, feature, and bounded-context level — rarely deeper. Each file captures contextual knowledge that source code alone cannot communicate: the why behind decisions, non-obvious behaviors, cross-cutting constraints, and the rules an AI agent must follow within that context.

Use the lean AI coder template as your base structure: .ai/templates/TEMPLATE_AGENTS.md. It provides a focused scaffold, and when combined with the quality standards rule it yields the required sections (TL;DR, Non-Negotiables, System Context, Architecture Decisions, Key Behaviors, Changelog) while keeping files focused on what an AI coder needs rather than human product documentation.

Pair the template with the quality standards rule: .ai/rules/knowledge-conventional-contexts-quality.instructions.md. This rule defines the required section order, the three-part value test (bug prevention, decision quality, system understanding), anti-patterns to avoid, and drift-minimization obligations. Use it together with the template — ideally by adding it to your AI agent's rules — to get AI-coder-focused AGENTS.md files whose content is cached separately and automatically prepended to every search response before code results.

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 --prerelease
dotnet tool update -g Smooth.CodeRepositoryIndexMcp.Cli --prerelease

Note: dotnet tool update -g installs the tool if missing and updates it if already installed — it handles both cases. --prerelease is required as this package has not yet reached a stable 1.0 release.

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 GitHub Copilot (VS Code):

Recommended: Use the dotnet tool with stdio transport (below). It is more reliable and better tested than the HTTP/API server. The API server is a fallback for editors that do not support stdio MCP.

GitHub Copilot in VS Code (1.99+) supports stdio MCP servers. Create .vscode/mcp.json:

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

For GitHub Copilot CLI (terminal, gh copilot interactive mode):

The Copilot CLI uses a separate config file: ~/.copilot/mcp-config.json (Linux/macOS) or %USERPROFILE%\.copilot\mcp-config.json (Windows). The CLI also supports /mcp add in interactive mode as an alternative to editing the file directly.

Mac/Linux or Windows with Git Bash:

{
  "mcpServers": {
    "smooth-repo-index": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "smooth-code-repo-index-mcp --root \"$(git rev-parse --show-toplevel)\""],
      "tools": ["*"]
    }
  }
}

Windows (PowerShell, no Git Bash):

{
  "mcpServers": {
    "smooth-repo-index": {
      "type": "stdio",
      "command": "pwsh",
      "args": ["-Command", "smooth-code-repo-index-mcp --root `\"$(git rev-parse --show-toplevel)`\""],
      "tools": ["*"]
    }
  }
}

Or via /mcp add in Copilot CLI interactive mode — when prompted, supply:

• Name: smooth-repo-index
• Server Type: 2 — STDIO
• Command (Mac/Linux/Windows+Git Bash): bash -c 'smooth-code-repo-index-mcp --root "$(git rev-parse --show-toplevel)"'
• Command (Windows PowerShell, no Git Bash): pwsh -Command "smooth-code-repo-index-mcp --root `"$(git rev-parse --show-toplevel)`""
• Environment Variables: (leave empty)
• Tools: *

For editors that require HTTP transport (API server):

⚠️ Note: The HTTP/API transport has not been extensively tested. Claude Code (stdio) is the primary supported and tested configuration. Use the API server only if your editor does not support stdio MCP.

For editors requiring HTTP transport, the API server runs in a container. 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 7b: Add AGENTS.md quality standards to the target repo's root AGENTS.md — MUST

Do not skip this step. Well-structured AGENTS.md files are indexed at critical priority and always loaded before code in search results. They are the primary mechanism for improving search_codebase ranking and get_agents_context retrieval quality across the repo.

Add the exact markdown block below verbatim to the root AGENTS.md of the target repo (create one at the repo root if it doesn't exist). Do not paraphrase or rewrite it:

## Contextual Knowledge Standards

When creating or updating `*_AGENTS.md` files in this repo, use [TEMPLATE_AGENTS.md](https://github.com/generik0/smooth-code-repo-index-mcp/blob/main/.ai/templates/TEMPLATE_AGENTS.md) as the base structure and follow [AGENTS.md Quality Standards](https://github.com/generik0/smooth-code-repo-index-mcp/blob/main/.ai/rules/knowledge-conventional-contexts-quality.instructions.md).

AGENTS.md files are indexed at `critical` priority by the MCP server and their content is always loaded before code in search results. Well-maintained AGENTS.md files directly improve `search_codebase` ranking and `get_agents_context` retrieval — they are the primary mechanism for optimizing what the MCP returns to AI agents.

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 --prerelease
dotnet tool update -g Smooth.CodeRepositoryIndexMcp.Cli --prerelease

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)
   • GitHub Copilot (VS Code): delete .vscode/mcp.json
   • GitHub Copilot CLI: remove the smooth-repo-index entry from ~/.copilot/mcp-config.json (Linux/macOS) or %USERPROFILE%\.copilot\mcp-config.json (Windows)
   • 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:
   • Claude Code: claude mcp add -s user smooth-repo-index ...
   • Cursor: .cursor/mcp.json
   • GitHub Copilot (VS Code 1.99+): .vscode/mcp.json with "servers" key (same stdio format as Cursor)
   • GitHub Copilot CLI (terminal): ~/.copilot/mcp-config.json (Linux/macOS) or %USERPROFILE%\.copilot\mcp-config.json (Windows) with "mcpServers" key; use bash command on Mac/Linux/Windows+Git Bash, or pwsh on Windows without Git Bash; alternatively use /mcp add in interactive mode (see Step 6)
   • HTTP transport: spin up the API container and point editor at http://localhost:5224
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. MUST: Add AGENTS.md quality standards block to the target repo's root AGENTS.md (create if missing) — this tells future AI agents which template and quality standards to follow when writing contextual knowledge documents, directly improving search and indexing quality.
11. 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.

For full tool parameter descriptions, see MCP Tools Reference.

CLI Reference

For a complete command reference and configuration options, see CLI Reference.

Contributing

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

How It Works, Architecture Decisions & Search Quality

For a full explanation of the indexing pipeline, architecture decision records (ADRs), and search quality reports, see How It Works.

License

MIT — see LICENSE.

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