ai-auto-collection

v0.2.7

Published

a month ago

MCP tool for collecting AI file modification evidence

0High
0Medium
0Low

toecrash

mcp ai code-collection

ai-auto-collection

本地 MCP 工具，用于采集 AI 会话中对文件的修改证据并上报。

项目地址：https://git.example.com/group/ai-report-mcp

快速理解：整体架构与配置流程

核心关系

安装 MCP 采集器 → 配置 IDE 的 MCP → 验证 MCP 启动 → 配置 Rule/Hook → 查看采集数据

MCP 采集器（本地运行）
- 本质：Node.js 服务，监听 AI 工具的调用请求
- 作用：接收 AI 会话中的文件修改证据，批量上报到收集器
- 安装：执行对应操作系统的安装脚本
IDE MCP 配置（让 IDE 能调用采集器）
- Cursor/VSCode/JetBrains 需要在各自配置文件中注册 MCP 服务
- 配置后 IDE 启动时会自动拉起 MCP 进程
Rule vs Hook（两种触发方式）
- Hook：Git Hook，在代码提交时自动触发采集（推荐）
- Rule：AI 行为规约，依赖 AI 主动调用采集工具（备用方案）
- 优先级：Hook > Rule，Hook 不生效时再用 Rule
数据查看
- 访问 https://collector.example.com/#/
- 联系管理员索要账密登录

操作系统与 IDE 选择指南

| 场景 | 推荐方案 | 说明 | |------|---------|------| | Windows / macOS / Ubuntu 原生 | Hook（任意 IDE） | Hook 完全支持，采集最完整 | | WSL / Linux 远程开发 | 优先 Hook，不生效则 Rule | WSL 中 Hook 可能因路径问题不生效，需降级为 Rule | | IDEA / PyCharm 等 JetBrains | Rule + MCP | JetBrains 对 Hook 支持有限，依赖 Rule 触发 | | Cursor / VSCode / Copilot | Hook + MCP | 完整支持 Hook，采集最准确 |

为什么 Hook 不生效时要改用 Rule？

WSL/Linux 中，Git Hook 的路径映射可能失败，导致无法触发
Hook 不生效时，Rule 作为备用方案确保采集不中断
代价：Rule 依赖 AI 主动调用，可能丢失部分未触发的修改记录

环境要求

Node.js 18+
Git（已克隆可忽略）
公司邮箱（配置 MCP 和 Hook 时必须使用）

推荐：一键安装 / 更新 / 发布

用户只需要提供邮箱和上报地址。安装器会自动写入 MCP、Hook、JetBrains Copilot 全局规则和 Codex 配置，安装后重启对应 IDE / Agent 客户端即可。

用户安装

macOS / Linux / WSL：

[email protected] \
AI_AUTO_COLLECTION_COLLECTOR_ENDPOINT=https://collector.example.com/api/v1/mcp/batch \
AI_AUTO_COLLECTION_PACKAGE_SPEC=ai-auto-collection \
npm install -g ai-auto-collection

Windows PowerShell：

$env:AI_AUTO_COLLECTION_USER_EMAIL="[email protected]"
$env:AI_AUTO_COLLECTION_COLLECTOR_ENDPOINT="https://collector.example.com/api/v1/mcp/batch"
$env:AI_AUTO_COLLECTION_PACKAGE_SPEC="ai-auto-collection"
npm install -g ai-auto-collection

如果 npm 不能直接拉 Git URL，改用 clone 产物分支。

macOS / Linux / WSL：

git clone -b release/latest https://git.example.com/group/ai-report-mcp.git
cd ai-report-mcp
[email protected] \
AI_AUTO_COLLECTION_COLLECTOR_ENDPOINT=https://collector.example.com/api/v1/mcp/batch \
AI_AUTO_COLLECTION_PACKAGE_SPEC=ai-auto-collection \
npm install -g .

Windows PowerShell：

