scythe-context-mcp 0.1.0

package/docs/architecture.md

@@ -0,0 +1,280 @@
+# Scythe Context MCP 架構設計
+
+## 目標
+
+Scythe Context MCP 的目標是做一個本機、可控、可接 Codex App / CLI 的上下文搜尋層：
+
+1. 對 repo 建立本機索引。
+2. 支援自然語言查詢程式碼。
+3. 返回可直接給 Codex 使用的檔案路徑、行號範圍、片段與 grep 建議。
+4. 支援官方 Gemini Embedding 2 與第三方 v1beta 中轉站。
+5. 後續可擴充成 hybrid search、symbol graph、git history 與多 repo context。
+
+## 系統邊界
+
+Scythe Context 負責：
+
+- 掃描工作區檔案。
+- 依語言與結構切 chunk。
+- 產生 embedding。
+- 儲存本機索引。
+- 查詢與排序。
+- 透過 MCP tools 回傳上下文。
+
+Codex 負責：
+
+- 決定何時呼叫 MCP tool。
+- 根據回傳片段讀取/編輯檔案。
+- 執行測試與修改程式碼。
+
+Embedding provider 負責：
+
+- 將 query/chunk 轉成向量。
+- 不負責保存程式碼。
+- 不負責判斷搜尋結果。
+
+## 高階流程
+
+```mermaid
+flowchart TD
+  A["Codex App / CLI"] --> B["MCP stdio server"]
+  B --> C["Tool router"]
+  C --> D["Index manager"]
+  D --> E["File scanner"]
+  D --> F["Chunker"]
+  D --> G["Symbol/dependency extractor"]
+  D --> H["Embedding provider"]
+  H --> I["Gemini official API or v1beta proxy"]
+  D --> J["SQLite metadata + sqlite-vec + FTS5"]
+  C --> K["Hybrid ranker"]
+  C --> L["Related-file lookup"]
+  K --> M["Result formatter"]
+  L --> M
+  M --> A
+```
+
+## 模組分層
+
+### MCP Layer
+
+位置：`src/index.ts`, `src/tools/registerTools.ts`
+
+職責：
+
+- 啟動 stdio MCP server。
+- 註冊工具。
+- 保持工具輸入 schema 穩定。
+- 將內部錯誤轉成可讀的 tool response。
+
+初期 tools：
+
+- `repo_index_status`
+- `gemini_embedding_probe`
+- `repo_reindex`
+- `repo_semantic_search`
+- `repo_related_files`
+- `repo_context_pack`
+
+後續 tools：
+
+- `repo_open_ranges`
+- `repo_grep_suggest`
+
+### Config Layer
+
+位置：`src/config.ts`
+
+職責：
+
+- 從環境變數讀取 provider 與索引設定。
+- 支援官方 Gemini 與中轉站差異。
+- 不讀取密鑰到 log 或回傳內容，只回傳 `hasApiKey`。
+
+### Embedding Provider Layer
+
+位置：`src/providers/*`
+
+目前 provider：
+
+- `GeminiEmbeddingProvider`
+
+設計原則：
+
+- 使用 REST，不綁定 Google SDK，方便中轉站相容。
+- provider 介面只暴露 `embed` / `embedBatch`。
+- query/document formatting 在 provider 內處理，避免上層漏掉 Gemini Embedding 2 的 task prefix。
+
+### Index Manager
+
+職責：
+
+- 判斷索引是否過期。
+- 比對檔案 hash。
+- 增量更新 chunk 和 vector。
+- 控制 batch embedding。
+- 控制併發與 rate limit。
+- 每次 reindex 重建單檔 symbol/dependency metadata。
+- 對未變更 chunks 保留 row id，避免重算 embeddings。
+
+### File Scanner
+
+候選規則：
+
+- 尊重 `.gitignore`。
+- 內建排除：`.git`, `node_modules`, `dist`, `build`, `.next`, `coverage`, binary files。
+- 預設只索引可讀文字檔。
+- 可用 allow/deny glob 擴充。
+
+### Chunker
+
+初期策略：
+
+- 通用文字 chunk：依行數與 token 粗估切分。
+- 每 chunk 保留 `path`, `startLine`, `endLine`, `language`, `hash`, `text`。
+- chunk 大小目標：300-900 tokens。
+- 相鄰 chunk overlap：30-80 tokens。
+
+進階策略：
+
+- tree-sitter 依 function/class/module 切分。
+- 對大型檔案建立 summary chunk。
+- 記錄 imports/exports/symbols。
+
+### Symbol Graph
+
+目前採用輕量 regex extractor，抽取常見 TS/JS/Python/Go/Rust 的 declarations 與 imports：
+
+- `file_symbols`: name、kind、line、signature、exported。
+- `file_dependencies`: raw specifier、resolved relative path、line。
+
+這層刻意獨立於 chunk/embedding storage，升級 extractor 或之後換成 tree-sitter 時，不會破壞既有 embedding cache。查詢上先提供 `repo_related_files`，讓 Codex 在搜尋命中後按需展開 imports / reverse imports，而不是每次搜尋都塞入大量相關檔案。
+
+### Context Packer
+
+`repo_context_pack` 是 Codex 實際查找上下文的主要入口。它會：
+
+- 執行 semantic/hybrid search。
+- 對 primary snippets 套用 `max_context_chars`。
+- 為命中的前幾個檔案附上 symbols、imports、importedBy。
+- 依 `related_depth` 做 bounded BFS，沿著 imports / importedBy 展開多跳 related files。
+- 對 related paths 做輕量分類，source 優先，test/mock/fixture/generated/docs 後置但不硬排除。
+- 產出 `suggestedPaths`，讓 Codex 判斷下一步要讀哪些檔案。
+- 可選擇打包 related snippets，但使用獨立 `max_related_context_chars`，不擠壓 primary snippets。
+
+related snippets 預設關閉，避免 context 膨脹。開啟時只讀 related graph 中非 primary result 的檔案片段，並受每檔 snippet 數、每段長度、總字元數三層限制。
+
+### Storage Layer
+
+MVP 儲存選型：
+
+- metadata: SQLite
+- vector: sqlite-vec
+- keyword: SQLite FTS5 + rg fallback
+
+不建議先用 JSON vector 當正式 MVP。1536 維向量若用 JSON 存放，索引體積、解析成本與相似度掃描成本都會太早變成瓶頸。可以在單元測試中保留 in-memory vector store，但實際索引從 Phase 2 開始使用 sqlite-vec。
+
+資料表草案：
+
+```sql
+files(
+  id integer primary key,
+  project_path text not null,
+  path text not null,
+  mtime_ms integer not null,
+  size integer not null,
+  hash text not null,
+  unique(project_path, path)
+);
+
+embedding_sets(
+  id integer primary key,
+  provider text not null,
+  base_url_hash text not null,
+  model text not null,
+  dimensions integer not null,
+  created_at text not null,
+  unique(provider, base_url_hash, model, dimensions)
+);
+
+chunks(
+  id integer primary key,
+  file_id integer not null,
+  start_line integer not null,
+  end_line integer not null,
+  language text,
+  title text,
+  text text not null,
+  hash text not null,
+  unique(file_id, start_line, end_line, hash)
+);
+
+embeddings(
+  chunk_id integer not null,
+  embedding_set_id integer not null,
+  primary key(chunk_id, embedding_set_id)
+);
+
+file_symbols(
+  id integer primary key,
+  file_id integer not null,
+  name text not null,
+  kind text not null,
+  line integer not null,
+  signature text not null,
+  exported integer not null
+);
+
+file_dependencies(
+  id integer primary key,
+  file_id integer not null,
+  specifier text not null,
+  resolved_path text,
+  line integer not null
+);
+```
+
+### Ranking Layer
+
+初期 hybrid score：
+
+```text
+score = 0.70 * vector_similarity
+      + 0.20 * keyword_score
+      + 0.05 * path_score
+      + 0.05 * recency_or_open_file_boost
+```
+
+Codex 使用情境下，結果要比一般 RAG 更偏向「可操作」：
+
+- 返回完整檔案路徑。
+- 返回行號範圍。
+- 返回短片段。
+- 返回為何匹配。
+- 返回建議 grep keywords。
+- 返回 context budget summary，並在超出 `max_context_chars` 時截斷 snippets。
+
+## 設計取捨
+
+Scythe Context 優先做本機索引、可配置 provider、可診斷 tool output 與 Codex 可操作上下文。MVP 目前不包含：
+
+- 團隊級跨 repo 權限系統。
+- 即時 IDE active context。
+- 完整 knowledge graph。
+- commit/issue/design docs 深度整合。
+- 商業級 context compression。
+
+可逐步補：
+
+- git history indexing。
+- symbol graph。
+- 多 repo workspace。
+- docs/tickets connector。
+
+## 安全與隱私
+
+- 索引資料預設存在 repo 內 `.scythe-context/`。
+- 原始程式碼不送到 Codex 以外的地方，除非呼叫 embedding provider。
+- 若使用 Gemini Embedding，chunk text 會送到 configured endpoint。
+- 若使用第三方中轉站，應視為會看到 query/chunk text。
+- 不在 tool output 顯示 API key。
+- 對私有或敏感 repo，應提供 `SCYTHE_CONTEXT_DISABLE_REMOTE_EMBEDDINGS=true` 這類後續開關，避免意外送出 chunk。

