catlog22/Claude-Code-Workflow

Fork 0

mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00

Files

catlog22 b74a90b416 Refactor code structure for improved readability and maintainability

2025-12-12 11:19:58 +08:00

13 KiB

Raw Blame History

程式碼索引 MCP

為大型語言模型提供智慧程式碼索引與分析

以先進的搜尋、分析和導航功能，徹底改變 AI 對程式碼庫的理解方式。

概述

程式碼索引 MCP 是一個模型上下文協定伺服器，架起 AI 模型與複雜程式碼庫之間的橋樑。它提供智慧索引、先進搜尋功能和詳細程式碼分析，幫助 AI 助理有效地理解和導航您的專案。

**適用於：**程式碼審查、重構、文件生成、除錯協助和架構分析。

快速開始

🚀 推薦設定（大多數使用者）

與任何 MCP 相容應用程式開始的最簡單方式：

前置需求： Python 3.10+ 和 uv

新增到您的 MCP 設定 (例如 claude_desktop_config.json 或 ~/.claude.json)：
```
{
  "mcpServers": {
    "code-index": {
      "command": "uvx",
      "args": ["code-index-mcp"]
    }
  }
}
```
若想在啟動時自動設定專案路徑，可在 args 陣列末尾加入 --project-path /絕對/路徑，效果等同於啟動後呼叫 set_project_path。
重新啟動應用程式 – uvx 會自動處理安裝和執行

開始使用（向您的 AI 助理提供這些提示）：

設定專案路徑為 /Users/dev/my-react-app
在這個專案中找到所有 TypeScript 檔案
搜尋「authentication」相關函數
分析主要的 App.tsx 檔案

如果啟動時已提供 --project-path，可以略過第一個指令，伺服器會自動記住路徑。

Codex CLI 設定

如果你使用 Anthropic 的 Codex CLI，請在 ~/.codex/config.toml 中加入下列伺服器設定。 Windows 的設定檔位於 C:\Users\<you>\.codex\config.toml：

[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]

如需要啟動時自動設定專案，請把 --project-path C:/絕對/路徑 加到 args 清單中，與手動呼叫 set_project_path 的結果相同。

在 Windows 中，uvx 需要找到標準的使用者目錄。保留下列環境變數覆寫設定，才能讓 MCP 穩定啟動：

env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Linux 與 macOS 預設會提供 HOME 與 XDG 路徑，因此通常不需要額外的 env 區塊；只有在受限的容器環境或想手動調整快取／設定位置時才需要覆寫。完整的環境變數清單請參考 uv 環境變數說明（包含 HOME、XDG_CACHE_HOME、XDG_CONFIG_HOME、APPDATA 等）。

典型使用場景

程式碼審查：「找出所有使用舊 API 的地方」
重構協助：「這個函數在哪裡被呼叫？」
學習專案：「顯示這個 React 專案的主要元件」
除錯協助：「搜尋所有錯誤處理相關的程式碼」

主要特性

🔍 智慧搜尋與分析

雙策略架構：7 種核心語言使用專業化 Tree-sitter 解析，50+ 種檔案類型使用備用策略
直接 Tree-sitter 整合：專業化語言無正則表達式備用 - 快速失敗並提供清晰錯誤訊息
進階搜尋：自動偵測並使用最佳工具（ugrep、ripgrep、ag 或 grep）
通用檔案支援：從進階 AST 解析到基本檔案索引的全面覆蓋
檔案分析：執行 build_deep_index 後深入了解結構、匯入、類別、方法和複雜度指標

🗂️ 多語言支援

7 種語言使用 Tree-sitter AST 解析：Python、JavaScript、TypeScript、Java、Go、Objective-C、Zig
50+ 種檔案類型使用備用策略：C/C++、Rust、Ruby、PHP 和所有其他程式語言
文件與配置檔案：Markdown、JSON、YAML、XML 適當處理
網頁前端：Vue、React、Svelte、HTML、CSS、SCSS
Java Web 與建置：JSP/Tag (.jsp, .jspx, .jspf, .tag, .tagx)、Grails/GSP (.gsp)、Gradle/Groovy 腳本 (.gradle, .groovy)、.properties、Protocol Buffers (.proto)
資料庫：SQL 變體、NoSQL、存儲過程、遷移腳本
配置檔案：JSON、YAML、XML、Markdown
查看完整列表

⚡ 即時監控與自動刷新

