Calendar MCP Tutorial

Vercel活动日历（演示）

此存储库是基于MCP的事件日历服务器的Vercel兼容演示。

• API终点： /api/mcp
• 前端： public/index.html （简单的聊天界面）

快速本地测试

1. 安装dev-deps进行本地测试：

python -m pip install -r requirements.txt

1. 运行测试线束：

python test_local.py

部署到Vercel

1. 确保 vercel CLI已安装并登录。
2. 跑 vercel deploy 并按照提示进行操作。
3. 您的无服务器端点将在 `https://

.vercel.app/api/mcp`.

Microsoft Outlook连接（顶部按钮）

• 标题按钮 Connect to Microsoft Calendar 现在调用后端端点：

- GET /api/oauth/microsoft/start

• 此端点构建Microsoft OAuth授权URL并重定向浏览器。
• OAuth回调端点：

- GET /api/oauth/microsoft/callback - 交换令牌的授权码，获取 displayName 来自Graph /me，然后重定向到 index.html 随着 ms_name 查询参数。 - 前端读取 ms_name 并展示 Connected: 在右上角的标题中。

• 所需的环境变量：

- MS_CLIENT_ID （或 MICROSOFT_CLIENT_ID)

• 回调令牌交换所需：

- MS_CLIENT_SECRET

• 可选环境变量：

- MS_TENANT_ID （默认值： common) - MS_REDIRECT_URI （默认值： /api/oauth/microsoft/callback) - MS_SCOPES （默认值： offline_access User.Read Calendars.ReadWrite)

• 如果缺少配置，前端将回退到 public/redirect_microsoft.html 所以按钮在dev中仍然有响应。

备注

• Vercel无服务器函数是无状态的——事件存储在内存中 将重置 经常。

• 演示包括 会话的 handle_message 接受简洁命令和自然语言的工具。示例：

- list 或 list events → 列出所有事件 - list events on 2026-01-01 或 What's on 2026-01-01? → 列出该日期的事件 - summarize / summary / what's coming up → 即将举行的活动摘要 - add:Title|YYYY-MM-DD|Desc （简写，仍受支持） - Add Birthday on 2026-02-01 about cake → 会话添加 - Create Meeting on 2026-03-03 → 会话添加 - Add Meeting tomorrow → 支持 today 和 tomorrow - delete:Title 或 delete Meeting 或 remove Meeting → 按标题删除

如果消息不被理解，处理程序将返回一个带有示例的简短帮助文本。

时间意识添加

• 要添加具有特定时间使用的事件：“添加 在YYYY-MM-DD的HH:MM（24小时）。示例：“添加2026-02-01 14:30的会议”。
• 时间紧迫： add:Title|YYYY-MM-DD HH:MM|Desc.

最近的更改（开发人员说明）

• 时间解析：聊天解析器现在只识别日期和日期+时间标记（上面的示例）。它接受 YYYY-MM-DD, YYYY-MM-DD HH:MM，以及 YYYY-MM-DDTHH:MM （24小时）。还支持带时间的月份名称日期，如“3月5日下午3点”。
• ICS导出：一个新的端点 GET /export.ics 从内存中的事件构建一个最小的iCalendar文件。有时间的事件产生定时 DTSTART 价值观；仅限日期的事件导出为全天 DTSTART;VALUE=DATE.
• 结束时间范围和DTEND：解析器现在可以识别简单的时间范围（例如“下午3点到5点”，“下午3时至5点”），并存储 end 事件存在时的价值。这 .ics 出口商排放a DTEND 在可能的情况下，针对此类事件。

重复选项（UI+服务器）

• 创建事件后显示的新快速重复选项：

- 无提醒 - 每天 - 每隔一天 - 周刊 - 每两周 - 工作日（周一至周五） - 每月（每月同日） - 每月第X天（提示要求输入日期） - 自定义（提示要求输入数字间隔，解释为天）

计划调试笔记

• create_tasks 需要命名输入参数 plan。客户端请求必须使用：

- {"tool":"create_tasks","input":{"plan": }}

• 计划行动领域包括 Export .ics now 下载按钮 .ics 从 /export.ics.
• 学生计划导出包括 Export by Student 选项和内联导出范围标签。

