Gorev

🚀 Gorev

⚠️ WARNING: HEAVY DEVELOPMENT ⚠️

This project is currently under active development. Breaking changes, API modifications, and feature updates may occur frequently. Use with caution in production environments.

Last Updated: November 28, 2025 | Version: v0.17.0

🇺🇸 English | 🇹🇷 Türkçe

🎉 NEW in v0.17.0: MCP tool parameter transformation fixes + 100% test success! See What's New

Modern task management system with Turkish support, designed for MCP-compatible AI assistants (Claude, VS Code, Windsurf, Cursor)

Features • Installation • Usage • Documentation • Contributing

🎯 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

1. gorev-vscode - VS Code extension (optional visual interface)
2. 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 ~/.gorev-daemon/.lock]

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

Handler[MCP Handlers 24 Unified Tools]

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

WebUI[Embedded Web UI 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

• 📅 Due date tracking - Deadline management and urgent task filtering
• 🏷️ Tagging system - Multi-tag categorization
• 🔄 Task dependencies - Inter-task automation
• 📋 Ready-made templates - Bug reports, feature requests, and more
• 🔍 Advanced filtering - Status, tag, date-based queries
• 🌳 Subtask hierarchy - Unlimited depth task tree structure
• 📊 Progress tracking - Subtask completion percentage in parent tasks
• 📁 File System Watcher - Monitor file changes and automatic task status transitions
• 🔔 Automatic Status Updates - "pending" → "in_progress" automation on file changes
• ⚙️ Configuration Management - Customizable ignore patterns and watch rules

🤖 AI Integration

• Natural language processing - Task management by talking to AI assistants
• Multi-editor support - Claude, VS Code, Windsurf, Cursor, Zed
• Contextual understanding - Smart command interpretation
• MCP standard - Compatible with all MCP-compatible tools

🎨 VS Code Extension Features (Optional)

• Bilingual Support - Turkish and English interface (v0.5.0+) 🌍
• TreeView Panels - Task, project, and template lists
• Visual Interface - Click-and-use experience
• Status Bar - Real-time status information
• Command Palette - Quick access (Ctrl+Shift+G)
• Color Coding - Priority-based visual distinction
• Context Menus - Right-click operations
• Automatic Language Detection - UI language based on VS Code language setting
• [Download from Marketplace](https://marketplace.visualstudio.com/items?itemName=mehmetsenol.gorev-vscode) 🚀

🌐 Web UI Features (NEW! v0.16.0)

• Modern Browser Interface - No IDE required, works in any browser
• Task Cards - Rich task visualization with metadata
• Subtask Hierarchy - Expandable/collapsible nested tasks
• Dependency Badges - Visual indicators for task dependencies
• Project Organization - Sidebar navigation with task counts
• Template-Based Creation - Wizard for creating structured tasks
• Real-time Updates - React Query for automatic synchronization
• Responsive Design - Works on desktop and mobile devices
• 🌍 Language Switcher - Toggle between Turkish/English, synchronized with MCP server
• Quick Actions - Edit, delete, and status updates
• **REST API B