semantic-code-index-mcp 0.2.0__tar.gz

semantic_code_index_mcp-0.2.0/.claude/.gitignore

@@ -0,0 +1 @@
+mcp.json

semantic_code_index_mcp-0.2.0/.claude/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "semantic-code-index": {
+      "command": "/Users/thinhdo/Documents/semantic-code-index-mcp/.venv/bin/semantic-code-index-mcp",
+      "env": {
+        "SEMANTIC_CODE_ROOT": "/Users/thinhdo/Documents/semantic-code-index-mcp"
+      }
+    }
+  }
+}

semantic_code_index_mcp-0.2.0/.claude/rules/semantic-search.md

@@ -0,0 +1,17 @@
+---
+description: Prefer semantic_search MCP tool over Grep/Glob for code exploration
+globs: "**/*"
+---
+
+# Semantic Code Search
+
+This project has a semantic code index (semantic-code-index MCP server).
+
+When you need to explore, understand, or find code:
+1. **Use `semantic_search` first** — it finds conceptually related code, not just exact string matches.
+2. Only fall back to Grep/Glob when you need exact string/pattern matching (e.g. finding a specific variable name or import).
+3. `semantic_search` auto-syncs changed files before searching — no need to manually sync.
+4. Run `index_project` once if the project has never been indexed.
+
+When spawning sub-agents (Agent tool) for code exploration or research, always include this instruction in the prompt:
+> Use the `mcp__semantic-code-index__semantic_search` tool to search code. It finds conceptually related code via semantic vector search. Prefer it over Grep/Glob.

semantic_code_index_mcp-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.DS_Store
+*.sqlite3
+.cache/
+.mcp.json

semantic_code_index_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: semantic-code-index-mcp
+Version: 0.2.0
+Summary: MCP server: semantic code search with SQLite + local free embeddings
+Requires-Python: >=3.11
+Requires-Dist: fastembed>=0.4.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: tiktoken>=0.7.0
+Description-Content-Type: text/markdown
+
+# semantic-code-index-mcp
+
+MCP server cho Claude / Claude Code: index semantic vào SQLite, embedding chạy local (miễn phí, không API), công cụ tìm kiếm và thống kê token ước lượng.
+
+## Cài đặt
+
+```bash
+cd /path/to/semantic-code-index-mcp
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Lần đầu chạy, `fastembed` sẽ tải model ONNX (khoảng vài chục MB).
+
+## Biến môi trường
+
+- `SEMANTIC_CODE_ROOT` hoặc `WORKSPACE_ROOT`: thư mục gốc project cần index (mặc định: thư mục làm việc của process MCP).
+
+## Claude Code / Cursor MCP
+
+Thêm server (stdio), ví dụ trong cấu hình MCP của client:
+
+```json
+{
+  "mcpServers": {
+    "semantic-code-index": {
+      "command": "semantic-code-index-mcp",
+      "env": {
+        "SEMANTIC_CODE_ROOT": "/absolute/path/to/your/repo"
+      }
+    }
+  }
+}
+```
+
+Nếu không set `SEMANTIC_CODE_ROOT`, đặt `cwd` của server trỏ vào repo hoặc truyền `root_path` trong từng tool call.
+
+## Tools
+
+| Tool | Mô tả |
+|------|--------|
+| `index_project` | Index lại toàn bộ |
+| `sync_index` | Chỉ cập nhật file thay đổi / mới / xóa |
+| `semantic_search` | Tìm theo ngôn ngữ tự nhiên |
+| `token_usage_stats` | Ước lượng token “đọc full repo” vs tích lũy từ search |
+
+Database: `<root>/.semantic_index/index.sqlite3`.
+
+## Ghi chú
+
+- Đếm token dùng `tiktoken` encoding `cl100k_base` (xấp xỉ Claude/GPT-4), không phải billing thực tế.
+- Vector search hiện quét toàn bộ chunk trong SQLite; repo rất lớn có thể cần mở rộng (sqlite-vec / ANN).

semantic_code_index_mcp-0.2.0/README.md

@@ -0,0 +1,53 @@
+# semantic-code-index-mcp
+
+MCP server cho Claude / Claude Code: index semantic vào SQLite, embedding chạy local (miễn phí, không API), công cụ tìm kiếm và thống kê token ước lượng.
+
+## Cài đặt
+
+```bash
+cd /path/to/semantic-code-index-mcp
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Lần đầu chạy, `fastembed` sẽ tải model ONNX (khoảng vài chục MB).
+
+## Biến môi trường
+
+- `SEMANTIC_CODE_ROOT` hoặc `WORKSPACE_ROOT`: thư mục gốc project cần index (mặc định: thư mục làm việc của process MCP).
+
+## Claude Code / Cursor MCP
+
+Thêm server (stdio), ví dụ trong cấu hình MCP của client:
+
+```json
+{
+  "mcpServers": {
+    "semantic-code-index": {
+      "command": "semantic-code-index-mcp",
+      "env": {
+        "SEMANTIC_CODE_ROOT": "/absolute/path/to/your/repo"
+      }
+    }
+  }
+}
+```
+
+Nếu không set `SEMANTIC_CODE_ROOT`, đặt `cwd` của server trỏ vào repo hoặc truyền `root_path` trong từng tool call.
+
+## Tools
+
+| Tool | Mô tả |
+|------|--------|
+| `index_project` | Index lại toàn bộ |
+| `sync_index` | Chỉ cập nhật file thay đổi / mới / xóa |
+| `semantic_search` | Tìm theo ngôn ngữ tự nhiên |
+| `token_usage_stats` | Ước lượng token “đọc full repo” vs tích lũy từ search |
+
+Database: `<root>/.semantic_index/index.sqlite3`.
+
+## Ghi chú
+
+- Đếm token dùng `tiktoken` encoding `cl100k_base` (xấp xỉ Claude/GPT-4), không phải billing thực tế.
+- Vector search hiện quét toàn bộ chunk trong SQLite; repo rất lớn có thể cần mở rộng (sqlite-vec / ANN).

