devlake-mcp 0.3.1__tar.gz

devlake_mcp-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DevLake MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devlake_mcp-0.3.1/PKG-INFO

@@ -0,0 +1,417 @@
+Metadata-Version: 2.4
+Name: devlake-mcp
+Version: 0.3.1
+Summary: Model Context Protocol server for DevLake
+Author-email: wangzhong <wangzhong@g7.com.cn>
+License: MIT
+Project-URL: Homepage, https://git.chinawayltd.com/engineering-efficiency/devlake-mcp
+Project-URL: Repository, https://git.chinawayltd.com/engineering-efficiency/devlake-mcp
+Project-URL: Issues, https://git.chinawayltd.com/engineering-efficiency/devlake-mcp
+Keywords: mcp,devlake,model-context-protocol,ai,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=0.5.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
+Requires-Dist: responses>=0.24.0; extra == "dev"
+Requires-Dist: freezegun>=1.4.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# DevLake MCP Server
+
+一个基于 [FastMCP](https://gofastmcp.com) 框架的 DevLake MCP 服务器，允许 AI 助手（如 Claude）与 DevLake 进行交互。
+
+
+## 安装
+
+### 方式 1: 使用 pipx（推荐）
+
+pipx 会在隔离环境中安装 Python 应用程序：
+
+```bash
+# 安装 pipx（如果还没有安装）
+# macOS
+brew install pipx
+
+# Linux
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+
+# 使用 pipx 安装 devlake-mcp
+pipx install devlake-mcp
+```
+
+### 方式 2: 从源码安装
+
+```bash
+# 克隆仓库
+git clone https://github.com/yourusername/devlake-mcp.git
+cd devlake-mcp
+
+# 使用 pip 安装（开发模式）
+pip install -e .
+
+# 或使用 uv（推荐用于开发）
+uv pip install -e .
+```
+
+
+## 使用方法
+
+### CLI 命令
+
+DevLake MCP 提供了多个命令行工具：
+
+```bash
+# 启动 MCP 服务器（用于 Claude Desktop 集成）
+devlake-mcp
+
+# 初始化 Claude Code hooks 配置
+devlake-mcp init [--force]
+
+# 初始化 Cursor hooks 配置
+devlake-mcp init-cursor [--force]
+
+# 手动触发失败重试
+devlake-mcp retry
+
+# 查看失败队列状态
+devlake-mcp queue-status
+
+# 清理过期的失败记录
+devlake-mcp queue-clean
+
+# 显示版本信息
+devlake-mcp --version
+
+# 显示帮助信息
+devlake-mcp --help
+```
+
+### 与 Claude Desktop 集成
+
+```bash
+claude mcp add devlake-mcp devlake-mcp
+```
+
+### Cursor Hooks 支持
+
+DevLake MCP 现在支持 Cursor IDE！通过 Cursor hooks，可以自动采集 AI 编程数据，与 Claude Code 完全兼容。
+
+**快速安装**：
+
+```bash
+# 使用 CLI 命令安装（推荐）
+devlake-mcp init-cursor
+
+# 强制覆盖已有配置
+devlake-mcp init-cursor --force
+```
+
+**支持的 Hooks**：
+- ✅ **beforeSubmitPrompt**：用户提交 prompt 前触发，记录用户输入
+- ✅ **beforeReadFile**：读取文件前触发，记录文件访问
+- ✅ **beforeShellExecution**：执行 Shell 命令前触发，记录命令信息
+- ✅ **afterShellExecution**：Shell 命令执行后触发，检测文件变更
+- ✅ **afterFileEdit**：文件编辑后触发，上传文件变更
+- ✅ **afterAgentResponse**：AI 回复后触发，记录对话内容
+- ✅ **stop**：会话结束时触发，上传会话统计
+
+**功能特性**：
+- ✅ **原生 Cursor 集成**：直接使用 Cursor 提供的 `conversation_id` 作为 session_id，无需额外状态管理
+- ✅ **变更关联追踪**：通过 `generation_id` 关联同一次 AI 生成的多个文件变更
+- ✅ **精确工作目录**：使用 Cursor 的 `workspace_roots` 字段准确定位项目根目录
+- ✅ **文件变更记录**：自动记录 before/after diff，支持文件编辑和 Shell 命令
+- ✅ **Shell 命令支持**：智能检测 vim/nano/echo>/cp/mv 等文件操作命令
+- ✅ **与 Claude Code 完全兼容**：相同的数据格式和 API 接口
+
+**技术亮点**：
+- **简化的 Session 管理**：由 Cursor 管理对话生命周期，无需 30 分钟超时逻辑
+- **Hook 事件追踪**：记录每次变更的 `hook_event_name`（如 afterFileEdit、afterShellExecution）
+- **异步上传**：所有 API 调用异步执行，不阻塞 Cursor Agent 工作流
+- **失败重试队列**：上传失败自动加入重试队列，确保数据不丢失
+
+**详细文档**：查看 [CURSOR_HOOKS.md](CURSOR_HOOKS.md) 了解完整配置和使用指南。
+
+### Claude Code Hooks 支持
+
+DevLake MCP 支持 Claude Code 的 Hooks 机制，通过配置 `.claude/settings.json` 自动采集 AI 编程数据。
+
+**已实现的 Hooks**：
+- ✅ **SessionStart**：会话启动时记录会话信息
+- ✅ **SessionEnd**：会话结束时上传会话数据
+- ✅ **UserPromptSubmit**：用户提交 prompt 时记录用户输入
+- ✅ **PreToolUse**：工具使用前记录文件状态
+- ✅ **PostToolUse**：工具使用后上传文件变更
+- ✅ **Stop**：AI 循环停止时更新会话统计
+
+**UserPromptSubmit Hook**（新增）：
+- **触发时机**：用户点击发送按钮后、发起后端请求之前
+- **功能**：
+  - 检查并创建 session（如果是首次）
+  - 记录用户的 prompt 输入
+  - 上传到 DevLake API
+- **自动管理**：
+  - 使用 Claude Code 提供的 `session_id` 作为会话标识
+  - 自动检测会话切换
+  - 异步执行，不阻塞用户操作
+
+**配置位置**：`.claude/settings.json`
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -m devlake_mcp.hooks.user_prompt_submit",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**技术特点**：
+- **静默失败**：Hook 执行失败不影响 Claude Code 正常工作
+- **失败重试**：上传失败自动保存到重试队列
+- **会话管理**：自动管理会话状态，检测会话切换
+
+
+## 环境变量配置
+
+在使用前，需要配置 DevLake API 连接信息。
+
+### 方式 1: 使用 .env 文件（推荐）
+
+```bash
+# 复制示例配置文件
+cp .env.example .env
+
+# 编辑配置文件，填写实际值
+vim .env
+```
+
+`.env` 文件内容：
+```bash
+# DevLake API 地址（必需）
+DEVLAKE_BASE_URL=http://devlake.test.chinawayltd.com
+
+# API 超时时间（秒，默认 30）
+DEVLAKE_TIMEOUT=30
+
+# API 认证 Token（可选）
+# DEVLAKE_API_TOKEN=your-token-here
+
+# 失败重试配置（可选）
+DEVLAKE_RETRY_ENABLED=true           # 启用失败重试（默认 true）
+DEVLAKE_RETRY_MAX_ATTEMPTS=5         # 最大重试次数（默认 5）
+DEVLAKE_RETRY_CLEANUP_DAYS=7         # 失败记录保留天数（默认 7）
+DEVLAKE_RETRY_CHECK_ON_HOOK=true     # Hook 执行时检查重试（默认 true）
+```
+
+### 方式 2: 直接设置环境变量
+
+```bash
+export DEVLAKE_BASE_URL="http://devlake.test.chinawayltd.com"
+export DEVLAKE_TIMEOUT=30
+```
+
+### Git 配置（必需）
+
+工具会自动从 Git 配置读取用户信息，请确保已配置：
+
+```bash
+# 配置 Git 用户信息
+git config user.name "Your Name"
+git config user.email "your.email@example.com"
+
+# 配置仓库远程地址
+git remote add origin <repository-url>
+```
+
+
+## 失败重试机制
+
+DevLake MCP 内置了智能的失败重试队列系统，确保数据不会因为网络问题或临时故障而丢失。
+
+### 工作原理
+
+当 API 调用失败时（如网络超时、服务器错误），失败的记录会自动保存到本地队列，并按照指数退避策略自动重试：
+
+**重试时间表**：
+- 第 1 次重试：1 分钟后
+- 第 2 次重试：5 分钟后
+- 第 3 次重试：15 分钟后
+- 第 4 次重试：60 分钟后
+- 第 5 次重试：4 小时后
+
+**队列类型**：
+- `session` - 会话记录
+- `prompt` - 用户输入记录
+- `prompt_update` - Prompt 更新记录
+- `file_change` - 文件变更记录
+
+### 管理失败队列
+
+```bash
+# 查看失败队列状态和统计信息
+devlake-mcp queue-status
+
+# 手动触发重试（不等待自动重试时间）
+devlake-mcp retry
+
+# 清理过期的失败记录（默认保留 7 天）
+devlake-mcp queue-clean
+```
+
+### 配置选项
+
+通过环境变量配置重试行为（参见"环境变量配置"章节）：
+
+- `DEVLAKE_RETRY_ENABLED` - 启用/禁用重试（默认 `true`）
+- `DEVLAKE_RETRY_MAX_ATTEMPTS` - 最大重试次数（默认 `5`）
+- `DEVLAKE_RETRY_CLEANUP_DAYS` - 失败记录保留天数（默认 `7`）
+- `DEVLAKE_RETRY_CHECK_ON_HOOK` - Hook 执行时检查重试（默认 `true`）
+
+### 自动重试
+
+当 `DEVLAKE_RETRY_CHECK_ON_HOOK=true` 时（默认），每次 Hook 执行时会自动检查并重试失败的记录（每次最多重试 3 条，避免阻塞）。
+
+如需禁用自动重试，可设置：
+```bash
+export DEVLAKE_RETRY_CHECK_ON_HOOK=false
+```
+
+然后使用 `devlake-mcp retry` 手动触发重试。
+
+
+## 可用工具
+
+当前服务器提供 3 个核心工具，用于记录 AI 编程会话和文件变更：
+
+### `record_session`
+记录 AI 会话的元数据和统计信息。
+
+**参数**：
+- `session_id` (string, 可选): 会话 ID，不提供则自动生成 UUID
+- `metadata` (dict, 可选): 会话元数据，支持字段：
+  - `user_intent`: 用户意图描述
+  - `model`: 模型名称（如 "claude-sonnet-4-5"）
+  - `ide`: IDE 类型（如 "cursor", "claude-code"）
+  - `project_path`: 项目路径
+
+**返回**：
+```json
+{
+  "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"}
+```
+
+---
+
+### `before_edit_file`
+在文件变更前调用，记录文件的当前状态。
+
+**参数**：
+- `session_id` (string, 必需): 会话唯一标识
+- `file_paths` (list[string], 必需): 即将变更的文件绝对路径列表
+
+**返回**：
+```json
+{
+  "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"]
+```
+
+---
+
+### `after_edit_file`
+在文件变更后调用，上传变更数据到 DevLake API。
+
+**参数**：
+- `session_id` (string, 必需): 会话唯一标识（与 before_edit_file 一致）
+- `file_paths` (list[string], 必需): 已变更的文件绝对路径列表
+
+**返回**：
+```json
+{
+  "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. [执行文件变更操作]
+3. after_edit_file() - 对比差异并上传
+```
+
+**示例**：
+```
+调用 after_edit_file 工具，session_id 为 "session-123"，file_paths 为 ["/path/to/file.py"]
+```
+
+## 相关资源
+
+- [Model Context Protocol 官方文档](https://modelcontextprotocol.io)
+- [FastMCP 官方文档](https://gofastmcp.com)
+- [FastMCP GitHub](https://github.com/jlowin/fastmcp)
+- [Claude Desktop](https://claude.ai/download)
+- [Cursor 编辑器](https://cursor.sh)