devlake-mcp 0.4.0

AI programming data collection tool - supports Hooks (Claude Code/Cursor) and MCP server modes

DevLake MCP

DevLake MCP 是一个 AI 编程数据采集工具，支持两种工作模式：

• 🔌 Hooks 模式 - 通过 IDE Hooks 自动采集 AI 编程数据（推荐日常使用）
• 🤖 MCP 模式 - 作为 MCP 服务器，让 AI 助手主动调用工具记录数据

Python 版本要求

Python 版本	Hooks 模式	MCP Server 模式
3.9.x	✅ 支持	❌ 不支持
3.10+	✅ 支持	✅ 支持

推荐使用 Python 3.10 或更高版本以获得完整功能支持。

快速安装

基础安装（Python 3.9+，仅 Hooks 模式）

# 使用 pipx 安装（推荐）
pipx install devlake-mcp

# 或使用 pip
pip install devlake-mcp

完整安装（Python 3.10+，Hooks + MCP Server）

# 使用 pipx 安装（推荐）
pipx install "devlake-mcp[mcp]"

# 或使用 pip
pip install "devlake-mcp[mcp]"

检查安装

# 查看版本号
devlake-mcp --version
# 输出: devlake-mcp 0.3.4

# 查看详细的版本和功能支持状态
devlake-mcp info

devlake-mcp info 输出示例：

============================================================
DevLake MCP - 版本信息
============================================================
DevLake MCP: v0.3.4
Python: 3.10.19

功能支持:
  - Hooks 模式: ✓
  - MCP Server: ✓ (FastMCP 2.13.0.2)
============================================================

环境配置

# 配置 DevLake API 地址（可选，默认使用测试环境）
export DEVLAKE_BASE_URL="http://devlake.test.chinawayltd.com"
export DEVLAKE_TIMEOUT=5

# 确保 Git 配置正确（必需）
git config user.name "Your Name"
git config user.email "[e-mail]"

日志配置（可选）

export DEVLAKE_MCP_LOGGING_ENABLED=true # 是否启用日志（默认 true） export DEVLAKE_MCP_LOG_LEVEL=INFO # 日志级别：DEBUG/INFO/WARNING/ERROR/CRITICAL（默认 INFO）

---

🔌 模式一：Hooks 自动采集（推荐）

Hooks 模式通过 IDE 的 Hooks 机制自动采集 AI 编程数据，无需 AI 主动调用工具，适合日常开发使用。

Claude Code Hooks

一键初始化

# 自动配置 .claude/settings.json
devlake-mcp init

# 强制覆盖已有配置
devlake-mcp init --force

支持的 Hooks

Hook	触发时机	功能
SessionStart	会话启动	创建 session 记录
UserPromptSubmit	用户提交 prompt	记录用户输入
PreToolUse	工具使用前	记录文件变更前状态
PostToolUse	工具使用后	上传文件变更（diff）
Stop	AI 循环停止	更新会话统计
SessionEnd	会话结束	上传完整会话数据

技术特点

• ✅ 使用 Claude Code 原生 session_id，无需额外管理
• ✅ 自动检测会话切换和超时（30 分钟）
• ✅ 异步上传，不阻塞 IDE 操作
• ✅ 失败自动加入重试队列

配置示例

初始化后会在 .claude/settings.json 中生成以下配置：

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "python3 -m devlake_mcp.hooks.session_start",
        "timeout": 5
      }]
    }],
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "python3 -m devlake_mcp.hooks.user_prompt_submit",
        "timeout": 5
      }]
    }],
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "python3 -m devlake_mcp.hooks.pre_tool_use",
        "timeout": 5
      }]
    }],
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "python3 -m devlake_mcp.hooks.post_tool_use",
        "timeout": 10
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "python3 -m devlake_mcp.hooks.stop",
        "timeout": 5
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "python3 -m devlake_mcp.hooks.session_end",
        "timeout": 10
      }]
    }]
  }
}

---

Cursor Hooks

一键初始化

