@lorrylurui/code-intelligence-mcp 1.1.14 → 1.1.15

package/README.md

@@ -1,614 +1,36 @@
 # Code Intelligence MCP (Minimal)
 
-最小可用的 Node MCP Server 框架，包含：
-
 - MCP Server（stdio）
-- Tool: `search_symbols`（支持 `semantic=true` 语义检索，Phase 5）
+- Tool: `search_symbols`
 - Tool: `get_symbol_detail`
 - Tool: `search_by_structure`
 - Tool: `reindex`
 - Tool: `recommend_component`
-- Prompt: `reusable-code-advisor`（与 Cursor Skill 同工作流，见 `src/prompts/reusableCodeAdvisorPrompt.ts`）
+- Tool: `incUsage`
+- Prompt: `reusable-code-advisor`
 - MySQL Repository（可选启用）
-- Cursor Skill：`reusable-code-advisor`（`.cursor/skills/reusable-code-advisor/`，未改动，与 MCP Prompt 并行维护）
-
-## 1) 安装
-
-```bash
-npm install
-```
-
-## 2) 环境变量
-
-复制 `.env.example` 为 `.env`。
-
-默认不强制连接 MySQL（未配置时走内存示例数据）。
-
-如果你要连接 MySQL，请设置：
-
-```env
-MYSQL_ENABLED=true
-MYSQL_HOST=127.0.0.1
-MYSQL_PORT=3306
-MYSQL_USER=root
-MYSQL_PASSWORD=devpassword
-MYSQL_DATABASE=code_intelligence
-
-# Phase 5（可选）：句向量服务根 URL，与 `npm run embedding:dev` 默认端口一致
-# EMBEDDING_SERVICE_URL=http://127.0.0.1:8765
-```
-
-密码需与下方 Docker / 本机 MySQL 配置一致（文档示例里 `devpassword` 对应 Compose）。
-
-### 用 Docker 启动 MySQL（推荐本地开发）
-
-1. 安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)（或 Docker Engine + Compose 插件）。
-2. 在项目根目录执行：
-
-```bash
-npm run docker:up
-# 或：docker compose up -d
-```
-
-3. 首次启动会自动挂载 `sql/schema.sql` 到 `docker-entrypoint-initdb.d`，**创建库表**（仅**空数据卷**时执行一次）。
-4. 复制 `.env.example` 为 `.env`，设置 `MYSQL_ENABLED=true`，`MYSQL_PASSWORD` 与 `docker-compose.yml` 里 `MYSQL_ROOT_PASSWORD`（默认 `devpassword`）一致。
-5. 等待容器健康（约数十秒）：
-
-```bash
-docker compose ps
-```
-
-6. 再执行 `npm run index` 或启动 MCP。
-
-常用命令：
-
-| 命令                     | 说明                           |
-| ------------------------ | ------------------------------ |
-| `npm run docker:logs`    | 查看 MySQL 日志                |
-| `npm run docker:down`    | 停止容器（数据卷保留，库仍在） |
-| `docker compose down -v` | **删除卷**（清空库，慎用）     |
-
-**端口冲突**：若本机已有服务占用 `3306`，把 `docker-compose.yml` 里 `ports` 改为 `"3307:3306"`，并在 `.env` 设 `MYSQL_PORT=3307`。
-
-## 3) 初始化数据库（可选）
-
-- **已用上述 Docker 首次启动**：若卷为空，建表已由 `sql/schema.sql` 自动执行，一般无需再跑下面命令。
-- **本机 mysql 客户端 / 手动执行**：
-
-```bash
-mysql -u root -p code_intelligence < sql/schema.sql
-```
-
-### 自定义表名（第三方项目集成）
-
-若需使用不同的表名，可通过环境变量配置：
-
-```bash
-# 设置自定义表名
-export MYSQL_SYMBOLS_TABLE=my_project_symbols
-
-# 然后server代码内部执行建表（表名会在代码中动态替换）
-mysql -u root -p code_intelligence -e "$(node -e \"import('./dist/db/schema.js').then(m => console.log(m.getSymbolsTableSQL()))\")"
-```
-
-或在 `.env` 中配置：
-
-```env
-MYSQL_SYMBOLS_TABLE=my_project_symbols
-```
-
-## 4) 本地运行
-
-### 普通开发（热更新）
-
-```bash
-npm run dev
-```
-
-使用 `tsx watch`，改 `src/` 会自动重启；已关闭清屏（`--clear-screen=false`），并排除 `node_modules`、`dist`。
-
-### 接 Cursor MCP（不污染 stdout）
-
-MCP 走 **stdio**，协议数据必须在子进程的 **stdout** 上；若用 `npm run dev` 接 MCP，`npm` 或部分工具可能往 stdout 打杂讯，导致握手异常。
-
-推荐用 **专用脚本**：子进程只跑 `tsx src/index.ts`，**监听/重启日志只打到 stderr**。
-
-```bash
-npm run dev:mcp
-```
-
-**Cursor `mcp.json` 示例（推荐直接调 node，避免 npm）：**
-
-```json
-{
-    "mcpServers": {
-        "code-intelligence-mcp": {
-            "command": "node",
-            "args": ["/绝对路径/Intelligence-code/scripts/mcp-dev-watch.mjs"],
-            "cwd": "/绝对路径/Intelligence-code"
-        }
-    }
-}
-```
-
-也可继续用 `"command": "npm"`, `"args": ["run", "dev:mcp"]`，但部分环境下 npm 仍可能产生额外输出；若 tools 不稳定，请改用上面的 `node .../mcp-dev-watch.mjs`。
-
-### MCP Prompt（非 Cursor 客户端）
-
-服务器注册 Prompt **`reusable-code-advisor`**：客户端执行 `prompts/list` 可见；`prompts/get` 时可传可选参数 **`userRequest`**（用户当前需求或关键词），返回的消息正文与 Cursor Skill 工作流一致。  
-文案与 `.cursor/skills/reusable-code-advisor/SKILL.md` 正文需**手动同步**（见 `src/prompts/reusableCodeAdvisorPrompt.ts` 顶部注释）。
-
-在 **MCP Inspector** 中切换到 **Prompts** 面板即可选择并调试。
-
-## 5) Phase 2：代码索引（ts-morph + fast-glob → MySQL）
-
-1. **建表 / 迁移**
-    - 新库：执行 `sql/schema.sql`（已含 `(path, name)` 唯一索引，便于重复执行 `npm run index` 时 upsert）。
-    - 旧库若只有早期表结构：执行 `sql/migrations/002_symbols_unique_path_name.sql`（若已有重复 `path+name` 需先清理）。
-
-2. **配置 MySQL**（`.env` 中 `MYSQL_ENABLED=true` 等）。
-
-3. **跑索引**（日志在 stderr，不污染 MCP stdout）：
-
-```bash
-npm run index
-```
-
-可选环境变量（见 `.env.example`）：
-
-| 变量           | 含义                                    |
-| -------------- | --------------------------------------- |
-| `INDEX_ROOT`   | 工程根目录，默认当前工作目录            |
-| `INDEX_GLOB`   | 空格分隔 glob，默认 `src/**/*.{ts,tsx}` |
-| `INDEX_IGNORE` | 额外忽略的 glob 片段（空格分隔）        |
-
-**分类规则（首版启发式）**：`interface` / `type` → `type`；`.tsx` 且函数体含 JSX → `component`；路径或导出名含 `selector` → `selector`；其余导出函数 → `util`；`class` → `util`（可后续细化）。
-
-**常见错误 `ECONNREFUSED 127.0.0.1:3306`**：本机没有在该端口监听 MySQL。请先启动数据库服务（例如 macOS Homebrew：`brew services start mysql` / `mariadb`），或把 `.env` 里的 `MYSQL_HOST`、`MYSQL_PORT` 改成你实际使用的实例（含 Docker 映射端口）。索引脚本会先执行 `SELECT 1` 再扫描代码，避免库不可用时仍跑完解析。
-
-## 6) 后续演进建议
-
-- 新增 Tool：`list_dependencies`、`get_usage_stats`
-- Indexer：更细的 selector 识别、`export default` 命名、类组件等
-- Phase 5 语义检索已落地（见下文）；后续可换 pgvector / FAISS、更大模型
-
-## 8) Phase 3（增强）
-
-- `search_symbols` 已支持 `ranked` 参数（默认 `true`），返回 `score` 和 `reason`。
-- 新增 `search_by_structure`，可按 `fields`（匹配 `meta.props/params/properties/hooks`）检索。
-- 两个搜索 tool 的 ranking 已升级：除可读 `reason` 外，还返回结构化 `reasonDetail`（含各维度得分、权重和匹配方式），方便前端/Agent解释。
-
-示例：
-
-```json
-{
-    "fields": ["onChange", "value"],
-    "type": "component",
-    "limit": 10
-}
-```
+- Cursor Skill：`reusable-code-advisor`（`.cursor/skills/reusable-code-advisor/`，
 
