npm package: @sharc-code/mcp
Description: SHARC MCP Server - Semantic code search for AI assistants
Author: SHARC
Latest version: 0.2.19

# @sharc-code/mcp

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

[![npm version](https://img.shields.io/npm/v/@sharc-code/mcp.svg)](https://www.npmjs.com/package/@sharc-code/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

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

```bash
# npm (recommended default)
npm install @sharc-code/mcp

# pnpm
pnpm add @sharc-code/mcp

# bun
bun add @sharc-code/mcp --trust
bun pm untrusted
```

If `bun pm untrusted` still lists `tree-sitter` packages, AST chunking may degrade to the recursive fallback splitter until those dependencies are trusted.

## Configuration

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

```bash
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`:

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

### VS Code / Cursor Configuration

Add to your settings:

```json
{
  "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.

```json
{
  "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):**

```text
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`):**

```text
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.

```json
{
  "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.

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

### `get_indexing_status`

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

```json
{
  "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.

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

### `stop_watch`

Stop watching a codebase for file changes.

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

### `get_watch_status`

Get the currently active watched codebase (if any).

```json
{}
```

## 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` | Recursive | File context |
| Config | `.json`, `.yaml`, `.yml`, `.toml`, `.xml` | Recursive | File context |
| Other | `.rb`, `.php`, `.swift`, `.kt`, `.vue`, `.html`, `.css`, `.sql` | Recursive | 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, recursive splitter for docs/config/fallback)
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:

```typescript
// 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 recursive code splitters |
| `@modelcontextprotocol/sdk` | MCP protocol implementation |
| `chokidar` | File watching |
| `zod` | Schema validation |

## Development

```bash
# Install dependencies
bun install

# Build
bun run build

# Type check
bun run typecheck

# Run locally
bun run start
```

## Related Packages

- **[@sharc-code/splitter](https://www.npmjs.com/package/@sharc-code/splitter)** - AST and recursive code splitters

## License

MIT