Scythe Context Mcp

CI npm version License: Apache-2.0 Node.js >=24.11

繁體中文 | English | 简体中文

Scythe Context MCP 是給 Codex App / Codex CLI 使用的本機程式碼上下文引擎。它在 repo 內建立 SQLite/sqlite-vec 索引，結合語義搜尋、關鍵字搜尋、符號/依賴關係與 context packing，讓 Codex 更快拿到可操作的檔案、行號、片段與相關路徑。

核心特性

• 本機優先：metadata、FTS 與向量索引都存在 repo 內的 .scythe-context/。
• 混合搜尋：結合 Gemini embeddings、SQLite FTS5、path/symbol ranking，避免只靠單一召回方式。
• Codex 友善輸出：回傳 line ranges、snippets、match reasons、grep keywords、related files 與 suggested paths。
• Gemini-compatible：支援官方 Gemini API，也支援第三方 v1beta proxy。
• 可診斷：內建 provider probe、index freshness、embedding coverage 與可修復建議。

隱私提醒：只有在執行 embedding 相關功能時，query 或 chunk text 才會送到你設定的 Gemini-compatible endpoint。第三方 proxy 應視為可看到這些文字。

快速開始

Codex MCP 設定可以直接用 npx -y scythe-context-mcp，不一定要先全域安裝。全域安裝主要適合先確認 CLI 可執行，或在 Codex 設定中使用短命令。

npm install -g scythe-context-mcp
scythe-context-mcp --version

Runtime 目標是 Node.js 24 LTS。Node 26 可能可用，但在進入 LTS 前不作為主要驗收基準。

從原始碼執行：

git clone https://github.com/Lianye-Scythe/scythe-context-mcp.git
cd scythe-context-mcp
npm install
cp .env.example .env
npm run build

舊專案名 repo-beacon-mcp 已改為 scythe-context-mcp。舊的 REPO_BEACON_* 環境變數仍作為 fallback 相容，但新設定應改用 SCYTHE_CONTEXT_*。

Codex 設定

Codex MCP 設定使用 command、args、cwd、env 與 env_vars 等欄位；可參考官方文件：Model Context Protocol 與 Configuration Reference。

先選執行環境

情境	建議
Codex 和 MCP 都在 Windows	用 Windows node.exe + Windows npm npx-cli.js。
Codex CLI 在 WSL/Linux/macOS	用同一個環境內的 npx 或 node dist/index.js。
Codex App on Windows 開 WSL repo	建議用 Windows wsl.exe 啟動 WSL Node，讓 SQLite index 留在 WSL filesystem。避免 Windows Node 直接讀寫 WSL repo 內的 .scythe-context/。

Native Windows

請先用 where node 和 npm root -g 確認你自己的 Windows Node/npm 路徑；下面是 nvm4w 安裝位置的範例。

最小設定：

[mcp_servers.scythe_context]
command = 'C:\nvm4w\nodejs\node.exe'
args = ['C:\nvm4w\nodejs\node_modules\npm\bin\npx-cli.js', '-y', 'scythe-context-mcp']
env_vars = ["GEMINI_API_KEY"]

如果 scythe-context-mcp 已全域安裝且 Codex 啟動時的 PATH 能找到它，可以更短：

[mcp_servers.scythe_context]
command = "scythe-context-mcp"
env_vars = ["GEMINI_API_KEY"]

WSL/Linux/macOS

Codex 和 MCP server 都在同一個 Unix-like 環境中執行時，最小設定是：

[mcp_servers.scythe_context]
command = "npx"
args = ["-y", "scythe-context-mcp"]
env_vars = ["GEMINI_API_KEY"]

從原始碼執行時：

[mcp_servers.scythe_context]
command = "node"
args = ["/path/to/scythe-context-mcp/dist/index.js"]
env_vars = ["GEMINI_API_KEY"]

這裡 args 指向 Scythe Context MCP 的 build 入口；全域設定不要把 cwd 固定到某個 repo。Scythe 會優先使用工具呼叫的 project_path，再使用 Codex 啟動 MCP 時的 workspace PWD / process cwd。只有在專案 scoped .codex/config.toml、或你真的想 pin 某個 repo 時，才需要設定 cwd 或 SCYTHE_CONTEXT_DEFAULT_PROJECT。

Windows Codex App + WSL repo

目前 Codex App on Windows 的 WSL agent mode 可能無法可靠直接啟動 WSL-side stdio MCP server。實測較穩的做法是讓 Codex 執行 Windows wsl.exe，再由 wsl.exe 在 WSL 內啟動 WSL Node 與 WSL npm package。

先在 WSL 內安裝：

npm install -g scythe-context-mcp
command -v scythe-context-mcp
scythe-context-mcp --version

然後在 Codex config 使用：

