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 "your.email@example.com"

# ============================================================
# 日志配置（可选）
# ============================================================
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 "your.email@example.com"
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

📚 相关文档

📄 许可证

MIT License

Metadata

Release files for devlake-mcp 0.5.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for devlake-mcp 0.5.10
File	Size	Uploaded
devlake_mcp-0.5.10.tar.gz	152.1 kB	Jul 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for devlake-mcp 0.5.10
File	Interpreter	ABI	Platform	Reset
devlake_mcp-0.5.10-py3-none-any.whl 196.9 kB Jul 1, 2026	Python 3	none	any	Details

Total release size: 349.0 kB

Release files / devlake_mcp-0.5.10.tar.gz

Download URL	devlake_mcp-0.5.10.tar.gz
Size	152.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`2970ba3826e3da08fdbd5070a046216f31aef58926f6e9427614b0fc3fda155e`
BLAKE2b-256 checksum How to use checksums	`9e063e29d5e6f8ebfc40137391e2ec5cf569873c6d6bb4d41bab5b9b89bb1635`
Upload date	Jul 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.8`

Release files / devlake_mcp-0.5.10-py3-none-any.whl

Download URL	devlake_mcp-0.5.10-py3-none-any.whl
Size	196.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c5a4a96f7b2c9773b3ec81631eb8b74909ccede7806026c5c4c436626b002006`
BLAKE2b-256 checksum How to use checksums	`78915227e242d85ea2d5550c4ea81be67faac0a12eca84c18b4d25ad78e2c390`
Upload date	Jul 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.8`