Goodday Mcp

Goodday MCP サーバー

Goodday プロジェクト管理プラットフォームと連携するための Model Context Protocol（MCP）サーバーです。このサーバーは、Goodday API v2 を通じてプロジェクト、タスク、ユーザーを管理するツールを提供します。

機能

プロジェクト管理

• get_projects：プロジェクト一覧を取得します（アーカイブ済みプロジェクトやルートプロジェクトのみで絞り込むオプションあり）
• get_project：特定のプロジェクトの詳細情報を取得します
• create_project：テンプレートや設定をカスタマイズして新しいプロジェクトを作成します
• get_project_users：特定のプロジェクトに関連付けられたユーザーを取得します

タスク管理

• get_project_tasks：特定のプロジェクトのタスクを取得します（完了済みタスクやサブフォルダーを含めるオプションあり）
• get_user_assigned_tasks：特定のユーザーに割り当てられたタスクを取得します
• get_user_action_required_tasks：ユーザーの対応が必要なタスクを取得します
• get_task：特定のタスクの詳細情報を取得します
• get_task_details：サブタスク、カスタムフィールド、すべてのメタデータを含む、タスクの包括的な詳細情報を取得します
• get_task_messages：特定のタスクのすべてのメッセージ／コメントを取得します
• create_task：サブタスク、割り当て、日付、優先度を含めて、新しいタスクを詳細にカスタマイズして作成します
• update_task_status：任意のコメントを添えてタスクのステータスを更新します
• add_task_comment：タスクにコメントを追加します

スプリント管理

• get_goodday_sprint_tasks：プロジェクト名とスプリント名／番号を指定して、特定のスプリントのタスクを取得します
• get_goodday_sprint_summary：タスクの詳細、ステータスの分布、主要な指標を含む、包括的なスプリント概要を生成します

ユーザー管理

• get_users：組織のユーザー一覧を取得します
• get_user：特定のユーザーの詳細情報を取得します

スマートクエリと検索

• get_goodday_smart_query：一般的なプロジェクト管理の問い合わせに対応する自然言語インターフェースです
• search_goodday_tasks：VectorDB バックエンドを使用してタスクを意味検索します
• search_project_documents：特定のプロジェクト内のドキュメントを検索します
• get_document_content：特定のドキュメントの全文を取得します

OpenWebUI との連携

このパッケージには、チャットインターフェースから Goodday のプロジェクト管理をすべて行える OpenWebUI ツールも含まれています。OpenWebUI ツールの機能は次のとおりです。

機能

• プロジェクト管理：プロジェクト、プロジェクトのタスク、プロジェクトの詳細を取得します
• スプリント管理：名前／番号を指定して特定のスプリントのタスクを取得し、包括的なスプリント概要を作成します
• ユーザー管理：特定のユーザーに割り当てられたタスクや、ユーザーの詳細情報を取得します
• タスクの詳細：サブタスク、カスタムフィールド、メタデータを含む、タスクの包括的な情報を取得します
• タスクメッセージ：タスクのすべてのメッセージとコメントを取得します
• スマートクエリ：一般的なプロジェクト管理の依頼に対応する自然言語インターフェースです
• 意味検索：埋め込み表現を使用する VectorDB バックエンドでタスクを検索します
• ドキュメント管理：プロジェクトのドキュメントを検索し、内容を取得します
• 高度なフィルタリング：アーカイブ済みプロジェクト、完了済みタスク、サブフォルダーなどに対応します

セットアップ

1. openwebui/goodday_openwebui_complete_tool.py を OpenWebUI のツールディレクトリにコピーします
2. API 認証情報を使用してバルブを設定します：
   • api_key：Goodday API トークン
   • search_url：VectorDB 検索エンドポイント（任意）
   • bearer_token：検索 API 用のベアラートークン（任意）

ベクトルデータベースのセットアップ（任意）

意味検索機能を利用するには、付属の n8n ワークフロー（openwebui/n8n-workflow-goodday-vectordb.json）を使ってベクトルデータベースをセットアップできます。このワークフローでは、次の処理を行います。

• Goodday のすべてのプロジェクトとタスクを取得します
• タスクのメッセージと内容を抽出します
• Ollama を使用して埋め込み表現を作成します
• Qdrant ベクトルデータベースに保存します
• 検索 API エンドポイントを提供します

詳しい使用方法については、openwebui/OPENWEBUI_TOOL_README.md を参照してください。

インストール

PyPI から（推奨）

pip install goodday-mcp

ソースから

前提条件

• Python 3.10 以降
• UV パッケージマネージャー（推奨）または pip
• Goodday API トークン

UV を使用したセットアップ

1. UV をインストール（まだインストールされていない場合）：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. プロジェクトをクローンしてセットアップ：

   git clone https://github.com/cdmx1/goodday-mcp.git
   cd goodday-mcp
   
   # Create virtual environment and install dependencies
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv sync
   

pip を使用したセットアップ

git clone https://github.com/cdmx1/goodday-mcp.git
cd goodday-mcp
pip install -e .

設定