-`reindex` 示例（Inspector / Agent 可直接调用，不用回终端）：
+## 1) 配置mcp servers
 
-```json
-{
-    "dryRun": false
-}
 ```
-
-可选参数：
-
-- `projectRoot`: 指定索引根目录（默认 MCP 进程当前目录）
-- `globPatterns`: 自定义扫描 glob 列表
-- `ignore`: 额外忽略规则
-- `dryRun`: `true` 时只扫描，不写 MySQL
-
-## 9) Phase 4（Skill）
-
-- 新增 Skill Tool：`recommend_component`
-- 流程已落地：关键词搜索 -> 结构过滤（可选 `props`）-> ranking -> detail 补全 -> 返回 reason
-- 新增 Prompt：`recommend-component`（用于在支持 MCP Prompt 的客户端快速触发该流程）
-
-示例：
-
-```json
-{
-    "query": "带校验的表单组件",
-    "props": ["value", "onChange"],
-    "limit": 3
-}
-```
-
-## 10) Phase 5（语义检索，可选）
-
-1. **迁移**：若库是在增加 `embedding` 列之前创建的，执行：
-
-```bash
-mysql -u root -p code_intelligence < sql/migrations/003_add_embedding.sql
-```
-
-2. **Python 依赖**（建议虚拟环境；首次运行会下载模型权重，体积约数百 MB）：
-
-```bash
-cd embedding-service
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-```
-
-3. **启动嵌入服务**（默认 `127.0.0.1:8765`）：
-
-```bash
-npm run embedding:dev
-```
-
-4. **`.env`** 增加 `EMBEDDING_SERVICE_URL=http://127.0.0.1:8765`，再执行 **`npm run index`** 或 MCP **`reindex`**（`dryRun=false`）写入向量。未配置 URL 时与 Phase 2 行为一致，不写入 `embedding`。
-
-5. **`search_symbols`**：传入 `semantic: true` 可做自然语言检索；可选 `limit`（默认 20）。返回中会含 `semanticSimilarity`（余弦相似度）。当前实现按 `usage_count` 取最多 3000 条有向量的候选再精排；超大规模仓库请改为 ANN。
-
-环境变量 **`EMBEDDING_MODEL`**（仅 Python）：覆盖默认的 `all-MiniLM-L6-v2`。
-
-## 7) VS Code 迁移
-
-迁移步骤见 `docs/vscode-mcp-migration.md`。
-
-# 使用说明
-
-Run with:
-
-````bash
-- 脚本 cli 启动：npx code-intelligence-mcp（走mcp不执行）
-- 给项目做索引，运行：npx code-intelligence-index, 项目根目录取配置或者cwd（重要，首次以及后续需要时执行：新项目必须执行一次建表）
----
-
-### MCP 配置（核心）
-
-```md
-## MCP Config
-
-```json
 {
   "mcpServers": {
-    "code-intelligence": {
+    "code-intelligence-mcp": {
       "command": "npx",
-      "args": ["code-intelligence-mcp"]
+      "args": ["-y", "@lorrylurui/code-intelligence-mcp"]
     }
   }
 }
----
-
-### 支持的 Tools Prompts
-
-```md
-## Tools
-
-- search_symbols
-- get_symbol_detail
-- search_by_structure
-- recommend_component
-- reindex
-
-## Prompts
-
-- recommend-component
-- reusable-code-advisor
-````
-
----
-
-Code Intelligence 功能完整总结
-
-项目定位
-
-智能代码推荐系统：解决日常团队开发中可复用逻辑（组件、样式、selectors、类型声明等）重复开发问题，提高代码复
-用率。
-
-一、系统架构
-
-┌─────────────────────────────────────────────────────────────────┐  
-│ MCP Client (Claude/Cursor) │  
-│ 用户提问 → 模型分析 → 返回结果 │
-└─────────────────────────────────────────────────────────────────┘  
- │  
- ▼  
-┌─────────────────────────────────────────────────────────────────┐  
-│ MCP Server (Node.js) │  
-├─────────────────────────────────────────────────────────────────┤  
-│ Tools (4个) │ Prompts (1个) │ DB Layer │  
-│ - search_symbols │ - reusable-code- │ - MySQL │  
-│ - get_symbol_detail │ advisor │ - embedding │  
-│ - search_by_struct │ │ │  
-│ - reindex │ │ │  
-└─────────────────────────────────────────────────────────────────┘  
- │  
- ▼  
-┌─────────────────────────────────────────────────────────────────┐  
-│ Indexer (源码解析) │  
-│ ts-ormorph (TS/TSX) + Babel (JS/JSX) │  
-└─────────────────────────────────────────────────────────────────┘  
- │  
- ▼  
-┌─────────────────────────────────────────────────────────────────┐  
-│ Embedding Service (Python FastAPI) │  
-│ 向量化 + 语义检索 │  
-└─────────────────────────────────────────────────────────────────┘
-
-二、MCP Server Tools（4个）
-
-1. search_symbols 通用检索
-
-功能：根据 query 和 type 进行语义搜索，对结果进行权重排序
-
-入参：  
-{  
- query: string, // 搜索关键词  
- type?: 'component' | 'util' | 'selector' | 'type', // 可选  
- semantic?: boolean, // 是否启用语义搜索（需 embedding 服务）
-ranked?: boolean, // 是否排序，默认 true  
- limit?: number, // 返回数量，默认 20  
-}
-
-权重排序算法（RANK_WEIGHTS）：  
-const RANK_WEIGHTS = {  
- textMatch: 0.4, // 文本匹配度  
- usage: 0.3, // 使用频率  
- recency: 0.15, // 最近更新时间  
- commonPath: 0.15, // common 路径偏好  
-}
-
-score = textScore _ 0.4 + usage _ 0.3 + recency _ 0.15 + commonPath _ 0.15
-
-难点：
-
-- 多维度权重调优
-- 文本匹配算法（模糊匹配 + 语义匹配）
-- 冷启动时无 embedding 向量fallback 到文本匹配
-
----
-
-2. get_symbol_detail 获取详情
-
-功能：根据 name 获取代码块的完整信息
-
-入参：  
- {  
- name: string, // 代码块名称  
- }
-
-返回：完整代码块信息包括 meta（props/params/properties/hooks）
-
-难点：需要从 MySQL 解析 JSON 格式的 meta 字段
-
----
-
-3. search_by_structure 结构化搜索
-
-功能：通过结构化字段搜索代码块，适用于 API 形态查询
-
-入参：  
- {  
- fields: string[], // 结构字段，如 ['onChange', 'value']  
- type?: 'component' | 'util' | 'selector' | 'type',  
- category?: string, // 业务分类  
- limit?: number,  
- }
-
-匹配逻辑：匹配 symbol.meta 中的：
-
-- props - 组件 props
-- params - 函数参数
-- properties - 对象属性
-- hooks - React hooks
-
-难点：
-
-- 不支持 LLM 向量检索，需全表扫描 + 内存过滤
-- 需要在 MySQL 中存储 JSON 格式的 meta
-
----
-
-4. reindex 重建索引
-
-功能：扫描源码目录，解析并写入 MySQL + 向量
-
-入参：  
- {  
- projectRoot?: string, // 项目根目录，默认 cwd  
- globPatterns?: string[], // glob 模式，默认 ['**/*.{ts,tsx}']  
- ignore?: string[], // 忽略目录  
- dryRun?: boolean, // 仅预览不写入  
- }
-
-处理流程：
-
-1. 收集文件（fast-glob）  
-   ↓
-2. 分离 TS/TSX 和 JS/JSX  
-   ↓
-3. TS/TSX：ts-ormorph 解析  
-   JS/JSX：Babel 解析  
-   ↓
-4. 提取 meta（props/params/properties/hooks）  
-   ↓
-5. 写入 MySQL  
-   ↓
-6. 写入 embedding 向量（可选）
-
-难点：
-
-- ts-ormorph：需要 tsconfig.json，不存在时用默认配置
-- Babel 解析：支持 JSX、TypeScript、装饰器等语法
-- meta 提取：
-    - extractFunctionMeta：提取函数参数、返回值类型
-    - extractHooksFromBody：提取 useState/useEffect 等
-    - extractInterfaceOrTypeMeta：提取接口属性
-- 路径推断 category：从路径智能推断业务分类（如 src/components/form/\* → form）
-- 忽略规则：node_modules、dist、build、.git、coverage、.next、.nuxt、.venv 等
-
----
-
-三、MCP Prompt（1个）
-
-reusable-code-advisor 多工具编排
-
-功能：在实现需求时检索并推荐最合适的可复用代码
-
-工作流：
-
-1. 调用 search_symbols 检索候选，type 根据用户需求传（component/util/selector/type）
-2. 如果用户指定了结构过滤条件（props/params/properties/hooks），额外调用 search_by_structure 做结构匹配
-3. 先 search_symbols(limit=20) 拉候选，再对 Top 3 调用 get_symbol_detail 做深度判断
-4. 若仅凭签名/摘要无法判断，调用 get_symbol_detail 获取详情
-5. 从以下维度对比候选：
-    - 功能匹配度
-    - API 是否简单、入参是否合适
-    - 依赖与副作用风险
-    - 复用安全性（稳定性、耦合度、是否便于扩展）
-6. 给出唯一首选推荐，并说明理由
-
-返回格式：
-
-- 首选：<代码块名>
-- 理由：1～3 条要点
-- 其他候选：简要列出及取舍
-- 用法提示：结合用户场景的最小集成说明
-
-难点：多工具组合调用逻辑、意图判断
-
----
-
-四、GitHub Actions（CI/CD 检测评论）
-
-1. duplicate-check 工作流
-
-功能：检测代码重复实现，在 PR/Commit 上自动评论
-
-触发条件：
-
-- push 到 main 分支
-- PR opened/synchronize/reopened
-
-工作流：
-
-1. 计算变更文件列表（git diff）
-2. 运行 detect-duplicates 脚本
-3. 生成报告（JSON + Markdown）
-4. 上传 artifact
-5. 评论到 PR 或 Commit
-
-评论逻辑：
-
-- PR 事件：直接评论到 PR
-- Push 事件：查找关联 PR 并评论，无关联则评论到 Commit
-
-发布为 GitHub Action：
-
-- 仓库：lorrylurui/code-intelligence-check
-- 第三方使用：
-- uses: lorrylurui/code-intelligence-check@v1  
-  with:  
-   is-mock-mode: 'true' # 无需 MySQL
-
----
-
-五、Embedding Service（Python FastAPI）
-
-功能
-
-- 文本向量化：将查询和代码块转为向量（384维 MiniLM）
-- 语义检索：余弦相似度计算
-
-API
-
-POST /embed  
- Body: { "texts": ["查询文本"] }  
- Response: { "embeddings": [[0.1, 0.2, ...]] }
-
-GET /health
-
----
-
-六、数据库设计
-
-symbols 表
-
-CREATE TABLE symbols (  
- id INT AUTO_INCREMENT PRIMARY KEY,  
- name VARCHAR(255) NOT NULL COMMENT '代码块名称',  
- type ENUM('component', 'util', 'selector', 'type') NOT NULL COMMENT '类型',
-category VARCHAR(100) COMMENT '业务分类',  
- path VARCHAR(500) NOT NULL COMMENT '文件路径',  
- description TEXT COMMENT '描述/文档',  
- content LONGTEXT COMMENT '完整代码内容',  
- meta JSON COMMENT '结构化元信息：props/params/properties/hooks',  
- usage_count INT DEFAULT 0 COMMENT '使用频率',  
- embedding JSON NULL COMMENT '向量',  
- created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,  
- INDEX idx_type (type),  
- INDEX idx_category (category),  
- INDEX idx_usage (usage_count DESC)  
- );
-
----
-
-七、环境配置
-
-环境变量
-
-┌───────────────────────┬──────────────┬───────────────────┐  
- │ 变量 │ 说明 │ 默认值 │
-├───────────────────────┼──────────────┼───────────────────┤  
- │ MYSQL_ENABLED │ 启用 MySQL │ false │  
- ├───────────────────────┼──────────────┼───────────────────┤  
- │ MYSQL_HOST │ MySQL 主机 │ - │  
- ├───────────────────────┼──────────────┼───────────────────┤  
- │ MYSQL_PORT │ MySQL 端口 │ 3306 │
-├───────────────────────┼──────────────┼───────────────────┤  
- │ MYSQL_USER │ MySQL 用户 │ - │  
- ├───────────────────────┼──────────────┼───────────────────┤  
- │ MYSQL_PASSWORD │ MySQL 密码 │ - │  
- ├───────────────────────┼──────────────┼───────────────────┤  
- │ MYSQL_DATABASE │ 数据库名 │ code_intelligence │  
- ├───────────────────────┼──────────────┼───────────────────┤  
- │ MYSQL_SYMBOLS_TABLE │ 表名 │ symbols │  
- ├───────────────────────┼──────────────┼───────────────────┤  
- │ EMBEDDING_SERVICE_URL │ 向量服务 URL │ - │  
- └───────────────────────┴──────────────┴───────────────────┘
-
-环境变量加载逻辑
-
-1. 加载本地 .env
-2. 加载第三方 .env（按变量维度覆盖，只覆盖第三方明确配置的变量）
-3. 命令行参数 --KEY=VALUE 优先级最高
-
----
+```
 
-八、技术难点总结
+## 2)配置流水线
 
-┌────────────┬───────────────────────────────────────────────────┐  
- │ 模块 │ 难点 │  
- ├────────────┼───────────────────────────────────────────────────┤  
- │ 权重排序 │ textMatch/usage/recency/commonPath 四维权重调优 │
-├────────────┼───────────────────────────────────────────────────┤  
- │ TS 解析 │ ts-ormorph 需要 tsconfig.json，不存在时用默认配置 │  
- ├────────────┼───────────────────────────────────────────────────┤  
- │ JS 解析 │ Babel 支持 JSX/TS/装饰器等复杂语法 │  
- ├────────────┼───────────────────────────────────────────────────┤  
- │ Meta 提取 │ 函数/接口/类/hooks 的参数、返回值、类型解析 │  
- ├────────────┼───────────────────────────────────────────────────┤  
- │ 路径推断 │ 从文件路径智能推断业务分类（category） │  
- ├────────────┼───────────────────────────────────────────────────┤
-│ 结构搜索 │ meta 存储为 JSON，全表扫描 + 内存过滤 │  
- ├────────────┼───────────────────────────────────────────────────┤
-│ 向量检索 │ 向量生成、存储、余弦相似度计算 │  
- ├────────────┼───────────────────────────────────────────────────┤
-│ 多工具编排 │ Prompt 中多 Tool 组合调用逻辑 │  
- ├────────────┼───────────────────────────────────────────────────┤
-│ 环境加载 │ 本地/第三方 .env 按变量维度合并 │  
- ├────────────┼───────────────────────────────────────────────────┤
-│ CI 评论 │ PR/Commit 评论逻辑、关联 PR 查找 │  
- └────────────┴───────────────────────────────────────────────────┘
+```
+    - uses: lorrylurui/code-intelligence-check@v1
+```
 
----
+## 3) 项目根目录环境变量
 
-这就是完整详细的功能总结。如需补充其他细节请告诉我。
+MYSQL\*SYMBOLS_TABLE=frontend_collections_symbols
+INDEX_GLOB=interview-code-collection/\*\*/\_.{js,jsx,ts,tsx}

package/dist/cli/index-codebase.js

@@ -10,19 +10,17 @@
 import { resolve } from 'node:path';
 import { loadProjectDotenv } from '../config/env.js';
 import { runReindex } from '../services/reindex.js';
-// dotenv.config();
 /**
  * 入口：加载第三方 .env → 校验环境 → 调用 runReindex。
  * 进度与统计输出到 **stderr**，避免占用 stdout。
  * 进程退出码：成功 `0`，无 MySQL 或异常 `1`。
  */
 async function main() {
-    // 2️ 确定项目根目录并加载第三方 .env（仅覆盖未定义的变量）
     const projectRoot = resolve(process.env.INDEX_ROOT ?? process.cwd());
     loadProjectDotenv(projectRoot);
-    console.error(`[index] projectRoot=${projectRoot}`);
     console.error(`[index] MYSQL_ENABLED=${process.env.MYSQL_ENABLED}, ` +
-        `MYSQL_HOST=${process.env.MYSQL_HOST}`);
+        `MYSQL_HOST=${process.env.MYSQL_HOST}` +
+        `[index] projectRoot=${projectRoot}`);
     const globPatterns = process.env.INDEX_GLOB
         ? process.env.INDEX_GLOB.split(/\s+/)
             .map((s) => s.trim())

package/dist/config/env.js

@@ -3,7 +3,6 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync, readFileSync } from 'node:fs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const projectRoot = __dirname;
 // 解析命令行参数 --key=value 格式，注入到 process.env
 for (const arg of process.argv) {
     const match = arg.match(/^--([A-Z_][A-Z0-9_]*)=(.+)$/);
@@ -11,11 +10,6 @@ for (const arg of process.argv) {
         process.env[match[1]] = match[2];
     }
 }
