# deciduus
## 基本信息
- Slug: `deciduus-calendar-mcp`
- Source: modelscope
- Publisher: @deciduus/calendar-mcp
- Categories: calendar-management / app-automation
- Hosted: No
- License: Other
- Source URL: https://www.modelscope.cn/mcp/servers/@deciduus/calendar-mcp
## 简介
暂无描述。
## MCP Server 详情

# Google 日历 MCP 服务器 (Python)

本项目实现了一个基于 Python 的 MCP（模型上下文协议）服务器，作为大型语言模型（LLMs）与 Google 日历 API 之间的接口。它使 LLMs 能够通过自然语言请求执行日历操作。

## 功能

*   **认证：** 使用 OAuth 2.0（桌面应用程序流，并自动存储/刷新令牌）安全访问 Google 日历 API。
*   **核心日历操作：**
    *   列出日历 (`mcp_google_calendar_list_calendars`)。
    *   创建日历 (`mcp_google_calendar_create_calendar`)。
    *   通过基本和高级过滤查找事件 (`mcp_google_calendar_find_events`)。
    *   创建详细事件 (`mcp_google_calendar_create_event`)。
    *   从文本快速添加事件 (`mcp_google_calendar_quick_add_event`)。
    *   更新事件 (`mcp_google_calendar_update_event`)。
    *   删除事件 (`mcp_google_calendar_delete_event`)。
    *   向事件添加参与者 (`mcp_google_calendar_add_attendee`)。
*   **高级调度与分析：**
    *   检查参与者的响应状态 (`mcp_google_calendar_check_attendee_status`)。
    *   查询多个日历的空闲/忙碌信息 (`mcp_google_calendar_query_free_busy`)。
    *   查找共同的空闲时间段并自动安排会议 (`mcp_google_calendar_schedule_mutual`)。
    *   分析每日事件数量和持续时间 (`mcp_google_calendar_analyze_busyness`)。
    *   *(在任务 3.5 中可能添加了重复事件预测功能，但尚未明确作为一个工具公开)*
*   **服务器：** 基于 FastAPI 的服务器，通过 RESTful API 暴露操作。
*   **MCP 集成：** 使用 `mcp_sdk` 库通过标准输入输出提供与 MCP 兼容的工具。

## 设置

1.  **先决条件：**
    *   安装了 Python 3.8+。
    *   安装了 Git。
    *   可以访问 Google Cloud Platform 项目。

2.  **克隆仓库：**
    bash
    git clone <repository-url> # 替换为你的仓库 URL
    cd <repository-directory>
    

