> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharc.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools Reference

> Complete reference for all 7 SHARC MCP tools

SHARC provides 7 MCP tools for indexing and searching codebases. This page documents each tool's parameters, behavior, and usage examples.

## index\_codebase

Index a codebase for semantic search. This is typically the first tool you'll use.

### Parameters

| Parameter            | Type      | Required | Description                                  |
| -------------------- | --------- | -------- | -------------------------------------------- |
| `path`               | string    | Yes      | Absolute path to the codebase directory      |
| `force`              | boolean   | No       | Force full re-index (deletes existing index) |
| `customExtensions`   | string\[] | No       | Additional file extensions to include        |
| `ignorePatterns`     | string\[] | No       | Glob patterns to exclude                     |
| `guardOverrideToken` | string    | No       | One-shot token to bypass multi-repo guard    |

### Behavior

**First Run (Full Indexing)**:

1. Scans directory for supported files
2. Splits code into semantic chunks (AST-based for supported languages)
3. Generates embeddings
4. Stores vectors in the search index
5. Saves a sync snapshot for future incremental sync
6. Auto-starts file watcher

**Multi-repo guard**:

If the target path contains 2 or more immediate child git repositories (e.g., `~/projects` containing multiple repos), SHARC blocks indexing and returns a `guarded_block` response with:

* The number of detected repos and sample paths
* A one-shot `guardOverrideToken` to proceed if intentional
* Guidance to index a specific child repo instead

This prevents accidentally indexing broad parent directories, which produces mixed search results and wastes token budget.

**Subsequent Runs (Incremental)**:

1. Loads previous sync snapshot
2. Computes current file hashes
3. Identifies changed files via diff
4. Only re-indexes added/modified files
5. Removes vectors for deleted files

### Example

```
> Please index this codebase

● index_codebase (MCP)
  path: "D:\\projects\\my-app"
  ⎿ Scanning files...
  ⎿ Found 342 files (skipping node_modules, .git, dist)
  ⎿ Chunking code (3,450 chunks)
  ⎿ Generating embeddings...
  ⎿ Storing in search index
  ⎿ ✓ Indexed 3,450 chunks in 22.4s
  ⎿ File watcher started
```

***

## search\_code

Search indexed code using natural language queries.

### Parameters

| Parameter         | Type      | Required | Default | Description                     |
| ----------------- | --------- | -------- | ------- | ------------------------------- |
| `path`            | string    | Yes      | -       | Codebase directory              |
| `query`           | string    | Yes      | -       | Natural language search query   |
| `limit`           | number    | No       | 3       | Max results (1-50)              |
| `extensionFilter` | string\[] | No       | -       | Filter by file extensions       |
| `searchMode`      | string    | No       | `auto`  | Filter results by document type |

### Search Modes

The `searchMode` parameter controls which types of code are returned:

| Mode                    | Behavior                                                               |
| ----------------------- | ---------------------------------------------------------------------- |
| `auto`                  | Returns all result types, ranked by relevance (default)                |
| `implementation_only`   | Excludes tests and documentation, returns only source code             |
| `tests_only`            | Returns only test files (`*.test.*`, `*.spec.*`, `__tests__/`)         |
| `docs_only`             | Returns only documentation and examples (`*.md`, `docs/`, `examples/`) |
| `prefer_implementation` | Ranks source code higher, but includes other types as fallback         |

This is useful when an agent needs to find specific categories of code. For example, use `implementation_only` when looking for how a feature works, or `tests_only` when looking for test coverage of a function.

### Behavior

1. Generates embedding for query
2. Performs hybrid search (dense vectors + BM25 sparse)
3. Reranks results for better relevance
4. Returns ranked code snippets with metadata

### Result Format

Each result includes:

* **Location**: File path and line numbers
* **Score**: Relevance score (0-1, higher is better)
* **Code**: The matching code snippet
* **Context**: Surrounding class/function information

### Understanding Scores

SHARC uses hybrid retrieval (dense vectors + BM25 sparse matching) combined with a reranker, which produces well-calibrated relevance scores:

| Score Range     | Meaning                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------- |
| **0.90+**       | Highly relevant. With targeted queries, scores of 0.98-0.99 indicate a precise match to the query. |
| **0.80 - 0.89** | Likely relevant. Related code that may partially match the intent.                                 |
| **\< 0.50**     | Usually not relevant. The code is tangential or unrelated.                                         |

If a targeted query does not return results in the 0.9+ range, it typically means the implementation doesn't exist in the codebase, the query was too vague, or the implementation itself is loosely structured. Try rephrasing with more specific terms.

### Example

