🚀 Gorev

🎯 What is Gorev

Gorev is a powerful Model Context Protocol (MCP) server written in Go that provides task management capabilities to all MCP-compatible AI editors (Claude Desktop, VS Code, Windsurf, Cursor, Zed, etc.). It combines project management, task tracking, and organization needs with the power of AI assistants to boost your productivity.

🏗️ Three-Module Architecture

1. gorev-mcpserver - MCP server written in Go (core component)
   • Embedded Web UI 🌐 - React interface embedded in binary (NEW! v0.16.0)
   • REST API server (Fiber framework)
   • MCP protocol support
2. gorev-vscode - VS Code extension (optional visual interface)
3. gorev-web - React + TypeScript source code (development)

Thanks to the MCP protocol, you can connect to the server from any MCP-compatible editor. The daemon automatically starts on first MCP connection, and the Web UI becomes available at http://localhost:5082. The VS Code extension provides a rich IDE-integrated experience with automatic daemon management.

🔌 Daemon Architecture (v0.16.0+)

Gorev runs as a background daemon process, providing these key benefits:

Core Features:

• Single Instance Management: Lock file (~/.gorev-daemon/.lock) prevents port conflicts
• Multi-Client Support: Multiple MCP clients (Claude, VS Code, Windsurf, Cursor) can connect simultaneously
• Auto-Start: VS Code extension automatically detects and starts daemon (v0.16.2+)
• Health Monitoring: Real-time status via /api/health endpoint
• WebSocket Support: Real-time task update events (experimental)

Quick Start:

# Start daemon in background
gorev daemon --detach

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

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

Architecture Diagram

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

Architecture Components:

• Lock File: ~/.gorev-daemon/.lock contains PID, port, version, and daemon URL
• REST API Server: 23 endpoints for VS Code extension (Fiber framework)
• MCP Proxy: Forwards stdio MCP protocol requests to internal handlers
• WebSocket Server: Real-time event broadcasting for task updates
• Workspace Manager: Multi-workspace support with SHA256-based IDs

VS Code Integration: The extension automatically manages the daemon lifecycle:

1. On activation, checks if daemon is running (reads lock file)
2. Starts daemon if not running
3. Connects to REST API for all operations
4. Optionally shuts down daemon on deactivation (if extension started it)

See Daemon Architecture Documentation for detailed technical specifications.

🎉 What's New in v0.17.0

🔧 MCP Tool Parameter Transformation Fixes (October 6, 2025)

gorev_bulk - All 3 operations now fully functional:

• update operation: Properly transforms {ids: [], data: {}} → {updates: [{id, ...fields}]}
• transition operation: Accepts both status and yeni_durum parameter names for flexibility
• tag operation: Accepts both operation and tag_operation parameter names
• Test result: 100% success rate (5/5 operations passed in production)

gorev_guncelle - Extended to support multiple field updates:

• Can update status (status), priority (priority), or both simultaneously
• At least one parameter required for validation
• Backward compatible with existing code

gorev_search (advanced mode) - Smart query parsing added:

• Example: "durum:devam_ediyor oncelik:yuksek tags:frontend"
• Automatically extracts filters from natural language queries
• Multi-filter support with space-separated key:value pairs
• Works seamlessly with existing filter parameters

VS Code Tree View - Dependency indicators now visible:

• 🔒 (blocked), 🔓 (unblocked), 🔗 (dependents) icons display correctly
• Fixed JSON serialization issue (removed omitempty from dependency counters)
• All dependency relationships now visible in tree structure

Validation: 100% success rate confirmed by Kilocode AI comprehensive test report

🐛 Previous Updates (v0.16.2 - October 5, 2025)

• NPM Binary Update Fix: Fixed critical bug where NPM package upgrades preserved old binaries
  • Users upgrading from v0.16.1 or earlier were stuck on v0.15.24 (September 2025)
  • Package size reduced from 78.4 MB to 6.9 KB (binaries now always downloaded from GitHub)
  • All users now get latest features (REST API, Web UI, VS Code auto-start)
• VS Code Auto-Start: Extension now automatically detects and starts daemon
  • No manual commands required - daemon auto-starts via lock file detection
  • Checks if daemon is running (~/.gorev-daemon/.lock), starts if needed
  • Proper database path configuration (workspace/.gorev/gorev.db)
  • Shared daemon across all MCP clients (Claude, Cursor, Windsurf)

🌐 Embedded Web UI (v0.16.0)

• Zero-Configuration: Modern React interface built into Go binary
• Instant Access: Automatically available at http://localhost:5082
• Full Features: Tasks, projects, templates, subtasks, and dependencies
• Language Sync: Turkish/English switcher synchronized with MCP server
• No Separate Installation: Just run npx @mehmetsenol/gorev-mcp-server serve and you're ready!

🗂️ Multi-Workspace Support (v0.16.0)

• Isolated Workspaces: Each project folder gets its own task database
• Workspace Switcher: Seamlessly switch between workspaces in Web UI
• Auto-Detection: Automatically detects .gorev/ directory in current folder
• SHA256 IDs: Secure workspace identification
• VS Code Integration: Extension auto-registers workspace on activation

🔌 REST API Migration

• 23 Endpoints: Complete Fiber-based REST API
• VS Code Extension: Migrated from MCP to REST API for better performance
• Type-Safe: 100% TypeScript with zero parsing errors
• Faster: Direct HTTP calls vs. stdio + markdown parsing
• Backward Compatible: MCP protocol still fully supported

🏷️ Template Aliases

• Quick Commands: Use bug, feature, research instead of template IDs
• Consistency: Same aliases across all workspaces
• No More UUID Hunting: Human-readable template identifiers
• Documentation: Full guide at MCP Config Examples

📦 NPM Package

• Package Name: @mehmetsenol/gorev-mcp-server
• Global Install: npm install -g @mehmetsenol/gorev-mcp-server
• NPX Ready: npx @mehmetsenol/gorev-mcp-server serve for instant use
• Cross-Platform: Works on Windows, macOS, and Linux

✨ Features

📝 Task Management

• Smart task creation - Using natural language commands
• Markdown support - Rich description formatting
• Status management - Pending → In Progress → Completed
• Priority levels - Low, Medium, High
• Flexible editing - Update all task properties

📁 Project Organization

• Hierarchical structure - Task grouping under projects
• Active project system - Quick operations with default project
• Project-based reporting - Detailed statistics
• Multi-project support - Unlimited project creation

🔗 Advanced Features