gorev

🚀 Gorev

🎯 Gorev 是什么

Gorev 是一个以 Go 编写的强大 Model Context Protocol（MCP） 服务，为所有兼容 MCP 的 AI 编辑器（Claude Desktop、VS Code、Windsurf、Cursor、Zed 等）提供任务管理能力。它将项目管理、任务跟踪和组织需求与 AI 助手的强大能力结合起来，帮助你提升工作效率。

🏗️ 三模块架构

1. gorev-mcpserver - 以 Go 编写的 MCP 服务（核心组件）
   • 内嵌 Web UI 🌐 - 嵌入二进制文件中的 React 界面（新增！v0.16.0）
   • REST API 服务（Fiber 框架）
   • MCP 协议支持
2. gorev-vscode - VS Code 扩展（可选的可视化界面）
3. gorev-web - React + TypeScript 源代码（开发用）

借助 MCP 协议，你可以从任何兼容 MCP 的编辑器连接到服务。首次建立 MCP 连接时，守护进程会自动启动，Web UI 随即在 http://localhost:5082 上可用。VS Code 扩展提供了丰富的 IDE 集成体验，并可自动管理守护进程。

🔌 守护进程架构（v0.16.0+）

Gorev 以后台守护进程的形式运行，带来以下主要优势：

核心功能：

• 单实例管理：锁文件（~/.gorev-daemon/.lock）可防止端口冲突
• 多客户端支持：多个 MCP 客户端（Claude、VS Code、Windsurf、Cursor）可以同时连接
• 自动启动：VS Code 扩展会自动检测并启动守护进程（v0.16.2+）
• 运行状况监控：通过 /api/health 端点实时查看状态
• WebSocket 支持：实时任务更新事件（实验性）

快速开始：

# Start daemon in background
gorev daemon --detach

# Check daemon status
curl http://localhost:5082/api/health

# Web UI automatically available
open http://localhost:5082

架构图

graph TB
    subgraph "External Clients"
        Claude[Claude Desktop/Code]
        VSCode[VS Code Extension]
        Cursor[Cursor IDE]
        Windsurf[Windsurf]
    end

    subgraph "Gorev Daemon (Port 5082)"
        Lock[Lock File<br/>~/.gorev-daemon/.lock]

        subgraph "Protocol Layers"
            MCP[MCP Proxy<br/>stdio]
            REST[REST API<br/>Fiber - 23 endpoints]
            WS[WebSocket<br/>Real-time events]
        end

        Handler[MCP Handlers<br/>24 Unified Tools]

        subgraph "Storage"
            DB[(SQLite DB<br/>.gorev/gorev.db)]
        end

        WebUI[Embedded Web UI<br/>React + TypeScript]
    end

    Claude -->|MCP/stdio| MCP
    VSCode -->|REST/HTTP| REST
    Cursor -->|MCP/stdio| MCP
    Windsurf -->|MCP/stdio| MCP

    MCP --> Handler
    REST --> Handler
    WS -.->|broadcasts| VSCode

    Handler --> DB

    REST --> WebUI

    Lock -.->|manages| MCP
    Lock -.->|manages| REST

    style Claude fill:#f9f,stroke:#333
    style VSCode fill:#9cf,stroke:#333
    style Cursor fill:#fc9,stroke:#333
    style Windsurf fill:#9fc,stroke:#333
    style Handler fill:#ff9,stroke:#333
    style DB fill:#9f9,stroke:#333

架构组件：

• 锁文件：~/.gorev-daemon/.lock 包含 PID、端口、版本和守护进程 URL
• REST API 服务：为 VS Code 扩展提供 23 个端点（Fiber 框架）
• MCP 代理：将 stdio MCP 协议请求转发给内部处理程序
• WebSocket 服务：实时广播任务更新事件
• 工作区管理器：支持多工作区，使用基于 SHA256 的 ID

VS Code 集成： 扩展会自动管理守护进程的生命周期：

1. 激活时检查守护进程是否正在运行（读取锁文件）
2. 如果未运行，则启动守护进程
3. 连接到 REST API 以执行所有操作
4. 可选择在停用时关闭守护进程（如果是由扩展启动的）

有关详细技术规范，请参阅守护进程架构文档。

🎉 v0.17.0 新增内容

🔧 MCP 工具参数转换修复（2025 年 10 月 6 日）

gorev_bulk - 现已全面支持全部 3 种操作：

