🚀 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

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:

Architecture Diagram

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: Properly transforms {ids: [], data: {}} → {updates: [{id, ...fields}]}

• transition: Accepts both status and yeni_durum parameter names for flexibility

• tag: 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 🚀

🌐 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 Backend - Fiber-based high-performance API server

• 🚀 No Installation Required: Automatically active with npx @mehmetsenol/gorev-mcp-server serve!

• Embedded UI: Bundled in Go binary, no separate setup needed

• Access: http://localhost:5082 (default port)

📦 Installation

🚀 NPM Quick Setup (Recommended!)

⚠️ Windows Users: NPM requires Node.js installation. Download Node.js and restart your system after installation.

Global Installation

Or use directly with NPX (no installation required):

MCP Client Configuration

For Claude Desktop:

For Kilo Code (VS Code Extension):

For Cursor:

📚 More Examples: MCP Configuration Guide

🔧 Windows NPX Troubleshooting

If you get ENOENT: spawn npx error:

1. Check if Node.js is installed:

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

2. Install Node.js:

   • Download LTS version from Node.js website

   • Check "Add to PATH" option during installation

   • Restart your computer after installation

3. Install NPX separately (if needed):

   npm install -g npx

4. Check PATH:

   echo %PATH%

   Should include Node.js paths (C:\Program Files\nodejs\).

For Cursor:

🔧 Traditional Installation (Automatic)

🪟 Windows

💻 VS Code Extension (Optional)

Option 1: Gorev VS Code Extension (Recommended)

Install from VS Code Marketplace

🎮 Usage

AI Assistant Example Commands

💡 Tip: These commands work with Claude, VS Code Copilot, Windsurf AI, Cursor, and other MCP-compatible AI assistants.

CLI Commands

📚 Documentation

For detailed documentation, see the docs/ folder:

Getting Started

• 🚀 Quick Start Guide - Get up and running in 10 minutes

• 📦 Installation Guide - Platform-specific installation instructions

• 🆘 Troubleshooting Guide - Common issues and solutions

• 🔄 Migration Guide (v0.15→v0.16) - Upgrade from v0.15

Features

• 🌐 Web UI Guide - Embedded React interface documentation

• 🗂️ Multi-Workspace Support - Managing multiple projects

• 📋 Template System - Structured task creation

• 🤖 AI Context Management - AI assistant integration

Reference

• 🛠️ MCP Tools Reference - Complete reference for 24 optimized MCP tools (unified from 45)

• 🔧 MCP Configuration Examples - IDE setup guides

• 📖 Usage Guide - Detailed usage examples

• 🎨 VS Code Extension - Extension documentation

Development

• 🏗️ System Architecture - Technical details

• 💻 Contributing Guide - How to contribute

• 🗺️ Roadmap - Development roadmap and future plans

• 📚 Development History - Complete project history

AI Assistant Documentation

• 🌍 CLAUDE.en.md - English AI assistant guidance

• 🤖 CLAUDE.md - Turkish AI assistant guidance

• 📋 MCP Tools Reference - Detailed MCP tool documentation

• 📚 Development History - Complete project history

🏗 Architecture

Project Structure

🧪 Development

Requirements

• Go 1.23+

• Make (optional)

• golangci-lint (for code quality)

Commands

📊 Project Status

• Version: v0.17.0 🚀

• Test Coverage: 75%+ (Comprehensive test coverage with ongoing improvements)

• Go Version: 1.23+

• MCP SDK: mark3labs/mcp-go v0.6.0

• Database: SQLite (embedded)

• Security: Production-ready audit compliant

• Thread Safety: 100% race condition free

🤝 Community

• 📦 GitHub Releases

• 🐛 Issue Tracker

• 💬 Discussions

• 📖 Wiki

📄 License

This project is licensed under the MIT License.

🚨 Breaking Change: Template Requirement

Starting from v0.10.0, the gorev_olustur tool has been removed. All task creation must now use the template system for better structure and consistency.

Migration Guide

Before (v0.9.x and earlier):

After (v0.10.0+):

Available templates:

• bug-report - Bug reports and fixes

• feature - New features and enhancements

• task - General tasks and activities

• meeting - Meeting planning and notes

• research - Research and investigation tasks

For more details, see MCP Tools Documentation.

Made with ❤️ by msenol

📚 Documentation enhanced by Claude (Anthropic) - Your AI pair programming assistant

⬆ Back to Top