devlake-mcp 0.4.8

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

DevLake MCP

DevLake MCP 是一个 AI 编程数据采集工具，用于统计 AI 出码率和研发效率指标。支持两种工作模式：

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

✨ 核心特性

• 🎯 自动采集 - 无需手动操作，IDE Hooks 自动记录 AI 编程数据
• 📊 AI 出码率统计 - 精确计算 AI 生成代码在最终提交中的占比
• 🔄 智能重试 - 失败请求自动重试，指数退避策略，数据不丢失
• 🚀 异步执行 - 后台运行，不阻塞 IDE 操作
• 🔧 双模式支持 - Hooks（自动）+ MCP（主动调用）
• 🌐 跨 IDE 支持 - Claude Code、Cursor、Claude Desktop 等

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)
============================================================

⚙️ 环境配置

点击展开详细配置选项

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

# API 请求超时时间（秒，默认 7 秒）
export DEVLAKE_TIMEOUT=7

# HTTP 请求失败后自动重试次数（默认 1 次）
export DEVLAKE_HTTP_RETRY_COUNT=1

# ============================================================
# Hooks 配置（可选）
# ============================================================
# Hook 执行超时时间（秒，默认 15 秒）
# 所有 hooks (SessionStart, Stop, UserPromptSubmit 等) 统一使用此超时值
export DEVLAKE_HOOK_TIMEOUT=15

# ============================================================
# Git 配置（必需）
# ============================================================
# 确保 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）
export DEVLAKE_MCP_CONSOLE_LOG=false     # 是否输出到控制台（默认 false，仅开发调试时启用）

# ============================================================
# 重试配置（可选）
# ============================================================
export DEVLAKE_RETRY_ENABLED=true           # 启用/禁用重试（默认 true）
export DEVLAKE_RETRY_MAX_ATTEMPTS=5         # 最大重试次数（默认 5）
export DEVLAKE_RETRY_CLEANUP_DAYS=7         # 失败记录保留天数（默认 7）
export DEVLAKE_RETRY_CHECK_ON_HOOK=true     # Hook 执行时自动检查重试（默认 true）

---

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

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

Claude Code Hooks

一键初始化

# 自动配置 .claude/settings.json
# 如果已有配置，将智能合并 hooks 部分（保留您的现有配置）
devlake-mcp init

# 强制完全覆盖已有配置（不推荐，将丢失现有配置）
devlake-mcp init --force

智能合并说明：

• ✅ 自动检测现有 settings.json 配置
• ✅ 仅添加或更新 hooks 部分
• ✅ 完全保留您的其他配置（如 mcpServers、permissions、statusLine 等）
• ✅ 如果 DevLake hooks 已配置，则跳过无需更新
• ⚠️ 使用 --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 集成文档 了解完整配置和使用指南。

---

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 调用失败时，失败记录自动保存到本地队列（~/.devlake/retry_queue.json），按指数退避策略自动重试：

重试次数	等待时间	累计时间
第 1 次	1 分钟	1 分钟
第 2 次	5 分钟	6 分钟
第 3 次	15 分钟	21 分钟
第 4 次	60 分钟	81 分钟
第 5 次	4 小时	~5.5 小时

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

队列管理命令

# 查看失败队列状态和统计
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-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 在特殊场景下主动记录

---

📚 相关文档

项目文档

• 文档中心 - 完整的文档索引和导航
• 架构设计 - 完整的架构设计和技术方案
• 开发指南 - 开发者指南和最佳实践
• Cursor 集成 - Cursor Hooks 详细配置指南
• MCP 工具指南 - MCP 工具调用规范
• 更新日志 - 版本更新记录
• 贡献指南 - 如何为项目贡献代码

外部资源

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

---

⚠️ 前置要求

Git 配置（必需）

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

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

# 配置仓库远程地址（用于识别项目）
git remote add origin <repository-url>

Python 环境

• Python 3.9+（Hooks 模式）
• Python 3.10+（完整功能，包括 MCP Server）
• 建议使用 pipx 进行全局安装

---

🐛 故障排查

点击查看常见问题解决方案

Hook 未执行

1. 检查配置文件：.claude/settings.json 或 .cursor/hooks.json
2. 查看日志：tail -f ~/.devlake/logs/devlake_mcp.log
3. 验证 Python 路径：which python3
4. 重新初始化：devlake-mcp init --force

API 调用失败

1. 检查网络：curl http://devlake.test.chinawayltd.com
2. 查看重试队列：devlake-mcp queue-status
3. 手动重试：devlake-mcp retry
4. 检查环境变量：echo $DEVLAKE_BASE_URL

数据未上传

1. 检查 Git 配置：git config user.name 和 git config user.email
2. 启用调试日志：export DEVLAKE_MCP_LOG_LEVEL=DEBUG
3. 查看完整日志：cat ~/.devlake/logs/devlake_mcp.log

Session ID 混乱

1. 清理状态文件：rm -rf ~/.devlake/sessions/*
2. 重启 IDE
3. 重新开始会话

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📄 许可证

MIT License