scythe-context-mcp 0.1.0

package/docs/gemini-compatibility.md

@@ -0,0 +1,214 @@
+# Gemini Embedding 2 與第三方 v1beta 中轉站相容設計
+
+## 官方 Gemini REST 格式
+
+官方 Gemini Embedding 2 REST endpoint：
+
+```text
+POST https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent
+```
+
+官方 key header：
+
+```text
+x-goog-api-key: $GEMINI_API_KEY
+```
+
+Scythe Context 預設設定：
+
+```env
+GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
+GEMINI_MODEL=gemini-embedding-2
+GEMINI_AUTH_MODE=x-goog-api-key
+GEMINI_API_KEY_HEADER=x-goog-api-key
+GEMINI_OUTPUT_DIMENSIONALITY=1536
+```
+
+## Embedding 2 query/document 格式
+
+Gemini Embedding 2 不用 `task_type` 欄位，而是在文字中加 task prefix。
+
+查詢：
+
+```text
+task: code retrieval | query: {query}
+```
+
+文件 chunk：
+
+```text
+title: {path or symbol} | text: {chunk}
+```
+
+Scythe Context 的 `GeminiEmbeddingProvider` 會自動套用這個格式。
+
+## Output dimensionality
+
+預設使用 1536 維：
+
+```env
+GEMINI_OUTPUT_DIMENSIONALITY=1536
+```
+
+建議：
+
+- `768`: 省空間，速度快，適合非常小的個人 repo 或低成本模式。
+- `1536`: Scythe Context 預設，精度與成本較平衡。
+- `3072`: 最高精度，但索引體積與相似度計算成本較高。
+
+## 第三方 v1beta 中轉站
+
+很多中轉站會保留 Google v1beta path：
+
+```text
+POST https://proxy.example.com/v1beta/models/gemini-embedding-2:embedContent
+```
+
+這種情況只要改：
+
+```env
+GEMINI_BASE_URL=https://proxy.example.com/v1beta
+GEMINI_API_KEY=proxy-key
+```
+
+`GEMINI_BASE_URL` 會先正規化，支援下列形式：
+
+```text
+https://proxy.example.com
+https://proxy.example.com/
+https://proxy.example.com/v1beta
+https://proxy.example.com/v1beta/
+https://proxy.example.com/gemini
+https://proxy.example.com/gemini/v1beta/
+```
+
+如果 URL 最後不是 `v1` 或 `v1beta`，Scythe Context 會自動補上 `/v1beta`。如果中轉站已經給完整 `/v1beta` 或 `/v1`，則不會重複追加。
+
+如果中轉站使用 Bearer token：
+
+```env
+GEMINI_AUTH_MODE=bearer
+```
+
+會送出：
+
+```text
+Authorization: Bearer proxy-key
+```
+
+如果中轉站使用 query key：
+
+```env
+GEMINI_AUTH_MODE=query
+GEMINI_API_KEY_QUERY_PARAM=key
+```
+
+會送出：
+
+```text
+...?key=proxy-key
+```
+
+如果中轉站自訂 header：
+
+```env
+GEMINI_AUTH_MODE=x-goog-api-key
+GEMINI_API_KEY_HEADER=Authorization
+```
+
+注意：這種模式會送 `Authorization: {key}`，不會自動加 `Bearer `；需要 Bearer 時應使用 `GEMINI_AUTH_MODE=bearer`。
+
+## Batch 相容性
+
+官方 batch endpoint：
+
+```text
+POST /v1beta/models/gemini-embedding-2:batchEmbedContents
+```
+
+部分中轉站可能只支援 `embedContent`，不支援 batch。Phase 2 實作索引時需要：
+
+1. 優先嘗試 batch。
+2. 如果 batch request 失敗，索引流程 fallback 到逐筆 `embedContent`。
+3. 後續可加入 provider capability cache，避免每次重試 batch。
+
+目前 `embedBatch` 已按官方 batch 格式送出，`repo_reindex(index_embeddings=true)` 的 embedding writer 會在 batch 失敗時 fallback 到單筆 embedding，並在結果中回報 `batchFallbacks`。
+
+## Codex MCP 設定範例
+
+官方 Gemini：
+
+```toml
+[mcp_servers.scythe_context]
+command = "node"
+args = ["/path/to/scythe-context-mcp/dist/index.js"]
+cwd = "/path/to/scythe-context-mcp"
+env_vars = ["GEMINI_API_KEY"]
+
+[mcp_servers.scythe_context.env]
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+GEMINI_AUTH_MODE = "x-goog-api-key"
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
+
+Bearer 中轉站：
+
+```toml
+[mcp_servers.scythe_context]
+command = "node"
+args = ["/path/to/scythe-context-mcp/dist/index.js"]
+cwd = "/path/to/scythe-context-mcp"
+env_vars = ["GEMINI_API_KEY"]
+
+[mcp_servers.scythe_context.env]
+GEMINI_BASE_URL = "https://proxy.example.com/v1beta"
+GEMINI_AUTH_MODE = "bearer"
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
+
+Query key 中轉站：
+
+```toml
+[mcp_servers.scythe_context]
+command = "node"
+args = ["/path/to/scythe-context-mcp/dist/index.js"]
+cwd = "/path/to/scythe-context-mcp"
+env_vars = ["GEMINI_API_KEY"]
+
+[mcp_servers.scythe_context.env]
+GEMINI_BASE_URL = "https://proxy.example.com/v1beta"
+GEMINI_AUTH_MODE = "query"
+GEMINI_API_KEY_QUERY_PARAM = "key"
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
+
+## 測試方式
+
+啟動 MCP 後呼叫：
+
+```text
+gemini_embedding_probe({ "text": "find code that handles payment logging" })
+```
+
+成功時應回：
+
+```json
+{
+  "status": "ok",
+  "latencyMs": 123,
+  "model": "gemini-embedding-2",
+  "dimensions": 1536,
+  "dimensionsMatchExpected": true,
+  "sample": [0.01, -0.02]
+}
+```
+
+失敗時會回傳 `status: "embedding_probe_failed"`、HTTP status、retryable 判斷、截斷後的 response snippet 與可修復建議；不會回傳 API key。
+
+如果失敗，優先檢查：
+
+1. `GEMINI_BASE_URL` 是否是正確中轉站根路徑；可帶或不帶 `/v1beta`。
+2. 中轉站是否真的支援 `models/{model}:embedContent`。
+3. auth 是 header、Bearer 還是 query。
+4. 中轉站是否支援 `output_dimensionality`。
+5. 模型名稱是否要用 `gemini-embedding-2` 或 `models/gemini-embedding-2`。

package/docs/tech-stack.md

@@ -0,0 +1,122 @@
+# 技術棧與效能設計
+
+## Runtime
+
+目標 runtime：
+
+- Node.js 24 LTS。
+- `package.json` 設定為 `>=24.11.0 <27`。
+- Node 26 可能可跑，但在進入 LTS 前不作為主要驗收基準。
+
+原因：
+
+- Codex MCP server 是本機長駐/短啟動工具，穩定性比追新 API 重要。
+- Node 24 已提供穩定 `fetch`、ESM、Web API 與足夠新的 V8。
+- 避免 Node 20 這類已不適合作為新專案基線的版本。
+
+## Current Dependencies
+
+| Package | 用途 | 策略 |
+| --- | --- | --- |
+| `@modelcontextprotocol/sdk` | MCP server / stdio transport | 用最新 1.x 穩定版 |
+| `zod` | MCP tool input schema | 用 v4；MCP SDK 支援 v3/v4 |
+| `dotenv` | 本機 `.env` 載入 | 只用於 dev/local |
+| `fast-glob` | repo scanner | Phase 1 使用 |
+| `ignore` | `.gitignore` 規則 | Phase 1 使用 |
+| `typescript` | typecheck/build | 用目前穩定版 |
+| `tsx` | dev runner | 只用於開發 |
+| `vitest` | unit tests | Phase 1 開始加入 |
+| `better-sqlite3` | SQLite native driver | 同步 API 簡單、效能好，適合本機 MCP |
+| `sqlite-vec` | SQLite vector extension | `vec0(embedding float[1536])` |
+
+暫不引入：
+
+- ORM：schema 很小，直接 SQL 更可控。
+- LangChain/LlamaIndex：抽象太厚，對本機 code search 反而增加不可控成本。
+- 外部向量 DB：MVP 不需要啟動 Qdrant/Weaviate 這類服務。
+- tree-sitter：目前先用輕量 regex symbol graph；只有當 retrieval 品質瓶頸明確時才引入。
+
+## Storage Choice
+
+正式索引從 Phase 2 使用：
+
+- SQLite metadata。
+- SQLite FTS5 keyword index。
+- sqlite-vec vector table。
+
+1536 維 float32 向量約 6 KB/chunk，不含 SQLite overhead。估算：
+
+```text
+1,000 chunks  ~= 6 MB vector raw data
+10,000 chunks ~= 60 MB vector raw data
+50,000 chunks ~= 300 MB vector raw data
+```
+
+這個量級仍適合本機 SQLite，但不適合 JSON vector 全表解析。
+
+Spike 結論：
+
+- Node 24 LTS + WSL 可載入 `sqlite-vec`。
+- `better-sqlite3` 可建立 `vec0(embedding float[1536])` virtual table。
+- 寫入 sqlite-vec virtual table 的 `rowid` 需要用 `BigInt` 綁定。
+- vector 以 `Float32Array` buffer 寫入與查詢。
+
+## Performance Targets
+
+Phase 1 scanner/chunker：
+
+- 小型 repo: < 1,000 files，dry-run 目標 < 2s。
+- 中型 repo: < 10,000 files，dry-run 目標 < 10s。
+- 大檔預設跳過或截斷，不允許單檔拖垮整次索引。
+
+Phase 2 indexing：
+
+- 增量索引必須以 file hash/chunk hash 避免重複 embedding。
+- embedding batch size 預設 16-64，依 provider 錯誤調整。
+- 中轉站不支援 batch 時 fallback 單筆，但要有 rate limit。
+- `repo_reindex` 預設只寫 metadata；必須顯式 `index_embeddings=true` 才會產生 embedding API 成本。
+- `max_embedding_chunks` 預設限制單次 embedding 數量，避免第一次索引大 repo 時成本失控。
+
+Phase 3 search：
+
+- 已建索引的小/中型 repo 查詢目標 < 500ms，不含 query embedding 網路時間。
+- query embedding 網路時間單獨計入，tool response 要能指出 provider latency。
+- topK retrieve 先取 50-100，再做 merge/rerank 回傳 8-12 個結果。
+
+## Retrieval Quality Targets
+
+搜尋不能只追 semantic similarity。最低標準：
+
+- 自然語言 query 可找到非字面匹配的實作。
+- 精確函式名、檔名、錯誤訊息不能被向量結果蓋掉。
+- 中文 query 對英文程式碼要靠 embedding + keyword extraction 雙路徑補強。
+- 結果必須有路徑、行號、短 snippet、match reason、grep keywords。
+
+## Efficiency Controls
+
+必要控制：
+
+- `max_file_bytes`
+- `max_chunk_chars`
+- `max_chunks_per_file`
+- `embedding_batch_size`
+- `embedding_concurrency`
+- `max_embedding_chunks`
+- `max_results`
+- `max_context_chars`
+
+這些要在 Phase 1/2 進入 config，避免工具在大型 repo 上不可控。
+
+## Risk Register
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+| 第三方 Gemini 中轉站不支援 batch | 索引變慢 | embedding writer 已有單筆 fallback；後續可加 provider capability cache |
+| sqlite-vec native extension 載入失敗 | Phase 2 卡住 | Spike 已通過；仍保留 FTS-only degrade mode |
+| 大 repo 初次 embedding 成本高 | 慢、花費高 | dry-run 預估 chunks/token/cost；增量索引 |
+| 純語義誤召回 | Codex 讀錯檔 | hybrid ranker、path/symbol boost、grep keywords |
+| 私有碼送到第三方 provider | 隱私風險 | 明確 remote embedding 開關與文檔警告 |
+
+## Recommendation
+
+Phase 1 dry-run scanner/chunker 已完成。Phase 2 已完成 `better-sqlite3 + sqlite-vec` 載入 spike、schema 初始化、file/chunk metadata 寫入流程與 embedding index writer。Phase 3 已完成 semantic vector lookup、keyword search 與 hybrid ranker。Phase 5 已完成輕量 symbol graph / related files MVP。Context packer、多跳 related-file traversal、related snippets、provider diagnostics 與 index freshness diagnostics 也已完成。下一步建議是 provider capability cache、錯誤 remediation polish 與必要時的 tree-sitter spike。

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "scythe-context-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP context engine for Codex with Gemini Embedding 2 support.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lianye-Scythe/scythe-context-mcp.git"
+  },
+  "keywords": [
+    "codex",
+    "mcp",
+    "context-engine",
+    "code-search",
+    "gemini-embedding",
+    "sqlite-vec"
+  ],
+  "bin": {
+    "scythe-context-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.en.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=24.11.0 <27"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "dotenv": "^17.4.2",
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
+    "sqlite-vec": "^0.1.9",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^24.13.2",
+    "tsx": "^4.19.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}