# MCP Repo Search

MCP server that clones a Git repo into a temp directory so Cursor (or other MCP clients) can search and read files from another repo for context. The clone is removed automatically after 5 minutes of inactivity.

## Requirements

- Node.js 18+
- Git installed and on `PATH`
- MCP host (e.g. Cursor)

## Install

**Option A – From npm (recommended if you published the package):**

```bash
# Global install (anyone can use it)
npm install -g mcp-repo-search
```

**Option B – With npx (no install; runs from npm cache):**

No install. Use `npx mcp-repo-search` in Cursor config below.

**Option C – From source (clone this repo):**

```bash
cd mcp-repo-search
npm install
npm run build
```

## Cursor configuration

**If you installed globally or use npx**, add to your MCP config (e.g. `.cursor/mcp.json` or Cursor Settings → MCP):

```json
{
  "mcpServers": {
    "repo-search": {
      "command": "npx",
      "args": ["mcp-repo-search"]
    }
  }
}
```

Or with global install:

```json
{
  "mcpServers": {
    "repo-search": {
      "command": "mcp-repo-search"
    }
  }
}
```

**If you use a local clone**, use the absolute path to the built entry point:

```json
{
  "mcpServers": {
    "repo-search": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-repo-search/build/index.js"]
    }
  }
}
```

Example path on macOS/Linux: `/Users/you/projects/multi-repo-mcp/mcp-repo-search/build/index.js`

---

## Tools

| Tool | Description |
|------|-------------|
| **ensure_repo** | Clone a repo (or reuse existing clone). Call this first with `repoUrl` (and optional `branch`). Resets the idle timer. |
| **get_repo_status** | Whether a repo is cloned, its path, URL, and idle TTL. Does not clone. |
| **read_file** | Read a file from the clone (path relative to repo root). Max 512 KB. Resets timer. |
| **list_directory** | List files and dirs under a path (default `"."`). Resets timer. |
| **search_repo** | Text/regex search in the clone. Optional `path` and `fileGlob` (e.g. `*.ts`). Resets timer. |

Typical flow: run **ensure_repo** with the repo URL, then use **search_repo**, **read_file**, or **list_directory** to pull context.

## Environment (optional)

- **`MCP_REPO_SEARCH_TTL_SECONDS`** – Idle timeout in seconds before the clone is deleted (default: `300`, i.e. 5 minutes).
- **`MCP_REPO_SEARCH_TEMP_DIR`** – Base directory for clones (default: `os.tmpdir()/mcp-repo-search`).

## Private repos

Git auth is not handled by this server. For private repos, rely on system Git config (e.g. credential helper, SSH keys, or `GIT_ASKPASS`). Clone is done with a shallow `--depth 1` and optional `--branch`.

## Logging

The server logs to **stderr** only (stdout is used for MCP JSON-RPC). Check your MCP client’s server logs (e.g. Cursor’s MCP server log) for errors.