• update 操作：可正确将 {ids: [], data: {}} 转换为 {updates: [{id, ...fields}]}
• transition 操作：为提高灵活性，接受 status 和 yeni_durum 两种参数名
• tag 操作：接受 operation 和 tag_operation 两种参数名
• 测试结果：在生产环境中成功率达 100%（5/5 项操作通过）

gorev_guncelle - 已扩展，支持更新多个字段：

• 可更新 status（状态）、priority（优先级），或同时更新两者
• 验证时至少需要一个参数
• 向后兼容现有代码

gorev_search（高级模式） - 新增智能查询解析：

• 示例："durum:devam_ediyor oncelik:yuksek tags:frontend"
• 自动从自然语言查询中提取筛选条件
• 支持以空格分隔的多个 key:value 键值对
• 与现有筛选参数无缝配合

VS Code 树视图 - 现在可显示依赖关系指示图标：

• 🔒（受阻）、🔓（未受阻）、🔗（依赖项）图标现可正确显示
• 已修复 JSON 序列化问题（从依赖计数器中移除了 omitempty）
• 现在可在树形结构中显示所有依赖关系

验证：Kilocode AI 的综合测试报告确认成功率达 100%

---

🐛 先前更新（v0.16.2 - 2025 年 10 月 5 日）

• NPM 二进制文件更新修复：修复了 NPM 包升级时仍保留旧二进制文件的严重问题
  • 从 v0.16.1 或更早版本升级的用户仍停留在 v0.15.24（2025 年 9 月）
  • 包大小从 78.4 MB 降至 6.9 KB（现在始终从 GitHub 下载二进制文件）
  • 所有用户现在都能获取最新功能（REST API、Web UI、VS Code 自动启动）
• VS Code 自动启动：扩展现在会自动检测并启动守护进程
  • 无需手动执行命令——通过检测锁文件自动启动守护进程
  • 检查守护进程是否正在运行（~/.gorev-daemon/.lock），若未运行则启动
  • 正确配置数据库路径（workspace/.gorev/gorev.db）
  • 所有 MCP 客户端（Claude、Cursor、Windsurf）共用同一守护进程

🌐 内嵌 Web UI（v0.16.0）

• 零配置：内置于 Go 二进制文件中的现代 React 界面
• 即时访问：自动在 http://localhost:5082 提供服务
• 功能齐全：任务、项目、模板、子任务和依赖关系
• 语言同步：土耳其语/英语切换器与 MCP 服务同步
• 无需单独安装：只需运行 npx @mehmetsenol/gorev-mcp-server serve 即可立即使用！

🗂️ 多工作区支持（v0.16.0）

• 工作区隔离：每个项目文件夹都有独立的任务数据库
• 工作区切换器：可在 Web UI 中无缝切换工作区
• 自动检测：自动检测当前文件夹中的 .gorev/ 目录
• SHA256 ID：安全地识别工作区
• VS Code 集成：扩展在激活时自动注册工作区

🔌 REST API 迁移

• 23 个端点：基于 Fiber 的完整 REST API
• VS Code 扩展：已从 MCP 迁移至 REST API，以提升性能
• 类型安全：100% TypeScript，零解析错误
• 更快：直接使用 HTTP 调用，取代 stdio + Markdown 解析
• 向后兼容：仍全面支持 MCP 协议

🏷️ 模板别名

• 快捷命令：使用 bug、feature、research 代替模板 ID
• 一致性：所有工作区使用相同的别名
• 无需再查找 UUID：模板标识符可读性更高
• 文档：完整指南见 MCP 配置示例

📦 NPM 包

• 包名称：@mehmetsenol/gorev-mcp-server
• 全局安装：npm install -g @mehmetsenol/gorev-mcp-server
• 可通过 NPX 运行：运行 npx @mehmetsenol/gorev-mcp-server serve 即可立即使用
• 跨平台：支持 Windows、macOS 和 Linux

✨ 功能

📝 任务管理

• 智能创建任务 - 使用自然语言命令
• Markdown 支持 - 丰富的描述格式
• 状态管理 - 待处理 → 进行中 → 已完成
• 优先级 - 低、中、高
• 灵活编辑 - 更新所有任务属性

📁 项目组织

• 分层结构 - 在项目下对任务进行分组
• 活跃项目系统 - 使用默认项目快速操作
• 按项目生成报告 - 详细统计信息
• 多项目支持 - 可创建无限个项目

🔗 高级功能

