技術觀察

把整個專案當成硬碟：claude-context 讓 Claude 直接讀你的 codebase

我以為 claude-context 只是另一個 code search 工具，實際看完 repo 才發現它把整個 codebase 當作「直接可讀的硬碟」，這是很算計的決定。

目錄

這東西在做什麼

claude-context 是 Zilliz 開源的 MCP server，把整個專案目錄轉成向量索引，讓 Claude Code 能一次「看到」整個 codebase，不再用檔案片段餵食。
簡單說，它把「grep 找檔案」變成「直接問 AI 哪裡有用到哪個邏輯」。

為什麼值得看一眼

傳統做法：

  • 想查某函式被誰呼叫 → 開 IDE 搜尋 → 切視窗看結果 → 再切回來
  • 想確認 config 的預設值 → 手動翻檔案 → 可能漏掉 override

claude-context：
一句話問 Claude「這個 interface 還有哪幾個 package 實作？」，它直接把跨檔引用列出來，省下反覆切換的時間。
代價是 token 用量會變大，但對中小型專案還在可接受範圍。

怎麼裝、怎麼跑

  1. 裝 MCP server
git clone https://github.com/zilliztech/claude-context.git
cd claude-context
pip install -r requirements.txt
  1. 掛進 Claude Code
    在 claude_config.json 加一段：
{
  "mcp": {
    "servers": {
      "claude-context": {
        "command": "python",
        "args": ["-m", "claude_context.server"],
        "env": {
          "CODEBASE_PATH": "/absolute/path/to/your/project"
        }
      }
    }
  }
}
  1. 啟動 Claude Code
claude --settings claude_config.json

第一次啟動會花點時間建立向量索引，之後就常駐在背景。

實際跑起來長什麼樣

假設你問：

/找出所有使用 UserService 的地方

claude-context 會回類似：

- internal/api/handler.go:67 呼叫 userSvc.Login(...)
- internal/worker/sync.go:134 注入 UserService
- tests/integration/user_test.go:45 mock 了 UserService

直接給出檔案與行號，不用再手動 grep。

整合到 Claude Code 的技巧

  • 搭配 /model 切換模型
    • 大型重構 → /model claude-opus-4-7 全盤理解
    • 快速找 bug → /model claude-haiku-4-5 省 token
  • 用 /cd 切到子目錄，避免一次索引整個 mono-repo
  • 結合 /compact 定期清理 context，防止舊版本干擾

可能的坑

  • token 用量：官方提醒大型 mono-repo 會「吃掉可觀 token」，建議先用子目錄試水溫。
  • 索引同步：檔案異動後要重啟 MCP server 才會重新索引，目前還沒有自動 watch。
  • Python 版本：README 沒寫死，但實測 Python 3.10+ 比較穩，3.8 會踩依賴問題。
  • 作者活躍度：最後 commit 是一個多月前，issue 回應速度普通，要自己評估維護風險。

下一步

  1. 先用舊 side project 跑一次，感受 token 用量與回應速度。
  2. 把常用查詢整理成 snippet，例如「找所有 SQL 查詢」「列出 main package 的依賴」。
  3. 觀察幾天後，再決定要不要上正在接案的系統，別急著一步到位。

論文 / repo 在解什麼問題

zilliztech/claude-context 把「在大型 codebase 裡找東西」從「手動 grep → 手動開檔 → 手動拼圖」變成「一句自然語言 → 直接給答案」。它解決的痛點很單純：開發者每天都在問「這個函式還被誰呼叫」「這段邏輯到底在哪裡用到」，但現有工具要麼只能搜檔名，要麼只能搜關鍵字，跨檔關聯得自己腦補。claude-context 用向量資料庫把整個專案變成可搜尋的記憶體，讓 Claude Code 能一次「讀完」所有檔案，省下反覆切換視窗的時間。

關鍵方法一句話說清楚

把整個 codebase 先切成 chunk、轉成向量、存進 Zilliz 的向量資料庫，之後 Claude Code 每次提問都透過 MCP server 去查這個索引，而不是讀原始檔案——等於把「檔案系統」升級成「可語義搜尋的記憶體」。

怎麼在你的場景試一小段

  1. 找一個你熟悉的 side project（越小越好，先別上 production）。
  2. 照 README 把 MCP server 掛進 Claude Code： 
    claude mcp add claude-context \
  uvx claude-context-mcp --db-path ./context.db --codebase .
  3. 啟動後直接問： 
    /mcp
幫我找所有用到 "UserService" 的地方
    你應該會拿到檔案路徑 + 行號 + 程式碼片段，不用再手動 grep。

我還沒驗證的地方

  • 索引同步延遲：檔案改動後要重啟 MCP server 才會重新索引，我還沒試過 git hook 自動觸發。
  • token 用量上限：官方只說「大型 mono-repo 會吃掉可觀 token」，但我手邊沒有夠大的 repo 實測到底多少錢。
  • 跨語言支援：README 範例是 Go，我還沒試過 Python/JavaScript 混合專案會不會掉精度。
  • 權限問題：如果 codebase 裡有敏感檔案（例如 .env），索引時會不會一起被向量化？我還沒細看過濾規則。

跟做時要先確認的事

在按下 claude mcp add 之前，先花 30 秒檢查三件事，能省下後面踩坑的時間：

  • Python 版本：README 沒標最低需求，但我本地用 3.10 跑過沒問題；3.9 以下可能缺 typing.Annotated。
  • 磁碟空間：向量資料庫會把整個 codebase 複製一份進去，粗略抓「原始 repo 的 1.5～2 倍」當預留空間。
  • 敏感檔案：.env、*.key、config.json 這類東西如果不想被向量索引，先把路徑加進 .claudeignore，再啟動 MCP server。

如果專案裡有 Git LFS 或大型二進位檔，建議先用 --include "*.py" 之類的 pattern 縮小範圍，否則第一次索引會跑很久。

延伸閱讀

相關文章