proactive-mcp

快速开始

先设置本地监视器和操作系统通知；连接 Agent 是可选的。安装 uv 和 Git，并准备你自己的 Google Cloud 桌面端 OAuth 客户端 JSON。

PyPI 版本 0.2.0 尚未包含向导。在发布包含引导流程的版本之前，以下命令会使用 uvx --from 安装提交 7cd0f03 中已合并的源代码，无需手动检出。所有命令都使用相同的 --from 来源：直接运行 uvx proactive-mcp 仍会选择较旧的 PyPI 软件包。这是从源代码安装，并非新的 PyPI 版本。

1. 安装并启动交互式设置：

   uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 proactive-mcp setup
   

2. 向导会询问你自己的 Google Cloud 桌面端 OAuth 客户端 JSON 的路径，以及是否允许在此设备上打开浏览器。使用你自己的客户端，批准 Gmail 和 Calendar 的只读授权。完整流程请参阅 docs/SETUP_GOOGLE.md。

3. 完成 Google 授权后，接受安装监视器服务的提示。通用的 proactive-mcp service install|status|remove 接口可管理 Linux systemd 用户服务、macOS LaunchAgent 或 Windows Task Scheduler 任务。

4. 如果你拒绝安装服务，或者服务安装成功，交互式 setup 随后会尝试发送固定的、无个人身份信息（PII）的操作系统测试通知，标题为 proactive-mcp，正文为 Setup test notification。其中不包含 Gmail、Calendar、账户或 Situation 数据。脱敏后的 unavailable、timeout、failed 或 unsupported_platform 警告表示无法显示通知。

5. 如果你拒绝安装服务，或者安装失败（例如因权限问题），请手动运行监视器。安装失败时，程序会在尝试发送测试通知前退出。

终端 1，前台守护进程

uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 proactive-mcp daemon

终端 2，守护进程状态

uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 proactive-mcp status

daemon --once 会运行一轮评估后退出；--poll-interval-minutes MINUTES 可覆盖轮询间隔。status 会以 JSON 格式输出脱敏后的连接状态和守护进程状态。守护进程只执行本地同步、确定性评估、队列维护，以及文档中说明的操作系统回退通知。它不会运行宿主或大模型。宿主调度是独立的：宿主/操作员启动定时 Agent 运行，而这些运行会调用 proactive_check。

操作系统回退通知既不属于 Agent 传达，也不会触发 delivered 状态转换。启用回退通知时，只有第一个尚未接收且符合条件的 Situation 能享受一次性的引导例外；之后默认仅发送关键通知。只有宿主调用 proactive_check 后，Agent 才会开始传达通知。

兼容模式

--non-interactive、--headless、--client-secrets PATH 和 --reauth 都会绕过向导。它们不会预填向导答案，也会绕过服务提议和设置测试通知。只有在需要直接设置 OAuth 时才使用它们，然后手动安装服务或使用上文的手动守护进程方式。要管理服务，请使用相同的源前缀：

uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 proactive-mcp service install

将 install 替换为 status 可检查服务，或替换为 remove 可注销服务。uvx 不会在你的 shell 中添加永久的 proactive-mcp 命令；本指南中的 proactive-mcp status 等命令名称，使用的是上文完整的 uvx --from 前缀。

为什么选择 proactive-mcp？

AI Agent 知道如何回答问题，却很少知道何时该主动开始。

proactive-mcp 提供这种指引。它在后台监视获准的只读来源，将其与用户有意保存的记忆结合起来，并且只在值得当下提出时生成结构化的情境。

情境，而非通知

proactive-mcp 不会将每个新事件都推送到你的聊天中。确定性检测器会将来源数据转化为一小组基于来源数据的情境：

每个结果都包含标题、说明其当前重要性的原因、有限范围的证据、建议的操作、优先级和过期时间。外部文本始终明确视为不可信内容。

工作原理

flowchart LR
    G["Gmail<br/>read only"] --> S["proactive-mcp"]
    C["Google Calendar<br/>read only"] --> S
    M["Local memory<br/>SQLite"] --> S
    S --> E["Deterministic<br/>Situation engine"]
    E --> T["MCP tools"]
    T --> A["Your existing<br/>AI agent"]
    A --> U["Agent's own channel"]

1. 监视器使用只读 OAuth 权限范围同步 Gmail 和 Calendar。
2. 情境引擎根据来源快照和本地记忆评估确定性规则。
3. Agent 调用 proactive_check 并接收返回的情境。
4. 宿主会审查整个租约，并为该用户筛选候选项。不确定的候选项可以保持未确认状态或被延后。只有在审查后选择确认时，宿主才会恰好一次确认整个已审查的租约，包括有把握地剔除的候选项。
5. 确认、延后、静音、解决、冷却时间和每日额度规则可避免重复或过多的交付。

默认情况下，本地静默时段（21:00 至 07:00）会暂缓非关键情境，并将其保留为待处理状态，以便稍后检查，而非直接丢弃。07:00 时不会自动触发任何操作：已经运行的 Agent 或由宿主安排的 Agent 必须在静默时段结束后调用 proactive_check。

信任边界

