Goodday Mcp

Goodday MCP 服务

一个用于与 Goodday 项目管理平台集成的模型上下文协议（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：为任务添加评论

Sprint 管理

• get_goodday_sprint_tasks：按项目名称和 Sprint 名称／编号获取特定 Sprint 中的任务
• get_goodday_sprint_summary：生成全面的 Sprint 摘要，包括任务详情、状态分布和关键指标

用户管理

• get_users：获取组织用户列表
• get_user：获取特定用户的详细信息

智能查询与搜索

• get_goodday_smart_query：通过自然语言查询常见的项目管理信息
• search_goodday_tasks：使用 VectorDB 后端对任务进行语义搜索
• search_project_documents：搜索特定项目中的文档
• get_document_content：获取特定文档的完整内容

OpenWebUI 集成

此软件包还包含一个 OpenWebUI 工具，可直接在聊天界面中提供完整的 Goodday 项目管理功能。OpenWebUI 工具包括：

功能

• 项目管理：获取项目、项目任务和项目详情
• Sprint 管理：按名称／编号获取特定 Sprint 中的任务，以及全面的 Sprint 摘要
• 用户管理：获取分配给特定用户的任务和用户详情
• 任务详情：获取全面的任务信息，包括子任务、自定义字段和元数据
• 任务消息：获取任务的所有消息和评论
• 智能查询：通过自然语言处理常见的项目管理请求
• 语义搜索：使用带有嵌入的 VectorDB 后端搜索任务
• 文档管理：搜索项目文档并获取文档内容
• 高级筛选：支持筛选已归档项目、已关闭任务、子文件夹等

设置

1. 将 openwebui/goodday_openwebui_complete_tool.py 复制到 OpenWebUI 工具目录
2. 使用 API 凭据配置阀值：
   • api_key：你的 Goodday API 令牌
   • search_url：VectorDB 搜索端点（可选）
   • bearer_token：搜索 API 的 Bearer 令牌（可选）

向量数据库设置（可选）

如需使用语义搜索功能，可以通过提供的 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. 添加工具函数：在 goodday_mcp/main.py 中使用 @mcp.tool() 装饰器：

   @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. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 适用时添加测试
5. 提交 pull request

许可证

本项目基于 MIT License 授权，详情请参阅 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，支持以自然语言查询项目
• 语义搜索：新增 search_goodday_tasks，集成 VectorDB 以实现智能任务搜索
• 文档管理：新增 search_project_documents 和 get_document_content，用于处理文档
• 改进错误处理：增强错误消息和状态报告
• 高级筛选：支持归档项目、已关闭任务和包含子文件夹

v1.0.0

• 初始版本
• 完整的项目管理功能
• 支持添加评论和更新状态的任务管理
• 用户管理
• 全面的错误处理
• 支持 UV 和现代 Python 打包