devlake-mcp

DevLake MCP

DevLake MCP 是一个 AI 编程数据采集工具，通过 IDE Hooks 自动采集 AI 编程数据，用于统计 AI 出码率和研发效率指标。

支持三种 IDE：Claude Code、Cursor、Codex CLI

✨ 核心特性

• 🎯 自动采集 - 无需手动操作，IDE Hooks 自动记录 AI 编程数据
• 📊 AI 出码率统计 - 精确计算 AI 生成代码在最终提交中的占比
• 🔄 智能重试 - 失败请求自动重试，指数退避策略，数据不丢失
• 🚀 异步执行 - 后台运行，不阻塞 IDE 操作
• 🌐 多 IDE 支持 - Claude Code、Cursor、Codex CLI 全覆盖
• 🛡️ Context Guardian - Claude Code 上下文 token 分级告警 + Opus 切换提示 + 长空闲提醒 + 状态栏展示（详见文档）

Python 版本要求

Python 3.9+ 即可使用全部功能。

📦 安装

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

# 或使用 pip
pip install devlake-mcp

# 验证安装
devlake-mcp --version

⚙️ 环境配置

点击展开详细配置选项

# ============================================================
# API 配置（可选）
# ============================================================
export DEVLAKE_BASE_URL="http://devlake.test.chinawayltd.com"
export DEVLAKE_TIMEOUT=15
export DEVLAKE_HTTP_RETRY_COUNT=1

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

# ============================================================
# 日志配置（可选）
# ============================================================
export DEVLAKE_MCP_LOGGING_ENABLED=true
export DEVLAKE_MCP_LOG_LEVEL=INFO
export DEVLAKE_MCP_CONSOLE_LOG=false  # 仅开发调试时启用

# ============================================================
# 重试配置（可选）
# ============================================================
export DEVLAKE_RETRY_ENABLED=true
export DEVLAKE_RETRY_MAX_ATTEMPTS=5
export DEVLAKE_RETRY_CLEANUP_DAYS=7
export DEVLAKE_RETRY_CHECK_ON_HOOK=true

🔌 Claude Code Hooks

一键初始化

# 自动配置 ~/.claude/settings.json（智能合并，保留现有配置）
devlake-mcp init

# 项目级配置（仅当前项目）
devlake-mcp init --project

# 强制覆盖（不推荐）
devlake-mcp init --force

支持的 Hooks

Hook	触发时机	功能
SessionStart	会话启动	创建 session 记录
UserPromptSubmit	用户提交 prompt	记录用户输入
PreToolUse	工具使用前	缓存文件变更前状态
PostToolUse	工具使用后	上传文件变更（diff）
Stop	AI 循环停止	更新会话统计
StopFailure	AI 因 API 错误结束	记录错误类型和错误详情
SessionEnd	会话结束	上传完整 transcript

技术特点

• ✅ 使用 Claude Code 原生 session_id，无需额外管理
• ✅ 自动检测会话超时（30 分钟）
• ✅ 异步上传，不阻塞 IDE 操作

🖱️ Cursor Hooks

一键初始化

# 自动配置 ~/.cursor/hooks.json
devlake-mcp init-cursor

# 项目级配置
devlake-mcp init-cursor --project

# 强制覆盖
devlake-mcp init-cursor --force

支持的 Hooks（20 个）

类别	Hook	功能
会话	sessionStart / sessionEnd	创建/结束会话，sessionEnd 自动上传 transcript
Prompt	beforeSubmitPrompt / afterAgentResponse / afterAgentThought	记录输入、响应和 AI 思考过程
工具追踪	preToolUse / postToolUse / postToolUseFailure	通用工具调用前后的文件变更追踪
文件操作	beforeReadFile / afterFileEdit	Agent 文件读写追踪
Tab 补全	beforeTabFileRead / afterTabFileEdit	Tab 内联补全写入的代码采集
Shell	beforeShellExecution / afterShellExecution	Shell 命令产生的文件变更
MCP 工具	beforeMCPExecution / afterMCPExecution	MCP 工具调用日志
子 Agent	subagentStart / subagentStop	子 Agent 生命周期日志
其他	preCompact / stop	上下文压缩监控、会话循环结束

技术特点

• ✅ 使用 Cursor 原生 conversation_id 作为 session_id
• ✅ generation_id 关联同一次 AI 生成的多个文件变更
• ✅ 区分 Agent 编辑（FileEdit）和 Tab 补全（TabEdit）两种来源
• ✅ 精确工作目录定位（workspace_roots）
• ✅ sessionEnd 自动上传 transcript JSONL

⚡ Codex CLI Hooks

一键初始化

# 自动配置 ~/.codex/hooks.json 并开启 Codex hooks feature
devlake-mcp init-codex

支持的 Hooks

Hook	触发时机	功能
session_start	会话启动	创建 session 记录（ide_type=codex）
user_prompt_submit	用户提交 prompt	记录用户输入
stop	AI 完成回复	PATCH 补全 prompt 记录，同步 transcript

🔄 Transcript 同步

所有 IDE 的 transcript 文件会在会话结束时自动上传。也可以手动扫描并补传缺失的 transcript：

# 扫描并上传（Claude Code + Cursor + Codex 全部）
devlake-mcp sync

# 预览模式，只扫描不上传
devlake-mcp sync --dry-run

# 强制重传（忽略缓存）
devlake-mcp sync --force

扫描路径：

• Claude Code：~/.claude/projects*/**/*.jsonl
• Cursor：~/.cursor/projects/*/agent-transcripts/*.jsonl
• Codex：~/.codex/sessions/**/*.jsonl

🔄 失败重试机制

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

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

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

CLI 命令总览

# Hooks 初始化
devlake-mcp init                  # Claude Code 全局配置
devlake-mcp init --project        # Claude Code 项目配置
devlake-mcp init-cursor           # Cursor 全局配置
devlake-mcp init-cursor --project # Cursor 项目配置
devlake-mcp init-codex            # Codex 全局配置

# Transcript 同步
devlake-mcp sync                  # 扫描并上传缺失 transcript
devlake-mcp sync --dry-run        # 预览模式
devlake-mcp sync --force          # 强制重传

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

# 版本信息
devlake-mcp --version
devlake-mcp info
devlake-mcp --help

⚠️ 前置要求

Git 配置（必需）

git config user.name "Your Name"
git config user.email "[e-mail]"
git remote add origin <repository-url>

🐛 故障排查

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

Hook 未执行

• 检查配置：.claude/settings.json 或 ~/.cursor/hooks.json
• 查看日志：tail -f ~/.devlake/logs/claude_hooks.log（或 cursor_hooks.log）
• 验证 Python：macOS/Linux 用 which python3，Windows 用 where python 或 py -0p
• 检查 hook command 是否可执行，必要时重新初始化：devlake-mcp init --force

API 调用失败

• 检查网络：curl $DEVLAKE_BASE_URL
• 查看重试队列：devlake-mcp queue-status
• 手动重试：devlake-mcp retry

数据未上传

• 检查 Git 配置：git config user.name
• 启用调试日志：export DEVLAKE_MCP_LOG_LEVEL=DEBUG
• 查看日志：cat ~/.devlake/logs/claude_hooks.log

📚 相关文档

• 架构设计
• Cursor 集成
• 更新日志

📄 许可证

MIT License