檔案監控器：檔案變更時自動更新索引
跨平台：原生作業系統檔案系統監控
智慧處理：批次處理快速變更以防止過度重建
淺層索引更新：監控檔案變更並維持檔案清單最新；需要符號資料時請執行 build_deep_index

⚡ 效能與效率

Tree-sitter AST 解析：原生語法解析以實現準確的符號提取
持久快取：儲存索引以實現超快速的後續存取
智慧篩選：智能排除建構目錄和暫存檔案
記憶體高效：針對大型程式碼庫優化
直接依賴：無備用機制 - 快速失敗並提供清晰錯誤訊息

支援的檔案類型

📁 程式語言（點擊展開）

專業化 Tree-sitter 策略語言：

Python (.py, .pyw) - 完整 AST 分析，包含類別/方法提取和呼叫追蹤
JavaScript (.js, .jsx, .mjs, .cjs) - ES6+ 類別和函數解析使用 Tree-sitter
TypeScript (.ts, .tsx) - 完整類型感知符號提取，包含介面
Java (.java) - 完整類別階層、方法簽名和呼叫關係
Go (.go) - 結構方法、接收者類型和函數分析
Objective-C (.m, .mm) - 類別/實例方法區分，使用 +/- 標記法
Zig (.zig, .zon) - 函數和結構解析使用 Tree-sitter AST

所有其他程式語言： 所有其他程式語言使用 備用解析策略，提供基本檔案索引和元資料提取。包括：

系統與低階語言： C/C++ (.c, .cpp, .h, .hpp)、Rust (.rs)
物件導向語言： C# (.cs)、Kotlin (.kt)、Scala (.scala)、Swift (.swift)
腳本與動態語言： Ruby (.rb)、PHP (.php)、Shell (.sh, .bash)
以及 40+ 種檔案類型 - 全部通過備用策略處理進行基本索引

🌐 網頁與前端（點擊展開）

框架與函式庫：

Vue (.vue)
Svelte (.svelte)
Astro (.astro)

樣式：

CSS (.css, .scss, .less, .sass, .stylus, .styl)
HTML (.html)

模板：

Handlebars (.hbs, .handlebars)
EJS (.ejs)
Pug (.pug)
FreeMarker (.ftl)
Mustache (.mustache)
Liquid (.liquid)
ERB (.erb)

🗄️ 資料庫與 SQL（點擊展開）

SQL 變體：

標準 SQL (.sql, .ddl, .dml)
資料庫特定 (.mysql, .postgresql, .psql, .sqlite, .mssql, .oracle, .ora, .db2)

資料庫物件：

程序與函式 (.proc, .procedure, .func, .function)
檢視與觸發器 (.view, .trigger, .index)

遷移與工具：

遷移檔案 (.migration, .seed, .fixture, .schema)
工具特定 (.liquibase, .flyway)

NoSQL 與現代資料庫：

圖形與查詢 (.cql, .cypher, .sparql, .gql)

📄 文件與配置（點擊展開）

Markdown (.md, .mdx)
配置 (.json, .xml, .yml, .yaml, .properties)

快速開始

🚀 建議設定（適用於大多數使用者）

在任何相容 MCP 的應用程式中開始使用的最簡單方法：

先決條件： Python 3.10+ 和 uv

新增到您的 MCP 配置（例如 claude_desktop_config.json 或 ~/.claude.json）：

{
  "mcpServers": {
    "code-index": {
      "command": "uvx",
      "args": ["code-index-mcp"]
    }
  }
}

重新啟動您的應用程式 – uvx 會自動處理安裝和執行

🛠️ 開發設定

適用於貢獻或本地開發：

克隆並安裝：

git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync

配置本地開發：

{
  "mcpServers": {
    "code-index": {
      "command": "uv",
      "args": ["run", "code-index-mcp"]
    }
  }
}

使用 MCP Inspector 除錯：

npx @modelcontextprotocol/inspector uv run code-index-mcp

替代方案：手動 pip 安裝

如果您偏好傳統的 pip 管理：

pip install code-index-mcp

然後配置：

{
  "mcpServers": {
    "code-index": {
      "command": "code-index-mcp",
      "args": []
    }
  }
}

可用工具

🏗️ 專案管理

工具	描述
`set_project_path`	為專案目錄初始化索引
`refresh_index`	在檔案變更後重建淺層檔案索引
`build_deep_index`	產生供深度分析使用的完整符號索引
`get_settings_info`	檢視目前專案配置和狀態

需要符號層級資料時，請執行 build_deep_index；預設的淺層索引提供快速檔案探索。

🔍 搜尋與探索

