{
  "markdown": "# 🚀 Gorev\n\n<div align=\"center\">\n\n> ⚠️ **WARNING: HEAVY DEVELOPMENT** ⚠️\n>\n> This project is currently under **active development**. Breaking changes, API modifications, and feature updates may occur frequently. Use with caution in production environments.\n>\n> **Last Updated:** November 28, 2025 | **Version:** v0.17.0\n\n[🇺🇸 English](README.md) | [🇹🇷 Türkçe](README.tr.md)\n\n> 🎉 **NEW in v0.17.0**: MCP tool parameter transformation fixes + 100% test success! [See What's New](#-whats-new-in-v0163)\n\n![Go Version](https://img.shields.io/badge/Go-1.23+-00ADD8?style=flat-square&logo=go)\n![MCP](https://img.shields.io/badge/MCP-Compatible-4A154B?style=flat-square&logo=anthropic)\n![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)\n![Test Coverage](https://img.shields.io/badge/Coverage-75%25-yellow?style=flat-square)\n![Platform](https://img.shields.io/badge/Platform-Linux%20|%20macOS%20|%20Windows-blue?style=flat-square)\n\n**Modern task management system with Turkish support, designed for MCP-compatible AI assistants (Claude, VS Code, Windsurf, Cursor)**\n\n[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Documentation](#-documentation) • [Contributing](#-contributing)\n\n</div>\n\n## 🎯 What is Gorev\n\nGorev 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.\n\n### 🏗️ Three-Module Architecture\n\n1. **gorev-mcpserver** - MCP server written in Go (core component)\n   - Embedded Web UI 🌐 - React interface embedded in binary (NEW! v0.16.0)\n   - REST API server (Fiber framework)\n   - MCP protocol support\n2. **gorev-vscode** - VS Code extension (optional visual interface)\n3. **gorev-web** - React + TypeScript source code (development)\n\nThanks 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.\n\n### 🔌 Daemon Architecture (v0.16.0+)\n\nGorev runs as a **background daemon process**, providing these key benefits:\n\n**Core Features:**\n\n- **Single Instance Management**: Lock file (`~/.gorev-daemon/.lock`) prevents port conflicts\n- **Multi-Client Support**: Multiple MCP clients (Claude, VS Code, Windsurf, Cursor) can connect simultaneously\n- **Auto-Start**: VS Code extension automatically detects and starts daemon (v0.16.2+)\n- **Health Monitoring**: Real-time status via `/api/health` endpoint\n- **WebSocket Support**: Real-time task update events (experimental)\n\n**Quick Start:**\n\n```bash\n# Start daemon in background\ngorev daemon --detach\n\n# Check daemon status\ncurl http://localhost:5082/api/health\n\n# Web UI automatically available\nopen http://localhost:5082\n```\n\n#### Architecture Diagram\n\n```mermaid\ngraph TB\n    subgraph \"External Clients\"\n        Claude[Claude Desktop/Code]\n        VSCode[VS Code Extension]\n        Cursor[Cursor IDE]\n        Windsurf[Windsurf]\n    end\n\n    subgraph \"Gorev Daemon (Port 5082)\"\n        Lock[Lock File<br/>~/.gorev-daemon/.lock]\n\n        subgraph \"Protocol Layers\"\n            MCP[MCP Proxy<br/>stdio]\n            REST[REST API<br/>Fiber - 23 endpoints]\n            WS[WebSocket<br/>Real-time events]\n        end\n\n        Handler[MCP Handlers<br/>24 Unified Tools]\n\n        subgraph \"Storage\"\n            DB[(SQLite DB<br/>.gorev/gorev.db)]\n        end\n\n        WebUI[Embedded Web UI<br/>React + TypeScript]\n    end\n\n    Claude -->|MCP/stdio| MCP\n    VSCode -->|REST/HTTP| REST\n    Cursor -->|MCP/stdio| MCP\n    Windsurf -->|MCP/stdio| MCP\n\n    MCP --> Handler\n    REST --> Handler\n    WS -.->|broadcasts| VSCode\n\n    Handler --> DB\n\n    REST --> WebUI\n\n    Lock -.->|manages| MCP\n    Lock -.->|manages| REST\n\n    style Claude fill:#f9f,stroke:#333\n    style VSCode fill:#9cf,stroke:#333\n    style Cursor fill:#fc9,stroke:#333\n    style Windsurf fill:#9fc,stroke:#333\n    style Handler fill:#ff9,stroke:#333\n    style DB fill:#9f9,stroke:#333\n```\n\n**Architecture Components:**\n\n- **Lock File**: `~/.gorev-daemon/.lock` contains PID, port, version, and daemon URL\n- **REST API Server**: 23 endpoints for VS Code extension (Fiber framework)\n- **MCP Proxy**: Forwards stdio MCP protocol requests to internal handlers\n- **WebSocket Server**: Real-time event broadcasting for task updates\n- **Workspace Manager**: Multi-workspace support with SHA256-based IDs\n\n**VS Code Integration:**\nThe extension automatically manages the daemon lifecycle:\n\n1. On activation, checks if daemon is running (reads lock file)\n2. Starts daemon if not running\n3. Connects to REST API for all operations\n4. Optionally shuts down daemon on deactivation (if extension started it)\n\nSee [Daemon Architecture Documentation](docs/architecture/daemon-architecture.md) for detailed technical specifications.\n\n## 🎉 What's New in v0.17.0\n\n### 🔧 MCP Tool Parameter Transformation Fixes (October 6, 2025)\n\n**gorev_bulk** - All 3 operations now fully functional:\n\n- **`update` operation**: Properly transforms `{ids: [], data: {}}` → `{updates: [{id, ...fields}]}`\n- **`transition` operation**: Accepts both `status` and `yeni_durum` parameter names for flexibility\n- **`tag` operation**: Accepts both `operation` and `tag_operation` parameter names\n- **Test result**: 100% success rate (5/5 operations passed in production)\n\n**gorev_guncelle** - Extended to support multiple field updates:\n\n- Can update `status` (status), `priority` (priority), or both simultaneously\n- At least one parameter required for validation\n- Backward compatible with existing code\n\n**gorev_search (advanced mode)** - Smart query parsing added:\n\n- **Example**: `\"durum:devam_ediyor oncelik:yuksek tags:frontend\"`\n- Automatically extracts filters from natural language queries\n- Multi-filter support with space-separated key:value pairs\n- Works seamlessly with existing filter parameters\n\n**VS Code Tree View** - Dependency indicators now visible:\n\n- 🔒 (blocked), 🔓 (unblocked), 🔗 (dependents) icons display correctly\n- Fixed JSON serialization issue (removed `omitempty` from dependency counters)\n- All dependency relationships now visible in tree structure\n\n**Validation**: 100% success rate confirmed by Kilocode AI comprehensive test report\n\n---\n\n### 🐛 Previous Updates (v0.16.2 - October 5, 2025)\n\n- **NPM Binary Update Fix**: Fixed critical bug where NPM package upgrades preserved old binaries\n  - Users upgrading from v0.16.1 or earlier were stuck on v0.15.24 (September 2025)\n  - Package size reduced from 78.4 MB to 6.9 KB (binaries now always downloaded from GitHub)\n  - All users now get latest features (REST API, Web UI, VS Code auto-start)\n- **VS Code Auto-Start**: Extension now automatically detects and starts daemon\n  - No manual commands required - daemon auto-starts via lock file detection\n  - Checks if daemon is running (~/.gorev-daemon/.lock), starts if needed\n  - Proper database path configuration (workspace/.gorev/gorev.db)\n  - Shared daemon across all MCP clients (Claude, Cursor, Windsurf)\n\n### 🌐 Embedded Web UI (v0.16.0)\n\n- **Zero-Configuration**: Modern React interface built into Go binary\n- **Instant Access**: Automatically available at http://localhost:5082\n- **Full Features**: Tasks, projects, templates, subtasks, and dependencies\n- **Language Sync**: Turkish/English switcher synchronized with MCP server\n- **No Separate Installation**: Just run `npx @mehmetsenol/gorev-mcp-server serve` and you're ready!\n\n### 🗂️ Multi-Workspace Support (v0.16.0)\n\n- **Isolated Workspaces**: Each project folder gets its own task database\n- **Workspace Switcher**: Seamlessly switch between workspaces in Web UI\n- **Auto-Detection**: Automatically detects `.gorev/` directory in current folder\n- **SHA256 IDs**: Secure workspace identification\n- **VS Code Integration**: Extension auto-registers workspace on activation\n\n### 🔌 REST API Migration\n\n- **23 Endpoints**: Complete Fiber-based REST API\n- **VS Code Extension**: Migrated from MCP to REST API for better performance\n- **Type-Safe**: 100% TypeScript with zero parsing errors\n- **Faster**: Direct HTTP calls vs. stdio + markdown parsing\n- **Backward Compatible**: MCP protocol still fully supported\n\n### 🏷️ Template Aliases\n\n- **Quick Commands**: Use `bug`, `feature`, `research` instead of template IDs\n- **Consistency**: Same aliases across all workspaces\n- **No More UUID Hunting**: Human-readable template identifiers\n- **Documentation**: Full guide at [MCP Config Examples](docs/guides/mcp-config-examples.md)\n\n### 📦 NPM Package\n\n- **Package Name**: `@mehmetsenol/gorev-mcp-server`\n- **Global Install**: `npm install -g @mehmetsenol/gorev-mcp-server`\n- **NPX Ready**: `npx @mehmetsenol/gorev-mcp-server serve` for instant use\n- **Cross-Platform**: Works on Windows, macOS, and Linux\n\n## ✨ Features\n\n### 📝 Task Management\n\n- **Smart task creation** - Using natural language commands\n- **Markdown support** - Rich description formatting\n- **Status management** - Pending → In Progress → Completed\n- **Priority levels** - Low, Medium, High\n- **Flexible editing** - Update all task properties\n\n### 📁 Project Organization\n\n- **Hierarchical structure** - Task grouping under projects\n- **Active project system** - Quick operations with default project\n- **Project-based reporting** - Detailed statistics\n- **Multi-project support** - Unlimited project creation\n\n### 🔗 Advanced Features\n\n- **📅 Due date tracking** - Deadline management and urgent task filtering\n- **🏷️ Tagging system** - Multi-tag categorization\n- **🔄 Task dependencies** - Inter-task automation\n- **📋 Ready-made templates** - Bug reports, feature requests, and more\n- **🔍 Advanced filtering** - Status, tag, date-based queries\n- **🌳 Subtask hierarchy** - Unlimited depth task tree structure\n- **📊 Progress tracking** - Subtask completion percentage in parent tasks\n- **📁 File System Watcher** - Monitor file changes and automatic task status transitions\n- **🔔 Automatic Status Updates** - \"pending\" → \"in_progress\" automation on file changes\n- **⚙️ Configuration Management** - Customizable ignore patterns and watch rules\n\n### 🤖 AI Integration\n\n- **Natural language processing** - Task management by talking to AI assistants\n- **Multi-editor support** - Claude, VS Code, Windsurf, Cursor, Zed\n- **Contextual understanding** - Smart command interpretation\n- **MCP standard** - Compatible with all MCP-compatible tools\n\n### 🎨 VS Code Extension Features (Optional)\n\n- **Bilingual Support** - Turkish and English interface (v0.5.0+) 🌍\n- **TreeView Panels** - Task, project, and template lists\n- **Visual Interface** - Click-and-use experience\n- **Status Bar** - Real-time status information\n- **Command Palette** - Quick access (Ctrl+Shift+G)\n- **Color Coding** - Priority-based visual distinction\n- **Context Menus** - Right-click operations\n- **Automatic Language Detection** - UI language based on VS Code language setting\n- **[Download from Marketplace](https://marketplace.visualstudio.com/items?itemName=mehmetsenol.gorev-vscode)** 🚀\n\n### 🌐 Web UI Features (NEW! v0.16.0)\n\n- **Modern Browser Interface** - No IDE required, works in any browser\n- **Task Cards** - Rich task visualization with metadata\n- **Subtask Hierarchy** - Expandable/collapsible nested tasks\n- **Dependency Badges** - Visual indicators for task dependencies\n- **Project Organization** - Sidebar navigation with task counts\n- **Template-Based Creation** - Wizard for creating structured tasks\n- **Real-time Updates** - React Query for automatic synchronization\n- **Responsive Design** - Works on desktop and mobile devices\n- **🌍 Language Switcher** - Toggle between Turkish/English, synchronized with MCP server\n- **Quick Actions** - Edit, delete, and status updates\n- **REST API Backend** - Fiber-based high-performance API server\n- **🚀 No Installation Required**: Automatically active with `npx @mehmetsenol/gorev-mcp-server serve`!\n- **Embedded UI**: Bundled in Go binary, no separate setup needed\n- **Access**: http://localhost:5082 (default port)\n\n## 📦 Installation\n\n### 🚀 NPM Quick Setup (Recommended!)\n\n> ⚠️ **Windows Users**: NPM requires Node.js installation. [Download Node.js](https://nodejs.org/) and restart your system after installation.\n\n#### Global Installation\n\n```bash\nnpm install -g @mehmetsenol/gorev-mcp-server\n```\n\nOr use directly with NPX (no installation required):\n\n```bash\nnpx @mehmetsenol/gorev-mcp-server serve\n```\n\n#### MCP Client Configuration\n\n**For Claude Desktop:**\n\n```json\n// Windows: %APPDATA%/Claude/claude_desktop_config.json\n// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\n// Linux: ~/.config/Claude/claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"gorev\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@mehmetsenol/gorev-mcp-server@latest\"\n      ],\n      \"env\": {\n        \"GOREV_LANG\": \"en\"\n      }\n    }\n  }\n}\n// Note: Daemon auto-starts on first connection. No manual setup required!\n```\n\n**For Kilo Code (VS Code Extension):**\n\n```json\n// .kilocode/mcp.json (workspace root)\n{\n  \"mcpServers\": {\n    \"gorev\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@mehmetsenol/gorev-mcp-server@latest\"\n      ],\n      \"env\": {\n        \"GOREV_LANG\": \"en\"\n      }\n    }\n  }\n}\n```\n\n**For Cursor:**\n\n```json\n// .cursor/mcp.json (workspace root)\n{\n  \"mcpServers\": {\n    \"gorev\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@mehmetsenol/gorev-mcp-server@latest\"\n      ],\n      \"env\": {\n        \"GOREV_LANG\": \"en\"\n      }\n    }\n  }\n}\n```\n\n> 📚 **More Examples**: [MCP Configuration Guide](docs/guides/mcp-config-examples.md)\n\n#### 🔧 Windows NPX Troubleshooting\n\nIf you get `ENOENT: spawn npx` error:\n\n1. **Check if Node.js is installed:**\n\n   ```cmd\n   node --version\n   npm --version\n   npx --version\n   ```\n\n2. **Install Node.js:**\n   - Download LTS version from [Node.js website](https://nodejs.org/)\n   - Check \"Add to PATH\" option during installation\n   - Restart your computer after installation\n\n3. **Install NPX separately (if needed):**\n\n   ```cmd\n   npm install -g npx\n   ```\n\n4. **Check PATH:**\n\n   ```cmd\n   echo %PATH%\n   ```\n\n   Should include Node.js paths (`C:\\Program Files\\nodejs\\`).\n\n**For Cursor:**\n\n```json\n{\n  \"mcpServers\": {\n    \"gorev\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@mehmetsenol/gorev-mcp-server@latest\"\n      ]\n    }\n  }\n}\n```\n\n### 🔧 Traditional Installation (Automatic)\n\n```bash\n# Linux/macOS\ncurl -fsSL https://raw.githubusercontent.com/msenol/Gorev/main/install.sh | bash\n\n# Specific version\ncurl -fsSL https://raw.githubusercontent.com/msenol/Gorev/main/install.sh | VERSION=v0.11.0 bash\n```\n\n### 🪟 Windows\n\n```powershell\n# PowerShell (no admin rights required)\nirm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex\n\n# Or for specific version:\n$env:VERSION=\"v0.11.0\"; irm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex\n```\n\n### 💻 VS Code Extension (Optional)\n\n**Option 1: Gorev VS Code Extension (Recommended)**\n\nInstall from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=mehmetsenol.gorev-vscode)\n\n```bash\ncode --install-extension mehmetsenol.gorev-vscode\n```\n\n## 🎮 Usage\n\n### AI Assistant Example Commands\n\n```\n\"Create a new task: Write API documentation\"\n\"List urgent tasks\"\n\"Show tasks tagged with bug\"\n\"Set Mobile App v2 project as active\"\n\"Create new project for sprint planning\"\n\"Mark task #5 as completed\"\n\"Create new task from feature request template\"\n\"Start watching project files\"\n\"Enable automatic status transitions on file changes\"\n\"Show watch list\"\n\"Add git ignore rules to file watcher\"\n```\n\n> 💡 **Tip**: These commands work with Claude, VS Code Copilot, Windsurf AI, Cursor, and other MCP-compatible AI assistants.\n\n### CLI Commands\n\n```bash\n# Daemon management (recommended)\ngorev daemon --detach        # Start daemon in background\ngorev daemon-status          # Check daemon status\ngorev daemon-stop            # Stop running daemon\n\n# Development/testing (foreground mode)\ngorev serve                  # Normal mode\ngorev serve --debug          # Debug mode\ngorev serve --port 8080      # Different port\n\n# Task operations\ngorev task list              # List tasks\ngorev task create            # Create new task\ngorev task show <id>         # Task details\n\n# Project operations\ngorev project list           # List projects\ngorev project create         # Create new project\n\n# Other\ngorev version                # Version info\ngorev help                 # Help\n```\n\n## 📚 Documentation\n\nFor detailed documentation, see the [docs/](docs/) folder:\n\n### Getting Started\n\n- 🚀 [Quick Start Guide](docs/guides/getting-started/quick-start.md) - Get up and running in 10 minutes\n- 📦 [Installation Guide](docs/guides/getting-started/installation.md) - Platform-specific installation instructions\n- 🆘 [Troubleshooting Guide](docs/guides/getting-started/troubleshooting.md) - Common issues and solutions\n- 🔄 [Migration Guide (v0.15→v0.16)](docs/migration/v0.15-to-v0.16.md) - Upgrade from v0.15\n\n### Features\n\n- 🌐 [Web UI Guide](docs/guides/features/web-ui.md) - Embedded React interface documentation\n- 🗂️ [Multi-Workspace Support](docs/guides/features/multi-workspace.md) - Managing multiple projects\n- 📋 [Template System](docs/guides/features/template-system.md) - Structured task creation\n- 🤖 [AI Context Management](docs/guides/features/ai-context-management.md) - AI assistant integration\n\n### Reference\n\n- 🛠️ [MCP Tools Reference](docs/api/MCP_TOOLS_REFERENCE.md) - Complete reference for 24 optimized MCP tools (unified from 45)\n- 🔧 [MCP Configuration Examples](docs/guides/mcp-config-examples.md) - IDE setup guides\n- 📖 [Usage Guide](docs/guides/user/usage.md) - Detailed usage examples\n- 🎨 [VS Code Extension](docs/guides/user/vscode-extension.md) - Extension documentation\n\n### Development\n\n- 🏗️ [System Architecture](docs/architecture/architecture-v2.md) - Technical details\n- 💻 [Contributing Guide](docs/development/contributing.md) - How to contribute\n- 🗺️ [Roadmap](ROADMAP.md) - Development roadmap and future plans\n- 📚 [Development History](docs/development/TASKS.md) - Complete project history\n\n### AI Assistant Documentation\n\n- 🌍 [CLAUDE.en.md](CLAUDE.en.md) - English AI assistant guidance\n- 🤖 [CLAUDE.md](CLAUDE.md) - Turkish AI assistant guidance\n- 📋 [MCP Tools Reference](docs/api/MCP_TOOLS_REFERENCE.md) - Detailed MCP tool documentation\n- 📚 [Development History](docs/development/TASKS.md) - Complete project history\n\n## 🏗 Architecture\n\n### Project Structure\n\n```\ngorev/\n├── gorev-mcpserver/        # MCP Server (Go)\n│   ├── cmd/gorev/         # CLI and server entry point\n│   ├── internal/\n│   │   ├── mcp/           # MCP protocol layer\n│   │   └── gorev/        # Business logic\n│   └── test/              # Integration tests\n├── gorev-vscode/           # VS Code Extension (TypeScript)\n│   ├── src/\n│   │   ├── commands/      # VS Code commands\n│   │   ├── providers/     # TreeView providers\n│   │   └── mcp/           # MCP client\n│   └── package.json       # Extension manifest\n└── docs/                   # Project documentation\n```\n\n## 🧪 Development\n\n### Requirements\n\n- Go 1.23+\n- Make (optional)\n- golangci-lint (for code quality)\n\n### Commands\n\n```bash\n# Download dependencies\nmake deps\n\n# Run tests (90%+ overall coverage)\nmake test\n\n# Coverage report\nmake test-coverage\n\n# Lint check\nmake lint\n\n# Build (all platforms)\nmake build-all\n\n# Docker image\nmake docker-build\n```\n\n## 📊 Project Status\n\n- **Version**: v0.17.0 🚀\n- **Test Coverage**: 75%+ (Comprehensive test coverage with ongoing improvements)\n- **Go Version**: 1.23+\n- **MCP SDK**: mark3labs/mcp-go v0.6.0\n- **Database**: SQLite (embedded)\n- **Security**: Production-ready audit compliant\n- **Thread Safety**: 100% race condition free\n\n## 🤝 Community\n\n- 📦 [GitHub Releases](https://github.com/msenol/gorev/releases)\n- 🐛 [Issue Tracker](https://github.com/msenol/gorev/issues)\n- 💬 [Discussions](https://github.com/msenol/gorev/discussions)\n- 📖 [Wiki](https://github.com/msenol/gorev/wiki)\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## 🚨 Breaking Change: Template Requirement\n\n**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.\n\n### Migration Guide\n\n**Before (v0.9.x and earlier):**\n\n```\nCreate a new task: Fix login bug\n```\n\n**After (v0.10.0+):**\n\n```\nUse bug-report template to create: Fix login bug\n```\n\nAvailable templates:\n\n- `bug-report` - Bug reports and fixes\n- `feature` - New features and enhancements  \n- `task` - General tasks and activities\n- `meeting` - Meeting planning and notes\n- `research` - Research and investigation tasks\n\nFor more details, see [MCP Tools Documentation](docs/user-guide/mcp-tools.md#gorev_template_olustur).\n\n---\n\n<div align=\"center\">\n\nMade with ❤️ by [msenol](https://github.com/msenol/gorev/graphs/contributors)\n\n📚 *Documentation enhanced by Claude (Anthropic) - Your AI pair programming assistant*\n\n**[⬆ Back to Top](#-gorev)**\n\n</div>\n",
  "bytes": 21318,
  "sha": "02bc8c15c5be77565f5c42575a5f55624dc02238d6a0fd2cab0419a242370d26",
  "repo_slug": "msenol/gorev",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_msenol_gorev_5734ed36/readme"
}