# 自动配置 Cursor hooks
devlake-mcp init-cursor

# 强制覆盖已有配置
devlake-mcp init-cursor --force

支持的 Hooks

Hook	触发时机	功能
beforeSubmitPrompt	用户提交 prompt 前	记录用户输入
beforeReadFile	读取文件前	记录文件访问
beforeShellExecution	执行 Shell 前	记录命令信息
afterShellExecution	Shell 执行后	检测命令产生的文件变更
afterFileEdit	文件编辑后	上传文件编辑变更
afterAgentResponse	AI 回复后	记录对话内容
stop	会话结束	上传会话统计

技术特点

• ✅ 使用 Cursor 原生 conversation_id 作为 session_id
• ✅ generation_id 关联同一次 AI 生成的多个文件变更
• ✅ 自动检测 vim/nano/echo>/cp/mv 等文件操作命令
• ✅ 智能 diff 算法计算文件变更
• ✅ 与 Claude Code 完全兼容的数据格式
• ✅ 精确的工作目录定位（workspace_roots）

详细文档

查看 CURSOR_HOOKS.md 了解完整配置和使用指南。

---

Hooks 模式对比

特性	Claude Code	Cursor
Session 管理	30分钟超时机制	对话生命周期管理
文件变更追踪	✅	✅
Shell 命令检测	❌	✅
变更关联追踪	单个变更	✅ generation_id 关联
工作目录定位	手动推断	✅ workspace_roots
数据格式	原生格式	完全兼容 Claude Code

---

🤖 模式二：MCP 服务器模式

MCP 模式将 DevLake 作为 Model Context Protocol 服务器运行，基于 FastMCP 框架，让 AI 助手可以主动调用工具记录数据。

配置方式

方式 1：使用 Claude CLI（推荐）

claude mcp add devlake-mcp devlake-mcp

方式 2：手动配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或相应配置文件：

{
  "mcpServers": {
    "devlake-mcp": {
      "command": "devlake-mcp"
    }
  }
}

配置完成后重启 Claude Desktop。

可用工具

MCP 模式提供 3 个核心工具，AI 助手可以主动调用：

1. record_session

功能：记录 AI 会话的元数据和统计信息

参数：

• session_id (string, 可选)：会话 ID，不提供则自动生成 UUID
• metadata (dict, 可选)：会话元数据
  • user_intent：用户意图描述
  • model：模型名称（如 "claude-sonnet-4-5"）
  • ide：IDE 类型（如 "cursor", "claude-code"）
  • project_path：项目路径

返回示例：

{
  "success": true,
  "session_id": "uuid-xxx",
  "timestamp": "2025-01-07T10:00:00Z",
  "git_info": {
    "git_repo_path": "yourorg/devlake",
    "git_branch": "main",
    "git_author": "Your Name"
  }
}

使用示例：

调用 record_session 工具，metadata 设置为 {"ide": "cursor", "model": "claude-sonnet-4-5"}

---

2. before_edit_file

功能：在文件变更前调用，记录文件的当前状态（快照）

参数：

• session_id (string, 必需)：会话唯一标识
• file_paths (list[string], 必需)：即将变更的文件绝对路径列表

返回示例：

{
  "success": true,
  "session_id": "session-123",
  "files_snapshot": {
    "/path/to/file.py": {
      "exists": true,
      "line_count": 100,
      "size": 2048
    }
  }
}

使用示例：

调用 before_edit_file 工具，session_id 为 "session-123"，file_paths 为 ["/path/to/file.py"]

---

3. after_edit_file

功能：在文件变更后调用，对比差异并上传变更数据到 DevLake API

参数：

• session_id (string, 必需)：会话唯一标识（与 before_edit_file 一致）
• file_paths (list[string], 必需)：已变更的文件绝对路径列表

返回示例：

{
  "success": true,
  "session_id": "session-123",
  "uploaded_count": 1,
  "changes": [
    {
      "file_path": "src/main.py",
      "change_type": "edit",
      "file_type": "py"
    }
  ]
}