工具	描述
`search_code_advanced`	智慧搜尋，支援正規表達式、模糊匹配和檔案篩選，預設每頁回傳 10 筆結果，可透過 `max_results` 與 `start_index` 調整
`find_files`	使用萬用字元模式尋找檔案（例如 `*/.py`）
`get_file_summary`	分析檔案結構、函式、匯入和複雜度（需要深度索引）

🔄 監控與自動刷新

工具	描述
`get_file_watcher_status`	檢查檔案監控器狀態和配置
`configure_file_watcher`	啟用/停用自動刷新並配置設定

🛠️ 系統與維護

工具	描述
`create_temp_directory`	設定索引資料的儲存目錄
`check_temp_directory`	驗證索引儲存位置和權限
`clear_settings`	重設所有快取資料和配置
`refresh_search_tools`	重新偵測可用的搜尋工具（ugrep、ripgrep 等）

使用範例

🎯 快速開始工作流程

1. 初始化您的專案

將專案路徑設定為 /Users/dev/my-react-app

自動索引您的程式碼庫並建立可搜尋的快取

2. 探索專案結構

在 src/components 中尋找所有 TypeScript 元件檔案

使用：find_files，模式為 src/components/**/*.tsx

3. 分析關鍵檔案

給我 src/api/userService.ts 的摘要

使用：get_file_summary 顯示函式、匯入和複雜度 提示：若收到 needs_deep_index 回應，請先執行 build_deep_index。

🔍 進階搜尋範例

程式碼模式搜尋

使用正規表達式搜尋所有符合 "get.*Data" 的函式呼叫

找到：getData()、getUserData()、getFormData() 等

模糊函式搜尋

使用 'authUser' 的模糊搜尋尋找驗證相關函式

匹配：authenticateUser、authUserToken、userAuthCheck 等

特定語言搜尋

只在 Python 檔案中搜尋 "API_ENDPOINT"

使用：search_code_advanced，file_pattern: "*.py"（預設回傳 10 筆；使用 max_results 擴充或 start_index 換頁）

自動刷新配置

配置檔案變更時的自動索引更新

使用：configure_file_watcher 啟用/停用監控並設定防抖時間

專案維護

我新增了新元件，請重新整理專案索引

使用：refresh_index 更新可搜尋的快取

故障排除

🔄 自動刷新無法運作

如果檔案變更時自動索引更新無法運作，請嘗試：

pip install watchdog（可能解決環境隔離問題）
使用手動刷新：在檔案變更後呼叫 refresh_index 工具
檢查檔案監視器狀態：使用 get_file_watcher_status 驗證監控是否處於活動狀態

開發與貢獻

🔧 從原始碼建構

git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code-index-mcp

🐛 除錯

npx @modelcontextprotocol/inspector uvx code-index-mcp

13 KiB

Raw Blame History

程式碼索引 MCP

概述

快速開始

🚀 推薦設定（大多數使用者）

Codex CLI 設定

典型使用場景

主要特性

🔍 智慧搜尋與分析

🗂️ 多語言支援

⚡ 即時監控與自動刷新

⚡ 效能與效率

支援的檔案類型

快速開始

🚀 建議設定（適用於大多數使用者）

🛠️ 開發設定

可用工具

🏗️ 專案管理

🔍 搜尋與探索

🔄 監控與自動刷新

🛠️ 系統與維護

使用範例

🎯 快速開始工作流程

🔍 進階搜尋範例

故障排除

🔄 自動刷新無法運作

開發與貢獻

🔧 從原始碼建構

🐛 除錯

🤝 貢獻

📜 授權條款

🌐 翻譯

13 KiB Raw Blame History Unescape Escape

程式碼索引 MCP

概述

快速開始

🚀 推薦設定（大多數使用者）

Codex CLI 設定

典型使用場景

主要特性

🔍 智慧搜尋與分析

🗂️ 多語言支援

⚡ 即時監控與自動刷新

⚡ 效能與效率

支援的檔案類型

快速開始

🚀 建議設定（適用於大多數使用者）

🛠️ 開發設定

可用工具

🏗️ 專案管理

🔍 搜尋與探索

🔄 監控與自動刷新

🛠️ 系統與維護

使用範例

🎯 快速開始工作流程

🔍 進階搜尋範例

故障排除

🔄 自動刷新無法運作

開發與貢獻

🔧 從原始碼建構

🐛 除錯

🤝 貢獻

📜 授權條款

🌐 翻譯

13 KiB

Raw Blame History