PostHog 桌面端团队 MCP 网关:架构解析、双端同步机制与源码实现指南
PostHog 桌面端团队 MCP 网关:架构解析、双端同步机制与源码实现指南
导读
本文以 products/desktop/packages/ui/src/features/mcp-gateway/README.md 为骨架,深入讲解 PostHog 桌面端中"团队 MCP 网关"(Team MCP Gateway)的完整实现:它是什么、由哪个特性开关控制渲染、页面与路由如何组织、数据 hooks 如何驱动增删改查,以及它为何与 Web 应用刻意双份实现、如何保持同步。读完本文,你将掌握 PostHog 桌面端 MCP 网关 UI 的源码布局、与 Web 端及后端 REST API 的协作关系,并能在此基础上进行功能扩展或对照开发。
一、什么是团队 MCP 网关
MCP(Model Context Protocol)网关是 PostHog 为团队提供的一套"控制平面"(control plane):它不是简单的个人 MCP 服务器市场,而是统一管理团队运行的 MCP 服务器、谁能访问它们(成员与 Agent 服务账号)、每个作用域(scope)下的按工具(per-tool)策略以及审计日志的集中式 UI。
这一点在 McpGatewayView.tsx 的源码注释中有明确表述:
Team MCP gateway: one control plane for the servers a team runs, who can reach them (members and agent service accounts), per-tool policies per scope, and the audit log. Renders behind the
mcp-gatewayflag in place of the per-user marketplace.
翻译过来即:团队 MCP 网关是一个控制平面,管理团队运行的服务器、可访问者(成员与 Agent 服务账号)、每个作用域的按工具策略以及审计日志;它在 mcp-gateway 特性开关开启时替代原先的"按用户(per-user)市场"进行渲染。
二、渲染入口与特性开关
桌面端 MCP 网关 UI 并非独立路由,而是由既有 MCP 服务器功能的入口组件按条件渲染:
- 入口组件:McpServersView.tsx,位于
products/desktop/packages/ui/src/features/mcp-servers/components/。 - 开关判定:该组件通过
useFeatureFlag(MCP_GATEWAY_FLAG)读取特性开关(MCP_GATEWAY_FLAG定义于@posthog/shared),当开关开启时渲染mcp-gateway/下的团队网关体验,否则回退到旧的按用户市场视图(见 mcp-servers/README.md)。
这意味着整个网关 UI 是一个"可替换场景"(scene):特性开关只决定入口处渲染哪一套视图,两套视图共用相同的后端能力。
三、页面结构与扁平路由模型
3.1 主视图 McpGatewayView
McpGatewayView.tsx 是网关的主容器,布局为左侧导航栏(GatewayRail,展示服务器列表与模板图标)+ 右侧主内容区(ScrollArea,最大宽度 960px)。它有三个值得注意的行为:
- 窗口聚焦自动刷新:通过
useEffect监听window的focus事件与document的visibilitychange事件,一旦窗口重新可见就执行queryClient.invalidateQueries({ queryKey: <a href="https://link.gitcode.com/i/b9213c5911128fb9757042313c6ae556" target="_blank">"mcp"] })。注释解释了原因——"连接与策略可能在此期间被 Web 应用或队友修改"([McpGatewayView.tsx)。 - 渲染期角色守卫:路由在渲染时校验权限,若配置解析出的角色权限不足以访问当前路由,则降级回
servers首页(McpGatewayView.tsx)。 - 按路由分发主内容:
switch (route.view)将add / server / team / agent / member / settings / audit / servers八种视图分别映射到对应组件(McpGatewayView.tsx)。
3.2 扁平路由类型 GatewayRoute
gatewayRoute.ts 定义了一个"单层扁平路由"(single flat route),不依赖 URL 路由库:
export type GatewayRoute =
| { view: "servers" }
| { view: "server"; serverId: string; scope?: GatewayPolicyScope }
| { view: "add" }
| { view: "team" }
| { view: "agent"; accountId: string }
| { view: "member"; userId: number }
| { view: "settings" }
| { view: "audit" };
其中权限规则清晰:
team、agent、member、settings为仅管理员视图(ADMIN_ONLY_VIEWS);add(添加服务器)要求canAddServers;audit(审计日志)对所有成员开放——后端会将查询范围限定为"通过调用者自身连接产生的事件",除非调用者是网关管理员(gatewayRoute.ts)。
3.3 页面组成一览
components/parts/ 目录下每个组件对应一个场景或弹窗,职责单一:
| 组件 | 职责 |
|---|---|
GatewayServersHome.tsx |
服务器首页:搜索、分类筛选、连接卡片、推荐模板卡片 |
GatewayServerDetail.tsx |
单个服务器详情:成员连接、Agent 访问、工具策略 |
GatewayAgentDetail.tsx |
Agent 服务账号详情 |
GatewayMemberDetail.tsx |
团队成员详情 |
GatewayTeamSettings.tsx |
团队级设置(如默认服务器开关) |
GatewayAuditLog.tsx |
审计日志 |
GatewayAddServer.tsx |
添加自定义服务器 |
GatewayConnectDialog.tsx |
连接授权对话框(凭证输入/OAuth) |
GatewayDeleteServerDialog.tsx / GiveAccessDialog.tsx / NewTokenDialog.tsx |
删除、授权、建令牌等操作对话框 |
GatewayRail.tsx |
左侧导航栏 |
GatewayTeamView.tsx |
团队视图容器 |
GatewayToolRow.tsx |
工具策略行 |
这些组件大多带有同名 .test.tsx 测试(如 GatewayRail.test.tsx、GatewayServerDetail.test.tsx、GatewayTeamSettings.test.tsx、GatewayToolRow.test.tsx),说明每个页面单元都有对应的交互测试覆盖。
四、数据层:hooks 与后端 REST API 的对应
网关 UI 的数据层全部基于 TanStack Query(useAuthenticatedQuery / useAuthenticatedMutation)封装在 hooks/ 目录,形成了"一个 hook 对应一组后端端点"的清晰映射:
4.1 useGatewayConfig:团队配置与调用者角色
useGatewayConfig.ts 调用 client.getMcpGatewayConfig(),返回并派生以下关键状态:
isAdmin:是否网关管理员;allowCustomServers:是否允许自定义服务器(默认true);allowMemberAgentAccess:是否允许成员管理 Agent 访问(默认true);defaultServersEnabled:未启用(无行记录)的目录服务器是否对团队默认可用(默认true);canManageAgentAccess:派生值,管理员或开启成员 Agent 访问时为true。注意其默认在配置加载完成前为false,这是刻意的安全设计——"未确认的成员不得发送agent_scope,否则后端会在其无权限时返回 403"(useGatewayConfig.ts)。
4.2 useGatewayServers:服务器注册表与全部变更操作
useGatewayServers.ts 是数据层的核心,覆盖服务器级所有 mutation:
- 连接/断开:
connect(携带可选凭证)、reconnect(OAuth 重新授权)、disconnect(uninstallMcpServer); - 成员自助开关:
toggleYourConnection("对我停用",只改自己的is_enabled); - 管理员控制:
updateServer、setTemplateEnabled(启用/停用某个目录模板并物化其网关行)、setAllEnabled(一键全开/全关,同时作用于存量行并预设未来目录服务器的姿态)、removeServer(对所有人删除); - 工具发现:
discoverTools——首次连接时服务器工具列表为空,必须主动向上游服务器拉取工具清单,否则注册表行会一直显示 0 个工具直到管理员手动刷新(useGatewayServers.ts)。
此外它还通过 useSubscription(trpc.mcpCallback.onOAuthComplete...) 订阅 OAuth 回调完成事件,授权成功后自动失效并刷新服务器列表。
4.3 连接流程的两种路径
从 GatewayServersHome.tsx 可以看到连接逻辑的分支:
- OAuth 服务器:无需凭证,直接发起浏览器 OAuth 往返(
connect({ server })),完成后经 tRPC 订阅回调刷新; - API-key 服务器与自定义服务器:弹出
GatewayConnectDialog收集凭证——自定义服务器没有固定认证机制(每位成员自行选择),API-key 模板需要成员自己的 key。
GatewayConnectDialog 的固定认证类型由 gatewayConnectAuthType(server) 决定;该组件还有 .stories.tsx,说明连接对话框是 Storybook 覆盖的交互单元。
4.4 缓存键与失效策略
hooks/gatewayKeys.ts 集中管理查询键;invalidateServers() 在连接/断开后不仅刷新 gatewayKeys.servers,还会级联刷新 gatewayKeys.accounts(Agent 的服务器列表,因为连接会自动授予内置 Agent 访问权、断开会解除授予)与 mcpKeys.installations(连接本质上是安装行,旧版 UI 也会变化),保证多界面数据一致(useGatewayServers.ts)。
五、服务器首页的交互细节
GatewayServersHome.tsx 实现了网关的门面页面,包含:
- 搜索与分类筛选:搜索框按名称/描述过滤,分类来自
MCP_CATEGORIES;筛选后展示数量计数与"Clear filters"。 - 两类卡片:
GatewayServerCard:已注册(有网关行)的服务器,展示连接状态(绿色对勾表示已连接)、描述、管理员视角的成员连接人数(AvatarStack+ "N teammates connected · M agents"),按is_team_enabled显示 "Off" 徽标;RecommendedTemplateCard:目录中尚未被任何人触碰的推荐模板,此时注册表是稀疏的、没有可打开的行,因此只能连接——连接成功后由后端物化出网关行(GatewayServersHome.tsx)。
- 默认开关的可见性规则:当团队默认关闭(
defaultServersEnabled为 false)时,普通成员完全看不到推荐模板卡片,管理员看到的是置灰禁用态,需在 Team settings 中启用(GatewayServersHome.tsx)。
六、与 Web 应用的双端同步:本文档的核心设计约束
原文档用了近一半篇幅强调这一条刻意为之的架构决策,这是理解该模块的重中之重:
This is one half of a deliberately duplicated UI.
即:桌面端网关 UI 是"有意双份实现"中的一半。具体分工为:
| 端 | 实现位置 | 技术栈 |
|---|---|---|
| 桌面端 | products/desktop/packages/ui/src/features/mcp-gateway/ |
React + Radix Themes + TanStack Query + tRPC |
| Web 应用(主实现) | products/mcp_store/frontend/gateway/ |
Kea + LemonUI |
| Web 应用(设置内嵌变体) | products/mcp_store/frontend/settings/ |
Kea + LemonUI |
三端都消费同一个网关 REST API:gateway_views.py(约 1767 行,含完整的服务端视图、序列化与 schema 描述)。
需要重点指出的是,README 中提到的 products/mcp_store/frontend/gateway/、products/mcp_store/frontend/settings/ 与 products/mcp_store/backend/presentation/gateway_views.py 在当前仓库中均已确认存在,且 Web 端的 GatewayServersHome.tsx、GatewayRail.tsx、GatewayAuditLog.tsx 等文件与桌面端组件一一对应,印证了"双份 UI、同一份语义"的格局。
6.1 手写镜像类型:mcp-gateway.ts
由于双端不共享代码,桌面端在 products/desktop/packages/api-client/src/mcp-gateway.ts(约 236 行)中手写维护了与后端序列化器对应的请求/响应类型镜像。这意味着:
serializer changes must update those too.
后端任何序列化字段的增删改,都必须同步修改该文件,否则桌面端类型与后端响应将失配。
6.2 双端同步的硬性协作规则
文档明确要求:MCP Store 的功能集总是双端一起变更——"当你在这里(桌面端)改变功能集或 UI 时,必须在同一个 PR 中在 Web 应用里做等价改动,或开启一个显式关联的 follow-up,反之亦然"。
这是一条工程纪律而非建议,它保证了:
- 功能集不因平台产生漂移;
- 后端 API 只演进一次,两端同时适配;
- 任何一端都不会出现另一端没有的"孤儿功能"。
6.3 产品级权威文档
products/mcp_store/README.md 是整个 MCP Store 产品的权威文档,包含两套应用之间的目录映射(directory mapping)。在桌面端 mcp-gateway 中做任何改动前,都应先阅读它以确认对应 Web 端的目录位置。
七、后端视图与数据模型速览
从 gateway_views.py 的模块 docstring 可确认后端的数据模型设计:
Registrations (
MCPGatewayServer) are the unit everything hangs off: enablement, per-scope tool policies, agent access, member revocations, org rules, and the audit log. Personal/shared credentials stay onMCPServerInstallation(see views.py); this module only adds the team layer.
即:
MCPGatewayServer(注册行) 是网关的挂载点:承载启用状态、按作用域的工具策略、Agent 访问、成员撤销、组织规则与审计日志;- 凭证不进入网关层:个人/共享凭证仍保存在
MCPServerInstallation上,网关模块只叠加"团队层"的语义。
该文件同时使用 DRF Spectacular(extend_schema 等装饰器)生成 OpenAPI 描述,是双端类型镜像的契约源头。
八、测试与验证路径
仓库为网关 UI 提供了多层验证:
- 组件测试:
GatewayAddServer.test.tsx、GatewayConnectDialog.test.tsx、GatewayRail.test.tsx、GatewayServerDetail.test.tsx、GatewayTeamSettings.test.tsx、GatewayToolRow.test.tsx、GiveAccessDialog.test.tsx等,覆盖主要页面与对话框的交互行为; - Hooks 测试:
useGatewayMembers.test.tsx、useGatewayToolPolicies.test.tsx、useRegisterGatewayServer.test.tsx、useServiceAccounts.test.tsx验证数据层逻辑; - 路由测试:
gatewayRoute.test.ts验证isRouteAllowed的权限判定; - Storybook:
GatewayConnectDialog.stories.tsx提供交互预览。
九、给开发者的实践清单
如果你要在桌面端 mcp-gateway 上做改动,请按以下清单操作:
- 先读权威文档:
products/mcp_store/README.md(产品全貌与双端目录映射); - 定位 Web 端对应实现:Web 主实现在
products/mcp_store/frontend/gateway/,设置内嵌变体在products/mcp_store/frontend/settings/; - 检查类型镜像:若后端序列化器变化,同步更新
products/desktop/packages/api-client/src/mcp-gateway.ts; - 遵守双端同步纪律:功能集改动必须在同一 PR 或显式关联的 follow-up 中双端落地;
- 遵守后端契约:所有变更以
products/mcp_store/backend/presentation/gateway_views.py暴露的 REST API 为准,桌面端不引入独立后端; - 补测试与 Storybook:参考同目录既有
.test.tsx与.stories.tsx的写法; - 注意缓存一致性:涉及连接/断开时,参照
invalidateServers()的级联失效策略,避免旧 UI 与网关 UI 数据不同步。
十、小结
PostHog 桌面端的团队 MCP 网关是一套结构清晰、纪律严明的"共享后端 + 双端镜像 UI"实现:前端以扁平路由组织八个场景,数据层用 hooks 对齐后端 REST 端点,权限在渲染期与后端双重把关,而"双份 UI 必须同步"的架构决策则由 README 作为制度性文档加以固化。理解这份文档及其配套源码,就等于同时理解了桌面端网关 UI 的布局、Web 端对应实现的映射,以及 MCP 网关后端 API 的团队层数据模型。