工作流程：

1. before_edit_file() - 记录文件变更前状态
2. [AI 执行文件变更操作]
3. after_edit_file() - 对比差异并上传

使用示例：

调用 after_edit_file 工具，session_id 为 "session-123"，file_paths 为 ["/path/to/file.py"]

---

MCP 模式特点

• ✅ AI 主动控制：由 AI 决定何时记录数据
• ✅ 精确记录时机：在最合适的时间点调用工具
• ✅ 完整的 before/after 对比：准确的文件变更 diff
• ✅ 跨 IDE 支持：适用于任何支持 MCP 的 AI 助手
• ✅ 手动 Session 管理：AI 自行管理会话生命周期

---

失败重试机制

DevLake MCP 内置智能失败重试队列，确保数据不会因网络问题或临时故障丢失。

工作原理

当 API 调用失败时，失败记录自动保存到本地队列，按指数退避策略自动重试：

重试次数	等待时间
第 1 次	1 分钟
第 2 次	5 分钟
第 3 次	15 分钟
第 4 次	60 分钟
第 5 次	4 小时

队列管理命令

# 查看失败队列状态和统计
devlake-mcp queue-status

# 手动触发重试（不等待自动重试时间）
devlake-mcp retry

# 清理过期的失败记录（默认保留 7 天）
devlake-mcp queue-clean

配置选项

通过环境变量配置重试行为：

# 启用/禁用重试（默认 true）
export DEVLAKE_RETRY_ENABLED=true

# 最大重试次数（默认 5）
export DEVLAKE_RETRY_MAX_ATTEMPTS=5

# 失败记录保留天数（默认 7）
export DEVLAKE_RETRY_CLEANUP_DAYS=7

# Hook 执行时检查重试（默认 true）
export DEVLAKE_RETRY_CHECK_ON_HOOK=true

自动重试

当 DEVLAKE_RETRY_CHECK_ON_HOOK=true 时（默认），每次 Hook 执行时会自动检查并重试失败的记录（每次最多 3 条，避免阻塞）。

如需禁用自动重试：

export DEVLAKE_RETRY_CHECK_ON_HOOK=false

然后使用 devlake-mcp retry 手动触发。

---

CLI 命令总览

# MCP 服务器
devlake-mcp                     # 启动 MCP 服务器

# Hooks 初始化
devlake-mcp init                # 初始化 Claude Code hooks
devlake-mcp init --force        # 强制覆盖 Claude Code hooks
devlake-mcp init-cursor         # 初始化 Cursor hooks
devlake-mcp init-cursor --force # 强制覆盖 Cursor hooks

# 失败队列管理
devlake-mcp queue-status        # 查看失败队列状态
devlake-mcp retry               # 手动触发重试
devlake-mcp queue-clean         # 清理过期记录

# 版本信息
devlake-mcp --version           # 显示版本号
devlake-mcp info                # 显示详细的版本和功能支持信息
devlake-mcp --help              # 显示帮助信息

---

使用建议

选择合适的模式

场景	推荐模式	理由
日常开发	Hooks 模式	自动采集，无需关注
精确控制记录时机	MCP 模式	AI 主动决定何时记录
Claude Code	Hooks 模式	原生集成，体验最佳
Cursor	Hooks 模式	专门优化，功能最全
Claude Desktop	MCP 模式	标准 MCP 协议支持

两种模式可以共存

Hooks 模式和 MCP 模式可以同时启用：

• Hooks 模式负责自动采集日常数据
• MCP 模式让 AI 在特殊场景下主动记录

---

相关资源

• Model Context Protocol 官方文档
• FastMCP 官方文档
• FastMCP GitHub
• Claude Desktop
• Cursor 编辑器
• Cursor Hooks 详细文档

---

Git 配置要求

工具会自动从 Git 配置读取用户信息，请确保已配置：

# 配置 Git 用户信息
git config user.name "Your Name"
git config user.email "[e-mail]"

# 配置仓库远程地址
git remote add origin <repository-url>