Polyxd

@polyxd/mcp

Polyxd 的 MCP 服务。宿主的模型负责生成：服务将规范作为指令提供给它，检查它编写的 UI 文档，并将其作为 MCP App 展示给用户，由 Polyxd 渲染器使用任意设计系统包进行绘制。

npx -y @polyxd/mcp        # stdio

也可以通过 URL 连接到托管服务，无需账户，也无需登录：

https://mcp.polyxd.com/mcp

通过 URL 连接

• Claude（claude.ai，以及通过账户使用的 Claude Desktop）：Customize > Connectors > Add custom connector，粘贴 URL，选择 No sign-in。
• Claude Code：claude mcp add --transport http polyxd https://mcp.polyxd.com/mcp
• ChatGPT：开启开发者模式（Settings > Security and login），然后在 chatgpt.com/plugins 添加服务，填写 URL，无需身份验证。
• Cursor：在 ~/.cursor/mcp.json 中添加 { "mcpServers": { "polyxd": { "url": "https://mcp.polyxd.com/mcp" } } }。
• VS Code：在 .vscode/mcp.json 中添加 { "servers": { "polyxd": { "type": "http", "url": "https://mcp.polyxd.com/mcp" } } }。

通过 stdio 添加到宿主

Claude Desktop（claude_desktop_config.json）和大多数其他 MCP 客户端：

{
  "mcpServers": {
    "polyxd": { "command": "npx", "args": ["-y", "@polyxd/mcp"] }
  }
}

Claude Code：

claude mcp add polyxd -- npx -y @polyxd/mcp

从此仓库的克隆版本开始：运行 npm install && npm run build -w @polyxd/mcp，然后使用 node <repo>/packages/mcp/dist/bin.js 作为命令。

工具

工具	功能	structuredContent
polyxd_guide	提供规范作为指令：如何使用这些工具，以及演示所用的生成器提示词（文档结构、生成屏幕的规则、绑定、操作、每个组件及其属性、各种模式）。	{ specVersion, guide }，其中 guide 与 content 的文本相同
polyxd_validate	验证文档。每个问题都附带其 JSON Pointer、所属组件，以及说明应如何修改的提示。	{ valid, errors, warnings, issues[{ severity, pointer, component?, message, hint? }] }
polyxd_verify	验证器的文档检查（来自 @polyxd/verifier/static 的 staticAudit，因此安装服务不会安装 Playwright）；可选择针对设计方向（一个对象，或 calm-finance / playful-personal）和能力注册表进行检查。生成简要报告。	{ errors, warnings, findings[{ severity, check, message, hint? }], direction?, rules }
polyxd_show	验证文档，然后返回用于显示的文档。pack 选择设计系统包（默认 material3），mode 选择浅色或深色模式（默认使用宿主主题）。有错误时不显示任何内容。	{ shown: true, document, pack, packName, mode?, specVersion }，或带有 isError 的 { shown: false, issues }
polyxd_packs	设计系统包：已发布的设计系统和原创模板。	{ default, packs[{ name, displayName, template, package, description }] }
polyxd_components	列出各组件及其单行摘要，或通过 name 获取某个组件的完整定义。	{ components[{ name, category, summary, shell }] }，或包含完整定义的 { component }
polyxd_docs	搜索此版本中随附的 polyxd.com 文档：最匹配 query 的章节、某个完整页面，或页面列表。	{ sections[{ page, title, heading, url, text }] }、{ page } 或 { pages[] }

所有工具均为只读。可以将 data 与文档分开传递给 polyxd_validate、polyxd_verify 和 polyxd_show；它会替代文档自身的 data。

每个工具都声明了一个 outputSchema（JSON Schema 2020-12，位于 src/output-schemas.ts，其中每个属性都针对模型进行了说明），每个成功结果都带有符合该架构的 structuredContent；SDK 会在发送前逐一检查。错误结果（isError: true）不受架构约束：polyxd_show 未显示结果仍符合架构，其他工具则仅返回文本。

资源

• ui://polyxd/surface.html（text/html;profile=mcp-app）：MCP 应用。
• polyxd://examples/<name>.json：规范的示例文档。
• polyxd://directions/<name>.json：规范的示例 Design Directions。

MCP 应用