semantic_code_index_mcp-0.2.0/npm/bin/cli.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { resolve, join } from "path";
+
+const RULE = `---
+description: Prefer semantic_search MCP tool over Grep/Glob for code exploration
+globs: "**/*"
+---
+
+# Semantic Code Search
+
+This project has a semantic code index (semantic-code-index MCP server).
+
+When you need to explore, understand, or find code:
+1. **Use \`semantic_search\` first** — it finds conceptually related code, not just exact string matches.
+2. Only fall back to Grep/Glob when you need exact string/pattern matching (e.g. finding a specific variable name or import).
+3. \`semantic_search\` auto-syncs changed files before searching — no need to manually sync.
+4. Run \`index_project\` once if the project has never been indexed.
+
+When spawning sub-agents (Agent tool) for code exploration or research, always include this instruction in the prompt:
+> Use the \`mcp__semantic-code-index__semantic_search\` tool to search code. It finds conceptually related code via semantic vector search. Prefer it over Grep/Glob.
+`;
+
+function mergeJson(path, entry) {
+  let config = {};
+  if (existsSync(path)) {
+    try {
+      config = JSON.parse(readFileSync(path, "utf8"));
+    } catch {}
+  }
+  config.mcpServers = config.mcpServers || {};
+  Object.assign(config.mcpServers, entry);
+  mkdirSync(resolve(path, ".."), { recursive: true });
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+  console.log(`✓ Wrote ${path}`);
+}
+
+function ensureGitignore(path, entry) {
+  let lines = [];
+  if (existsSync(path)) {
+    lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+  }
+  if (!lines.includes(entry)) {
+    lines.push(entry);
+    writeFileSync(path, lines.join("\n") + "\n");
+  }
+}
+
+function install(root, localBin) {
+  const entry = localBin
+    ? { command: resolve(localBin), env: { SEMANTIC_CODE_ROOT: root } }
+    : {
+        command: "uvx",
+        args: ["--from", "semantic-code-index-mcp", "semantic-code-index-mcp"],
+        env: { SEMANTIC_CODE_ROOT: root },
+      };
+  const serverEntry = { "semantic-code-index": entry };
+
+  mergeJson(join(root, ".claude", "mcp.json"), serverEntry);
+  mergeJson(join(root, ".mcp.json"), serverEntry);
+
+  ensureGitignore(join(root, ".gitignore"), ".mcp.json");
+  ensureGitignore(join(root, ".gitignore"), ".claude/");
+
+  const ruleFile = join(root, ".claude", "rules", "semantic-search.md");
+  mkdirSync(resolve(ruleFile, ".."), { recursive: true });
+  writeFileSync(ruleFile, RULE);
+  console.log(`✓ Wrote ${ruleFile}`);
+
+  console.log(`  root: ${root}`);
+  console.log(
+    "\nDone! Open Claude Code in this project — it will auto-detect the MCP server."
+  );
+  console.log(
+    'First time? Ask Claude: "index this project with semantic_search"'
+  );
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (cmd === "install") {
+  let target = ".";
+  let localBin = null;
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--local" && args[i + 1]) {
+      localBin = args[++i];
+    } else {
+      target = args[i];
+    }
+  }
+  install(resolve(target), localBin);
+} else {
+  console.log("Usage: npx semantic-code-index-mcp install [path] [--local bin]");
+  console.log("");
+  console.log("  Install semantic code search MCP server into a project.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --local <bin>  Use local binary instead of uvx (for dev)");
+  process.exit(cmd ? 1 : 0);
+}

semantic_code_index_mcp-0.2.0/npm/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "semantic-code-index-mcp",
+  "version": "0.2.0",
+  "description": "MCP server: semantic code search with SQLite + local embeddings. One command install for Claude Code.",
+  "bin": {
+    "semantic-code-index-mcp": "bin/cli.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thinhdo/semantic-code-index-mcp"
+  },
+  "keywords": ["mcp", "claude", "semantic-search", "code-index", "embeddings"]
+}

semantic_code_index_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "semantic-code-index-mcp"
+version = "0.2.0"
+description = "MCP server: semantic code search with SQLite + local free embeddings"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.2.0",
+    "fastembed>=0.4.0",
+    "numpy>=1.26.0",
+    "tiktoken>=0.7.0",
+]
+
+[project.scripts]
+semantic-code-index-mcp = "semantic_code_index_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["semantic_code_index_mcp"]

semantic_code_index_mcp-0.2.0/semantic_code_index_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

semantic_code_index_mcp-0.2.0/semantic_code_index_mcp/indexer.py

