🚀 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 打包