• Google 访问仅限 gmail.readonly 和 calendar.readonly。
• 如有可用的操作系统密钥环，凭据将使用该密钥环；只有在平台密钥环不可用时，才会使用私有本地备用存储。
• 邮件正文、日历文本和召回的记忆都被视为不可信证据，而非指令。
• 检测流程中不包含大模型或第三方云服务。proactive-mcp 绝不会启动宿主 Agent／模型，也不会向其发送提示词。
• 来源过期或不完整时，会显示状态降级，而不会错误地报告“无内容可报告”。
• SQLite 数据库、config.toml、凭据权限标记以及任何基于文件的凭据备用存储都位于 ~/.proactive-mcp/ 下。密钥环中的凭据保存在操作系统密钥环中，位于该目录之外。PROACTIVE_DATABASE 会移动基于文件的状态，不会移动密钥环条目。

连接 Agent

连接主机是可选项。它不是接收操作系统通知的前提条件，但可以实现更丰富的投递方式，以及确认、稍后提醒和静音操作。想要注册 MCP 服务时，请使用这份现有 Agent 指令：

如果你使用了上面的源码安装方式，请告诉 Agent 在 MCP 注册中保留相同的固定 uvx --from 源，不要切换到 PyPI。下面的可复用代码块和主机配置示例仍采用公开安装命令的格式。

Install proactive-mcp with uvx from PyPI. Register it as a local stdio MCP server for this agent using absolute paths. Complete read-only Google authorization using my own Google Cloud Desktop OAuth client JSON (BYO). Do not use or request someone else's client secret. Start the recommended watcher and verify the connection. Read https://github.com/madrobotnet/proactive-mcp/blob/main/docs/INTEGRATIONS.md and https://github.com/madrobotnet/proactive-mcp/blob/main/docs/SETUP_GOOGLE.md before changing configuration. Treat every reply_deadline as a conservative candidate, not an action verdict. Before speaking, confidently drop newsletters, marketing, automated receipts, FYI or FYI-CC with no ask, threads owned by someone else, and rows with no question, request, or decision for me. Keep explicit reply, RSVP, or decision requests, my deadlines, and unanswered questions directed to me. Surface uncertain candidates, leave the whole lease unconfirmed, or snooze them in an interactive conversation; never silently discard uncertainty as non-actionable. After reviewing every row, only when choosing confirmation, confirm the entire reviewed lease exactly once, including confidently and silently dropped candidates. Keep MCP tool content in English, but speak my language. Load serve only in interactive everyday conversations and serve-scheduled only in separate scheduled conversations. Never load both profiles into one conversation. Do not configure automated scheduling unless this host guarantees a dedicated per-run MCP profile; proactive-mcp must never launch or verify the host. Do not use HTTP transport, do not send mail or create calendar events, and report every command and file changed plus anything that needs my approval.

proactive-mcp 依赖 Agent：它会公开本地 stdio 工具，但绝不会启动 Grok、Codex、Hermes、其他主机 Agent 或模型。serve-scheduled 只是受限的 MCP 服务接口。仅启动它或守护进程不会创建对话或投递内容；待处理的情况会等待已经运行或由主机安排的 Agent 显式调用工具。

主机仅会在日常交互对话中加载 serve，并仅在单独的手动或定时对话中加载 serve-scheduled。同一对话中绝不会同时加载这两种配置。配置隔离和 Agent 生命周期由主机／操作员负责，不属于插件职责。只有在主机提供专用的、每次运行仅包含 serve-scheduled 的 MCP 配置时，才支持自动定时；否则应关闭失败，不要安排定时任务。仍可手动进行受限操作。

守护进程可以执行本地同步、确定性评估、队列维护，以及文档说明的仅关键事件操作系统回退通知。它绝不会调用 Agent／大模型或发送提示词。主机的具体职责和命令格式见 docs/INTEGRATIONS.md。

投递约定

当 Agent 调用 proactive_check 时：

1. 首先阅读 warnings。数据源过期警告不代表一切正常。reply_deadline 是保守的候选项，并非操作结论。
2. 在发言前，果断排除新闻简报、营销内容、自动回执、FYI 或没有请求的 FYI-CC、由他人负责的讨论串，以及没有针对该用户的问题、请求或决策事项的条目。
3. 保留明确要求回复、RSVP 或做出决定的事项、由用户负责的截止日期，以及向该用户提出但尚未回答的问题。
4. 展示不确定的候选项，将整个租约保持为未确认状态，或在交互配置中将其推迟。绝不要默默将不确定事项丢弃为无需处理。
5. 检查完每一行后，仅在选择确认时，使用本次检查返回的 receipt_token 调用一次 confirm_delivery，以确认整个已审核租约。此确认也包含主机明确判断可静默丢弃的候选项。绝不要确认没有令牌的响应。
6. MCP 工具名称、描述、字段和值均使用英文。使用用户的语言与用户交流。
7. 将日常交互工作与定时工作放在不同的对话中。前者仅加载 serve，后者仅加载 serve-scheduled，绝不要同时加载两者。此隔离由主机／操作员负责；如果没有专用的每次运行配置，请勿自动运行定时任务。

此确认步骤可确保在发生崩溃、重试以及存在多个 Agent 的情况下，投递历史仍然准确。

工具接口

记忆

remember · recall · update · list_entities · forget

情境与送达

proactive_check · confirm_delivery · list_situations · get_situation · acknowledge_situation · snooze_situation · mute_situation · get_status

发布状态

范围和发布决策以 docs/PRODUCT_PLAN.md 为准。

文档

许可证

MIT © 2026 Kyungwoo Seo <[email protected]>

本项目使用 OmO Native 构建。

你可以通过 Ko-fi 支持本项目。