@@ -0,0 +1,834 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import sqlite3
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Generator
+
+import numpy as np
+import tiktoken
+
+try:
+    from fastembed import TextEmbedding
+except ImportError:
+    TextEmbedding = None  # type: ignore[misc, assignment]
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+DEFAULT_EMBED_MODEL = "BAAI/bge-small-en-v1.5"
+MAX_FILE_SIZE_BYTES = 512_000  # skip files > 512 KB
+SNIPPET_MAX_CHARS = 500
+EMBED_BATCH_SIZE = 64
+RRF_K = 60  # reciprocal rank fusion constant
+
+DEFAULT_SKIP_DIR_NAMES = frozenset(
+    {
+        ".git",
+        ".semantic_index",
+        "node_modules",
+        "__pycache__",
+        ".venv",
+        "venv",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "dist",
+        "build",
+        ".next",
+        ".turbo",
+        "target",
+        ".idea",
+        ".vscode",
+    }
+)
+
+DEFAULT_EXTENSIONS = frozenset(
+    {
+        ".py", ".pyi",
+        ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+        ".vue", ".svelte",
+        ".go", ".rs",
+        ".java", ".kt", ".cs",
+        ".rb", ".php", ".swift", ".scala",
+        ".md",
+        ".json", ".yaml", ".yml", ".toml",
+        ".html", ".css", ".scss",
+        ".sql",
+        ".sh", ".bash", ".zsh",
+        ".dockerfile",
+    }
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _normalize_path(p: Path, root: Path) -> str:
+    try:
+        rel = p.resolve().relative_to(root.resolve())
+    except ValueError:
+        rel = p
+    return rel.as_posix()
+
+
+def _fts_sanitize(query: str) -> str | None:
+    """Convert natural-language query to safe FTS5 MATCH expression."""
+    words = []
+    for word in query.split():
+        clean = "".join(c for c in word if c.isalnum() or c == "_")
+        if clean:
+            words.append(f'"{clean}"')
+    return " OR ".join(words) if words else None
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SearchHit:
+    path: str
+    start_line: int
+    end_line: int
+    score: float
+    snippet: str
+
+
+@dataclass
+class _VecCache:
+    """In-memory cache: all chunk embeddings as a single numpy matrix."""
+
+    chunk_ids: list[int] = field(default_factory=list)
+    paths: list[str] = field(default_factory=list)
+    matrix: np.ndarray | None = None  # (n, dim)
+    version: int = -1
+
+
+# ---------------------------------------------------------------------------
+# CodeIndexer
+# ---------------------------------------------------------------------------
+
+
+class CodeIndexer:
+    """Chunk code, embed locally, store in SQLite, hybrid search."""
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        db_path: Path | None = None,
+        embed_model: str = DEFAULT_EMBED_MODEL,
+        max_chunk_lines: int = 100,
+        overlap_lines: int = 15,
+    ) -> None:
+        self.root = root.resolve()
+        self.db_path = db_path or self._default_db_path(self.root)
+        self.embed_model = embed_model
+        self.max_chunk_lines = max_chunk_lines
+        self.overlap_lines = overlap_lines
+
+        self._embedder: TextEmbedding | None = None
+        self._enc = tiktoken.get_encoding("cl100k_base")
+        self._vec_cache = _VecCache()
+        self._index_version = 0
+        self._fts_available: bool | None = None
+
+    @staticmethod
+    def _default_db_path(root: Path) -> Path:
+        """~/.cache/semantic-code-index/<hash>/index.sqlite3"""
+        h = hashlib.sha256(str(root).encode()).hexdigest()[:16]
+        return Path.home() / ".cache" / "semantic-code-index" / h / "index.sqlite3"
+
+    # -- connection ----------------------------------------------------------
+
+    def _connect(self) -> sqlite3.Connection:
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(str(self.db_path))
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    @contextmanager
+    def open(self) -> Generator[sqlite3.Connection, None, None]:
+        conn = self._connect()
+        try:
+            yield conn
+        finally:
+            conn.close()
+
+    # -- schema --------------------------------------------------------------
+
+    def init_db(self, conn: sqlite3.Connection) -> None:
+        conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS meta (
+              key TEXT PRIMARY KEY,
+              value TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS files_state (
+              path TEXT PRIMARY KEY,
+              mtime REAL NOT NULL,
+              size INTEGER NOT NULL,
+              hash TEXT NOT NULL,
+              tokens INTEGER NOT NULL DEFAULT 0
+            );
+            CREATE TABLE IF NOT EXISTS chunks (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              path TEXT NOT NULL,
+              start_line INTEGER NOT NULL,
+              end_line INTEGER NOT NULL,
+              content TEXT NOT NULL,
+              embedding BLOB NOT NULL,
+              UNIQUE(path, start_line, end_line)
+            );
+            CREATE INDEX IF NOT EXISTS idx_chunks_path ON chunks(path);
+            CREATE TABLE IF NOT EXISTS metrics (
+              id INTEGER PRIMARY KEY CHECK (id = 1),
+              total_native_tokens_est INTEGER NOT NULL DEFAULT 0,
+              total_search_queries INTEGER NOT NULL DEFAULT 0,
+              total_search_result_tokens_est INTEGER NOT NULL DEFAULT 0,
+              total_query_tokens_est INTEGER NOT NULL DEFAULT 0,
+              updated_at REAL NOT NULL
+            );
+            INSERT OR IGNORE INTO metrics (id, updated_at) VALUES (1, 0);
+            CREATE TABLE IF NOT EXISTS search_log (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              ts REAL NOT NULL,
+              query TEXT NOT NULL,
+              limit_val INTEGER NOT NULL,
+              path_prefix TEXT,
+              hits INTEGER NOT NULL,
+              query_tokens INTEGER NOT NULL,
+              result_tokens INTEGER NOT NULL,
+              native_tokens_full_repo INTEGER NOT NULL,
+              duration_ms REAL NOT NULL
+            );
+            """
+        )
+        # Migrate: add tokens column if missing (upgrade from v0.1)
+        cols = {r[1] for r in conn.execute("PRAGMA table_info(files_state)").fetchall()}
+        if "tokens" not in cols:
+            conn.execute("ALTER TABLE files_state ADD COLUMN tokens INTEGER NOT NULL DEFAULT 0")
+
+        # FTS5 setup
+        if self._fts_available is None:
+            self._init_fts(conn)
+
+        conn.commit()
+
+    def _init_fts(self, conn: sqlite3.Connection) -> None:
+        """Try to create FTS5 virtual table; populate from existing chunks if needed."""
+        try:
+            conn.execute(
+                "CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts "
+                "USING fts5(content, tokenize='porter unicode61')"
+            )
+            self._fts_available = True
+            # Backfill FTS from existing chunks if FTS is empty but chunks exist
+            chunk_count = conn.execute("SELECT COUNT(*) FROM chunks").fetchone()[0]
+            if chunk_count > 0:
+                fts_count = conn.execute("SELECT COUNT(*) FROM chunks_fts").fetchone()[0]
+                if fts_count == 0:
+                    rows = conn.execute("SELECT id, content FROM chunks").fetchall()
+                    for r in rows:
+                        conn.execute(
+                            "INSERT INTO chunks_fts(rowid, content) VALUES(?, ?)",
+                            (r[0], r[1]),
+                        )
+        except Exception:
+            self._fts_available = False
+
+    # -- meta helpers --------------------------------------------------------
+
+    def _set_meta(self, conn: sqlite3.Connection, key: str, value: str) -> None:
+        conn.execute(
+            "INSERT INTO meta(key, value) VALUES(?, ?) "
+            "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+            (key, value),
+        )
+
+    def _get_meta(self, conn: sqlite3.Connection, key: str) -> str | None:
+        row = conn.execute("SELECT value FROM meta WHERE key = ?", (key,)).fetchone()
+        return str(row[0]) if row else None
+
+    # -- embedding -----------------------------------------------------------
+
+    def _get_embedder(self) -> TextEmbedding:
+        if TextEmbedding is None:
+            raise RuntimeError("fastembed is not installed")
+        if self._embedder is None:
+            self._embedder = TextEmbedding(model_name=self.embed_model)
+        return self._embedder
+
+    def _embed_batch(self, texts: list[str]) -> list[np.ndarray]:
+        model = self._get_embedder()
+        vecs: list[np.ndarray] = []
+        for emb in model.embed(texts):
+            v = np.asarray(emb, dtype=np.float32)
+            n = np.linalg.norm(v)
+            if n > 0:
+                v = v / n
+            vecs.append(v)
+        return vecs
+
+    def _blob_from_vec(self, v: np.ndarray) -> bytes:
+        return v.astype(np.float32).tobytes()
+
+    def _vec_from_blob(self, blob: bytes) -> np.ndarray:
+        return np.frombuffer(blob, dtype=np.float32).copy()
+
+    # -- tokenizer -----------------------------------------------------------
+
+    def count_tokens(self, text: str) -> int:
+        return len(self._enc.encode(text))
+
+    # -- file iteration ------------------------------------------------------
+
+    def _iter_source_files(self) -> list[Path]:
+        out: list[Path] = []
+        root = self.root
+        for dirpath, dirnames, filenames in os.walk(root, topdown=True):
+            dirnames[:] = [d for d in dirnames if d not in DEFAULT_SKIP_DIR_NAMES]
+            base = Path(dirpath)
+            for name in filenames:
+                p = base / name
+                if p.suffix.lower() in DEFAULT_EXTENSIONS or name == "Dockerfile":
+                    try:
+                        if p.stat().st_size > MAX_FILE_SIZE_BYTES:
+                            continue
+                    except OSError:
+                        continue
+                    out.append(p)
+        return sorted(out)
+
+    # -- chunking ------------------------------------------------------------
+
+    def _chunk_file(self, _rel_path: str, text: str) -> list[tuple[int, int, str]]:
+        lines = text.splitlines(keepends=True)
+        if not lines:
+            return []
+        chunks: list[tuple[int, int, str]] = []
+        i = 0
+        n = len(lines)
+        max_l = self.max_chunk_lines
+        ov = self.overlap_lines
+        while i < n:
+            end = min(i + max_l, n)
+            block = "".join(lines[i:end])
+            chunks.append((i + 1, end, block))
+            if end >= n:
+                break
+            i = max(end - ov, i + 1)
+        return chunks
+
+    # -- chunk CRUD (with FTS sync) ------------------------------------------
+
+    def _delete_path_chunks(self, conn: sqlite3.Connection, path: str) -> None:
+        """Delete all chunks (+ FTS entries) for a given path."""
+        if self._fts_available:
+            ids = [
+                r[0]
+                for r in conn.execute(
+                    "SELECT id FROM chunks WHERE path = ?", (path,)
+                ).fetchall()
+            ]
+            if ids:
+                placeholders = ",".join("?" * len(ids))
+                conn.execute(
+                    f"DELETE FROM chunks_fts WHERE rowid IN ({placeholders})", ids
+                )
+        conn.execute("DELETE FROM chunks WHERE path = ?", (path,))
+
+    def _insert_chunk(
+        self,
+        conn: sqlite3.Connection,
+        path: str,
+        sl: int,
+        el: int,
+        content: str,
+        vec: np.ndarray,
+    ) -> None:
+        cur = conn.execute(
+            "INSERT INTO chunks(path, start_line, end_line, content, embedding) "
+            "VALUES(?,?,?,?,?)",
+            (path, sl, el, content, self._blob_from_vec(vec)),
+        )
+        if self._fts_available:
+            conn.execute(
+                "INSERT INTO chunks_fts(rowid, content) VALUES(?, ?)",
+                (cur.lastrowid, content),
+            )
+
+    # -- vector cache --------------------------------------------------------
+
+    def _invalidate_vec_cache(self) -> None:
+        self._index_version += 1
+
+    def _load_vec_cache(self, conn: sqlite3.Connection) -> None:
+        if self._vec_cache.version == self._index_version:
+            return
+        rows = conn.execute("SELECT id, path, embedding FROM chunks").fetchall()
+        if not rows:
+            self._vec_cache = _VecCache(version=self._index_version)
+            return
+        ids = [r[0] for r in rows]
+        paths = [str(r[1]) for r in rows]
+        dim = len(np.frombuffer(rows[0][2], dtype=np.float32))
+        matrix = np.empty((len(rows), dim), dtype=np.float32)
+        for i, r in enumerate(rows):
+            matrix[i] = np.frombuffer(r[2], dtype=np.float32)
+        self._vec_cache = _VecCache(
+            chunk_ids=ids, paths=paths, matrix=matrix, version=self._index_version
+        )
+
+    # -- index full ----------------------------------------------------------
+
+    def index_full(self, conn: sqlite3.Connection) -> dict[str, int | float | str]:
+        """Full rebuild: clear everything and re-index all source files."""
+        self.init_db(conn)
+        conn.execute("DELETE FROM chunks")
+        conn.execute("DELETE FROM files_state")
+        if self._fts_available:
+            conn.execute("DELETE FROM chunks_fts")
+        conn.commit()
+
+        files = self._iter_source_files()
+        inserted = 0
+        native_tokens = 0
+        batch_texts: list[str] = []
+        batch_rows: list[tuple[str, int, int, str]] = []
+        t0 = time.time()
+
+        def flush() -> None:
+            nonlocal inserted
+            if not batch_texts:
+                return
+            vecs = self._embed_batch(batch_texts)
+            for (path, sl, el, content), v in zip(batch_rows, vecs, strict=True):
+                self._insert_chunk(conn, path, sl, el, content, v)
+                inserted += 1
+            batch_texts.clear()
+            batch_rows.clear()
+
+        for fp in files:
+            rel = _normalize_path(fp, self.root)
+            try:
+                raw = fp.read_bytes()
+                text = raw.decode("utf-8", errors="replace")
+            except OSError:
+                continue
+            st = fp.stat()
+            h = _sha256_text(text)
+            tok = self.count_tokens(text)
+            native_tokens += tok
+            conn.execute(
+                "INSERT INTO files_state(path, mtime, size, hash, tokens) VALUES(?,?,?,?,?) "
+                "ON CONFLICT(path) DO UPDATE SET mtime=excluded.mtime, size=excluded.size, "
+                "hash=excluded.hash, tokens=excluded.tokens",
+                (rel, st.st_mtime, st.st_size, h, tok),
+            )
+            for sl, el, content in self._chunk_file(rel, text):
+                batch_rows.append((rel, sl, el, content))
+                batch_texts.append(content[:8000])
+                if len(batch_texts) >= EMBED_BATCH_SIZE:
+                    flush()
+
+        flush()
+        conn.execute(
+            "UPDATE metrics SET total_native_tokens_est = ?, updated_at = ? WHERE id = 1",
+            (native_tokens, time.time()),
+        )
+        self._set_meta(conn, "embed_model", self.embed_model)
+        self._set_meta(conn, "last_full_index", str(time.time()))
+        conn.commit()
+        self._invalidate_vec_cache()
+        return {
+            "files_indexed": len(files),
+            "chunks": inserted,
+            "native_tokens_est": native_tokens,
+            "seconds": round(time.time() - t0, 2),
+        }
+
+    # -- incremental sync ----------------------------------------------------
+
+    def sync_incremental(
+        self, conn: sqlite3.Connection
+    ) -> dict[str, int | float | str | list[str]]:
+        """Update index for changed / new / removed files (incremental tokens)."""
+        self.init_db(conn)
+        disk_files = {_normalize_path(p, self.root): p for p in self._iter_source_files()}
+        rows = conn.execute(
+            "SELECT path, mtime, size, hash, tokens FROM files_state"
+        ).fetchall()
+        db_state = {
+            str(r["path"]): (float(r["mtime"]), int(r["size"]), str(r["hash"]), int(r["tokens"]))
+            for r in rows
+        }
+
+        # Current native_tokens from metrics
+        m = conn.execute(
+            "SELECT total_native_tokens_est FROM metrics WHERE id = 1"
+        ).fetchone()
+        native_tokens = int(m[0] or 0)
+
+        # Removed files
+        removed = [p for p in db_state if p not in disk_files]
+        for p in removed:
+            self._delete_path_chunks(conn, p)
+            native_tokens -= db_state[p][3]  # subtract old tokens
+            conn.execute("DELETE FROM files_state WHERE path = ?", (p,))
+
+        # Changed / new files
+        to_reindex: list[str] = []
+        batch_texts: list[str] = []
+        batch_rows: list[tuple[str, int, int, str]] = []
+
+        def flush() -> None:
+            if not batch_texts:
+                return
+            vecs = self._embed_batch(batch_texts)
+            for (path, sl, el, content), v in zip(batch_rows, vecs, strict=True):
+                self._insert_chunk(conn, path, sl, el, content, v)
+            batch_texts.clear()
+            batch_rows.clear()
+
+        for rel, fp in sorted(disk_files.items()):
+            try:
+                st = fp.stat()
+            except OSError:
+                continue
+            prev = db_state.get(rel)
+            # Quick check: mtime + size unchanged → skip (no hash needed)
+            if prev and prev[0] == st.st_mtime and prev[1] == st.st_size:
+                continue
+            try:
+                raw = fp.read_bytes()
+                text = raw.decode("utf-8", errors="replace")
+            except OSError:
+                continue
+            h = _sha256_text(text)
+            # If hash matches (mtime changed but content didn't), just update mtime
+            if prev and prev[2] == h:
+                conn.execute(
+                    "UPDATE files_state SET mtime = ?, size = ? WHERE path = ?",
+                    (st.st_mtime, st.st_size, rel),
+                )
+                continue
+
+            to_reindex.append(rel)
+            # Adjust native token count: subtract old, add new
+            tok = self.count_tokens(text)
+            if prev:
+                native_tokens -= prev[3]
+            native_tokens += tok
+
+            self._delete_path_chunks(conn, rel)
+            conn.execute(
+                "INSERT INTO files_state(path, mtime, size, hash, tokens) VALUES(?,?,?,?,?) "
+                "ON CONFLICT(path) DO UPDATE SET mtime=excluded.mtime, size=excluded.size, "
+                "hash=excluded.hash, tokens=excluded.tokens",
+                (rel, st.st_mtime, st.st_size, h, tok),
+            )
+            for sl, el, content in self._chunk_file(rel, text):
+                batch_rows.append((rel, sl, el, content))
+                batch_texts.append(content[:8000])
+                if len(batch_texts) >= EMBED_BATCH_SIZE:
+                    flush()
+
+        flush()
+        conn.execute(
+            "UPDATE metrics SET total_native_tokens_est = ?, updated_at = ? WHERE id = 1",
+            (native_tokens, time.time()),
+        )
+        conn.commit()
+        self._invalidate_vec_cache()
+        return {
+            "removed_paths": len(removed),
+            "reindexed_files": len(to_reindex),
+            "paths_reindexed": to_reindex[:50],
+            "native_tokens_est": native_tokens,
+        }
+
+    # -- needs sync (fast stat-only check) -----------------------------------
+
+    def needs_sync(self, conn: sqlite3.Connection) -> bool:
+        """Quick O(n) stat check — no file reads, no hashing."""
+        self.init_db(conn)
+        disk_files = {_normalize_path(p, self.root): p for p in self._iter_source_files()}
+        rows = conn.execute("SELECT path, mtime, size FROM files_state").fetchall()
+        db_paths: set[str] = set()
+        for r in rows:
+            path = str(r["path"])
+            db_paths.add(path)
+            fp = disk_files.get(path)
+            if fp is None:
+                return True  # file removed
+            try:
+                st = fp.stat()
+            except OSError:
+                return True
+            if float(r["mtime"]) != st.st_mtime or int(r["size"]) != st.st_size:
+                return True
+        if set(disk_files.keys()) - db_paths:
+            return True  # new files
+        return False
+
+    # -- search --------------------------------------------------------------
+
+    def _semantic_search(
+        self,
+        conn: sqlite3.Connection,
+        query_vec: np.ndarray,
+        limit: int,
+        path_prefix: str | None = None,
+    ) -> list[tuple[int, float]]:
+        """Vectorized cosine search via cached numpy matrix."""
+        self._load_vec_cache(conn)
+        cache = self._vec_cache
+        if cache.matrix is None or len(cache.chunk_ids) == 0:
+            return []
+
+        scores = cache.matrix @ query_vec
+
+        if path_prefix:
+            mask = np.array(
+                [p.startswith(path_prefix) for p in cache.paths], dtype=bool
+            )
+            scores = np.where(mask, scores, -np.inf)
+
+        k = min(limit, len(cache.chunk_ids))
+        if k < len(cache.chunk_ids):
+            indices = np.argpartition(scores, -k)[-k:]
+        else:
+            indices = np.arange(len(cache.chunk_ids))
+        indices = indices[np.argsort(scores[indices])[::-1]]
+        return [
+            (cache.chunk_ids[i], float(scores[i]))
+            for i in indices
+            if scores[i] > -np.inf
+        ]
+
+    def _keyword_search(
+        self,
+        conn: sqlite3.Connection,
+        query: str,
+        limit: int,
+        path_prefix: str | None = None,
+    ) -> list[tuple[int, float]]:
+        """FTS5 BM25 keyword search."""
+        if not self._fts_available:
+            return []
+        fts_q = _fts_sanitize(query)
+        if not fts_q:
+            return []
+        try:
+            if path_prefix:
+                rows = conn.execute(
+                    "SELECT rowid, bm25(chunks_fts) AS score FROM chunks_fts "
+                    "WHERE chunks_fts MATCH ? "
+                    "AND rowid IN (SELECT id FROM chunks WHERE path LIKE ? || '%') "
+                    "ORDER BY score LIMIT ?",
+                    (fts_q, path_prefix, limit),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT rowid, bm25(chunks_fts) AS score FROM chunks_fts "
+                    "WHERE chunks_fts MATCH ? ORDER BY score LIMIT ?",
+                    (fts_q, limit),
+                ).fetchall()
+        except sqlite3.OperationalError:
+            return []
+        # bm25() returns negative scores (lower = more relevant)
+        return [(int(r[0]), -float(r[1])) for r in rows]
+
+    def search(
+        self,
+        conn: sqlite3.Connection,
+        query: str,
+        *,
+        limit: int = 12,
+        path_prefix: str | None = None,
+    ) -> tuple[list[SearchHit], dict[str, object]]:
+        """Hybrid search: semantic + keyword fused with Reciprocal Rank Fusion.
+
+        Returns (hits, usage) where usage contains token stats for this query.
+        """
+        self.init_db(conn)
+        t0 = time.time()
+        query_vec = self._embed_batch([query])[0]
+
+        fetch_limit = limit * 3
+        sem_results = self._semantic_search(conn, query_vec, fetch_limit, path_prefix)
+        kw_results = self._keyword_search(conn, query, fetch_limit, path_prefix)
+
+        rrf: dict[int, float] = {}
+        for rank, (cid, _score) in enumerate(sem_results):
+            rrf[cid] = rrf.get(cid, 0.0) + 1.0 / (RRF_K + rank + 1)
+        for rank, (cid, _score) in enumerate(kw_results):
+            rrf[cid] = rrf.get(cid, 0.0) + 1.0 / (RRF_K + rank + 1)
+
+        top_ids = sorted(rrf, key=lambda k: rrf[k], reverse=True)[:limit]
+
+        hits: list[SearchHit] = []
+        for cid in top_ids:
+            row = conn.execute(
+                "SELECT path, start_line, end_line, content FROM chunks WHERE id = ?",
+                (cid,),
+            ).fetchone()
+            if not row:
+                continue
+            content = str(row["content"])
+            snippet = content[:SNIPPET_MAX_CHARS] + ("…" if len(content) > SNIPPET_MAX_CHARS else "")
+            hits.append(
+                SearchHit(
+                    path=str(row["path"]),
+                    start_line=int(row["start_line"]),
+                    end_line=int(row["end_line"]),
+                    score=rrf[cid],
+                    snippet=snippet,
+                )
+            )
+
+        q_tokens = self.count_tokens(query)
+        result_text = "\n\n".join(h.snippet for h in hits)
+        r_tokens = self.count_tokens(result_text)
+        duration_ms = round((time.time() - t0) * 1000, 1)
+        native = int(
+            conn.execute(
+                "SELECT total_native_tokens_est FROM metrics WHERE id = 1"
+            ).fetchone()[0] or 0
+        )
+
+        conn.execute(
+            """
+            UPDATE metrics SET
+              total_search_queries = total_search_queries + 1,
+              total_search_result_tokens_est = total_search_result_tokens_est + ?,
+              total_query_tokens_est = total_query_tokens_est + ?,
+              updated_at = ?
+            WHERE id = 1
+            """,
+            (r_tokens, q_tokens, time.time()),
+        )
+        now = time.time()
+        conn.execute("DELETE FROM search_log WHERE ts < ?", (now - 86400,))
+        conn.execute(
+            "INSERT INTO search_log(ts, query, limit_val, path_prefix, hits, "
+            "query_tokens, result_tokens, native_tokens_full_repo, duration_ms) "
+            "VALUES(?,?,?,?,?,?,?,?,?)",
+            (now, query, limit, path_prefix, len(hits),
+             q_tokens, r_tokens, native, duration_ms),
+        )
+        conn.commit()
+
+        usage = {
+            "query_tokens": q_tokens,
+            "result_tokens": r_tokens,
+            "total_tokens": q_tokens + r_tokens,
+            "native_tokens_full_repo": native,
+            "saved_tokens": native - (q_tokens + r_tokens) if native else None,
+            "duration_ms": duration_ms,
+        }
+        return hits, usage
+
+    # -- list / detail -------------------------------------------------------
+
+    def list_files(self, conn: sqlite3.Connection) -> list[dict[str, object]]:
+        """List all indexed files with token count and chunk count."""
+        self.init_db(conn)
+        rows = conn.execute(
+            "SELECT fs.path, fs.tokens, COUNT(c.id) AS chunks "
+            "FROM files_state fs "
+            "LEFT JOIN chunks c ON c.path = fs.path "
+            "GROUP BY fs.path ORDER BY fs.path"
+        ).fetchall()
+        return [
+            {"path": str(r["path"]), "tokens": int(r["tokens"]), "chunks": int(r["chunks"])}
+            for r in rows
+        ]
+
+    def get_file_chunks(self, conn: sqlite3.Connection, path: str) -> list[dict[str, object]]:
+        """Return all chunks for a given file path (full content, no truncation)."""
+        self.init_db(conn)
+        rows = conn.execute(
+            "SELECT start_line, end_line, content FROM chunks WHERE path = ? "
+            "ORDER BY start_line",
+            (path,),
+        ).fetchall()
+        return [
+            {
+                "start_line": int(r["start_line"]),
+                "end_line": int(r["end_line"]),
+                "content": str(r["content"]),
+            }
+            for r in rows
+        ]
+
+    # -- stats ---------------------------------------------------------------
+
+    def stats(self, conn: sqlite3.Connection) -> dict[str, object]:
+        self.init_db(conn)
+        n_chunks = int(conn.execute("SELECT COUNT(*) FROM chunks").fetchone()[0])
+        n_files = int(conn.execute("SELECT COUNT(*) FROM files_state").fetchone()[0])
+        m = conn.execute(
+            "SELECT total_native_tokens_est, total_search_queries, "
+            "total_search_result_tokens_est, total_query_tokens_est "
+            "FROM metrics WHERE id = 1"
+        ).fetchone()
+        native = int(m[0] or 0)
+        nq = int(m[1] or 0)
+        rtok = int(m[2] or 0)
+        qtok = int(m[3] or 0)
+        avg_per_query = (qtok + rtok) / nq if nq else 0
+        ratio = (qtok + rtok) / native if native else None
+        return {
+            "files_indexed": n_files,
+            "chunks": n_chunks,
+            "fts5_enabled": bool(self._fts_available),
+            "embed_model": self._get_meta(conn, "embed_model") or self.embed_model,
+            "index_db": str(self.db_path),
+            "root": str(self.root),
+            "native_tokens_est_full_repo": native,
+            "search_queries": nq,
+            "search_total_query_tokens_est": qtok,
+            "search_total_result_tokens_est": rtok,
+            "search_avg_tokens_per_query_est": round(avg_per_query, 2),
+            "search_vs_native_ratio_est": round(ratio, 6) if ratio is not None else None,
+        }
+
+    def search_logs(
+        self, conn: sqlite3.Connection, last_n: int = 50
+    ) -> list[dict[str, object]]:
+        self.init_db(conn)
+        rows = conn.execute(
+            "SELECT ts, query, limit_val, path_prefix, hits, "
+            "query_tokens, result_tokens, native_tokens_full_repo, duration_ms "
+            "FROM search_log ORDER BY id DESC LIMIT ?",
+            (last_n,),
+        ).fetchall()
+        return [
+            {
+                "ts": r["ts"],
+                "query": r["query"],
+                "limit": r["limit_val"],
+                "path_prefix": r["path_prefix"],
+                "hits": r["hits"],
+                "query_tokens": r["query_tokens"],
+                "result_tokens": r["result_tokens"],
+                "native_tokens_full_repo": r["native_tokens_full_repo"],
+                "saved_tokens": r["native_tokens_full_repo"] - r["query_tokens"] - r["result_tokens"],
+                "duration_ms": r["duration_ms"],
+            }
+            for r in rows
+        ]

semantic_code_index_mcp-0.2.0/semantic_code_index_mcp/server.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from semantic_code_index_mcp.indexer import CodeIndexer
+
+mcp = FastMCP(
+    "semantic-code-index",
+    instructions=(
+        "Semantic code search over a local index (SQLite + local embeddings). "
+        "Use semantic_search to find code — it auto-syncs changed files before searching. "
+        "Call index_project once per workspace for initial setup. "
+        "Use list_indexed_files to see what's indexed, get_file_chunks for full content."
+    ),
+)
+
+_indexer_cache: dict[str, CodeIndexer] = {}
+
+
+def _default_root() -> Path:
+    env = os.environ.get("SEMANTIC_CODE_ROOT") or os.environ.get("WORKSPACE_ROOT")
+    if env:
+        return Path(env).expanduser().resolve()
+    return Path.cwd()
+
+
+def _get_indexer(root: str | None = None) -> CodeIndexer:
+    r = Path(root).expanduser().resolve() if root else _default_root()
+    key = str(r)
+    if key not in _indexer_cache:
+        _indexer_cache[key] = CodeIndexer(r)
+    return _indexer_cache[key]
+
+
+@mcp.tool()
+def index_project(root_path: str | None = None) -> str:
+    """Full re-index: xóa index cũ và vector hóa lại toàn bộ codebase dưới root_path (hoặc SEMANTIC_CODE_ROOT / cwd)."""
+    idx = _get_indexer(root_path)
+    with idx.open() as conn:
+        out = idx.index_full(conn)
+    return json.dumps(out, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+def sync_index(root_path: str | None = None) -> str:
+    """Đồng bộ tăng dần: file mới/sửa/xóa → cập nhật chunk + embedding; không đụng file không đổi."""
+    idx = _get_indexer(root_path)
+    with idx.open() as conn:
+        out = idx.sync_incremental(conn)
+    return json.dumps(out, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+def semantic_search(
+    query: str,
+    limit: int = 12,
+    path_prefix: str | None = None,
+    auto_sync: bool = True,
+    root_path: str | None = None,
+) -> str:
+    """Tìm đoạn code liên quan (hybrid: semantic vector + keyword BM25).
+    auto_sync=true sẽ tự đồng bộ file thay đổi trước khi tìm.
+    path_prefix lọc theo tiền tố đường dẫn tương đối."""
+    idx = _get_indexer(root_path)
+    with idx.open() as conn:
+        if auto_sync and idx.needs_sync(conn):
+            idx.sync_incremental(conn)
+        hits, usage = idx.search(
+            conn, query, limit=min(max(limit, 1), 50), path_prefix=path_prefix
+        )
+    payload = {
+        "results": [
+            {
+                "path": h.path,
+                "lines": [h.start_line, h.end_line],
+                "score": round(h.score, 6),
+                "snippet": h.snippet,
+            }
+            for h in hits
+        ],
+        "usage": usage,
+    }
+    return json.dumps(payload, ensure_ascii=False)
+
+
+@mcp.tool()
+def list_indexed_files(root_path: str | None = None) -> str:
+    """Liệt kê các file đã index, kèm token count và số chunks mỗi file."""
+    idx = _get_indexer(root_path)
+    with idx.open() as conn:
+        out = idx.list_files(conn)
+    return json.dumps(out, ensure_ascii=False)
+
+
+@mcp.tool()
+def get_file_chunks(path: str, root_path: str | None = None) -> str:
+    """Lấy toàn bộ chunks đã index của một file (full content, không cắt). Dùng sau semantic_search để xem context đầy đủ."""
+    idx = _get_indexer(root_path)
+    with idx.open() as conn:
+        out = idx.get_file_chunks(conn, path)
+    return json.dumps(out, ensure_ascii=False)
+
+
+@mcp.tool()
+def token_usage_stats(root_path: str | None = None) -> str:
+    """So sánh tích lũy: token ước lượng nếu đọc full repo đã index vs token query+kết quả từ semantic_search."""
+    idx = _get_indexer(root_path)
+    with idx.open() as conn:
+        out = idx.stats(conn)
+    return json.dumps(out, ensure_ascii=False)
+
+
+@mcp.tool()
+def search_log(last_n: int = 50, root_path: str | None = None) -> str:
+    """Xem log các lần search gần đây: query, tokens dùng, tokens tiết kiệm, thời gian."""
+    idx = _get_indexer(root_path)
+    with idx.open() as conn:
+        out = idx.search_logs(conn, last_n)
+    return json.dumps(out, ensure_ascii=False)
+
+
+def _find_server_bin() -> str:
+    bin_path = shutil.which("semantic-code-index-mcp")
+    if bin_path:
+        return str(Path(bin_path).resolve())
+    return str(Path(sys.executable).parent / "semantic-code-index-mcp")
+
+
+def _merge_mcp_entry(path: Path, server_bin: str, root: Path) -> None:
+    config: dict = {}
+    if path.exists():
+        try:
+            config = json.loads(path.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    config.setdefault("mcpServers", {})
+    config["mcpServers"]["semantic-code-index"] = {
+        "command": server_bin,
+        "env": {"SEMANTIC_CODE_ROOT": str(root)},
+    }
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config, indent=2, ensure_ascii=False) + "\n")
+    print(f"✓ Wrote {path}")
+
+
+def _ensure_gitignore(gitignore: Path, entry: str) -> None:
+    lines: list[str] = []
+    if gitignore.exists():
+        lines = gitignore.read_text().splitlines()
+    if entry not in lines:
+        lines.append(entry)
+        gitignore.write_text("\n".join(lines) + "\n")
+
+
+_SEMANTIC_SEARCH_RULE = """\
+---
+description: Prefer semantic_search MCP tool over Grep/Glob for code exploration
+globs: "**/*"
+---
+
+# Semantic Code Search
+
+This project has a semantic code index (semantic-code-index MCP server).
+
+When you need to explore, understand, or find code:
+1. **Use `semantic_search` first** — it finds conceptually related code, not just exact string matches.
+2. Only fall back to Grep/Glob when you need exact string/pattern matching (e.g. finding a specific variable name or import).
+3. `semantic_search` auto-syncs changed files before searching — no need to manually sync.
+4. Run `index_project` once if the project has never been indexed.
+
+When spawning sub-agents (Agent tool) for code exploration or research, always include this instruction in the prompt:
+> Use the `mcp__semantic-code-index__semantic_search` tool to search code. It finds conceptually related code via semantic vector search. Prefer it over Grep/Glob.
+"""
+
+
+def install(target: str | None = None) -> None:
+    root = Path(target).expanduser().resolve() if target else Path.cwd()
+    server_bin = _find_server_bin()
+
+    _merge_mcp_entry(root / ".claude" / "mcp.json", server_bin, root)
+
+    _merge_mcp_entry(root / ".mcp.json", server_bin, root)
+    _ensure_gitignore(root / ".gitignore", ".mcp.json")
+    _ensure_gitignore(root / ".gitignore", ".claude/")
+
+    rule_file = root / ".claude" / "rules" / "semantic-search.md"
+    rule_file.parent.mkdir(parents=True, exist_ok=True)
+    rule_file.write_text(_SEMANTIC_SEARCH_RULE)
+    print(f"✓ Wrote {rule_file}")
+
+    print(f"  server: {server_bin}")
+    print(f"  root:   {root}")
+    db = CodeIndexer._default_db_path(root)
+    print(f"  db:     {db}")
+
+
+def main() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] == "install":
+        target = sys.argv[2] if len(sys.argv) > 2 else None
+        install(target)
+    else:
+        mcp.run()