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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

devlake_mcp-0.5.10.tar.gz (152.1 kB view details)

Uploaded Jul 1, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

devlake_mcp-0.5.10-py3-none-any.whl (196.9 kB view details)

Uploaded Jul 1, 2026 Python 3

File details

Details for the file devlake_mcp-0.5.10.tar.gz.

File metadata

Download URL: devlake_mcp-0.5.10.tar.gz
Upload date: Jul 1, 2026
Size: 152.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.8

File hashes

Hashes for devlake_mcp-0.5.10.tar.gz
Algorithm	Hash digest
SHA256	`2970ba3826e3da08fdbd5070a046216f31aef58926f6e9427614b0fc3fda155e`
MD5	`172887d1b3c3f4ba4817140b2a22591e`
BLAKE2b-256	`9e063e29d5e6f8ebfc40137391e2ec5cf569873c6d6bb4d41bab5b9b89bb1635`

See more details on using hashes here.

File details

Details for the file devlake_mcp-0.5.10-py3-none-any.whl.

File metadata

Download URL: devlake_mcp-0.5.10-py3-none-any.whl
Upload date: Jul 1, 2026
Size: 196.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.8

File hashes

Hashes for devlake_mcp-0.5.10-py3-none-any.whl
Algorithm	Hash digest
SHA256	`c5a4a96f7b2c9773b3ec81631eb8b74909ccede7806026c5c4c436626b002006`
MD5	`b222ac846ba5b3b31852bfdf311e3a7e`
BLAKE2b-256	`78915227e242d85ea2d5550c4ea81be67faac0a12eca84c18b4d25ad78e2c390`