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 泛型会被简化处理。
• 跨项目跟踪要求所有项目一起进行索引。