git clone -b release/latest https://git.example.com/group/ai-report-mcp.git
cd ai-report-mcp
$env:AI_AUTO_COLLECTION_USER_EMAIL="[email protected]"
$env:AI_AUTO_COLLECTION_COLLECTOR_ENDPOINT="https://collector.example.com/api/v1/mcp/batch"
$env:AI_AUTO_COLLECTION_PACKAGE_SPEC="ai-auto-collection"
npm install -g .

用户更新

ai-auto-collection update

修改邮箱或上报地址

ai-auto-collection config --email [email protected]
ai-auto-collection config --collector-endpoint http://new-host:8081/api/v1/mcp/batch

检查安装

ai-auto-collection doctor

卸载集成配置

先移除本工具写入各 IDE / Agent 的 MCP、Hook、规则和插件配置：

ai-auto-collection uninstall --all

再卸载 npm 全局包：

npm uninstall -g ai-auto-collection

发布新版本

在 main 分支开发，发布时推送编译后的产物分支 release/latest。下面命令在 macOS / Linux / Windows PowerShell 通用，GitLab remote 使用 HTTPS：

git remote set-url origin https://git.example.com/group/ai-report-mcp.git
npm install
npm run release:git -- --branch release/latest --remote origin

发布脚本会执行 npm run build，只把可运行产物复制到 release/latest：package.json、package-lock.json、dist/、运行所需 scripts/、README。用户安装 release/latest，不安装 main，也不需要本地编译 TypeScript。

自动配置范围：

Cursor MCP：~/.cursor/mcp.json
VSCode MCP：用户目录 mcp.json
VSCode Copilot Hook：~/.github/hooks/ai-auto-collection-hook.json
JetBrains Copilot MCP + 全局规则：github-copilot/intellij/mcp.json、github-copilot/intellij/global-copilot-instructions.md
Codex MCP + Hook：~/.codex/config.toml、~/.codex/hooks.json
Claude Code / Cursor Hook：~/.claude/settings.json
OpenCode Hook：~/.config/opencode/opencode.json

安装步骤

下面是历史手工安装流程，适用于需要从源码仓库调试或手工排查的场景。普通用户优先使用上面的 npm 一键安装流程。

第一步：安装 MCP 采集器

Windows

# 1. 克隆仓库
git clone https://git.example.com/group/ai-report-mcp.git
cd ai-report-mcp

# 2. 以管理员身份打开 PowerShell，执行安装脚本
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
.\win\install-mcp\install.ps1

macOS

git clone https://git.example.com/group/ai-report-mcp.git
cd ai-report-mcp

chmod +x ./mac/install-mcp/install-mac.sh
./mac/install-mcp/install-mac.sh
# 可选参数：--non-interactive | --force | --clean

CentOS 7

git clone https://git.example.com/group/ai-report-mcp.git
cd ai-report-mcp

chmod +x ./centos/install-mcp/install-centos7.sh
./centos/install-mcp/install-centos7.sh

Ubuntu（原生，非 WSL）

git clone https://git.example.com/group/ai-report-mcp.git
cd ai-report-mcp

chmod +x ./Ubuntu/install-mcp/install-ubuntu.sh
./Ubuntu/install-mcp/install-ubuntu.sh
# 可选参数：--non-interactive | --force | --clean | --collector-endpoint | --batch-size

详见 Ubuntu/install-mcp/README.md。

WSL

git clone https://git.example.com/group/ai-report-mcp.git
cd ai-report-mcp

chmod +x ./wsl/install-mcp/install-wsl.sh
./wsl/install-mcp/install-wsl.sh

手动安装（可选）

npm install
npm run build

产物为 dist/index.js，后续 MCP 配置需使用此路径。

第二步：配置 IDE 的 MCP

重要：将路径 D:\your-path\ai-report-mcp 替换为实际仓库路径，[email protected] 替换为公司邮箱。

IDEA / PyCharm 等（JetBrains）

