@sharc-code/mcp

SHARC MCP Server - Semantic code search for AI assistants via the Model Context Protocol (MCP).

This package provides an MCP server that enables AI assistants like Claude Code, Cursor, and VS Code Copilot to perform semantic code search across codebases using natural language queries.

Features

• Semantic Code Search - Find code using natural language queries (e.g., "JWT authentication middleware")
• Incremental Indexing - Merkle-based diffing, only re-indexes changed files (~0.3s for no changes)
• Real-time File Watching - Automatically updates index when files change (single watcher per instance)
• AST-based Chunking - Smart code splitting that preserves semantic units with context injection
• Decorator Support - Preserves decorators/annotations (@Get(), #[derive], @Injectable) in context
• Multi-language Support - TypeScript, JavaScript, Python, Go, Rust, Java, C#, C++, Scala

Installation

npm install @sharc-code/mcp

Configuration

The MCP server requires only an API key to connect to SHARC Cloud. Backend URL defaults to https://api.sharc.sh:

SHARC_API_KEY=<your-api-key>           # API key for authentication
# Optional override:
# SHARC_BACKEND_URL=https://api.sharc.sh

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "sharc": {
      "command": "npx",
      "args": ["@sharc-code/mcp"],
      "env": {
        "SHARC_API_KEY": "<your-api-key>"
      }
    }
  }
}

VS Code / Cursor Configuration

Add to your settings:

{
  "mcp.servers": {
    "sharc": {
      "command": "npx",
      "args": ["@sharc-code/mcp"],
      "env": {
        "SHARC_API_KEY": "<your-api-key>"
      }
    }
  }
}

MCP Tools

The server exposes 7 tools to AI assistants:

index_codebase

Index a codebase for semantic search. Uses Merkle-based diffing for incremental updates.

{
  "path": "/path/to/project",
  "force": false,
  "customExtensions": [".vue", ".svelte"],
  "ignorePatterns": ["generated/**"]
}

Parameters:

• path (required) - Absolute path to the codebase directory
• force (optional) - Force full re-index even if already indexed
• customExtensions (optional) - Additional file extensions beyond defaults
• ignorePatterns (optional) - Additional glob patterns to exclude (for example static/**, *.tmp, private/**)

Ignore precedence (highest last):

1. Built-in default skip set
2. Root .gitignore
3. Root .sharcignore
4. Runtime ignorePatterns

.sharcignore and .gitignore are read from the indexed codebase root only.

Non-overridable safety denylist:

• Secret material and env files: .pem, .key, .p12, .pfx, .env, .env.* (except .env.example)
• Binary/object/bytecode: .exe, .dll, .so, .dylib, .bin, .o, .obj, .class, .pyc, .pyo
• Media/archive/docs: common image/audio/video/archive/document binaries (for example .png, .mp4, .zip, .pdf)
• OS/editor junk: .DS_Store, Thumbs.db, .suo, .ntvs_analysis.dat

If customExtensions includes blocked types, SHARC warns and skips them.

Default skip set (always applied):

node_modules/**, target/**, dist/**, build/**, out/**, .next/**, .nuxt/**, .svelte-kit/**,
.turbo/**, .parcel-cache/**, .cache/**, coverage/**, .nyc_output/**, __pycache__/**,
.pytest_cache/**, .mypy_cache/**, .ruff_cache/**, .tox/**, .nox/**, .venv/**, venv/**, env/**,
.git/**, .svn/**, .hg/**, .idea/**, .vscode/**, tmp/**, temp/**, logs/**, *.log, *.min.js,
*.min.css, *.bundle.js, *.chunk.js, *.map

Optional team-dependent patterns (opt-in via ignorePatterns):

vendor/**, third_party/**, generated/**, *.gen.*, *.pb.*, Pods/**, DerivedData/**, .gradle/**,
CMakeFiles/**, cmake-build-*/**, .terraform/**, .serverless/**, .aws-sam/**

Performance:

• First time: ~15-30s (full indexing)
• No changes: ~0.3s (Merkle hash comparison)
• Incremental: ~2-4s per changed file

index_codebase responses include skip summaries (counts + sample paths) when files are excluded by ignore rules, safety policy, binary detection, or size limits.

search_code

Search code using natural language queries with hybrid search (dense + sparse vectors) and reranking.

{
  "path": "/path/to/project",
  "query": "JWT authentication middleware",
  "limit": 5,
  "extensionFilter": [".ts", ".js"]
}

Parameters:

• path (required) - Absolute path to the codebase
• query (required) - Natural language search query
• limit (optional, default: 3) - Maximum results (1-50)
• extensionFilter (optional) - Filter by file extensions

Score Interpretation:

• Score >0.40: Highly relevant (primary implementation)
• Score 0.25-0.40: Relevant (supporting code, tests)
• Score 0.15-0.25: Possibly relevant (check context)
• Score <0.15: Likely noise

clear_index

Delete the search index for a codebase.

{
  "path": "/path/to/project"
}

get_indexing_status

Check indexing progress for a codebase. Shows percentage for active indexing, completion status for indexed.

{
  "path": "/path/to/project"
}

start_watch

Start watching a codebase for file changes. Only one codebase can be watched at a time per MCP instance - starting a new watch automatically stops any previous one.

{
  "path": "/path/to/project"
}

stop_watch

Stop watching a codebase for file changes.

{
  "path": "/path/to/project"
}

get_watch_status

Get the currently active watched codebase (if any).

{}

Supported Languages

| Language | Extensions | Chunking | Features | |----------|------------|----------|----------| | TypeScript | .ts, .tsx | AST | Context injection, decorators | | JavaScript | .js, .jsx, .mjs, .cjs | AST | Context injection, decorators | | Python | .py, .pyw | AST | Context injection, decorators | | Go | .go | AST | Context injection | | Rust | .rs | AST | Context injection, #[...] attributes | | Java | .java | AST | Context injection, annotations | | C# | .cs | AST | Context injection, attributes | | C++ | .cpp, .hpp, .cc, .cxx, .c, .h | AST | Context injection | | Scala | .scala | AST | Context injection, annotations | | Markdown | .md, .mdx | LangChain | File context | | Config | .json, .yaml, .yml, .toml, .xml | LangChain | File context | | Other | .rb, .php, .swift, .kt, .vue, .html, .css, .sql | LangChain | File context |

How It Works

Indexing Flow

1. Scan - Find all supported files in the codebase
2. Chunk - Split files using tiered strategy (AST for code, LangChain for docs)
3. Embed - Generate 4096-dim vectors via SHARC backend (Qwen3-Embedding-8B)
4. Store - Save to Qdrant Cloud with hybrid index (dense + BM25 sparse)
5. Snapshot - Store Merkle tree for incremental updates

Search Flow

1. Embed Query - Generate query vector via backend
2. Hybrid Search - Qdrant searches both dense vectors and BM25 keywords
3. Rerank - Results reranked via Qwen3-Reranker-4B
4. Return - Top results with scores, file locations, and code snippets

Context Injection

The AST splitter adds context comments to code chunks for better search relevance:

// Context: class UserService > module auth (services/user.ts)
@Injectable()
async authenticate(user: string): Promise<boolean> {
  return this.validateCredentials(user);
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SHARC_BACKEND_URL | No | Backend API URL (default: https://api.sharc.sh) | | SHARC_API_KEY | Yes | API key for authentication | | SHARC_WATCH_DEBOUNCE_MS | No | File watcher debounce (default: 2000) | | DEBUG | No | Enable verbose logging |

Dependencies

| Package | Purpose | |---------|---------| | @sharc-code/splitter | AST and LangChain code splitters | | @modelcontextprotocol/sdk | MCP protocol implementation | | chokidar | File watching | | zod | Schema validation |

Development

# Install dependencies
bun install

# Build
bun run build

# Type check
bun run typecheck

# Run locally
bun run start

Related Packages

• @sharc-code/splitter - AST and LangChain code splitters

License

MIT