evite-mcp

evite-mcp

一个适用于 Evite 的 Model Context Protocol 服务——既可以作为宾客（收到邀请），也可以作为主办方（创建活动）读取并管理活动：列出活动、查看宾客名单和 RSVP 统计、回复 RSVP、给宾客发送消息，以及创建／编辑活动。基于 @chrischall/mcp-utils 构建。

状态：读写工具均已上线。 五个读取工具可通过 Evite 的内部 API 工作，支持使用电子邮件／密码（一级认证，POST /ajax_login）、原始 Cookie 环境变量，或已登录的浏览器标签页（fetchproxy 引导）进行身份验证。十三个写入工具会先请求你确认——未经批准不会发送任何内容（参见确认），其端点均已在线验证（参见 docs/EVITE-API.md）；其中少数请求正文仍为推测，而非实际捕获（#3）。

工具

六个读取工具（均为只读）、十三个需确认的写入工具，以及 evite_healthcheck：

工具	端点	返回内容
evite_list_events	GET /services/events/v1/	你的活动 + 总数细分（filterBy = all/host/others，可重复指定 status，支持 offset/numResults 分页）
evite_get_event	GET /services/event/v1/{id}	单个活动的详情（活动、设置、地点）
evite_list_guests	GET /services/event/v1/{id}/guests/	宾客名单 + RSVP 回复（投递状态、查看情况、短链接）
evite_rsvp_summary	（根据宾客名单生成）	仅 RSVP 摘要（yes/no/maybe/noReply + 人数统计）
evite_list_messages	GET /services/event/v1/{id}/posts/	活动的消息讨论串
evite_list_templates	抓取 /invites/{category}/	邀请模板 slug（evite_create_event 所需的 template_name）+ 显示名称

写入工具（已确认）

每个写入工具在发送任何内容前都会要求你确认。能够显示确认提示的客户端（Claude Code）会显示将要发送的确切值（除非 MCP_CONFIRM_ELICITATION=off）。其他客户端（claude.ai、Claude Desktop）首次调用不会执行写入（最多进行只读查询 — 例如，evite_update_guest 会读取草稿宾客名单以生成确切预览），并返回该预览和一个 confirmToken；只有再次携带该令牌调用才会执行写入。令牌只能使用一次，会过期，并且绑定到特定工具和确切值 — 任何内容发生变化都会被拒绝（DRAFT_CHANGED），并返回新的预览。请参阅确认。端点均已验证；CSRF 令牌（X-CSRFToken，每次请求时都会重新读取，因为它会轮换）由中央逻辑附加。

工具	端点	操作
evite_rsvp	PUT /services/event/v1/{id}/guests/{guestId}	为宾客回复出席情况（回复 + 成人／儿童人数 + 可选备注）
evite_send_message	POST /tsunami/v1/services/event/{id}/guest/{gid}/messages	向一位宾客发送私信（假定正文已提供）
evite_broadcast	POST /tsunami/v1/services/event/{id}/broadcast/	一次向整个 RSVP 分组（virtual_groups）广播消息
evite_upload_photo	POST …/photos/v1/{id}/upload/request/ → GCS → 完成 → 共享相册	将本地图片上传到活动的共享相册（4 步 GCS 签名上传）
evite_create_event	POST /services/event/v1/ ({event:{…}})	创建活动草稿（需要 template_name；即使成功，API 也会返回 500）
evite_update_event	PATCH /services/event/v1/{id} ({event:{…}})	编辑活动（仅更改传入的字段）
evite_add_guest	POST /ajax/event/{id}/guestlist/draft/	将宾客添加到草稿（未发送）名单 — [{name,email}]
evite_update_guest	PATCH /ajax/event/{id}/guestlist/draft/	编辑草稿宾客的姓名／电子邮件／电话
evite_remove_guest	DELETE /ajax/event/{id}/guestlist/draft/{gid}	移除草稿宾客
evite_send	POST /services/event/v1/{id}/send/	“立即发送” — 向已准备好接收邀请的宾客发送电子邮件
evite_cancel_event	POST …/actions/cancel/	取消活动／删除草稿（有破坏性；可撤销）
evite_reinstate_event	POST …/actions/reinstate/	恢复已取消的活动
evite_duplicate_event	GET /plus/create/{id}/copy/ (→302)	将活动复制为一个新的草稿；返回新活动 ID

创作流程为 evite_create_event → evite_add_guest → evite_send。evite_send、evite_send_message、evite_broadcast 和 evite_cancel_event 会产生实际影响（发送电子邮件／取消通知），因此确认至关重要。

确认

