Goodday MCP

🚀 Goodday MCP Server

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：特定のタスクの詳細情報を取得します
• create_task：完全にカスタマイズ可能な新しいタスクを作成します（サブタスク、割り当て、日付、優先度）
• update_task_status：オプションのコメント付きでタスクのステータスを更新します
• add_task_comment：タスクにコメントを追加します

ユーザー管理

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

📚 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
   
   # 仮想環境を作成し、依存関係をインストール
   uv venv
   source .venv/bin/activate  # 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組織にアクセスします
   • 設定 → 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ドキュメント を参照してください。

📚 詳細ドキュメント

環境変数

ツールの例

プロジェクトを取得する

# すべてのアクティブなプロジェクトを取得する
get_projects()

# アーカイブされたプロジェクトを取得する
get_projects(archived=True)

# ルートレベルのプロジェクトのみを取得する
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/         # メインパッケージディレクトリ
│   ├── __init__.py      # パッケージの初期化
│   └── main.py          # メインMCPサーバーの実装
├── pyproject.toml       # プロジェクトの設定と依存関係
├── README.md           # このファイル
├── LICENSE             # MITライセンス
├── uv.lock            # 依存関係のロックファイル
└── .env               # 環境変数（これを作成する）

新しいツールを追加する

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

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

@mcp.tool()
async def your_new_tool(param1: str, param2: Optional[int] = None) -> str:
    """ツールの機能を説明します。
    
    引数:
        param1: パラメータ1の説明
        param2: オプションのパラメータ2の説明
    """
    # ここに実装を記述します
    return "Result"

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

テスト

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

# PyPIからインストールした場合
goodday-mcp

# ソースから実行する場合
uv run goodday-mcp

サーバーは起動し、stdin/stdoutを介してMCPプロトコルメッセージを待機します。

コントリビューション

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

📄 ライセンス

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

サポート

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

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

変更履歴

v1.0.0

• 初期リリース
• 完全なプロジェクト管理機能
• コメントとステータス更新を含むタスク管理
• ユーザー管理
• 包括的なエラー処理
• 最新のPythonパッケージングでのUVサポート