- 范围选项： - 所有日历事件（默认 Export .ics 按钮） - 所有被选中的学生(/export.ics?students=name1,name2) - 一名学生(/export.ics?student=name)

• 学生课程里程碑现在包括事件描述中的个性化目标文本。
• 浏览器规划诊断以前缀记录 [plan-client].
• 服务器处理程序诊断以前缀记录 [mcp-handler].
• 如果任务创建失败，请先比较两个日志以确认有效负载形状和工具验证路径。

在哪里编辑行为

• 服务器重复逻辑： set_recurrence(title, frequency, interval) 在 main.py

- 用于计算的简单步进算法 next_due. - 对于生产级重复处理，请替换为RFC5545 RRULE库（python dateutil RRULE），并将重复持久化到DB/KV。

• 重复选项的客户端UI提示： showRecurrencePrompt(title) 在 public/script.js.

- 要添加/删除选项，请编辑此函数中的HTML和处理程序逻辑 monthly_on_day / custom 提示。

备注

• 当前实现将重复元数据存储在内存事件列表中。坚持使用DB/KV进行实际使用。
• monthly_on_day 使用interval参数来携带月份中的日期。

在哪里编辑代码（快速指针）

• main.py --核心工具和解析：

- add_event(title, date, description) --验证和存储（现在接受时间）。 - handle_message(message) --会话解析器；日期检测存在 find_date_in_msg() 时间标准化 parse_time_token(). - /export.ics route--构建并返回.ics文件。

• public/index.html --UI：编辑器、工具提示/示例、身份验证按钮、， Export .ics 链接。
• public/script.js --欢迎消息、测试登录处理程序和网络调用 /api/mcp.
• public/style.css --编辑器、身份验证按钮和标题控件的视觉样式。
• api/mcp.py --用于Vercel部署的无服务器包装器（保持CORS处理和工具调用整形）。

如果您计划扩展功能：

• 添加结束时间解析（DTEND）并更新 .ics 世代包括 DTEND.
• 添加时区处理（存储时区或转换为UTC）；iCalendar事件受益于显式的TZ或UTC时间戳。
• 添加以下单元测试 find_date_in_msg() 和 parse_time_token() 以验证解析边缘情况。

前端改进：

• 聊天UI现在支持键入指示符、时间戳、头像、复制到剪贴板按钮、换行符的Shift+Enter、发送的Enter和对话持久化 localStorage作曲家在后端响应时显示微调器，并禁用输入，直到收到回复。

聊天重新设计说明

• UI重新设计的核心文件：

- public/index.html （布局） - public/style.css （视觉造型） - public/script.js (renderMessage, showTyping，计划器动作绑定）

• 保持计划器动作类挂钩完好无损(.create-tasks-btn, .export-ics-btn)除非你也更新JS选择器。
• 保留上的可访问性行为 #messages (role="log" + aria-live="polite").
• 重新设计后端到端重新测试计划流程：计划生成→ 创建任务→ 出口 .ics.

发展与贡献

如果您计划编辑或扩展此项目，请参阅 DEVELOPING.md 获取详细的开发人员指南（设置、编辑前端和后端、测试和部署到Vercel）。

贡献应遵循每个功能分支的工作流程，并包括明确的提交消息（使用前缀，如 feat:, fix:, style:，或 docs:).请在合并到主分支机构之前打开一个PR进行审查和测试。

编辑和定制

• 按钮（UI）：编辑中的登录按钮 public/index.html这两个按钮是 #signinGoogle 和 #signinMicrosoft 在标题的内部 .auth-controls 元素。在那里更改标签文本或类。

• 按钮行为（客户端）：修改中的单击处理程序和模拟响应 public/script.jsThe testSignIn(provider) 功能（或 startOauth(provider) 如果你恢复OAuth）控制着点击时会发生什么。要还原真正的OAuth，请将处理程序连接到 startOauth('google') / startOauth('microsoft').

• 重定向页面：小着陆页是 public/rerect_google.html 和 public/rerect_microsoft.html。它们对外部站点执行1s元刷新；如果需要，可以编辑这些文件中的副本或目标URL。