```
> How does authentication work in this project?

● search_code (MCP)
  path: "D:\\projects\\my-app"
  query: "authentication"
  limit: 3
  ⎿ Found 3 results for query: "authentication"

  1. Code snippet (typescript) [my-app]
     Location: src/middleware/auth.ts:45-89
     Score: 0.9847
     // Context: class AuthMiddleware
     async authenticate(req: Request): Promise<User> {
       const token = req.headers.authorization?.split(' ')[1];
       if (!token) throw new UnauthorizedError();
       return this.jwtService.verify(token);
     }
     ... +34 lines

  2. Code snippet (typescript) [my-app]
     Location: src/services/jwt.service.ts:12-45
     Score: 0.9234
     ...
```

### Query Tips

| Query Type  | Example                  | Notes                   |
| ----------- | ------------------------ | ----------------------- |
| Semantic    | "user login flow"        | Understands meaning     |
| Specific    | "JWT token validation"   | Technical terms work    |
| Behavioral  | "error handling for API" | Describes functionality |
| Exploratory | "database queries"       | Finds related code      |

***

## clear\_index

Remove a codebase from the index.

### Parameters

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| `path`    | string | Yes      | Codebase directory to remove |

### Behavior

1. Stops file watcher (if active)
2. Deletes indexed data for that codebase
3. Removes sync snapshot metadata
4. Clears local caches

### Example

```
> Remove this project from the index

● clear_index (MCP)
  path: "D:\\projects\\old-app"
  ⎿ Stopped file watcher
  ⎿ Deleted collection: old-app
  ⎿ Removed metadata
  ⎿ ✓ Index cleared
```

***

## get\_indexing\_status

Check the indexing status of a codebase.

### Parameters

| Parameter | Type   | Required | Description        |
| --------- | ------ | -------- | ------------------ |
| `path`    | string | Yes      | Codebase directory |

### Response States

| Status        | Description                           |
| ------------- | ------------------------------------- |
| `indexed`     | Fully indexed and ready               |
| `indexing`    | Currently indexing (shows progress %) |
| `indexfailed` | Indexing failed (shows error)         |
| `not_indexed` | Not yet indexed                       |

### Example

```
> What's the indexing status?

● get_indexing_status (MCP)
  path: "D:\\projects\\my-app"
  ⎿ Status: indexed ✓
  ⎿ Chunks: 3,450
  ⎿ Last updated: 2 minutes ago
  ⎿ File watcher: active
```

***

## start\_watch

Start watching a codebase for file changes.

### Parameters

| Parameter | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `path`    | string | Yes      | Codebase directory to watch |

### Behavior

* Requires codebase to be already indexed
* Uses chokidar for file system events
* 2-second debounce for batched processing
* Automatically filters unsupported files
* Validates syntax before indexing (prevents broken code)

### Example

```
> Start watching this project for changes

● start_watch (MCP)
  path: "D:\\projects\\my-app"
  ⎿ ✓ Started watching D:\\projects\\my-app
  ⎿ Monitoring 342 files
```

<Info>
  File watching starts automatically after `index_codebase` completes. You only need `start_watch` if you previously stopped watching.
</Info>

***

## stop\_watch

Stop watching a codebase for file changes.

### Parameters

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `path`    | string | Yes      | Codebase directory to stop watching |

### Example

```
> Stop watching this project

● stop_watch (MCP)
  path: "D:\\projects\\my-app"
  ⎿ ✓ Stopped watching D:\\projects\\my-app
```

***

## get\_watch\_status

Get the list of codebases currently being watched.

### Parameters

None.

### Example

```
> What codebases are being watched?

● get_watch_status (MCP)
  ⎿ Currently watching 2 codebases:
  ⎿ 1. D:\\projects\\my-app (3,450 chunks)
  ⎿ 2. D:\\projects\\api-server (1,234 chunks)
```

***

## Supported File Extensions

### Tier 1: AST-Parsed (Best Quality)

Full semantic understanding with context injection:

`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `.pyw`, `.go`, `.rs`, `.java`, `.cs`, `.cpp`, `.cc`, `.cxx`, `.c`, `.h`, `.hpp`, `.scala`

### Tier 2: Documentation

Character-based chunking with overlap:

`.md`, `.mdx`, `.rst`, `.txt`

### Tier 3: Configuration

Grouped key-value chunking:

`.json`, `.yaml`, `.yml`, `.toml`, `.xml`, `.env.example`, `.ini`, `.cfg`

### Tier 4: Other Code

Fallback chunking for unsupported languages:

`.rb`, `.php`, `.swift`, `.kt`, `.kts`, `.vue`, `.svelte`, `.html`, `.css`, `.scss`, `.less`, `.sql`