[mcp_servers.scythe_context]
command = "/mnt/c/Windows/System32/wsl.exe"
args = ["-d", "Ubuntu", "--", "bash", "-lc", "PATH=/home/you/.nvm/current/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin exec /home/you/.nvm/current/bin/scythe-context-mcp"]
startup_timeout_sec = 40
tool_timeout_sec = 120
env_vars = ["PWD", "GEMINI_API_KEY"]

[mcp_servers.scythe_context.env]
WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
GEMINI_MODEL = "gemini-embedding-2"
GEMINI_AUTH_MODE = "bearer"
GEMINI_OUTPUT_DIMENSIONALITY = "1536"

注意：

• Ubuntu 要換成你的 WSL distribution 名稱；可用 wsl.exe -l -v 查看。
• /home/you/.nvm/current/bin 要換成你的 WSL Node/npm 路徑；可在 WSL 內用 which node、which scythe-context-mcp 確認。
• 不要在全域 config 固定 cwd 或 SCYTHE_CONTEXT_DEFAULT_PROJECT。這個設定會跟著 Codex 目前 workspace 走，不需要每換 repo 就改一次。
• WSLENV 這裡列的是要跨 WSL/Windows interop 保留的變數名，不是 key 內容。建議把 GEMINI_API_KEY 放在 Codex 啟動環境或系統環境，並用 env_vars 轉發；本機臨時測試才考慮直接寫在 [mcp_servers.scythe_context.env]。
• 不建議用 Windows Node 直接索引 WSL repo 內的 .scythe-context/。SQLite 在 UNC / WSL filesystem 邊界可能出現 database is locked，而且 native modules 也容易混到 Windows/WSL 不同平台的 binary。

可選強化設定

以下設定不是最小啟動必需，但在大型 repo、首次 npx 下載或想固定工具面時有用：

[mcp_servers.scythe_context]
startup_timeout_sec = 40
tool_timeout_sec = 120
enabled_tools = [
  "repo_index_status",
  "repo_reindex",
  "repo_context_pack",
  "repo_semantic_search",
  "repo_related_files",
  "gemini_embedding_probe",
  "repo_doctor"
]

enabled = true 和 required = false 通常是預設行為，不需要特別寫。

如果你真的想固定某一個預設專案，可以在 [mcp_servers.scythe_context.env] 設 SCYTHE_CONTEXT_DEFAULT_PROJECT。一般多 repo 使用不需要這樣做；Scythe 會優先使用工具呼叫的 project_path，再使用 PWD，最後才使用 MCP process 的 cwd。

SCYTHE_CONTEXT_RERANK_MODE 可設為 auto 或 off。預設 auto 會啟用 local code-aware reranker；排查 ranking 問題時可暫時設為 off，回到 semantic/keyword merge 的原始排序。

Scythe 會在 repo-local .scythe-context/provider-capabilities.json 記錄目前 Gemini-compatible provider 的能力觀察結果，例如 batch embedding 是否可用、output dimensionality 是否符合預期，以及最近一次 probe / success / failure。這個檔案不提交；repo_reindex(index_embeddings=true) 會使用它避免反覆嘗試已知不支援的 batch endpoint。

Gemini / v1beta proxy

如果不填 URL/model/auth，預設會使用官方 Gemini 相容設定：

• GEMINI_BASE_URL: https://generativelanguage.googleapis.com/v1beta
• GEMINI_MODEL: gemini-embedding-2
• GEMINI_AUTH_MODE: x-goog-api-key
• GEMINI_OUTPUT_DIMENSIONALITY: 1536

因此官方 Gemini 使用者通常只需要提供 GEMINI_API_KEY。第三方中轉站或自訂模型才需要覆蓋下面這些非秘密設定：

模型與 REST endpoint 可對照 Google 官方 Gemini embeddings 文件。

[mcp_servers.scythe_context.env]
GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
GEMINI_MODEL = "gemini-embedding-2"
GEMINI_AUTH_MODE = "bearer"
GEMINI_OUTPUT_DIMENSIONALITY = "1536"

GEMINI_API_KEY 建議放在 Codex 啟動環境或系統環境變數，並用 env_vars = ["GEMINI_API_KEY"] 轉發給 MCP server。除非只做本機臨時測試，否則不要把 key 寫進可同步或可提交的 config。

支援的 auth mode：

• x-goog-api-key
• bearer
• query

官方 Gemini 通常使用 x-goog-api-key；很多第三方中轉站使用 bearer。如果中轉站要求 query string key，可以使用 query，必要時再設定 GEMINI_API_KEY_QUERY_PARAM。

WSLENV 是 WSL interop 規則，不是 Codex 專用欄位。只有在 Windows Codex App + WSL repo 並透過 wsl.exe wrapper 或 Windows Node 跨環境啟動時才需要。若使用上面的 wsl.exe wrapper，通常使用無 suffix 形式：