• 📅 截止日期跟踪 - 管理截止日期并筛选紧急任务
• 🏷️ 标签系统 - 使用多个标签进行分类
• 🔄 任务依赖关系 - 任务间自动化
• 📋 现成模板 - 缺陷报告、功能请求等
• 🔍 高级筛选 - 按状态、标签和日期查询
• 🌳 子任务层级 - 支持无限深度的任务树结构
• 📊 进度跟踪 - 在父任务中显示子任务完成百分比
• 📁 文件系统监视器 - 监控文件变更并自动转换任务状态
• 🔔 自动更新状态 - 文件变更时自动将“待处理”更新为“进行中”
• ⚙️ 配置管理 - 可自定义忽略模式和监视规则

🤖 AI 集成

• 自然语言处理 - 通过与 AI 助手对话来管理任务
• 多编辑器支持 - Claude、VS Code、Windsurf、Cursor、Zed
• 上下文理解 - 智能解析命令
• MCP 标准 - 兼容所有支持 MCP 的工具

🎨 VS Code 扩展功能（可选）

• 双语支持 - 土耳其语和英语界面（v0.5.0+）🌍
• TreeView 面板 - 任务、项目和模板列表
• 可视化界面 - 点击即可使用
• 状态栏 - 实时状态信息
• 命令面板 - 快速访问（Ctrl+Shift+G）
• 颜色编码 - 根据优先级进行视觉区分
• 上下文菜单 - 右键操作
• 自动检测语言 - 根据 VS Code 语言设置确定 UI 语言
• 从 Marketplace 下载 🚀

🌐 Web UI 功能（全新！v0.16.0）

• 现代浏览器界面 - 无需 IDE，可在任何浏览器中使用
• 任务卡片 - 丰富的任务可视化，包含元数据
• 子任务层级 - 可展开或折叠的嵌套任务
• 依赖关系徽章 - 直观显示任务依赖关系
• 项目组织 - 侧边栏导航，显示任务数量
• 基于模板创建 - 用于创建结构化任务的向导
• 实时更新 - 使用 React Query 自动同步
• 响应式设计 - 兼容桌面设备和移动设备
• 🌍 语言切换器 - 在土耳其语和英语之间切换，并与 MCP 服务同步
• 快速操作 - 编辑、删除和更新状态
• REST API 后端 - 基于 Fiber 的高性能 API 服务端
• 🚀 无需安装：运行 npx @mehmetsenol/gorev-mcp-server serve 后即可自动启用！
• 内嵌 UI：已打包在 Go 二进制文件中，无需单独设置
• 访问地址：http://localhost:5082（默认端口）

📦 安装

🚀 NPM 快速设置（推荐！）

⚠️ Windows 用户：NPM 需要安装 Node.js。下载 Node.js，安装后重启系统。

全局安装

npm install -g @mehmetsenol/gorev-mcp-server

或者使用 NPX 直接运行（无需安装）：

npx @mehmetsenol/gorev-mcp-server serve

MCP 客户端配置

对于 Claude Desktop：

// Windows: %APPDATA%/Claude/claude_desktop_config.json
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}
// Note: Daemon auto-starts on first connection. No manual setup required!

对于 Kilo Code（VS Code 扩展）：

// .kilocode/mcp.json (workspace root)
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}

对于 Cursor：

// .cursor/mcp.json (workspace root)
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}

📚 更多示例：MCP 配置指南

🔧 Windows NPX 故障排除

如果出现 ENOENT: spawn npx 错误：

1. 检查是否已安装 Node.js：

   node --version
   npm --version
   npx --version
   

2. 安装 Node.js：

   • 从 Node.js 网站 下载 LTS 版本
   • 安装过程中勾选“Add to PATH”选项
   • 安装完成后重启计算机

3. 单独安装 NPX（如有需要）：

   npm install -g npx
   

4. 检查 PATH：

   echo %PATH%
   

   应包含 Node.js 路径（C:\Program Files\nodejs\）。

对于 Cursor：

{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "@mehmetsenol/gorev-mcp-server@latest"
      ]
    }
  }
}

🔧 传统安装（自动）

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/msenol/Gorev/main/install.sh | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/msenol/Gorev/main/install.sh | VERSION=v0.11.0 bash

🪟 Windows

# PowerShell (no admin rights required)
irm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex

# Or for specific version:
$env:VERSION="v0.11.0"; irm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex

💻 VS Code 扩展（可选）

选项 1：Gorev VS Code 扩展（推荐）

从 VS Code Marketplace 安装

code --install-extension mehmetsenol.gorev-vscode

🎮 使用方法

AI 助手示例命令

