workvivo-mcp

workvivo-mcp

面向 Claude 的只读 Workvivo MCP 服务。涵盖公司的动态流、新闻文章、帖子及其评论和赞誉、活动、人员目录、空间、通知和全文搜索。

此项目由 AI（Claude Code）开发并维护。请自行斟酌使用。

工作原理

Workvivo 需要通过公司的单点登录访问，其公共 API 需要管理员签发的令牌。因此，此服务不会自行发送任何请求。每个请求都在你已登录 Workvivo 的浏览器标签页中执行，并通过 ContextMint Bridge 扩展，经由 fetchproxy 桥接（127.0.0.1:37149）转发。每个请求都是在你的标签页中发起的同源 fetch，使用你的会话和权限。此服务只读取信息；绝不会发布内容、点赞、发表评论、回复活动邀请或将任何内容标记为已读。

设置

1. 安装 ContextMint Bridge 扩展，并在该浏览器中登录你的 Workvivo 站点 （例如 https://acme.workvivo.us）。

2. 将此服务添加到你的 MCP 客户端：

   {
     "mcpServers": {
       "workvivo": {
         "command": "npx",
         "args": ["-y", "workvivo-mcp"],
         "env": { "WORKVIVO_HOST": "acme.workvivo.us" }
       }
     }
   }
   

3. 调用 workvivo_healthcheck。首次运行时会返回一组配对码。在 ContextMint Bridge 弹出窗口中批准该配对（只需一次；信任关系会持续保留）。

变量	必需
WORKVIVO_HOST	是	你所在组织的 Workvivo 主机，例如 acme.workvivo.us。
WORKVIVO_WS_PORT	否	覆盖 fetchproxy WebSocket 端口（默认值为 37149）。
WORKVIVO_DEBUG	否	设为 1 可将详细请求信息记录到 stderr。
WORKVIVO_DOWNLOAD_DIR	否	保存链接文档的位置（默认值为 ~/Downloads/workvivo-mcp）。
WORKVIVO_MAX_DOWNLOAD_MB	否	超过此大小的文档将被跳过，不会下载（默认值为 50）。
WORKVIVO_SKIP_FILE_TYPES	否	永不下载的逗号分隔扩展名或 MIME 类型，例如 mp4,.mov,video/*（默认值为 video/*,audio/*；none 表示不跳过任何内容）。

工具

工具	读取内容
workvivo_healthcheck	端到端检查桥接、扩展配对和 Workvivo 登录状态
workvivo_get_feed	首页动态流、某个空间的动态流或某人的帖子
workvivo_list_news / workvivo_get_article	新闻文章；单篇文章及其正文文本，或通过 body_format: "markdown" 获取 Markdown 格式正文
workvivo_get_post / workvivo_list_shoutouts	单篇帖子或赞誉；近期赞誉
workvivo_get_comments	帖子、文章、活动或赞誉的评论及评论者姓名
workvivo_get_question	一条问答问题及其回答、投票和已采纳的答案
workvivo_list_events / workvivo_get_event	即将举行的活动（UTC 时间、回复状态）；单项活动
workvivo_search_people / workvivo_get_person	人员目录；个人资料（职位、经理、简介）
workvivo_get_me / workvivo_get_my_team	你；你的团队
workvivo_list_pages / workvivo_get_page	某个空间（或全局集合）的页面树；单个页面的 Markdown，其中包含所链接页面和文档的索引
workvivo_get_document	链接文档（PDF、Word、文本、HTML）的 Markdown 内容 — 浏览器通过你的会话下载文档
workvivo_digest_space	将整个空间汇总为一份 Markdown 文档：每个页面、链接文档索引、资源库、活动、近期帖子（可选包含文档文本）
workvivo_list_spaces / workvivo_get_space	你的空间、所有空间、热门空间或按名称查找的空间；单个空间
workvivo_list_notifications	通知和未读计数
workvivo_search	跨文章、帖子、活动、人员、空间和文档进行全文搜索
workvivo_api_get	其他任何只读 /api/ 路径（拒绝 action 风格的路径）
读取工具默认返回精简视图。传入 view: "full" 可获取 Workvivo 发送的完整记录。密码形态的字段（例如会议密码和实时令牌）在所有视图中都会被隐藏。workvivo_list_notifications 和
workvivo_list_events 还接受 view: "brief"——在不可信数据封装中，每项占一行
（`title — <UTC time	no date> — ，最多 120 个字符）；对于空白页或部分页面，还会附带以 -- 开头的注释行——并提供上下文组提示（_meta.mint，组 work），供读取这些提示的宿主使用。请注意，workvivo_search` 会将查询添加到你自己的 Workvivo 搜索历史中。

文档（workvivo_get_document，以及带有 include_documents 的 workvivo_digest_space）：Workvivo 的文档链接会重定向到你所在租户文件主机上的短时有效签名 URL。浏览器跟随链接时，桥接程序会捕获该 URL，因此浏览器不会下载任何内容。服务器随后会在发送任何请求之前，根据文件的名称检查文件类型是否符合 WORKVIVO_SKIP_FILE_TYPES，并在读取正文之前检查其大小是否符合 WORKVIVO_MAX_DOWNLOAD_MB。符合条件的文件会保存到 WORKVIVO_DOWNLOAD_DIR，且不会覆盖已有文件。如果无法捕获 URL，浏览器会改为下载文件；随后同样会应用这些规则，并将文件移至 WORKVIVO_DOWNLOAD_DIR。这需要包含 capture_redirect 和 download 权限的配对。如果你配对的是早期版本，请在 ContextMint Bridge 弹出窗口中移除 workvivo-mcp，然后批准新的配对码。

在托管服务器（mcp-host）上，服务器无法访问文件主机，也无法与浏览器共享磁盘，因此浏览器会获取文件，并通过桥接程序返回其字节内容。这需要 ContextMint Bridge 1.8.0 或更高版本；旧版本会被拒绝，并提示你更新。系统会应用相同的类型和大小规则，并在使用文件内容之前根据文件声明的类型和大小进行检查，但大小上限取 WORKVIVO_MAX_DOWNLOAD_MB 和 16 MB 中较小的值（单次桥接响应最多可传输 16 MB）。超出限制的文件会列为已跳过，并注明其大小和上限。服务器不会保存任何文件：workvivo_get_document 会返回文本，以及指向文件本身的短时有效下载 link。

端点及其特殊行为记录在 docs/WORKVIVO-API.md 中。

升级

下个版本

在托管服务器上，文档读取功能（workvivo_get_document，以及带有 include_documents 的 workvivo_digest_space）现已可用：浏览器会获取文件，并通过桥接程序将其传回。请先将 ContextMint Bridge 更新到 1.8.0 或更高版本；旧版本会导致读取失败，并显示相应提示；摘要则会将每份文档标记为未获取，并注明原因。

你现有的配对仍可正常使用，无需重新批准。文件主机（attachments.<your Workvivo domain>）已由配对批准的域名涵盖，因此声明的域名保持不变。（扩展程序会将配对的域名作为集合进行比较：如果域名有所变化，它就会要求你批准新的配对码。）本地安装不受影响。

无需服务器：workvivo-fpx 技能

skills/workvivo-fpx 使用 fpx CLI 和可供 source 的辅助脚本（scripts/wv.sh），让你从 shell 获得同样的读取权限，并为每个端点提供现成的 jq 配方。

开发

npm install
npm run build   # tsc --noEmit + esbuild bundle → dist/bundle.js
npm test        # typecheck + vitest (all mocked; no network)

许可证

MIT