polyxd_show 按照 MCP Apps 扩展（SEP-1865，2026-01-26）声明 _meta.ui.resourceUri: "ui://polyxd/surface.html"，以及 ChatGPT 的别名 openai/outputTemplate。支持 MCP Apps 的宿主会读取该资源，并在沙盒化 iframe 中渲染。此页面完全自包含：@polyxd/web 渲染器、渲染器的样式表以及每个 pack 的主题都内嵌其中，不访问任何外部源，因此宿主的默认内容安全策略就足够了。

资源的 _meta 会针对每个宿主说明这些信息（appResourceMeta()）：

• ui.csp：{ connectDomains: [], resourceDomains: [] }。页面不会加载任何内容。
• ui.prefersBorder: true。
• ChatGPT 自有的键：openai/widgetCSP（同样是空列表）、openai/widgetPrefersBorder、openai/widgetDescription，以及 openai/widgetDomain: "https://mcp.polyxd.com"，这是 ChatGPT 分配给应用沙盒的源。
• 不设置 ui.domain。Claude 要求此处填写连接器 URL 的哈希值，而 ChatGPT 要求填写源；Claude 会拒绝渲染 ui.domain 不符合其格式的应用。页面不需要稳定的源，因此不设置该字段，而 ChatGPT 会读取 openai/widgetDomain。

页面通过 postMessage 使用 MCP Apps 协议：先发送 ui/initialize，再发送 ui/notifications/initialized。它会从 ui/notifications/tool-result 通知的 structuredContent 中获取文档，并使用所选的 pack 渲染；除非指定了 mode，否则会根据宿主的 theme 选择浅色或深色主题。页面会通过 ui/notifications/size-changed 报告自身高度。

用户按下操作按钮时，页面会发送 ui/message，其中包含一条用户消息，说明操作名称、按钮标签以及该操作的上下文（绑定到该操作的值，包括用户输入的内容）：

[Polyxd] In the "New task" screen I pressed "Add task" (action task.save).
Context: {"title":"Buy milk","due":"2026-10-01"}

模型会将其作为用户的下一条消息接收并据此采取行动。关闭屏幕（ui.dismiss）也会以同样的方式发送。不支持 MCP Apps 的宿主会改为显示 polyxd_show 的文本摘要。

提示词

生成器提示词来自 @polyxd/runtime，它会根据规范构建提示词。src/packs.generated.ts 列出所有 pack，src/spec-files.generated.ts 则将规范中的组件定义和示例作为 JSON 模块导入，因此服务无需读取任何文件。运行 npm run sync -w @polyxd/mcp 会重写这两个文件；若任一文件不是最新版本，测试就会失败。

通过 HTTP 提供服务

@polyxd/mcp/http 通过 MCP 的 Streamable HTTP 传输，以符合 Web 标准的 (Request) => Promise<Response> 处理器形式提供同一服务。它不依赖 Node，因此可运行于 Cloudflare Worker、Deno 或 Bun。

import { createHttpHandler, rateLimiter } from "@polyxd/mcp/http";
import viewHtml from "@polyxd/mcp/view.html"; // bundled as text

const mcp = createHttpHandler({ viewHtml: () => viewHtml, rateLimit: rateLimiter({ limit: 600, windowMs: 60_000 }) });
export default { fetch: (request: Request) => (new URL(request.url).pathname === "/mcp" ? mcp(request) : new Response(null, { status: 404 })) };

该传输使用 SDK 的 createMcpHandler，采用无状态模式：每个请求都会创建一个新的服务，不使用会话。对于 2025 年前后的客户端，GET 和 DELETE 请求会返回 405，符合规范对不提供独立流且不使用会话的服务的要求。对于 2026-07-28 协议的客户端（每个请求都会附带版本号），也同样适用。其外围功能包括：

• 请求体大小限制：maxBodyBytes，默认值为 1 MiB，超限时返回 413。首先检查 Content-Length，读取请求体时还会再次检查。
• 超时：整个响应的超时时间由 timeoutMs 指定，默认值为 15 秒。超时后才完成的响应会收到 JSON-RPC 错误：普通请求返回 504；SSE 流则会针对该请求的 id 返回错误。
• 速率限制：rateLimit(request) 返回 false 时，会返回 429 和 Retry-After。rateLimiter() 使用基于内存的固定窗口，并以 CF-Connecting-IP 为键。计数范围为单个进程或 Worker isolate，因此只能尽力限制。
• CORS：允许任意来源，因为服务不保存凭据，也不保存任何人的数据。预检请求会允许其请求的标头，响应会公开 Mcp-Session-Id 和 Mcp-Protocol-Version。
• 日志：每个请求记录一行，包含方法、路径、状态和耗时。不记录其他任何内容：不会记录请求体、标头、查询字符串、地址或错误消息。