[mcp_servers.scythe_context.env]
WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
GEMINI_MODEL = "gemini-embedding-2"
GEMINI_AUTH_MODE = "bearer"
GEMINI_OUTPUT_DIMENSIONALITY = "1536"

若你刻意採用 Windows Node 方案，才需要 PWD/p 把 WSL path 轉成 Windows 可讀 UNC path；但目前不建議用它直接讀寫 WSL repo 內的 SQLite index。

常用工作流

1. 先檢查索引狀態：

   repo_index_status
   

2. 如果 metadata 不存在或 freshness 顯示 stale：

   repo_reindex({ "dry_run": false })
   

3. 第一次安裝或環境異常時，先跑本機診斷：

   repo_doctor
   

4. 需要語義搜尋或 context pack 時，再建立 embeddings：

   repo_reindex({ "dry_run": false, "index_embeddings": true })
   

5. 讓 Codex 針對任務拿上下文：

   repo_context_pack({ "query": "where is auth token validation handled?" })
   

6. 對某個命中檔案展開 imports / reverse imports：

   repo_related_files({ "path": "src/server/auth.ts" })
   

MCP 工具

Tool	用途
repo_index_status	查看 index path、metadata/embedding coverage、freshness diagnostics 與建議動作。
repo_reindex	掃描專案並寫入 metadata；設定 index_embeddings=true 時才會呼叫 embedding provider。
repo_context_pack	針對任務查詢打包 primary snippets、match reasons、related files 與 suggested paths。
repo_semantic_search	對已索引 chunks 做 hybrid 或 semantic search，主要用於排查 raw ranking；一般查找優先用 repo_context_pack。
repo_related_files	查看單一檔案的 symbols、imports、importedBy。
gemini_embedding_probe	測試 Gemini 或 proxy 相容性，回傳 endpoint、latency、錯誤分類與可修復建議。
repo_doctor	不呼叫外部 API，檢查 Node runtime、native modules、Gemini env、provider capability cache、WSL interop 與 index health。

repo_context_pack(mode="hybrid") 和 repo_semantic_search(mode="hybrid") 在 query embedding 不可用時會降級成 keyword-only 結果，並回傳 effectiveMode: "keyword" 與 fallback.reason: "embedding_unavailable"。mode="semantic" 不會降級，會回傳 status: "embedding_unavailable"，因為純 semantic search 必須有 query embedding。精確字串、已知路徑或小範圍檢查仍建議直接用 rg / 直接讀檔。

為了控制 Codex token 消耗，repo_index_status、repo_related_files、repo_reindex、repo_doctor 與 gemini_embedding_probe 預設回傳 compact 摘要，包含決策必要資訊與估算輸出 token；需要完整診斷資料、完整 skipped file list、vector sample 或 provider capability raw details 時，才使用 response_mode="full"。

repo_context_pack 與 repo_semantic_search 也支援 response_mode：

• compact：預設模式，回傳短 snippets、決策導向 related metadata、suggested paths 與估算輸出 token。
• paths_only：第一輪探索用，只回傳路徑、行號、match reason 與精簡關聯路徑摘要，適合先找要讀的檔案。
• snippets：需要更多上下文或 ranking 診斷時使用，保留較完整 snippets、分數與 metadata。

建議先用 repo_context_pack(response_mode="paths_only") 找到候選檔案，再用 Codex 直接讀特定檔案或小範圍片段；如果短片段能直接幫助修改，再使用預設 compact。需要排名分數或較完整片段來排查 ranking 時，再使用 repo_semantic_search(response_mode="snippets")。

功能狀態

已完成：repo 掃描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、embedding 失敗時的 keyword-only fallback、local code-aware reranker、輕量 symbol/dependency graph、experimental opt-in tree-sitter extractor、related-file lookup、repo_context_pack、provider diagnostics、provider capability cache、index freshness diagnostics、repo_doctor。

下一步：持續整理真實 dogfood 使用回饋，優先處理會影響 Codex 找檔效率或 token 消耗的 ranking / output 問題；tree-sitter 維持 experimental opt-in，等 benchmark 或使用者回饋證明有明確收益再提高投入。

隱私與本機檔案

• .scythe-context/: 預設索引目錄，不提交。
• .repo-beacon/: 舊索引目錄名稱，仍被 ignore。
• local/: 私密 API 測試檔、參考 HTML、截圖等本機資料，不提交。
• .env: 本機設定，不提交。

不要把 API key、proxy token、私有程式碼片段或 index database 放進 issue、PR 或公開 logs。

文件

• 架構設計
• 開發計畫
• Gemini 相容性
• 技術棧
• Codex 整合審查
• Context search benchmark
• Dogfood evaluation
• Troubleshooting and first-run checks
• Release process

開發與發佈檢查

npm test
npm run build
npm audit --omit=dev
npm pack --dry-run

確認 package 不包含 .env、.scythe-context/, .repo-beacon/, local/, API key 或私密參考檔。