{
  "servers": {
    "ai-auto-collection": {
      "type": "stdio",
      "command": "node",
      "args": ["D:\\your-path\\ai-report-mcp\\dist\\index.js"],
      "cwd": "D:\\your-path\\ai-report-mcp",
      "env": {
        "USER_EMAIL": "[email protected]",
        "BATCH_SIZE": "10",
        "COLLECTOR_ENDPOINT": "https://collector.example.com/api/v1/mcp/batch"
      }
    }
  }
}

VSCode

{
  "servers": {
    "ai-auto-collection": {
      "command": "node",
      "args": ["D:\\your-path\\ai-report-mcp\\dist\\index.js"],
      "env": {
        "USER_EMAIL": "[email protected]",
        "BATCH_SIZE": "10",
        "COLLECTOR_ENDPOINT": "https://collector.example.com/api/v1/mcp/batch"
      }
    }
  }
}

Cursor

{
  "servers": {
    "ai-auto-collection": {
      "command": "node",
      "args": ["D:\\workspace\\ai-report-mcp\\dist\\index.js"],
      "env": {
        "USER_EMAIL": "[email protected]",
        "BATCH_SIZE": "10",
        "COLLECTOR_ENDPOINT": "https://collector.example.com/api/v1/mcp/batch"
      }
    }
  }
}

配置后重启 IDE。

第三步：验证 MCP 是否成功启动

配置完成后，打开 IDE 并检查：

IDE 输出面板：查看是否有 MCP 启动日志
MCP 状态：确认 MCP 服务显示为 "Running" 或 "Connected"
日志文件：检查 ~/.cursor/logs/ 或对应 IDE 日志目录

如未成功启动，参考 troubleshooting/README.md 排查。

第四步：配置 Rule 或 Hook

方案 A：配置 Hook（推荐，采集最完整）

按使用工具选一种，在仓库根目录执行。

| 方案 | 适用 | Windows | macOS / Linux | |------|------|---------|----------------| | VSCode Hook | 项目级，每项目配一次 | .\win\install-hook\vscode\install-hooks-vscode-win.ps1 或双击 .bat | chmod +x ./mac/install-hook/vscode/install-hooks-vscode-mac.sh 后执行 | | Cursor / Claude Hook | 用户级，全局一次 | 双击 win\install-hook\cursor\install-cursor-claude-win.bat 或执行对应 .ps1 | chmod +x ./mac/install-hook/cursor/install-cursor-claude-mac.sh 后执行 | | OpenCode Hook | 用户级，全局一次 | 双击 win\install-hook\opencode\install-hooks-opencode-win.bat 或执行对应 .ps1 | chmod +x ./mac/install-hook/opencode/install-hooks-opencode-mac.sh 后执行 |

安装说明：

VSCode：按提示输入业务项目根目录、本仓库路径；生成 .github/hooks/ai-auto-collection-hook.json
Cursor/Claude：按提示输入本仓库路径、Collector 地址、公司邮箱；写入 ~/.claude/hooks/
OpenCode：按提示输入本仓库路径、Collector 地址、公司邮箱；安装后需重启 OpenCode

注意：安装 Hook 前请先执行 npm run build。

方案 B：配置 Rule（Hook 不生效时的备用方案）

使用统一规约文件 INSTRUCTIONS.md（适用于 Cursor、VSCode、Copilot、IDEA、PyCharm 等）。

| 环境 | 做法 | |------|------| | Cursor | Settings → Cursor Settings → Features → Rules for AI，粘贴 INSTRUCTIONS.md 内容；或项目根目录创建 .cursorrules 并粘贴。 | | VSCode | 项目根目录创建 .github/copilot-instructions.md，粘贴 INSTRUCTIONS.md 内容。 | | IDEA / PyCharm 等（JetBrains） | 全局 Rule：Copilot → Agent → Configure Agents… → settings → GitHub Copilot → Customizations → Global，粘贴 INSTRUCTIONS.md 全文。 |

重要：

依靠 RULE 采集的 IDE（IDEA、PyCharm 等）：需先完成 第二步（配置 MCP） 并确认 MCP 可用后，再配置本全局 Rule
修改后重启对应 IDE
如果使用较新的 GitHub Copilot / JetBrains Copilot，手工调用 beforeEditFile / afterEditFile 时优先使用 targets 字段，不要再传 filePath: []；新版本客户端对数组路径参数存在兼容性问题。