package/docs/codex-integration.md

@@ -0,0 +1,114 @@
+# Codex App / CLI Integration Review
+
+## Sources Checked
+
+- Official OpenAI Codex manual fetched by the `openai-docs` skill on 2026-06-13.
+- Official Codex MCP documentation.
+- Official Codex `AGENTS.md` documentation.
+- `openai/codex` GitHub README, current public repository page.
+
+## Findings
+
+### MCP transport
+
+Scythe Context is aligned with Codex's local MCP path:
+
+- Codex supports local STDIO MCP servers.
+- Scythe Context runs as a STDIO server through `node dist/index.js`.
+- Configuration should use `[mcp_servers.scythe_context]` and `[mcp_servers.scythe_context.env]` tables in `config.toml`.
+- Secrets should be forwarded with `env_vars = ["GEMINI_API_KEY"]` instead of written into project config.
+
+This is preferable to a remote HTTP MCP server for the current project because the index database and scanner are local to the repo.
+
+### Server instructions
+
+Codex reads the MCP server `instructions` field during initialization. The most important guidance should appear early because Codex may use the beginning of the instructions while deciding whether to call a server.
+
+Scythe Context's server instructions now put the key workflow first:
+
+1. Check `repo_index_status`.
+2. Run metadata reindex only when needed.
+3. Prefer `repo_context_pack` for task lookup.
+4. Only embed when semantic vectors are needed.
+5. Keep context budgets bounded.
+
+### Codex surfaces
+
+Codex CLI and the IDE extension share MCP configuration through `config.toml`. The Codex app also exposes plugins/MCP-related extension points, but local setup behavior can vary by App settings and installed plugins. For direct reproducible setup, document CLI/IDE `config.toml` first and keep App usage phrased as "Codex local MCP compatible" rather than assuming every App install auto-loads a project config.
+
+### AGENTS.md
+
+Codex reads `AGENTS.md` before work and layers global plus project guidance. Scythe Context's `AGENTS.md` is intentionally short enough to fit comfortably under the default project instruction limit and focuses on:
+
+- Preferred tool workflow.
+- Privacy rules for `.scythe-context/` and `local/`.
+- Verification commands.
+
+This is aligned with Codex's expected durable instruction surface.
+
+### Tool output shape
+
+The current MCP output is optimized for Codex use:
+
+- JSON text responses are deterministic and easy to inspect.
+- `repo_context_pack` is the preferred single-call workflow for code lookup.
+- `max_context_chars` and `max_related_context_chars` keep output bounded.
+- `suggestedPaths`, line ranges, `matchReason`, `grepKeywords`, symbols, imports, reverse imports, and related snippets give Codex actionable next steps without forcing whole-file reads.
+
+### Tool policy
+
+Recommended config should expose all tools by default during development, but `enabled_tools` is documented so users can pin the expected tool surface. Keep `gemini_embedding_probe` available because it is the fastest way to debug official Gemini or proxy compatibility.
+
+## Optimizations Already Applied
+
+- STDIO MCP server.
+- Early, self-contained server instructions.
+- `AGENTS.md` project guidance.
+- Valid Codex TOML examples using `[mcp_servers.scythe_context.env]`.
+- Secret-safe config examples using `env_vars` for `GEMINI_API_KEY`.
+- `cwd` in MCP config so relative `.env` loading is predictable.
+- `startup_timeout_sec` and `tool_timeout_sec` tuned above defaults.
+- Bounded context output for primary and related snippets.
+- Explicit opt-in embedding and opt-in related snippet packing.
+- `repo_index_status` freshness diagnostics for stale/new/modified/missing files.
+
+## Remaining Work
+
+- Consider a plugin package later if Codex App plugin distribution becomes the preferred installation route.
+- Add tree-sitter symbol extraction only if regex extraction becomes a retrieval-quality bottleneck.
+- Continue expanding provider capability caching and error-specific remediation hints.
+
+## Troubleshooting
+
+### MCP server does not appear
+
+1. In the Codex TUI, run `/mcp` and confirm `scythe_context` appears.
+2. Confirm the config is in `~/.codex/config.toml` or in a trusted project's `.codex/config.toml`.
+3. Restart Codex after changing config. Codex reads MCP config at session startup.
+4. Check that `command`, `args`, and `cwd` point to the built repo and that `npm run build` has produced `dist/index.js`.
+5. If startup is slow on WSL or a cold Node install, raise `startup_timeout_sec`.
+
+### Tool starts but embedding fails
+
+1. Run `gemini_embedding_probe` with a short test string.
+2. Verify `GEMINI_API_KEY` is present in the environment Codex launches from.
+3. For proxy endpoints, verify `GEMINI_BASE_URL` can include or omit a trailing slash and can include or omit `/v1beta`.
+4. If batch indexing fails but single requests work, run `repo_reindex(index_embeddings=true, max_embedding_chunks=...)` again; the embedding writer falls back to single requests.
+
+### Search returns index missing
+
+1. Run `repo_index_status`.
+2. Run `repo_reindex(dry_run=false)` for metadata.
+3. Run `repo_reindex(dry_run=false, index_embeddings=true)` only when semantic search or context packs need vectors.
+4. Keep `max_embedding_chunks` low for the first pass on large repos.
+
+### Context output is too large
+
+1. Lower `max_context_chars`.
+2. Keep `include_related_snippets=false` for broad exploration.
+3. Lower `max_related_files`, `related_depth`, or `max_related_context_chars`.
+4. Use `repo_related_files` for one focused file instead of a broad context pack.
+
+### AGENTS.md changes do not apply
+
+Codex reads `AGENTS.md` when a run or TUI session starts. Restart Codex in the project root after changing guidance. If using nested instructions, remember that closer files override earlier root guidance.

