Flyto Indexer

🚀 Flyto Indexer

Flyto Indexer 是一個 MCP 服務器，能為 AI 助手提供影響分析、跨項目引用跟蹤和代碼健康評分功能。它零依賴、純 Python 實現且完全本地化運行，讓你在代碼變更前預知潛在問題。

🚀 快速開始

安裝

pip install flyto-indexer
flyto-index setup .

上述命令會完成以下操作：

1. 掃描項目並構建代碼索引。
2. 生成包含工具使用說明的 CLAUDE.md 文件。
3. 配置 Claude Code MCP 設置（~/.claude/settings.json）。

安裝完成後，重啟 Claude Code 即可開始使用。該工具可與任何 MCP 客戶端配合使用，如 Claude Code、Cursor、Windsurf 等。

手動配置（其他 MCP 客戶端）

若你的 MCP 客戶端不使用 ~/.claude/settings.json，可在 MCP 配置中添加以下內容：

{
  "mcpServers": {
    "flyto-indexer": {
      "command": "python3",
      "args": ["-m", "flyto_indexer.mcp_server"]
    }
  }
}

然後分別執行掃描和設置 CLAUDE.md 的操作：

flyto-index scan .
flyto-index setup-claude .

從源碼運行

git clone https://github.com/flytohub/flyto-indexer.git
cd flyto-indexer && pip install -e .
flyto-index setup .

卸載

flyto-index setup . --remove
pip uninstall flyto-indexer

✨ 主要特性

影響分析 — 核心功能

現有的工具（如 grep、文件讀取、glob）只能查找文本，無法回答“哪些內容依賴於這個元素？”的問題。impact_analysis 會構建反向依賴圖，精確告訴你代碼變更會影響哪些部分：

→ impact_analysis("useAuth")

  12 處引用分佈在 4 個項目中：
    flyto-cloud:  LoginPage.vue, RegisterPage.vue, AuthGuard.ts, api.ts
    flyto-pro:    vscode_agent/tools.py, middleware/auth.py
    flyto-vscode: ChatHandler.ts, AuthProvider.ts
    flyto-core:   modules/auth/login.py
  風險等級: 高 — 涉及 4 個項目

→ edit_impact_preview("useAuth", change_type="signature_change")
  顯示每個調用點需要更新的具體代碼行。

跨語言 API 跟蹤

Python 後端端點會自動與 TypeScript/Vue 前端調用者關聯：

→ list_apis()

  POST /api/checkout
    定義位置: backend/routes/order.py (create_order)
    調用位置:   frontend/Cart.vue, frontend/api/orders.ts
    調用次數: 4

該功能可檢測 FastAPI、Flask、Starlette 裝飾器以及 fetch()、axios、$http 調用。

代碼健康與安全

→ code_health_score()            → security_scan()

  得分: 74/100 (C)               2 個關鍵問題: 硬編碼 API 密鑰
  複雜度:    22/25             1 個高風險問題: SQL 字符串拼接
  死代碼:     18/25             0 箇中等風險問題
  文檔完整性: 16/25
  模塊化程度: 18/25

→ suggest_refactoring()

  [高]   process_data() — 87 行，深度=6 → 提取子函數
  [中]   dead_fn() — 未被引用，45 行 → 可安全刪除
  [低]    utils.py — 800 行 → 拆分為專注功能的模塊

任務分析 — 編碼前規劃

analyze_task 會從 6 個維度評估風險，並生成包含具體工具調用序列的執行計劃：

→ analyze_task("Rename validateOrder to validate_order", intent="refactor")

  維度評估:
    影響範圍:      高 (8.0)  — 3 個項目中存在 7 個調用者
    破壞風險:     高 (7.0)  — 公共 API，被外部消費者使用
    測試風險:         中 (5.0) — 7 個調用者中有 2 個有測試覆蓋
    跨項目耦合度:    高 (8.0)  — 在 3 個項目中被引用
    複雜度:        低 (2.0)   — 簡單的重命名操作
    回滾難度: 中 (5.0) — 涉及多項目變更

  策略: 安全重構（因影響範圍大，從最小差異策略升級）

  執行計劃:
    1. scope_callers       → find_references("validateOrder")
    2. verify_test_coverage → find_test_file("checkout.py")
    3. check_cross_project → cross_project_impact("validateOrder")
    4. gate_before_plan    → task_gate_check(phase="plan")
    5. preview_changes     → edit_impact_preview("validateOrder", "rename")
    6. gate_before_apply   → task_gate_check(phase="apply")