变量	默认值
MCP_CONFIRM_MODE	ask-user	在无法显示确认提示的客户端（claude.ai、Claude Desktop）上，写入操作的处理方式。ask-user：分两步执行 — 首次调用不写入任何内容，并返回预览和令牌；模型必须先在聊天中获得你的批准，然后才能再次携带令牌调用。auto：同样分两步执行，但模型查看预览后可自行使用令牌。refuse：此类客户端上的写入操作会被拒绝。能够显示提示的客户端（Claude Code）始终会显示实际提示，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值会按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示始终不显示确认提示，因此所有客户端都会遵循 MCP_CONFIRM_MODE 的行为。对于声称能够显示提示但实际不会显示的客户端（写入操作会卡住 — opencode 2.0.x），请设置此项。任何其他值都按 on 处理，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；仅当令牌必须在服务重启后继续有效时才设置。

照片上传

变量	默认值
EVITE_UPLOAD_DIR	~/Downloads/evite-mcp	evite_upload_photo 可以读取的目录——一个或多个，以平台的路径分隔符分隔（macOS/Linux 上为 :，Windows 上为 ;）；允许使用 ~。相对路径会相对于第一个目录解析。对于这些目录之外的路径（包括符号链接），或其中的隐藏文件或目录，系统会在查看文件之前拒绝访问。请将要上传的照片放在 ~/Downloads/evite-mcp 中，或将此项指向其他位置。

架构

Fetchproxy-archetype MCP。Evite 没有公开 API，因此服务会使用你的会话调用 Evite 的内部 /services/ Web API。src/auth.ts 按优先级顺序解析会话：

1. EVITE_EMAIL + EVITE_PASSWORD（第 1 级，首选）——无头的邮箱/密码表单登录：将凭据 POST 到 https://www.evite.com/ajax_login，然后根据响应的 Set-Cookie cookie jar 创建会话（x-evite-session、evtsession、csrftoken、x-evite-features）。无需浏览器桥接，也无需手动复制 Cookie。必须同时设置这两个变量，否则解析器会继续尝试下一个方式。（已验证可用。）
2. EVITE_SESSION_COOKIE——从已登录的 evite.com 标签页复制的原始 cookie: 标头（或在 CI 中设置）。按原样使用。（已验证可用。）
3. Fetchproxy 引导（回退方式）——通过 @fetchproxy/bootstrap 从已登录的 evite.com 浏览器标签页提取会话 Cookie（x-evite-session、evtsession、x-evite-features、csrftoken）。这需要安装 ContextMint Bridge 浏览器扩展（Chrome：从发布页面下载 Chrome zip 并解压加载。Safari 目前尚不可用——它将随 ContextMint 应用一起发布，但该应用目前没有公开下载，因此暂时请使用 Chrome）。ContextMint Bridge 是 fetchproxy 浏览器扩展的新名称，由同一维护者提供。fetchproxy 自己的 README 中也指向了它。它的源代码公开于 nullnet-app/contextmint-bridge：你可以自行构建，或使用旁边发布的 .sha256 文件校验发布 zip（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。引导过程只运行一次；之后每次 API 调用都会通过普通的 Node fetch() 发送，并附带 Cookie。设置 EVITE_DISABLE_FETCHPROXY=1 可禁用此方式。（已验证可用。）

有一个级别会有意暂缓实现（解析器的结构已预留接入位置）：

• Fetchproxy 作为传输方式（通过浏览器桥接重试以绕过 bot 墙）——只有普通 fetch 遇到拦截时才需要的回退方式；探索期间未遇到此情况。

十三个写入工具（rsvp、add/update/remove-guest、send、send-message、broadcast、upload-photo、create/update/cancel/reinstate/duplicate event）都会先要求你确认（通过提示词，或通过预览 + 一次性 confirmToken；请参阅确认）。唯一的私有 client.write() 辅助函数会通过一个集中的标头（CSRF_HEADER = X-CSRFToken）附加 CSRF 令牌（csrftoken Cookie 会在会话期间轮换，因此每次请求都会重新读取）。端点分布在三个基址——REST /services/…、旧版 /ajax/event/{id}/… 客人列表，以及 /tsunami/… 消息服务——均已通过实际验证；少数请求正文仍为推测（#3）。

开发

npm install      # resolves @chrischall/mcp-utils from a local tarball (see issue #4)
npm run build
npm test

文档与路线图

• 设计规范：docs/superpowers/specs/2026-05-31-evite-mcp-design.md
• 计划 1（脚手架 + 技术验证）：docs/superpowers/plans/2026-05-31-evite-mcp-scaffold-and-spike.md
• 计划 2（身份验证 + 读取工具）：docs/superpowers/plans/2026-05-31-evite-mcp-auth-and-reads.md
• 内部 API 参考（已通过实时会话验证）：docs/EVITE-API.md

待完成工作： #3 — 写入端点和 CSRF 现已通过实时验证；仅有少数请求正文（send / send-message）仍是假设的。#4 跟踪共享库的发布事宜。（发现工作 #1、tier-1 电子邮件/密码登录 #2 以及读取工具均已完成。）

许可证

MIT