gorev

🚀 Gorev

🎯 Gorev とは

Gorev は、Go で記述された強力な Model Context Protocol（MCP） サーバーで、すべての MCP 互換 AI エディター（Claude Desktop、VS Code、Windsurf、Cursor、Zed など）にタスク管理機能を提供します。プロジェクト管理、タスク追跡、整理に必要な機能を AI アシスタントの力と組み合わせ、生産性を高めます。

🏗️ 3 モジュール構成

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（優先度）、または両方を同時に更新できます
• 検証には少なくとも 1 つのパラメーターが必要です
• 既存のコードとの後方互換性があります

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 に移行しました
• 型安全：TypeScript を 100％使用し、解析エラーはゼロです
• 高速化：stdio と Markdown の解析を介さず、HTTP を直接呼び出します
• 後方互換性：MCP プロトコルも引き続き完全にサポートされます

🏷️ テンプレートの別名

• クイックコマンド：テンプレート ID の代わりに bug、feature、research を使用できます
• 一貫性：すべてのワークスペースで同じ別名を使用できます
• UUID を探す必要はありません：人が読みやすいテンプレート識別子です
• ドキュメント：MCP Config Examples に詳しいガイドがあります

📦 NPM パッケージ

• パッケージ名：@mehmetsenol/gorev-mcp-server
• グローバルインストール：npm install -g @mehmetsenol/gorev-mcp-server
• NPX に対応：すぐに使うには npx @mehmetsenol/gorev-mcp-server serve を実行します
• クロスプラットフォーム：Windows、macOS、Linux で動作します

✨ 機能

📝 タスク管理

• スマートなタスク作成 - 自然言語のコマンドを使用
• Markdown 対応 - 詳細な説明の書式設定
• ステータス管理 - 保留中 → 進行中 → 完了
• 優先度レベル - 低、中、高
• 柔軟な編集 - すべてのタスクプロパティを更新

📁 プロジェクトの整理

• 階層構造 - プロジェクト内でタスクをグループ化
• アクティブプロジェクトシステム - デフォルトのプロジェクトで素早く操作
• プロジェクト単位のレポート - 詳細な統計情報
• 複数プロジェクト対応 - プロジェクトを無制限に作成

🔗 高度な機能

• 📅 期限の追跡 - 期限の管理と緊急タスクのフィルタリング
• 🏷️ タグシステム - 複数のタグによる分類
• 🔄 タスクの依存関係 - タスク間の自動化
• 📋 すぐに使えるテンプレート - バグ報告、機能リクエストなど
• 🔍 高度なフィルタリング - ステータス、タグ、日付に基づくクエリ
• 🌳 サブタスクの階層 - 深さに制限のないタスクツリー構造
• 📊 進捗の追跡 - 親タスクにおけるサブタスクの完了率
• 📁 ファイルシステムウォッチャー - ファイルの変更を監視し、タスクのステータスを自動で切り替え
• 🔔 ステータスの自動更新 - ファイルの変更に応じて「pending」→「in_progress」に自動更新
• ⚙️ 設定管理 - 除外パターンと監視ルールをカスタマイズ可能

🤖 AI 連携

• 自然言語処理 - AI アシスタントと会話してタスクを管理
• 複数のエディターに対応 - Claude、VS Code、Windsurf、Cursor、Zed
• 文脈の理解 - コマンドをスマートに解釈
• MCP 標準 - すべての MCP 対応ツールと互換

🎨 VS Code 拡張機能の機能（オプション）

• 二言語対応 - トルコ語と英語のインターフェース（v0.5.0 以降）🌍
• ツリービューパネル - タスク、プロジェクト、テンプレートの一覧
• ビジュアルインターフェース - クリックして使える操作性
• ステータスバー - リアルタイムのステータス情報
• コマンドパレット - すばやくアクセス（Ctrl+Shift+G）
• 色分け - 優先度に基づく視覚的な区別
• コンテキストメニュー - 右クリックで操作
• 言語の自動検出 - VS Code の言語設定に基づく UI 言語
• マーケットプレイスからダウンロード 🚀

🌐 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 - バグ報告と修正
• feature - 新機能と機能強化
• task - 一般的なタスクとアクティビティ
• meeting - 会議の計画と議事録
• research - 調査と研究タスク

詳しくは、MCP ツールのドキュメントをご覧ください。

---