托管服务

https://mcp.polyxd.com/mcp 是 apps/mcp，一个 Cloudflare Worker：/mcp 是上文的处理程序，/health 返回 JSON，/ 则重定向到文档。视图以文本形式打包进 Worker（总计约 2.4 MB，gzip 压缩后为 385 KB）。其速率限制由 Cloudflare 的速率限制绑定提供，每个 IP 地址每分钟 600 个请求。该绑定按 Cloudflare 位置计数，因此用于抵御请求洪流，而非实施精确配额。Claude 和 ChatGPT 从各自的服务器发起调用，因此限制设得比较宽松。wrangler.jsonc 中关闭了 Cloudflare 的调用日志、追踪和 Issues，因此只保留 Worker 自身的日志行。设置 POSTHOG_KEY 密钥后，托管 Worker 还会匿名统计初始化次数和工具调用次数（apps/mcp/src/analytics.ts）：只记录名称和次数，绝不记录文档、文档数据或地址。此软件包和 npx @polyxd/mcp 不会向任何地方发送数据。

npm run dev -w @polyxd/mcp-remote                        # wrangler dev on http://127.0.0.1:8787/mcp
node apps/mcp/scripts/smoke.ts http://127.0.0.1:8787/mcp  # every tool, in both protocol eras, over real HTTP
npm run deploy -w @polyxd/mcp-remote                     # builds @polyxd/mcp, then wrangler deploy

部署时会在 polyxd.com 区域上创建 mcp.polyxd.com 自定义域名。workers.dev 和预览 URL 均已关闭。

MCP Registry

server.json 将托管服务描述为 MCP Registry 中的 com.polyxd/mcp。要使用 com.polyxd 下的名称，需要证明你拥有 polyxd.com 的控制权：

openssl genpkey -algorithm Ed25519 -out key.pem
echo "polyxd.com. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""
mcp-publisher login dns --domain polyxd.com --private-key "$(openssl pkey -in key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
mcp-publisher publish      # from packages/mcp

这需要 OpenSSL 3（macOS 的 LibreSSL 不支持 Ed25519）。请妥善保管 key.pem，不要将其放入仓库。TXT 记录应添加到顶级域名 polyxd.com。也可以通过 HTTP 进行验证：在 https://polyxd.com/.well-known/mcp-registry-auth 提供相同的 v=MCPv1; k=ed25519; p=... 行，并使用 mcp-publisher login http。域名必须是 polyxd.com，不能是 mcp.polyxd.com，后者的验证只能覆盖 com.polyxd.mcp 下的名称。

发布工作流会在每个版本标签上将 server.json 发布到 Registry；待 npm 上有该版本后，使用 MCP_REGISTRY_KEY Actions 密钥中的私钥登录（即上文 --private-key 命令打印的十六进制字符串）。如果没有该密钥，或 Registry 中已存在该版本，则会跳过此步骤并显示提示。

server.json 同时列出托管服务（remotes）和 npm 软件包（packages），以便主机可以提供其中任一种。Registry 会检查 package.json 中软件包的 mcpName。请确保 server.json 中的两个 version 字段与 package.json 保持一致；有测试会对此进行检查。

构建和测试

npm run build -w @polyxd/mcp     # tsc, then scripts/build-view.ts writes dist/view.html
npm test -w @polyxd/mcp
npm test -w @polyxd/mcp-remote   # the Worker's routes

测试会将客户端连接到内存中的服务，并针对每个规范示例和错误文档调用每个工具；启动构建后的二进制文件，并通过 stdio 与其进行 JSON-RPC 通信；通过 Streamable HTTP 向 SDK 客户端提供服务，覆盖两个协议时期，并发送客户端库绝不会发送的原始请求（无效 JSON、超大请求体、过多请求、预检请求、缓慢响应）；为 Worker 打包 HTTP 入口，并检查它不依赖任何 Node 功能；还会在无头 Chromium 中加载 MCP App，由测试模拟主机，从握手到收到作为 ui/message 的操作。如果 Playwright 没有 Chromium，浏览器测试会跳过（npx playwright install chromium）。