金大哥 - goodday-mcp MCP 详情

article

README

🚀 Goodday MCP 服务器

Goodday MCP 服务器是一个模型上下文协议（MCP）服务器，用于与 Goodday 项目管理平台集成。该服务器通过 Goodday API v2 提供了管理项目、任务和用户的工具。

🚀 快速开始

安装

从 PyPI 安装（推荐）

pip install goodday-mcp

从源码安装

前提条件

Python 3.10 或更高版本
UV 包管理器（推荐）或 pip
Goodday API 令牌

使用 UV 进行设置

安装 UV（如果尚未安装）：

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

克隆并设置项目：

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 .

配置

设置环境变量：在项目根目录创建一个 .env 文件或导出变量：

export GOODDAY_API_TOKEN=your_goodday_api_token_here

要获取你的 Goodday API 令牌：

进入你的 Goodday 组织
导航到“设置”→“API”
点击生成按钮创建一个新令牌

运行服务器

独立运行服务器

如果从 PyPI 安装：

goodday-mcp

如果从源码使用 UV 运行：

uv run goodday-mcp

与 Claude Desktop 一起使用

配置 Claude Desktop，编辑你的配置文件：

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

添加服务器配置： 选项 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"
            }
        }
    }
}

重启 Claude Desktop 以加载新服务器。

与其他 MCP 客户端一起使用

服务器通过标准输入输出传输进行通信，可以与任何 MCP 兼容的客户端集成。请参考 MCP 文档获取特定客户端的集成说明。

✨ 主要特性

项目管理

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 后端对任务进行语义搜索
任务详情：获取详细的任务信息和消息

设置

将 openwebui/goodday_openwebui_complete_tool.py 复制到你的 OpenWebUI 工具目录。
使用你的 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。

📚 详细文档

API 参考

环境变量

| 属性 | 详情 | | ---- | ---- | | 模型类型 | GOODDAY_API_TOKEN：你的 Goodday API 令牌，必需 |

工具示例

获取项目

# 获取所有活跃项目
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               # 环境变量（需创建）

添加新工具

要向服务器添加新工具：

在 goodday_mcp/main.py 中使用 @mcp.tool() 装饰器添加工具函数：

@mcp.tool()
async def your_new_tool(param1: str, param2: Optional[int] = None) -> str:
    """描述工具的功能。

    Args:
        param1: 参数 1 的描述
        param2: 可选参数 2 的描述
    """
    # 实现代码
    return "Result"

测试工具：运行服务器并使用 MCP 客户端进行测试。

测试

直接运行服务器进行测试：

# 如果从 PyPI 安装
goodday-mcp

# 如果从源码运行
uv run goodday-mcp

服务器将启动并通过标准输入输出等待 MCP 协议消息。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

问题反馈

MCP 服务器：在本仓库中创建问题
Goodday API：参考 Goodday API 文档
MCP 协议：参考 MCP 文档

变更日志

v1.0.0

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