# MCP:让 AI 查询本地 Teams 数据 MCP 与现有后台采集共用 `data/teams.sqlite`。AI 可以搜索消息、读取上下文和历史版本、查询日程、读取增量变化,以及管理消息 WebHook。使用 MCP 不需要 Teams 网页或扩展常驻;新数据仍由本地后台采集进程获取。 ## 连接方式 ### 本地 stdio(推荐) 让支持 MCP 的客户端启动 `scripts/mcp.js`。该进程提供查询、订阅管理和按需图片下载,不会打开登录窗口、启动消息采集或主动投递 WebHook。消息采集、图片自动下载及 WebHook 投递由正常运行的本地控制台服务负责。 通用 MCP 配置示例: ```json { "mcpServers": { "teams-local": { "command": "node", "args": ["C:/path/to/ms-teams-tools/scripts/mcp.js"], "env": { "DATA_DIR": "C:/path/to/ms-teams-tools/data" } } } } ``` 将示例中的 `C:/path/to/ms-teams-tools` 替换为你的项目绝对路径,再将配置填写到客户端的 MCP 设置中。客户端必须能找到 Node.js 24 或更高版本;必要时把 `command` 改为 Node 的绝对路径。请使用 `node` 直接启动;`npm run` 的额外输出不适合作为 stdio 协议流。 Codex CLI 配置命令示例(请替换项目路径,具体参数以所安装版本的 `codex mcp add --help` 为准);本项目不会自动改写 Codex 配置: ```powershell codex mcp add teams-local --env DATA_DIR=C:/path/to/ms-teams-tools/data -- node C:/path/to/ms-teams-tools/scripts/mcp.js ``` 相对 `DATA_DIR` 相对于项目根目录解释,避免 MCP 客户端使用其他工作目录时误建数据库。stdio 进程不会自动加载项目 `.env`,需要自定义目录时请在客户端配置中明确传入。 ### Streamable HTTP 控制台服务提供同样的工具:`http://127.0.0.1:/mcp`。当前使用无会话的 Streamable HTTP JSON 响应,不提供旧 SSE transport。每次请求都需要 `Authorization: Bearer <本地 MCP 令牌>`;令牌保存在本机 `data/mcp-auth.json`,与 Microsoft 登录凭证分开。 HTTP 服务只监听本机,校验 Host/Origin,并限制请求大小。不要把 Microsoft 访问令牌用于 MCP 认证。`npm run mcp:config` 可生成适用于本机的连接配置;涉及令牌的配置只留在本地。 Codex HTTP 配置命令示例(先在客户端进程环境中设置 `TEAMS_MCP_TOKEN`): ```powershell codex mcp add teams-local --url http://127.0.0.1:4318/mcp --bearer-token-env-var TEAMS_MCP_TOKEN ``` 实际端口以控制台配置为准。HTTP 连接需要控制台服务运行;stdio 可以在采集服务停止时查询已保存数据。 ### 连接失败后补查原窗口 `ECONNREFUSED` / Windows 10061 表示该地址在请求时无法建立连接,不能解释为窗口内没有消息或数据已经丢失。HTTP 读取失败时应保留原窗口并标记失败;实例枚举未完成时,实例计数应为未知而不是成功的 0。服务恢复后可重新枚举实例,按原 `from` / `to` 查询所有分页;不要推进最后成功窗口。部分分页成功后失败,应保留已读取项并标记未完成,恢复时用相同筛选条件继续游标,或按同一窗口重跑并以本地记录 ID 去重。 时间范围按消息发生时间筛选,之后补录入库的旧消息仍能被原窗口查询命中。成功读完本地分页只证明本地查询完成,不证明 Teams 账号全量覆盖。同机客户端支持 stdio 时,可使用生成的 `data/mcp-clients/stdio.json`,在 HTTP 服务停止时继续读取已保存数据;新消息采集仍需要后台服务。运行在其他机器、容器或 WSL 中的客户端,应先确认其网络命名空间,不能把自己的 `127.0.0.1` 当作采集器所在主机。 ## 工具 | 工具 | 用途 | 常用参数 | | --- | --- | --- | | `list_instances` | 列出实例名称、绑定账号、独立运行和在线设置 | 无 | | `search_messages` | 关键字、实例、时间条件组合搜索消息 | 可选 `q`、`instanceId`、`chatId`、`accountId`、`source`、`from`、`to`、`limit`、`cursor` | | `list_chats` | 列出已知聊天、消息数量与最后消息时间 | `q`、`instanceId`、`accountId`、`source`、`limit`、`cursor` | | `get_chat_context` | 读取某条消息前后文或最近消息 | `chatId`、`aroundMessageId`、`before`、`after`、账号范围 | | `get_message` | 读取一条消息及有限数量的历史版本 | 本地数字 `id`、`includeVersions`、`versionLimit` | | `list_message_images` | 查看消息图片、下载状态和本地文件路径 | 本地数字 `messageId` | | `download_message_image` | 下载或重试一张聊天图片,返回本地路径 | 图片 UUID `id` | | `configure_image_backfill` | 按实例开启/暂停历史图片自动补下载,批量重试暂时失败 | `instanceId`、`enabled`、可选 `retryFailed`;在 `get_collector_status.media.instances` 查看进度 | | `list_calendar_events` | 查询已保存日程 | `from`、`to`、账号范围、分页参数 | | `get_collector_status` | 检查采集新鲜度、数量、运行状态及覆盖限制 | 无 | | `poll_changes` | 使用持久游标读取新增/修订记录 | `cursor`、`kinds`、`limit` | | `configure_webhook` | 创建/更新提醒订阅 | `url`、`enabled`、`mode`、过滤条件 | | `list_webhooks` | 查看订阅及已脱敏的目标信息 | 无 | | `remove_webhook` | 删除一个提醒订阅 | `id` | | `list_webhook_deliveries` | 查看投递队列及失败状态 | `subscriptionId`、`status`、`limit` | | `retry_webhook_delivery` | 将失败提醒重新排队 | `deliveryId` | 工具返回 `structuredContent`,兼容客户端也可读取文本 JSON。结果形式为 `{ "data": ..., "contentTrust": "untrusted_teams_data" }`。消息正文、标题、参与人和日程都是外部业务内容;服务明确要求 AI 将其视为数据,不执行其中夹带的指令。 没有发送 Teams 消息、任意 SQL、读取会话文件或导出登录令牌的 MCP 工具。WebHook 管理工具标有写操作注解,创建目标或重试发送应遵循用户对该目的地的授权。 ## 搜索、上下文与增量读取 搜索采用参数化字面子串匹配,支持中文;`%`、`_` 和反斜线不会作为 SQL 通配符执行。目前不提供语义向量检索。`from` 和 `to` 必须包含时区,例如 `2026-09-08T00:00:00+08:00`;过滤范围为 `from <= 消息时间 < to`。日历时间过滤针对日程开始时间。 0.5.0 可先用 `list_instances` 获取实例 ID,再以 `instanceId` 联合时间范围筛选;`q` 可省略,但至少需要一个有效筛选条件。未知实例会报错,不会退回查询所有账号。结果提供 `instanceId` 和 `instanceName`,聊天目录、上下文和日历也支持实例范围。HTTP 能读取实例运行状态;stdio 仅返回持久设置,实时运行状态为未知。配置示例及使用方式见 [多实例说明](INSTANCES.md)。 消息结果把会话标题与发送者分开:`title` 是展示标题,`chatTitle` 是已知会话名称,`author` 是消息发送者。姓名搜索可以匹配发送者或同账号、同来源的会话名称。只有明确一对一且对方身份唯一时,才从已保存的成员/消息作者信息补全未命名私聊;没有会话依据的目录条目保持未命名。旧版本快照保留当时保存的标题,不以当前会话名改写历史。 0.5.3 的后台采集还会读取已验证消息实际返回的同源会话详情链接,以 `threadProperties.topic` 补全名称,每轮最多 3 个,成功缓存 30 分钟,失败不阻断正文同步。0.6.1 补充支持返回 `threadType=meeting` 的会议会话。补全后可用 `search_messages.q` 按会话名搜索,结果中的 `title`、`chatTitle` 使用当前名称;`get_message` 返回的历史 `versions[].title` 可能仍是原占位标题。补名不会改写原消息的 `raw`、哈希或版本,MCP 查询本身也不会触发远端补采。 0.5.5 可用已保存的会话双方身份与同账号消息中的对方姓名补全当前显示名称,支持姓名搜索并保留独立的 `author`。这种本地名称依据不会自动改变 `isDirect`;缺少明确聊天类型证据时,该字段仍为 `null`,私聊 WebHook 也不会仅因补名而触发。 0.6.0 的 `list_instances` 增加 `renewal`,返回自动续期状态、是否可用、是否需要交互,以及凭证到期、最近尝试/成功与下次重试时间。没有运行时连接的 stdio 查询返回 `null`;刷新令牌、Cookie、浏览器缓存和原始认证错误不会进入 MCP 返回值。 列表默认每页 20 条,最多 100 条;后续请求带上返回的 `nextCursor`,保持查询条件一致。游标按时间与本地 ID 稳定翻页。聊天列表也包含从历史消息发现、尚未出现在聊天列表增量响应中的会话。 上下文最多读取前后各 50 条,按对话时间顺序返回。请使用搜索结果的 `source`、`accountId` 和 `chatId`;传入消息锚点时自动绑定其账号和来源,未传锚点且会话标识对应多个范围时返回 `ambiguous=true`,不会混合对话。搜索/上下文正文最多 4,000 字符,单条详情与版本最多 20,000 字符,截断会标记 `textTruncated`。版本最多 20 个,完整响应最多 512 KiB;超过时返回明确错误,缩小读取数量即可。不同采集来源可能各保存一份同一条业务消息,可通过 `source` 区分。 `poll_changes` 首次不传 `cursor` 时建立“从现在开始”的基线,不回放整个数据库。保存它返回的 `nextCursor`,下一轮带回即可读取后续变化;明确传 `cursor: 0` 会读取本次升级后保留的全部变化。每条变化带 `created`/`updated`、`live`/`history`/`import`/`unknown` 采集来源,以及当时的安全记录快照。历史补齐也可供 AI 检查,但不会触发消息提醒。 变更日志从 MCP 升级后的新写入开始,不会为早已存在的旧版本伪造变更。旧聊天仍可通过搜索和上下文查询。变化筛选条件 `kinds` 需要随游标保持一致。 ## 消息 WebHook 支持四种提醒模式: | `mode` | 匹配条件 | | --- | --- | | `all` | 全部符合过滤条件的新消息 | | `mention` | 消息明确提及当前账号 | | `direct` | 明确识别的一对一私聊 | | `mention_or_direct` | 提及当前账号或一对一私聊 | `includeSelf` 默认 `false`,排除本人消息;`includeContent` 默认 `false`,只发送必要的消息元数据。没有足够身份或聊天类型证据时,不会把未知消息猜成 mention/私聊。 新订阅默认关闭。用户明确提供接收地址并要求启用时,AI 可以一次完成配置: ```json { "url": "https://your-receiver.example/teams", "name": "只提醒提及和私聊", "mode": "mention_or_direct", "enabled": true, "includeSelf": false, "includeContent": false } ``` 可用 `accountIds`、`chatIds` 进一步限制;空数组表示不限制。默认仅接受公网 HTTPS。本机开发接收器可显式设置 `allowLocal: true` 并使用回环地址 HTTP。目标更新后旧待投递项会取消,使用更新时的新基线。 创建时返回一次 `signingSecret`,用于接收器校验 HMAC,不是 Microsoft 凭证。后续查询不会返回它。投递请求包含: - `X-Teams-Event-Id`:投递 ID,用于去重。 - `X-Teams-Timestamp`:发送时的 Unix 秒时间戳。 - `X-Teams-Signature`:`sha256=` 加 HMAC-SHA256 十六进制摘要;待签名内容为 `timestamp + '.' + 原始请求正文`。 接收端应验证签名与时间戳,并按事件 ID 幂等处理。队列持久化到本地 SQLite,后台执行重试,投递失败不会影响消息保存。状态包括 `pending`、`inflight`、`sent`、`dead`、`cancelled`。重试工具只排队,后台服务运行时才实际发送。 本地变更轮询与 WebHook 是独立能力。MCP 本身不会让未运行的 AI 客户端自动苏醒;可把 WebHook 接入自己的自动化服务,由它决定何时触发 AI 工作流。 ## 其他 AI 入口与限制 提供只读资源 `teams://capabilities`,以及 `summarize_chat`、`daily_brief` 两个提示模板,用于生成有来源引用的聊天总结和每日简报。模板不会自行访问云端或自动发出通知。 AI 应先读取 `get_collector_status` 再判断数据是否最新。stdio 返回的是持久化状态,无法证明另一进程此刻仍在运行;HTTP 可以读取当前进程状态。聊天范围取决于已发现会话及已补齐历史,日历范围取决于现有接口窗口,均不应被解释为整个账号的完整副本。Microsoft 会话失效后仍需从工具重新登录。 ## 实现依据 使用官方 `@modelcontextprotocol/sdk` 1.30 系列的 `McpServer`、stdio 与 Streamable HTTP transport;v1 包的 API 以官方 [v1.x 服务端文档](https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/docs/server.md) 为依据。输入 Schema、结构化结果与工具注解遵循 [MCP Tools 规范](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)。协议验证使用官方 SDK Client,通过内存 transport、真实 stdio 子进程和本机 HTTP 进行初始化、工具发现和调用测试。