-// 加载本地 .env（外部传入的 env 已经在 process.env 中，override: false 不会覆盖它们）
-// dotenv.config({
-//     path: path.resolve(projectRoot, '.env'),
-//     override: false,
-// });
 // MCP Server 本地 .env 路径（固定指向项目根目录）
 const MCP_SERVER_ROOT = path.resolve(__dirname, '..', '..', './dist'); // MCP Server 根目录
 const MCP_SERVER_ENV_PATH = path.resolve(MCP_SERVER_ROOT, '.env');
@@ -28,9 +22,6 @@ dotenv.config({
  * 行为：优先使用第三方显式设置的值，否则保留 MCP Server 本地配置
  */
 export function loadProjectDotenv(projectRoot) {
-    // 始终确保 MCP Server 本地的 .env 被加载（补充加载，确保有默认值）
-    // if (existsSync(MCP_SERVER_ENV_PATH)) {
-    // }
     const envPath = path.resolve(projectRoot, '.env');
     if (!existsSync(envPath)) {
         return;
@@ -69,9 +60,6 @@ export function loadProjectDotenv(projectRoot) {
         }
     }
 }
-// 尝试从第三方项目目录加载 .env，按变量维度覆盖（只覆盖第三方明确配置的变量）
-// const clientProjectRoot = process.env.INDEX_ROOT || process.cwd();
-// loadProjectDotenv(clientProjectRoot);
 // 外部传入的 env 已在上一步保留，这里确保环境变量已正确设置
 for (const arg of process.argv) {
     const match = arg.match(/^--([A-Z_][A-Z0-9_]*)=(.+)$/);
@@ -113,87 +101,3 @@ export function validateEnv() {
         }
     }
 }
-// import dotenv from 'dotenv';
-// import path from 'node:path';
-// import { fileURLToPath } from 'node:url';
-// import { existsSync, readFileSync } from 'node:fs';
-// const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// const projectRoot = path.resolve(__dirname, '../../');
-// // 解析命令行参数 --key=value 格式，注入到 process.env
-// for (const arg of process.argv) {
-//     const match = arg.match(/^--([A-Z_][A-Z0-9_]*)=(.+)$/);
-//     if (match) {
-//         process.env[match[1]] = match[2];
-//     }
-// }
-// // 加载本地 .env（外部传入的 env 已经在 process.env 中，override: false 不会覆盖它们）
-// dotenv.config({
-//     path: path.resolve(projectRoot, '.env'),
-//     override: false,
-// });
-// // 尝试从第三方项目目录加载 .env，按变量维度覆盖（只覆盖第三方明确配置的变量）
-// const clientProjectRoot = process.env.INDEX_ROOT || process.cwd();
-// const clientEnvPath = path.resolve(clientProjectRoot, '.env');
-// if (existsSync(clientEnvPath)) {
-//     console.error(
-//         `[Config] Merging .env from client project root: ${clientProjectRoot}`
-//     );
-//     // 手动解析第三方 .env，只覆盖其明确配置的变量
-//     const clientEnvContent = readFileSync(clientEnvPath, 'utf-8');
-//     for (const line of clientEnvContent.split('\n')) {
-//         const trimmed = line.trim();
-//         if (!trimmed || trimmed.startsWith('#')) continue;
-//         const eqIdx = trimmed.indexOf('=');
-//         if (eqIdx === -1) continue;
-//         const key = trimmed.slice(0, eqIdx).trim();
-//         const value = trimmed.slice(eqIdx + 1).trim();
-//         // 移除引号
-//         const cleanValue = value.replace(/^["']|["']$/g, '');
-//         if (key) {
-//             process.env[key] = cleanValue;
-//         }
-//     }
-// }
-// // 外部传入的 env 已在上一步保留，这里确保环境变量已正确设置
-// for (const arg of process.argv) {
-//     const match = arg.match(/^--([A-Z_][A-Z0-9_]*)=(.+)$/);
-//     if (match) {
-//         process.env[match[1]] = match[2];
-//     }
-// }
-// const requiredWhenEnabled = [
-//     'MYSQL_HOST',
-//     'MYSQL_USER',
-//     'MYSQL_DATABASE',
-// ] as const;
-// console.error(
-//     `[Config] MYSQL_ENABLED: ${process.env.MYSQL_ENABLED},
-//     MYSQL_HOST: ${process.env.MYSQL_HOST},
-//     MYSQL_USER: ${process.env.MYSQL_USER},
-//     MYSQL_DATABASE: ${process.env.MYSQL_DATABASE},
-//     EMBEDDING_SERVICE_URL: ${process.env.EMBEDDING_SERVICE_URL},
-//     MYSQL_SYMBOLS_TABLE: ${process.env.MYSQL_SYMBOLS_TABLE}
-//     `
-// );
-// export const env = {
-//     mysqlEnabled: process.env.MYSQL_ENABLED === 'true',
-//     mysqlHost: process.env.MYSQL_HOST ?? '127.0.0.1',
-//     mysqlPort: Number(process.env.MYSQL_PORT ?? '3306'),
-//     mysqlUser: process.env.MYSQL_USER ?? 'root',
-//     mysqlPassword: process.env.MYSQL_PASSWORD ?? '',
-//     mysqlDatabase: process.env.MYSQL_DATABASE ?? 'code_intelligence',
-//     /** symbols 表名，可通过 MYSQL_SYMBOLS_TABLE 环境变量配置 */
-//     mysqlSymbolsTable: process.env.MYSQL_SYMBOLS_TABLE ?? 'symbols',
-//     /** Phase 5：指向 Python FastAPI 嵌入服务根 URL，如 http://127.0.0.1:8765 */
-//     embeddingServiceUrl: (process.env.EMBEDDING_SERVICE_URL ?? '').trim(),
-// };
-// export function validateEnv(): void {
-//     if (!env.mysqlEnabled) {
-//         return;
-//     }
-//     for (const key of requiredWhenEnabled) {
-//         if (!process.env[key]) {
-//             throw new Error(`Missing environment variable: ${key}`);
-//         }
-//     }
-// }

package/dist/indexer/babelParser.js

@@ -3,7 +3,7 @@
  */
 import * as babelParser from '@babel/parser';
 import * as bt from '@babel/types';
-import { getRelativePathForDisplay, inferCategoryFromPath } from './heuristics.js';
+import { getRelativePathForDisplay, inferCategoryFromPath, } from './heuristics.js';
 /** 从 JS 文件内容解析导出的代码块 */
 export function parseJsFile(filePath, content, projectRoot) {
     const out = [];
@@ -70,10 +70,14 @@ function processStatement(stmt, filePath, isJsx, projectRoot) {
         }
         else if (bt.isVariableDeclaration(decl)) {
             for (const declarator of decl.declarations) {
-                if (bt.isVariableDeclarator(declarator) && declarator.id && bt.isIdentifier(declarator.id)) {
+                if (bt.isVariableDeclarator(declarator) &&
+                    declarator.id &&
+                    bt.isIdentifier(declarator.id)) {
                     const name = declarator.id.name;
                     const init = declarator.init;
-                    if (name && (bt.isArrowFunctionExpression(init) || bt.isFunctionExpression(init))) {
+                    if (name &&
+                        (bt.isArrowFunctionExpression(init) ||
+                            bt.isFunctionExpression(init))) {
                         const fnDecl = arrowToFunction(name, init);
                         out.push(createRowFromFunction(name, fnDecl, filePath, projectRoot, isJsx));
                     }
@@ -84,19 +88,26 @@ function processStatement(stmt, filePath, isJsx, projectRoot) {
     // 处理 module.exports = xxx
     else if (bt.isExpressionStatement(stmt)) {
         const expr = stmt.expression;
-        if (bt.isAssignmentExpression(expr) && bt.isMemberExpression(expr.left)) {
+        if (bt.isAssignmentExpression(expr) &&
+            bt.isMemberExpression(expr.left)) {
             const left = expr.left;
             // module.exports = xxx
-            if (bt.isIdentifier(left.object) && left.object.name === 'module' &&
-                bt.isIdentifier(left.property) && left.property.name === 'exports') {
+            if (bt.isIdentifier(left.object) &&
+                left.object.name === 'module' &&
+                bt.isIdentifier(left.property) &&
+                left.property.name === 'exports') {
                 const right = expr.right;
                 if (bt.isObjectExpression(right)) {
                     for (const prop of right.properties) {
-                        if (bt.isObjectProperty(prop) && bt.isIdentifier(prop.key)) {
+                        if (bt.isObjectProperty(prop) &&
+                            bt.isIdentifier(prop.key)) {
                             const name = prop.key.name;
                             const value = prop.value;
-                            if (bt.isFunctionExpression(value) || bt.isArrowFunctionExpression(value)) {
-                                const fnDecl = arrowToFunction(name, bt.isArrowFunctionExpression(value) ? value : value);
+                            if (bt.isFunctionExpression(value) ||
+                                bt.isArrowFunctionExpression(value)) {
+                                const fnDecl = arrowToFunction(name, bt.isArrowFunctionExpression(value)
+                                    ? value
+                                    : value);
                                 out.push(createRowFromFunction(name, fnDecl, filePath, projectRoot, isJsx));
                             }
                         }
@@ -112,11 +123,15 @@ function processStatement(stmt, filePath, isJsx, projectRoot) {
                 }
             }
             // exports.xxx = xxx
-            else if (bt.isIdentifier(left.object) && left.object.name === 'exports') {
-                const name = bt.isIdentifier(left.property) ? left.property.name : null;
+            else if (bt.isIdentifier(left.object) &&
+                left.object.name === 'exports') {
+                const name = bt.isIdentifier(left.property)
+                    ? left.property.name
+                    : null;
                 if (name) {
                     const right = expr.right;
-                    if (bt.isFunctionExpression(right) || bt.isArrowFunctionExpression(right)) {
+                    if (bt.isFunctionExpression(right) ||
+                        bt.isArrowFunctionExpression(right)) {
                         const fnDecl = arrowToFunction(name, bt.isArrowFunctionExpression(right) ? right : right);
                         out.push(createRowFromFunction(name, fnDecl, filePath, projectRoot, isJsx));
                     }
@@ -166,10 +181,14 @@ function scanAllDeclarations(stmt, filePath, isJsx, projectRoot) {
     // 变量声明: const foo = () => {}, const bar = function() {}
     else if (bt.isVariableDeclaration(stmt)) {
         for (const declarator of stmt.declarations) {
-            if (bt.isVariableDeclarator(declarator) && declarator.id && bt.isIdentifier(declarator.id)) {
+            if (bt.isVariableDeclarator(declarator) &&
+                declarator.id &&
+                bt.isIdentifier(declarator.id)) {
                 const name = declarator.id.name;
                 const init = declarator.init;
-                if (name && (bt.isArrowFunctionExpression(init) || bt.isFunctionExpression(init))) {
+                if (name &&
+                    (bt.isArrowFunctionExpression(init) ||
+                        bt.isFunctionExpression(init))) {
                     const fnDecl = arrowToFunction(name, init);
                     out.push(createRowFromFunction(name, fnDecl, filePath, projectRoot, isJsx));
                 }
@@ -215,6 +234,8 @@ function createRowFromFunction(name, decl, filePath, projectRoot, isJsx) {
     const params = decl.params
         .filter((p) => bt.isIdentifier(p))
         .map((p) => p.name);
+    const hooks = extractHooksFromBody(decl);
+    const sideEffects = extractSideEffects(decl);
     return {
         name,
         type,
@@ -223,8 +244,11 @@ function createRowFromFunction(name, decl, filePath, projectRoot, isJsx) {
         description: null,
         content: `function ${decl.id?.name || 'anonymous'}(${params.join(', ')}) { ... }`,
         meta: {
+            kind: 'function',
             params,
             returnType: getReturnType(decl),
+            ...(hooks.length ? { hooks } : {}),
+            ...(sideEffects.length ? { sideEffects } : {}),
         },
     };
 }
@@ -253,7 +277,17 @@ function containsJsx(node) {
             return;
         }
         // 只遍历常见的包含子节点的属性
-        const keys = ['body', 'declarations', 'arguments', 'callee', 'init', 'left', 'right', 'consequent', 'alternate'];
+        const keys = [
+            'body',
+            'declarations',
+            'arguments',
+            'callee',
+            'init',
+            'left',
+            'right',
+            'consequent',
+            'alternate',
+        ];
         for (const key of keys) {
             const val = n[key];
             if (Array.isArray(val)) {
@@ -294,3 +328,173 @@ function getReturnType(fn) {
     }
     return undefined;
 }
+/**
+ * 遍历 Babel AST 节点，收集所有满足条件的回调
+ */
+function visitNodes(node, callback) {
+    callback(node);
+    for (const key of Object.keys(node)) {
+        const val = node[key];
+        if (Array.isArray(val)) {
+            for (const v of val) {
+                if (v && typeof v === 'object' && 'type' in v) {
+                    visitNodes(v, callback);
+                }
+            }
+        }
+        else if (val && typeof val === 'object' && 'type' in val) {
+            visitNodes(val, callback);
+        }
+    }
+}
+/**
+ * 从函数体中提取 React Hooks（use 开头的函数调用）
+ */
+function extractHooksFromBody(fn) {
+    const seen = new Set();
+    const body = fn.body;
+    if (!body || !bt.isBlockStatement(body))
+        return [];
+    visitNodes(body, (n) => {
+        if (bt.isCallExpression(n)) {
+            const callee = n.callee;
+            if (bt.isIdentifier(callee) && callee.name.startsWith('use')) {
+                seen.add(callee.name);
+            }
+        }
+    });
+    return [...seen].sort();
+}
+/**
+ * 获取节点的文本表示（通过 AST 节点属性构建）
+ */
+function getNodeText(n) {
+    const node = n;
+    if (!node || typeof node !== 'object')
+        return '';
+    const type = node.type;
+    if (type === 'MemberExpression' || type === 'OptionalMemberExpression') {
+        const obj = getNodeText(node.object);
+        const propNode = node.property;
+        let prop = '';
+        if (propNode && typeof propNode === 'object') {
+            const propType = propNode.type;
+            if (propType === 'Identifier') {
+                prop = propNode.name || '';
+            }
+            else if (propType === 'Literal') {
+                prop = String(propNode.value ?? '');
+            }
+        }
+        const computed = node.computed;
+        return obj + (computed ? `[${prop}]` : `.${prop}`);
+    }
+    if (type === 'Identifier') {
+        return node.name || '';
+    }
+    if (type === 'Literal' || type === 'NullLiteral') {
+        const val = node.value;
+        return val === null ? 'null' : String(val);
+    }
+    if (type === 'CallExpression' || type === 'OptionalCallExpression') {
+        const callee = getNodeText(node.callee);
+        return callee + '(...)';
+    }
+    if (type === 'AssignmentExpression') {
+        const left = getNodeText(node.left);
+        return left + ' = ...';
+    }
+    return '';
+}
+/**
+ * 静态分析函数体的副作用
+ */
+function extractSideEffects(fn) {
+    const effects = new Set();
+    const body = fn.body;
+    if (!body || !bt.isBlockStatement(body))
+        return [];
+    const paramNames = new Set(fn.params
+        .filter((p) => bt.isIdentifier(p))
+        .map((p) => p.name));
+    visitNodes(body, (n) => {
+        // 1. 网络请求
+        if (bt.isCallExpression(n)) {
+            const calleeText = n.callee && 'name' in n.callee
+                ? n.callee.name
+                : '';
+            const calleeTextLower = calleeText.toLowerCase();
+            if (calleeTextLower === 'fetch' ||
+                calleeTextLower === 'axios' ||
+                calleeTextLower === 'xhr' ||
+                calleeTextLower === 'ajax' ||
+                calleeText.startsWith('axios.') ||
+                calleeTextLower.includes('request')) {
+                effects.add('network');
+            }
+            if (calleeTextLower.includes('xmlhttprequest')) {
+                effects.add('network');
+            }
+        }
+        // 2. 计时器
+        if (bt.isCallExpression(n)) {
+            const calleeName = n.callee && 'name' in n.callee
+                ? n.callee.name
+                : '';
+            if (calleeName === 'setTimeout' ||
+                calleeName === 'setInterval' ||
+                calleeName === 'requestAnimationFrame' ||
+                calleeName === 'setImmediate') {
+                effects.add('timer');
+            }
+        }
+        // 3. DOM/全局对象操作
+        if (bt.isExpressionStatement(n)) {
+            const text = getNodeText(n.expression);
+            if (/\bdocument\.\w+/.test(text) ||
+                /\bwindow\.\w+/.test(text) ||
+                /\bnavigator\.\w+/.test(text) ||
+                /\blocation\.\w+/.test(text)) {
+                if (/=/.test(text) &&
+                    !text.includes('===') &&
+                    !text.includes('==')) {
+                    effects.add('dom');
+                }
+            }
+        }
+        // 4. 存储操作
+        if (bt.isCallExpression(n)) {
+            const text = getNodeText(n);
+            if (text.includes('localStorage') ||
+                text.includes('sessionStorage') ||
+                text.includes('cookie')) {
+                effects.add('storage');
+            }
+        }
+        // 5. 入参修改
+        if (bt.isAssignmentExpression(n)) {
+            const leftText = getNodeText(n.left);
+            for (const param of paramNames) {
+                if (leftText.startsWith(`${param}.`) ||
+                    leftText.startsWith(`${param}[`)) {
+                    effects.add('mutation');
+                    break;
+                }
+            }
+        }
+        if (bt.isCallExpression(n) && n.callee) {
+            const calleeText = getNodeText(n.callee);
+            for (const param of paramNames) {
+                if (calleeText.startsWith(`${param}.`) ||
+                    calleeText.startsWith(`${param}[`)) {
+                    // 检测 push/pop/splice 等 mutations
+                    if (/\.(push|pop|shift|unshift|splice|sort|reverse|fill)\(/.test(calleeText)) {
+                        effects.add('mutation');
+                        break;
+                    }
+                }
+            }
+        }
+    });
+    return [...effects].sort();
+}

package/dist/indexer/extractMeta.js

@@ -87,6 +87,7 @@ export function extractFunctionMeta(fn) {
     const returnType = extractReturnTypeText(fn);
     const sideEffects = extractSideEffects(fn);
     return {
+        kind: 'function',
         params,
         ...(paramTypeFields.length ? { paramTypeFields } : {}),
         ...(hooks.length ? { hooks } : {}),
@@ -116,6 +117,7 @@ export function extractInterfaceOrTypeMeta(node) {
     if (Node.isTypeAliasDeclaration(node)) {
         return { kind: 'typeAlias' };
     }
+    // 其他类型（如 enum）暂不处理，标记为 unknown 以供后续扩展。
     return { kind: 'unknown' };
 }
 /**
@@ -166,7 +168,9 @@ export function extractSideEffects(node) {
                 /\bnavigator\.\w+/.test(text) ||
                 /\blocation\.\w+/.test(text)) {
                 // 区分读取和写入
-                if (/=/.test(text) && !text.includes('===') && !text.includes('==')) {
+                if (/=/.test(text) &&
+                    !text.includes('===') &&
+                    !text.includes('==')) {
                     effects.add('dom');
                 }
             }
@@ -199,7 +203,8 @@ export function extractSideEffects(node) {
                 const text = n.getText();
                 // 检测 param.x = ... 或 param.push/pop/splice 等
                 for (const param of paramNames) {
-                    if (text.includes(`${param}.`) || text.startsWith(`${param} =`)) {
+                    if (text.includes(`${param}.`) ||
+                        text.startsWith(`${param} =`)) {
                         effects.add('mutation');
                         break;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lorrylurui/code-intelligence-mcp",
-    "version": "1.1.14",
+    "version": "1.1.15",
     "private": false,
     "description": "MCP server 提供仓库内可复用代码块（ts/tsx/js/jsx/css/less）的索引和查询能力，支持基于代码上下文的智能推荐。",
     "type": "module",