每個步驟都預填充了參數和依賴關係，AI 可根據數據結構執行操作，而非依賴提示。

💻 使用示例

不使用 Flyto Indexer 的情況

You:    "Rename validateOrder to validate_order"

AI:     *重命名函數*
        *使用 grep 查找 "validateOrder"*
        *在同一項目中找到 3 處匹配*
        *錯過前端倉庫中的 4 個調用者*
        *錯過路由到該函數的 API 端點*
        *推送有問題的代碼*

使用 Flyto Indexer 的情況

You:    "Rename validateOrder to validate_order"

AI:     → impact_analysis("validateOrder")

        ⚠️ 3 個項目中存在 7 個調用點：
          backend/checkout.py:42     — 調用 validateOrder()
          backend/api/orders.py:18   — 導入 validateOrder
          frontend/Cart.vue:55       — 通過 useCheckout() 調用
          frontend/QuickBuy.vue:23   — 通過 useCheckout() 調用
          mobile/OrderScreen.tsx:67  — 對 /api/validate 的 API 調用
          tests/test_orders.py:12    — 單元測試
          tests/test_api.py:88       — 集成測試
          風險等級: 高 — 3 個項目受影響

        → edit_impact_preview("validateOrder", change_type="rename")
        *重命名所有 7 個調用點，更新測試，推送無問題的代碼*

📚 詳細文檔

工具列表

該工具提供了 32 個 MCP 工具，按功能分類如下：

影響與依賴相關工具

這些是安裝該工具的主要原因：

任務分析相關工具

用於編碼前的規劃：

代碼質量相關工具

用於在代碼審查前發現問題：

所有 32 個工具詳情（包括搜索、元數據、會話、任務分析）

支持的語言

🔧 技術細節

工作原理

flyto-index scan .

該命令會執行以下操作：

1. 解析：使用 AST（Python）或正則表達式（其他語言）提取每個函數、類和導入信息。
2. 構建圖：構建依賴圖和反向索引（調用者 → 被調用者）。
3. 服務：MCP 服務器從內存中的圖結構中回答查詢。
4. 增量更新：僅重新掃描有變更的文件（通過內容哈希跟蹤）。

索引文件結構

.flyto-index/
├── index.json       # 符號 + 依賴圖 + 反向索引
├── content.jsonl    # 源代碼（懶加載）
├── bm25.json        # 搜索索引
└── manifest.json    # 變更跟蹤

CI：阻止高風險變更

# 如果變更影響的調用點過多，PR 將失敗
- run: pip install flyto-indexer
- run: flyto-index scan .
- run: flyto-index check . --threshold medium --base main

CLI 命令

flyto-index setup .                       # 一鍵完成掃描、生成 CLAUDE.md 和 MCP 配置
flyto-index scan .                        # 索引（或重新索引）
flyto-index impact useAuth --path .       # 影響分析
flyto-index check . --threshold medium    # CI 檢查
flyto-index demo .                        # 30 秒演示
flyto-index install-hook .                # 提交時自動重新索引
flyto-index setup . --remove              # 卸載

📄 許可證

本項目採用 MIT 許可證。

隱私說明

該工具完全本地化運行，不會將代碼發送到任何外部服務器。刪除 .flyto-index/ 目錄即可徹底清理數據。

侷限性

• 僅支持靜態分析，不跟蹤動態導入和元編程。
• 不進行類型推斷，複雜的 TypeScript 泛型會被簡化處理。
• 跨項目跟蹤要求所有項目一起進行索引。