"Create a new task: Write API documentation"
"List urgent tasks"
"Show tasks tagged with bug"
"Set Mobile App v2 project as active"
"Create new project for sprint planning"
"Mark task #5 as completed"
"Create new task from feature request template"
"Start watching project files"
"Enable automatic status transitions on file changes"
"Show watch list"
"Add git ignore rules to file watcher"

💡 提示：这些命令适用于 Claude、VS Code Copilot、Windsurf AI、Cursor 以及其他兼容 MCP 的 AI 助手。

CLI 命令

# Daemon management (recommended)
gorev daemon --detach        # Start daemon in background
gorev daemon-status          # Check daemon status
gorev daemon-stop            # Stop running daemon

# Development/testing (foreground mode)
gorev serve                  # Normal mode
gorev serve --debug          # Debug mode
gorev serve --port 8080      # Different port

# Task operations
gorev task list              # List tasks
gorev task create            # Create new task
gorev task show <id>         # Task details

# Project operations
gorev project list           # List projects
gorev project create         # Create new project

# Other
gorev version                # Version info
gorev help                 # Help

📚 文档

详细文档请参阅 docs/ 文件夹：

入门

• 🚀 快速入门指南 - 10 分钟内完成安装并开始使用
• 📦 安装指南 - 各平台的安装说明
• 🆘 故障排除指南 - 常见问题及解决方案
• 🔄 迁移指南（v0.15→v0.16） - 从 v0.15 升级

功能

• 🌐 Web UI 指南 - 嵌入式 React 界面文档
• 🗂️ 多工作区支持 - 管理多个项目
• 📋 模板系统 - 结构化任务创建
• 🤖 AI 上下文管理 - AI 助手集成

参考

• 🛠️ MCP 工具参考 - 24 个优化后的 MCP 工具（由 45 个整合而来）的完整参考
• 🔧 MCP 配置示例 - IDE 设置指南
• 📖 使用指南 - 详细的使用示例
• 🎨 VS Code 扩展 - 扩展文档

开发

• 🏗️ 系统架构 - 技术详情
• 💻 贡献指南 - 如何参与贡献
• 🗺️ 路线图 - 开发路线图和未来计划
• 📚 开发历史 - 完整的项目历史

AI 助手文档

• 🌍 CLAUDE.en.md - 英文 AI 助手指南
• 🤖 CLAUDE.md - 土耳其语 AI 助手指南
• 📋 MCP 工具参考 - 详细的 MCP 工具文档
• 📚 开发历史 - 完整的项目历史

🏗 架构

项目结构

gorev/
├── gorev-mcpserver/        # MCP Server (Go)
│   ├── cmd/gorev/         # CLI and server entry point
│   ├── internal/
│   │   ├── mcp/           # MCP protocol layer
│   │   └── gorev/        # Business logic
│   └── test/              # Integration tests
├── gorev-vscode/           # VS Code Extension (TypeScript)
│   ├── src/
│   │   ├── commands/      # VS Code commands
│   │   ├── providers/     # TreeView providers
│   │   └── mcp/           # MCP client
│   └── package.json       # Extension manifest
└── docs/                   # Project documentation

🧪 开发

要求

• Go 1.23+
• Make（可选）
• golangci-lint（用于代码质量检查）

命令

# Download dependencies
make deps

# Run tests (90%+ overall coverage)
make test

# Coverage report
make test-coverage

# Lint check
make lint

# Build (all platforms)
make build-all

# Docker image
make docker-build

📊 项目状态

• 版本：v0.17.0 🚀
• 测试覆盖率：75%+（全面的测试覆盖率，并持续改进）
• Go 版本：1.23+
• MCP SDK：mark3labs/mcp-go v0.6.0
• 数据库：SQLite（嵌入式）
• 安全性：符合生产环境审计要求
• 线程安全：100% 无竞态条件

🤝 社区

• 📦 GitHub 发行版
• 🐛 问题跟踪器
• 💬 讨论区
• 📖 Wiki

📄 许可证

本项目采用 MIT 许可证 授权。

🚨 重大变更：模板要求

从 v0.10.0 开始，gorev_olustur 工具已被移除。现在必须使用模板系统创建所有任务，以提升结构性和一致性。

迁移指南

之前（v0.9.x 及更早版本）：

Create a new task: Fix login bug

之后（v0.10.0+）：

Use bug-report template to create: Fix login bug

可用模板：

• bug-report - Bug 报告和修复
• feature - 新功能和增强
• task - 常规任务和活动
• meeting - 会议规划和笔记
• research - 研究和调查任务

详情请参阅 MCP 工具文档。

---