package/docs/development-plan.md

@@ -0,0 +1,218 @@
+# 開發設計方案
+
+## Phase 0: 初始化與設計
+
+狀態：已完成。
+
+交付：
+
+- Git repository 初始化。
+- TypeScript MCP server 骨架。
+- Gemini Embedding 2 REST provider。
+- 官方 Gemini / 第三方 v1beta 中轉站設定。
+- 架構與開發文檔。
+
+驗收：
+
+- `npm run build` 成功。
+- Codex 可啟動 MCP server。
+- `repo_index_status` 可回傳狀態。
+- `gemini_embedding_probe` 可測 provider。
+
+## Phase 1: File Scanner + Chunker
+
+狀態：已完成 dry-run MVP。
+
+目標：能掃描 repo 並產生穩定 chunks。
+
+工作項：
+
+1. 實作 `.gitignore` 載入。
+2. 實作內建 ignore 清單。
+3. 偵測 binary / 大檔。
+4. 實作文字 chunker。
+5. 產出 chunk hash。
+6. 加入 `repo_reindex` dry-run 模式。
+7. 加入 scanner/chunker 單元測試。
+
+工具變更：
+
+```text
+repo_reindex(project_path, force, dry_run)
+repo_index_status(project_path)
+```
+
+驗收：
+
+- 能列出會被索引的檔案數與 chunk 數。
+- dry-run 會輸出 skipped files 與 skip reasons。
+- 超過預設大小限制的檔案會被跳過或截斷，不能拖垮索引。
+- HTML 參考檔這類大檔不會讓索引失控。
+- chunk hash 對同內容穩定，換行與路徑處理有測試覆蓋。
+
+## Phase 2: Local Storage
+
+狀態：已完成。
+
+目標：能把檔案、chunk、embedding metadata 存到本機。
+
+MVP 儲存選型：
+
+- SQLite metadata。
+- sqlite-vec vector index。
+- SQLite FTS5 keyword index。
+- 測試可用 in-memory fake store，但正式索引不走 JSON vector。
+
+工作項：
+
+1. 建立 schema migration。
+2. 實作 file/chunk upsert。
+3. 實作 stale chunk cleanup。
+4. 實作 embedding cache。
+5. 記錄 provider/model/dimensions。
+6. 建立 `embedding_sets`，避免不同 base URL/model/dimensions 的向量混用。
+7. `embedBatch` 不支援時 fallback 到逐筆 `embedContent`。
+8. 加入 embedding rate limit 與 batch size 設定。
+9. sqlite-vec rowid 寫入使用 `BigInt`，避免 better-sqlite3 綁定成非整數型別。
+
+已完成：
+
+- SQLite metadata schema。
+- dimension-specific sqlite-vec virtual table，例如 `vec_embeddings_1536`。
+- file upsert。
+- chunk insert de-duplication。
+- embedding set de-duplication。
+- embedding metadata id 與 sqlite-vec rowid 的連結測試。
+- `repo_reindex(dry_run=false)` 寫入 `.scythe-context/index.sqlite` 的 metadata index。
+- `repo_reindex(dry_run=false, index_embeddings=true)` 會顯式呼叫 embedding provider，寫入 `embeddings` 與 `vec_embeddings_1536`。
+- `max_embedding_chunks` 限制單次 embedding 工作量，避免成本失控。
+- batch embedding 失敗時 fallback 到逐筆 embedding。
+- `file_symbols` 與 `file_dependencies` 已加入 schema，與 chunk/embedding cache 解耦。
+
+驗收：
+
+- 重跑索引不重複 embedding 未變更 chunks。
+- 更換 `GEMINI_MODEL` 或 dimensions 時會建立新 embedding set。
+- 中轉站不支援 batch 時，索引仍可完成。
+- 1536 維向量會被驗證 dimensions，一旦 provider 回傳維度不符就 fail fast。
+
+## Phase 3: Semantic Search + Minimal Keyword
+
+狀態：已完成。
+
+目標：`repo_semantic_search` 真正返回相關程式碼片段。
+
+工作項：
+
+1. query embedding。
+2. cosine similarity。
+3. topK retrieve。
+4. result formatter。
+5. line range merge。
+6. grep keyword suggestion。
+7. 對 path、filename、symbol-looking tokens 加最低限度 boost。
+
+回傳格式草案：
+
+```json
+{
+  "query": "payment logging flow",
+  "results": [
+    {
+      "path": "src/services/payments.ts",
+      "startLine": 42,
+      "endLine": 96,
+      "score": 0.88,
+      "matchType": "semantic",
+      "snippet": "...",
+      "grepKeywords": ["processPayment", "logger", "payment"]
+    }
+  ]
+}
+```
+
+驗收：
+
+- 自然語言查詢可找到非同字面命中的檔案。
+- 返回結果可讓 Codex 直接接著 Read/Edit。
+- 精確函式名查詢不應被純語義結果完全蓋掉。
+
+已完成：
+
+- query embedding。
+- sqlite-vec KNN lookup。
+- 回傳 path、line range、distance、snippet。
+- index missing 時回傳可修復訊息。
+- SQLite FTS5 keyword search。
+- hybrid ranker 合併 semantic/keyword 結果。
+- result formatter 回傳 `matchReason` 與 `grepKeywords`。
+
+## Phase 4: Advanced Hybrid Search
+
+狀態：MVP 已完成。
+
+目標：改善 precision，避免純 embedding 漏掉符號名稱。
+
+工作項：
+
+1. 加入 keyword search。
+2. path/name boost。
+3. symbols boost。
+4. query rewrite：從自然語言抽 grep keywords。
+5. 結果去重與合併。
+
+工具：
+
+```text
+repo_semantic_search(query, project_path, max_results, mode="hybrid")
+```
+
+驗收：
+
+- 已知函式名搜尋優先命中精確檔案。
+- 中文 query 仍可找到英文程式碼片段。
+
+## Phase 5: Symbol Graph
+
+狀態：輕量 MVP 已完成；bounded multi-hop traversal 已完成；tree-sitter / deeper semantic graph 尚未實作。
+
+目標：接近 context engine 的「關係理解」。
+
+工作項：
+
+1. 解析 imports/exports。已完成常見 TS/JS/Python/Go/Rust 的保守 regex 抽取。
+2. 記錄 function/class/interface symbols。已完成常見 declarations。
+3. 建立 file dependency graph。已完成 relative import resolution 與 reverse-import 查詢。
+4. 查詢時加入 related files。已完成 `repo_related_files`，採按需展開。
+5. 支援從 router -> service -> model 的鏈路返回。已完成 bounded BFS traversal 與 source-first related path ranking，後續可加入語言感知排序與 schema/test boost。
+
+驗收：
+
+- `repo_reindex(dry_run=false)` 會寫入 symbols/dependencies 統計。
+- `repo_index_status` 會回報 symbol/dependency rows。
+- `repo_related_files(path)` 會返回該檔 symbols、imports、importedBy。
+- 查詢 API 行為時，可透過 context pack 同時返回 route、handler、service、schema/test 候選路徑；更精準的語言感知排序留待後續優化。
+
+## Phase 6: Codex Workflow Polish
+
+狀態：context budget、context packer、bounded multi-hop related-file traversal、related snippet packing、server instructions、AGENTS.md、provider diagnostics、index freshness diagnostics 已完成。
+
+目標：讓 Codex 更穩定地使用工具。
+
+工作項：
+
+1. 補 server instructions。
+2. 加一份可放入 `AGENTS.md` 的使用指南。
+3. 對結果加 token budget。已完成字元級 MVP。
+4. 支援 `max_context_chars`。已完成 `repo_semantic_search` 的 snippet 總字元限制。
+5. 新增 context packer。已完成 `repo_context_pack`，會打包 primary snippets、related metadata 與 suggested paths。
+6. 新增 related snippet packing。已完成 opt-in `include_related_snippets` 與獨立 `max_related_context_chars`。
+7. 錯誤訊息加入可修復建議。已完成 Gemini probe diagnostics 與 secret-safe provider errors。
+8. 新增 index freshness diagnostics。已完成 `repo_index_status` 的 new/modified/missing/metadata_changed stale reason samples。
+
+## 風險與取捨
+
+- Gemini Embedding 2 品質高，但會把 chunk 送出本機；敏感 repo 要允許 provider 關閉或換本地 embedding。
+- 第三方中轉站相容性不一致，所以 provider 必須保留 header/query/bearer 三種 auth。
+- 大型 repo 需要增量索引和 rate limit，不能每次全量 embedding。
+- 純 vector search 對精確 symbol 不一定好，hybrid search 是必要項。