升级采集器

当采集器仓库有新功能或修复时，客户端按下面步骤升级即可生效。

1. 更新仓库代码

在本仓库根目录执行：

git pull

如果本地还有未提交改动，先自行处理冲突或暂存后再执行 git pull。

2. 重新安装依赖（可选）

一般只有依赖变化时才需要执行：

npm install

3. 重新构建采集器

npm run build

构建完成后，IDE 实际启动的 dist/index.js 才会更新；如果只 git pull 不重建，新功能不会生效。

4. 如使用 Hook，建议重新执行一次 Hook 安装脚本

如果本次更新包含 scripts/、win/install-hook/、mac/install-hook/、Ubuntu/install-hook/、wsl/install-hook/ 下的变更，建议重新执行你当前使用的 Hook 安装脚本，确保本地 hook 脚本同步到最新版本。

例如：

.\win\install-hook\vscode\install-hooks-vscode-win.ps1

或 macOS / Linux：

./mac/install-hook/vscode/install-hooks-vscode-mac.sh

5. 重启 IDE

必须完全关闭并重新打开当前 IDE / Agent 客户端，让它重新拉起 MCP 进程。

适用场景包括：

VSCode
Cursor
GitHub Copilot（JetBrains / VSCode）
IDEA / PyCharm
OpenCode / Claude Code

如果不重启，IDE 很可能还在使用旧的 MCP 进程，更新不会生效。

6. 验证是否生效

可以通过以下方式确认：

IDE 的 MCP 面板或日志中，看到新启动的 MCP 进程
仓库根目录重新执行测试：

npm run test:tools

重新触发一次实际采集，确认新字段或新行为已经出现

最短升级命令可以直接按下面执行：

git pull
npm install
npm run build

然后重启 IDE；如果本次更新涉及 hook 脚本，再补执行一次对应的 hook 安装脚本。

查看采集数据

访问：https://collector.example.com/#/
使用公司邮箱登录
进入 "MCP 数据列表" 查看采集记录

故障排查

安装或运行异常（如 spawn node ENOENT）可参考：

troubleshooting/README.md
Windows 环境检查：.\troubleshooting\check-mcp-env.ps1（可选 -FixPath 输出 PATH 建议）

常见问题

Q: Hook 安装后不生效？

WSL/Linux 用户：尝试改用 Rule 方案
检查 Hook 脚本是否有执行权限：chmod +x
确认 dist/index.js 存在（执行过 npm run build）

Q: MCP 在 IDE 中未启动？

检查 Node.js 版本：node -v（需 18+）
检查配置文件路径是否正确
查看 IDE 日志确认错误信息

Q: 数据采集不完整？

Hook 方案：确认 Git Hook 触发正常
Rule 方案：依赖 AI 主动调用，可能遗漏，建议改用 Hook

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ai-auto-collection

快速理解：整体架构与配置流程

核心关系

操作系统与 IDE 选择指南

环境要求

推荐：一键安装 / 更新 / 发布

用户安装

用户更新

修改邮箱或上报地址

检查安装

卸载集成配置

发布新版本

安装步骤

第一步：安装 MCP 采集器

Windows

macOS

CentOS 7

Ubuntu（原生，非 WSL）

WSL

手动安装（可选）

第二步：配置 IDE 的 MCP

IDEA / PyCharm 等（JetBrains）

VSCode

Cursor

第三步：验证 MCP 是否成功启动

第四步：配置 Rule 或 Hook

方案 A：配置 Hook（推荐，采集最完整）

方案 B：配置 Rule（Hook 不生效时的备用方案）

升级采集器

1. 更新仓库代码

2. 重新安装依赖（可选）

3. 重新构建采集器

4. 如使用 Hook，建议重新执行一次 Hook 安装脚本

5. 重启 IDE

6. 验证是否生效

查看采集数据

故障排查

常见问题