3.  **Google Cloud 设置（OAuth 凭证）：**
    *   前往 [Google Cloud 控制台](https://console.cloud.google.com/)。
    *   创建一个新项目或选择一个现有项目。
    *   **为您的项目启用 Google 日历 API**。
    *   导航到“API 和服务” > “凭证”。
    *   点击“+ 创建凭据” > “OAuth 客户端 ID”。
    *   选择 **应用程序类型：桌面应用**。给它命名（例如，“Calendar MCP Local”）。
    *   点击“创建”。弹出窗口将显示您的 **客户端 ID** 和 **客户端密钥**。**现在复制这些信息** - 您将在 `.env` 文件中需要它们。您*不需要*下载其他应用程序类型提供的 JSON 文件。
    *   配置 **OAuth 同意屏幕**：
        *   将用户类型设置为“外部”。
        *   填写所需的应用程序信息（应用程序名称、用户支持电子邮件、开发者联系人）。
        *   添加范围：点击“添加或删除范围”，搜索 `calendar`，添加 `.../auth/calendar` 范围（读/写权限）。点击“更新”。
        *   添加测试用户：添加您将用于身份验证的 Google 帐户电子邮件地址。
        *   保存并返回仪表板。
    *   返回“API 和服务” > “凭证”，然后点击您创建的桌面应用程序凭据的名称。
    *   在“授权重定向 URI”下，点击“+ 添加 URI”，然后输入 `http://localhost:8080/oauth2callback`。点击“保存”。（如果您更改了 `.env` 中的 `OAUTH_CALLBACK_PORT`，请相应调整端口）。

4.  **环境配置（`.env` 文件）：**
    *   在项目的根目录中，复制 `env.example` 文件并将副本重命名为 `.env`。
    *   打开 `.env` 文件并粘贴从 Google Cloud 获取的 **客户端 ID** 和 **客户端密钥**：
        dotenv
        # Google OAuth 2.0 客户端凭证（来自 Google Cloud 控制台 - 桌面应用程序类型）
        GOOGLE_CLIENT_ID= YOUR_GOOGLE_CLIENT_ID_HERE 
        GOOGLE_CLIENT_SECRET= YOUR_GOOGLE_CLIENT_SECRET_HERE 

        # 用户 OAuth 令牌首次认证后存储的文件路径
        # 该文件会自动生成。默认是 .gcp-saved-tokens.json
        TOKEN_FILE_PATH= .gcp-saved-tokens.json 

        # OAuth 回调期间本地 Web 服务器的端口（必须与 Google Cloud 重定向 URI 匹配）
        OAUTH_CALLBACK_PORT=8080

        # Google 日历 API 范围（默认为读/写权限）
        # 对于只读访问，请使用 https://www.googleapis.com/auth/calendar.readonly
        CALENDAR_SCOPES= https://www.googleapis.com/auth/calendar*   确保 `TOKEN_FILE_PATH` 指向应用程序可以写入 token 文件的位置（通常是根目录下的默认文件 `.gcp-saved-tokens.json`）。此文件会自动添加到 `.gitignore` 中。

5.  **安装依赖项：**
    *   在终端中导航到项目目录。
    *   安装所需的 Python 包：
        bash
        pip install -r requirements.txt
        
    *   *(建议使用 Python 虚拟环境，但非必需)*

## 运行服务器（用于初始身份验证和测试）

您只需手动运行一次服务器以完成初始的 Google OAuth 身份验证流程。之后，您的 MCP 客户端将根据配置中的命令自动启动服务器。

1.  **首次运行（身份验证）：**
    *   从终端运行服务器脚本：
        bash
        python run_server.py
        
    *   脚本会检查保存的 token（`.gcp-saved-tokens.json`）。由于这些 token 尚不存在，它将：
        *   打印授权 URL。
        *   自动打开浏览器并跳转到该 URL。
        *   引导您登录 Google 帐户并授予日历权限。
        *   授权后，Google 会重定向回本地 URL (`http://localhost:8080/oauth2callback`)。
        *   脚本捕获授权码并将必要的 token 保存到 `.env` 文件中指定的位置（`.gcp-saved-tokens.json`）。
    *   一旦 token 保存成功，脚本通常会启动 FastAPI 服务器（例如，在 `http://localhost:8000` 上）。在看到 token 已保存或服务器已启动的确认信息后，您可以停止它（Ctrl+C）。

2.  **可选：直接测试服务器：**
    *   如果您想直接测试 FastAPI 服务器（例如，通过使用 `curl` 或 Postman 发送 HTTP 请求），可以再次运行 `python run_server.py`。它将加载保存的 token 并启动服务器，而无需浏览器身份验证。

**注意：** 对于常规使用 MCP 客户端的情况，在初始身份验证后，您**不需要**手动运行 `python run_server.py`。客户端会处理其启动。

## MCP 客户端配置（Cursor/Claude Desktop 示例）

要将此服务器作为工具在 MCP 客户端中使用，您需要配置客户端以运行 `run_server.py` 脚本。这通常在一个 JSON 设置文件中完成。

**示例 `mcp.json` 条目：**

json
{
  "tools": {
    "google_calendar": {
      "command": "python",
      "args": [
        "C:/path/to/your/calendar-mcp/run_server.py"
      ]
    }
  }
}


**配置详情：**

*   **`google_calendar`:** 您为 MCP 客户端内的此工具实例选择的唯一名称。
*   **`command`:** 如果 `python` 在系统的 PATH 中，则设置为 `python`。否则，请提供 `python.exe` 或 `python` 可执行文件的*完整绝对路径*（例如，`/path/to/your/venv/bin/python` 或 `C:/path/to/your/venv/Scripts/python.exe`）。
*   **`args`:** 提供项目目录中 `run_server.py` 脚本的*完整绝对路径*。**将占位符 `/path/to/your/calendar-mcp/run_server.py` 替换为您系统中的实际路径。**
*   **(可选) `api`:** 某些客户端可能仍需要 `api` 字段来指向底层的 FastAPI 服务器（例如，`"api": "http://localhost:8000"`），以便进行模式发现，尽管通信是通过 stdio 进行的。
*   **(可选) `timeout`:** 您可以添加超时时间（例如，`"timeout": 30000` 表示 30 秒）。

**工作原理：** 当 MCP 客户端调用此工具时，它会使用指定的 `command` 和 `args` 执行。`run_server.py` 脚本会检测到它是通过管道化的 stdin/stdout 运行的，并自动启动 MCP 通信桥接，而不是仅启动 HTTP 服务器。

**重要提示：**
*   您的 Google Client ID/Secret 保留在项目的 `.env` 文件中，*不在* MCP 客户端配置中。*   请参阅您特定的MCP客户端文档，以获取确切的配置文件位置和所需字段。

## 开发

*   **代码结构：**
    *   `run_server.py`：主入口点，处理服务器启动和MCP检测。
    *   `src/server.py`：FastAPI应用程序定义，HTTP端点。
    *   `src/calendar_actions.py`：与Google Calendar API交互的核心逻辑。
    *   `src/analysis.py`：高级分析功能。
    *   `src/auth.py`：处理OAuth 2.0认证流程和令牌管理。
    *   `src/models.py`：用于请求/响应数据结构的Pydantic模型。
    *   `src/mcp_bridge.py`：使用`mcp_sdk`实现MCP工具定义，并委托给FastAPI服务器。
*   **日志记录：** 日志将写入项目根目录下的`calendar_mcp.log`文件中。
*   **测试：** （待定）
*   **贡献：** （待定）

## 下一步（计划任务）

*   实现MCP资源/提示支持（任务6.1, 6.2）。
*   增强MCP工具参数验证和响应格式化（任务6.3, 6.4）。
*   改进MCP错误处理（任务6.5）。
*   优化开发工作流（任务7）。

## 许可证

本项目采用双许可模式，以支持开源协作和可持续发展：

1.  **GNU Affero通用公共许可证v3.0 (AGPL-3.0)：**
    *   该软件在AGPLv3许可证条款下免费使用、修改和分发。
    *   主要条件包括衍生作品（包括在网络中使用的修改版本）也必须在AGPLv3下许可，并且其源代码必须公开。
    *   该许可证适用于开源项目或内部使用，在这些情况下遵守AGPLv3是可行的。
    *   请参阅[LICENSE](LICENSE)文件以获取完整文本。

2.  **商业许可证：**
    *   如果AGPLv3的条款不适合您的特定用例（例如，将此软件集成到专有、闭源的商业产品或服务中而不遵守AGP…