MCP Tools Reference

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):

Scans directory for supported files
Splits code into semantic chunks (AST-based for supported languages)
Generates embeddings
Stores vectors in the search index
Saves a sync snapshot for future incremental sync
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):

Loads previous sync snapshot
Computes current file hashes
Identifies changed files via diff
Only re-indexes added/modified files
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

Generates embedding for query
Performs hybrid search (dense vectors + BM25 sparse)
Reranks results for better relevance
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

Stops file watcher (if active)
Deletes indexed data for that codebase
Removes sync snapshot metadata
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

File watching starts automatically after index_codebase completes. You only need start_watch if you previously stopped watching.

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

Getting started

MCP reference

Packages

Architecture

MCP Tools Reference

index_codebase

Parameters

Behavior

Example

search_code

Parameters

Search Modes

Behavior

Result Format

Understanding Scores

Example

Query Tips

clear_index

Parameters

Behavior

Example

get_indexing_status

Parameters

Response States

Example

start_watch

Parameters

Behavior

Example

stop_watch

Parameters

Example

get_watch_status

Parameters

Example

Supported File Extensions

Tier 1: AST-Parsed (Best Quality)

Tier 2: Documentation

Tier 3: Configuration

Tier 4: Other Code

​index_codebase

​Parameters

​Behavior

​Example

​search_code

​Parameters

​Search Modes

​Behavior

​Result Format

​Understanding Scores

​Example

​Query Tips

​clear_index

​Parameters

​Behavior

​Example

​get_indexing_status

​Parameters

​Response States

​Example

​start_watch

​Parameters

​Behavior

​Example

​stop_watch

​Parameters

​Example

​get_watch_status

​Parameters

​Example

​Supported File Extensions

​Tier 1: AST-Parsed (Best Quality)

​Tier 2: Documentation

​Tier 3: Configuration

​Tier 4: Other Code

index_codebase

Parameters

Behavior

Example

search_code

Parameters

Search Modes

Behavior

Result Format

Understanding Scores

Example

Query Tips

clear_index

Parameters

Behavior

Example

get_indexing_status

Parameters

Response States

Example

start_watch

Parameters

Behavior

Example

stop_watch

Parameters

Example

get_watch_status

Parameters

Example

Supported File Extensions

Tier 1: AST-Parsed (Best Quality)

Tier 2: Documentation

Tier 3: Configuration

Tier 4: Other Code