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