• 主题/颜色：颜色变量位于顶部 public/style.css.更改 --bg, --panel-bg, --text, --accent，以及 --send 调整调色板。默认主题设置在 public/script.js (loadTheme() 使用本地存储密钥 ui_theme).要再次默认为深色，请在中设置默认值 loadTheme().

• 头像和图标：头像样式在 public/style.css 在...之下 .message .avatar.更新 color, background，或边界半径以更改其外观。表情符号头像被呈现为文本；集 color 为了对比。

• 后端工具：服务器端MCP工具已上线 api/mcp.py 消息处理程序可用作 handle_message 工具。如果添加调用后端工具的新UI控件，请确保POST主体与前端使用的MCP形状匹配({ tool: 'tool_name', input: { ... } }).

• 本地测试：运行快速测试线束：

python -m pip install -r requirements.txt
python test_local.py
# then open http://localhost:3000 (or the printed URL)

• 承诺与推动：推荐的提交模式：

git checkout -b feat/your-feature
git add 
git commit -m "feat: brief description"
git push origin HEAD:copilot/integrate-oauth-email-login

• 恢复OAuth：如果要重新启用OAuth流，请在中还原测试处理程序 public/script.js 打电话 startOauth(provider) 并在中重新启用服务器端OAuth代码 oauth_manager.py 以及任何 api/oauth_*.py 回调。同时更新OAuth提供者控制台中的提供者重定向URI，以指向您部署的回调端点（例如。， /api/oauth_google).

这些注释为应用程序中最常编辑的部分提供了快速地图。如果你愿意，我可以加一个简短的 DEVELOPING.md 具有相同的内容和PR的小清单。

确切位置

为了快速编辑，以下是常见编辑的确切文件位置和行范围：

• 登录按钮： public/index.html
• 客户端处理程序和助手： public/script.js (startOauth 在 public/script.js, testSignIn 在 public/script.js, loadTheme 在 public/script.js)
• 消息呈现助手（&A）： renderMessage 在 public/script.js, addLocalMessage 在 public/script.js
• 主题变量（调色板）： public/style.css
• 登录按钮样式： public/style.css
• 头像样式： public/style.css
• 重定向页面： public/rerect_google.html 和 public/rerect_microsoft.html

进行小编辑时使用这些链接；它们直接指向工作区中的相关行。

UI中显示的自然语言示例

聊天UI显示示例输入以帮助用户。您可以在下面的UI文件中编辑这些行：

• 欢迎/预热消息（显示为第一条机器人消息）： public/script.js --寻找 addLocalMessage(...) 包含欢迎文本的呼叫。
• 底部帮助行（作曲家下方显示的简短示例）： public/index.html --编辑 p.help 段落。

当前示例字符串（复制/粘贴到测试或README中）：

• “添加2026-02-01的生日”
• “添加3月5日关于规划的会议”
• “明天加午餐”
• 速记： add:Title|YYYY-MM-DD|Desc

编辑这些文件以更改措辞、添加更多示例或本地化文本。

编辑测试登录按钮

UI中的这些按钮目前作为本地测试按钮连接（它们不执行OAuth）。要编辑它们或更改其行为，请执行以下操作：

• 文件： public/index.html

- 按钮： #signinGoogle 和 #signinMicrosoft 在标题下 .auth-controls. - 直接在此文件中更改按钮标签或标记。

• 文件： public/script.js

- 测试处理人员： testSignIn(provider) 模拟登录。编辑或替换此函数以更改测试行为。 - 要恢复真实的OAuth行为，请将点击处理程序替换为 startOauth(provider) 电话：

// example: restore OAuth start
document.getElementById('signinGoogle').addEventListener('click', () => startOauth('google'));
document.getElementById('signinMicrosoft').addEventListener('click', () => startOauth('microsoft'));

• 本地快速测试：

# start the local test harness
python -m pip install -r requirements.txt
python test_local.py

# open the app at http://localhost:3000 (or the port printed by the harness)

• 提交并推动更改：

git add public/index.html public/script.js README.md
git commit -m "chore: add test sign-in buttons and docs"
git push origin HEAD:copilot/integrate-oauth-email-login

这些注释使UI测试保持友好，并使以后重新连接按钮以实现真正的OAuth流变得容易。