1. 環境変数を設定： プロジェクトのルートに .env ファイルを作成するか、変数をエクスポートします：

   export GOODDAY_API_TOKEN=your_goodday_api_token_here
   

   Goodday API トークンを取得するには：

   • Goodday 組織に移動します
   • 「Settings → API」に移動します
   • 生成ボタンをクリックして新しいトークンを作成します

使用方法

サーバーを単独で実行する

PyPI からインストールした場合：

goodday-mcp

UV を使用してソースから実行する場合：

uv run goodday-mcp

Claude Desktop で使用する

1. 設定ファイルを編集して Claude Desktop を設定します：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. サーバーの設定を追加します：

   オプション A：PyPI からインストールした場合：

   {
     "mcpServers": {
       "goodday": {
         "command": "goodday-mcp",
         "env": {
           "GOODDAY_API_TOKEN": "your_goodday_api_token_here"
         }
       }
     }
   }
   

   オプション B：ソースから実行する場合：

   {
     "mcpServers": {
       "goodday": {
         "command": "uv",
         "args": ["run", "goodday-mcp"],
         "env": {
           "GOODDAY_API_TOKEN": "your_goodday_api_token_here"
         }
       }
     }
   }
   

3. 新しいサーバーを読み込むために Claude Desktop を再起動します。

その他の MCP クライアントで使用する

このサーバーは stdio トランスポートで通信し、MCP 互換の任意のクライアントと統合できます。クライアントごとの統合手順については、MCP のドキュメントを参照してください。

API リファレンス

環境変数

変数	説明	必須
GOODDAY_API_TOKEN	Goodday API トークン	はい

ツールの例

プロジェクトを取得

# Get all active projects
get_projects()

# Get archived projects
get_projects(archived=True)

# Get only root-level projects
get_projects(root_only=True)

タスクを作成

create_task(
    project_id="project_123",
    title="Implement new feature",
    from_user_id="user_456",
    message="Detailed description of the task",
    to_user_id="user_789",
    deadline="2025-06-30",
    priority=5
)

タスクのステータスを更新

update_task_status(
    task_id="task_123",
    user_id="user_456",
    status_id="status_completed",
    message="Task completed successfully"
)

データ形式

日付形式

すべての日付は YYYY-MM-DD 形式で指定してください（例：2025-06-16）。

優先度

• 1-10：通常の優先度
• 50：ブロッカー
• 100：緊急

プロジェクトの色

プロジェクトの色は 1-24 の整数で指定し、Goodday のカラーパレットに対応します。

エラー処理

このサーバーには、包括的なエラー処理が含まれています：

• 認証エラー：API トークンがない場合、または無効な場合
• ネットワークエラー：Goodday API に接続できない場合
• 検証エラー：必須パラメーターが不足している場合
• 権限エラー：ユーザーに要求された操作を行う権限がない場合

トラブルシューティングに役立つよう、すべてのエラーは内容を説明する文字列として返されます。

開発

プロジェクト構成

goodday-mcp/
├── goodday_mcp/         # Main package directory
│   ├── __init__.py      # Package initialization
│   └── main.py          # Main MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── README.md           # This file
├── LICENSE             # MIT license
├── uv.lock            # Dependency lock file
└── .env               # Environment variables (create this)

新しいツールの追加

サーバーに新しいツールを追加するには：

1. @mcp.tool() デコレーターを使用して、goodday_mcp/main.py にツール関数を 追加します：

   @mcp.tool()
   async def your_new_tool(param1: str, param2: Optional[int] = None) -> str:
       """Description of what the tool does.
       
       Args:
           param1: Description of parameter 1
           param2: Description of optional parameter 2
       """
       # Implementation here
       return "Result"
   

2. サーバーを実行し、MCP クライアントでテストして ツールをテストします。

テスト

サーバーを直接実行してテストします：

# If installed from PyPI
goodday-mcp

# If running from source
uv run goodday-mcp

サーバーが起動し、stdin/stdout 経由で MCP プロトコルメッセージを待機します。

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。

サポート

以下に関する問題について：

• MCP サーバー：このリポジトリで Issue を作成してください
• Goodday API：Goodday API ドキュメントを参照してください
• MCP プロトコル：MCP のドキュメントを参照してください

変更履歴

v1.1.0（現在）

• タスク管理の強化：タスク情報を包括的に取得する get_task_details と get_task_messages を追加
• スプリント管理：スプリントを追跡する get_goodday_sprint_tasks と get_goodday_sprint_summary を追加
• スマートクエリーインターフェース：自然言語でプロジェクトを検索する get_goodday_smart_query を追加
• セマンティック検索：インテリジェントなタスク検索のため、VectorDB 統合を備えた search_goodday_tasks を追加
• ドキュメント管理：ドキュメントを扱う search_project_documents と get_document_content を追加
• エラー処理の改善：エラーメッセージとステータスレポートを強化
• 高度なフィルタリング：アーカイブ済みプロジェクト、完了済みタスク、サブフォルダーの包含に対応

v1.0.0

• 初回リリース
• プロジェクト管理の全機能
• コメントとステータス更新に対応したタスク管理
• ユーザー管理
• 包括的なエラー処理
• 最新の Python パッケージングを用いた UV サポート