semantic-retrieval-mcp

Semantic code retrieval MCP Server — natural language queries → relevant code snippets.

What it does

In any MCP-compatible AI client (Claude Code, Cline, Windsurf, etc.), ask:

"Find the authentication handler in this project"

The AI calls this MCP Server, which performs semantic search across your codebase and returns precisely matched code snippets.

Core capability: Natural language → relevant code. Cross-language, real-time index, far better than grep.

Install

npm install -g semantic-retrieval-mcp

Or use directly with npx:

npx -y semantic-retrieval-mcp

Configuration

With npx (recommended)

{
  "mcpServers": {
    "semantic-retrieval": {
      "command": "npx",
      "args": ["-y", "semantic-retrieval-mcp"],
      "env": {
        "SR_TOKEN": "your-access-token",
        "SR_TENANT": "https://your-tenant-url/"
      }
    }
  }
}

With global install

{
  "mcpServers": {
    "semantic-retrieval": {
      "command": "semantic-retrieval-mcp",
      "env": {
        "SR_TOKEN": "your-access-token",
        "SR_TENANT": "https://your-tenant-url/"
      }
    }
  }
}

Auto-detect from editor

If you have a compatible editor with an active session, the server can read credentials automatically:

{
  "mcpServers": {
    "semantic-retrieval": {
      "command": "npx",
      "args": ["-y", "semantic-retrieval-mcp"],
      "env": {
        "SR_EDITOR": "cursor"
      }
    }
  }
}

Environment Variables

| Variable | Description | |---|---| | SR_TOKEN | Access token (recommended) | | SR_TENANT | Tenant URL (recommended) | | SR_EDITOR | Auto-detect from editor: vscode / cursor / windsurf / trae / kiro | | SR_WATCH | File watching enabled by default; set to 0 to disable |

Usage Scenarios

Scenario 1: AI auto-invokes (most common)

After configuration, just chat with your AI normally. When it needs to understand code, it calls the tool automatically:

You: "Refactor the login logic from session-based to JWT"

AI internally: → calls codebase-retrieval("authentication and login logic")
              → receives relevant code snippets
              → provides solution based on actual code

You don't need to do anything. On first query for a directory, the server automatically:

1. Scans all source files
2. Computes fingerprints (SHA256)
3. Uploads new files to the indexing backend
4. Creates a checkpoint
5. Performs semantic retrieval

Subsequent queries reuse the cached checkpoint — no re-scanning or re-uploading.

Scenario 2: Different project directory

Each directory_path is managed independently. New directories get indexed automatically.

Scenario 3: Force re-sync after major changes

You: "I just merged a big branch, re-index the project"
AI: → calls sync-workspace(directory_path)

Scenario 4: Real-time file watching

File watching is enabled by default. When active, chokidar monitors file changes:

• File edits/creates/deletes → automatic fingerprint update
• 2-second debounce for batch processing (or 50 changes triggers immediately)
• Auto upload + checkpoint update
• Next query always uses the latest index

Scenario 5: Token rotation

When the token changes, cached checkpoints auto-invalidate. Next query re-syncs with the new token automatically.

Tools

codebase-retrieval

| Parameter | Type | Description | |---|---|---| | information_request | string | Natural language query (e.g. "Find the database connection code") | | directory_path | string | Absolute path to the project directory to search |

sync-workspace

| Parameter | Type | Description | |---|---|---| | directory_path | string | Absolute path to the project directory to re-sync |

How it works

Your AI Client
    │ MCP (stdio)
    ▼
MCP Server (index.js)
    │
    ├─ First query for a dir ──→ BlobManager
    │   ├─ Scan files → SHA256(path+content) = blobName
    │   ├─ POST find-missing     → Which files does the server not have?
    │   ├─ POST batch-upload     → Upload missing files
    │   ├─ POST checkpoint-blobs → Create snapshot, get checkpointId
    │   └─ Persist to ~/.semantic-retrieval-mcp/<hash>.json
    │
    ├─ Subsequent queries ──→ Use cached checkpointId
    │
    └─ POST agents/codebase-retrieval
        → Cloud semantic search
        → Return matching code snippets to AI

File watching (SR_WATCH=1):
    chokidar → file change → debounce → find-missing → upload → checkpoint

Cache

Each workspace directory's state is cached in ~/.semantic-retrieval-mcp/<hash>.json.

• Survives MCP Server restarts
• Same tenant, different token → checkpoint reused (content-based SHA256)
• Different tenant → checkpoint auto-invalidated
• Delete ~/.semantic-retrieval-mcp/ to clear all caches

License

MIT