Goodday MCP

🚀 Goodday MCP 服務器

Goodday MCP 服務器是一個模型上下文協議（MCP）服務器，用於與 Goodday 項目管理平臺集成。該服務器通過 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 集成

此軟件包還包含一個 OpenWebUI 工具，可直接在聊天界面中為 Goodday 項目管理提供完整界面。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 "結果"

2. 測試工具：運行服務器並使用 MCP 客戶端進行測試。

測試

直接運行服務器進行測試：

# 如果從 PyPI 安裝
goodday-mcp

# 如果從源代碼運行
uv run goodday-mcp

服務器將啟動並通過 stdin/stdout 等待 MCP 協議消息。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

支持

有關以下方面的問題：

• MCP 服務器：在此倉庫中創建問題
• Goodday API：參閱 Goodday API 文檔
• MCP 協議：參閱 MCP 文檔

更新日誌

v1.0.0

• 初始版本
• 完整的項目管理功能
• 支持註釋和狀態更新的任務管理
• 用戶管理
• 全面的錯誤處理
• 支持 UV 和現代 Python 打包