开发新的 MCP 应用时,请遵循 MCP Apps UI 和 OpenAI MCP 扩展规范。 ChatGPT 支持这两项规范,并将遵循这两项规范作为向 MCP 服务器添加 UI 的官方推荐方式。
本页介绍旧版 window.openai API。这些 API 的推出早于上述两项规范。仅在实现这两项规范未涵盖的功能时使用这些 API。
window.openai 组件桥接接口
ChatGPT 通过 window.openai 提供兼容别名和可选的 ChatGPT 扩展。开发新 UI 时,只要通用规范提供了等效功能,就应使用 MCP Apps 桥接接口。仅在需要 ChatGPT 专用功能时使用 window.openai。
有关具体实现步骤,请参阅构建 ChatGPT UI。
如果您的工具需要用户确认,初始 toolInput 缺失是正常情况。在用户批准调用之前,ChatGPT 不会将需要审批的参数填入小组件。用户批准后,主机才会通过 ui/notifications/tool-input 传递这些参数。
功能
| 功能类别 | 接口 | 典型用法 |
|---|---|---|
| 状态和数据 | window.openai.toolInput |
工具调用时传入的参数。对于需要审批的工具,该值可能一直为 null,直到主机在审批通过后发送 ui/notifications/tool-input。 |
| 状态和数据 | window.openai.toolOutput |
工具返回的 structuredContent。请保持字段内容简洁,模型会逐字读取。 |
| 状态和数据 | window.openai.toolResponseMetadata |
仅供小组件使用的标准工具结果元数据。在 ChatGPT 中,这些元数据包括 status、call_tool_result 和 mcp_tool_result,保留了完整的 MCP 结果结构,包括隐藏的 _meta。 |
| 状态和数据 | window.openai.widgetState |
在多次渲染之间保留的 UI 状态快照。 |
| 状态和数据 | window.openai.setWidgetState(state) |
同步保存新快照。每次发生有意义的 UI 交互后都应调用此方法。 |
| 小组件运行时 API | window.openai.callTool(name, args) |
从小组件调用另一个 MCP 工具,调用方式与模型发起的调用一致。 |
| 小组件运行时 API | window.openai.sendFollowUpMessage({ prompt, scrollToBottom }) |
请求 ChatGPT 发布由组件撰写的消息。scrollToBottom 是可选参数,默认为 true,设为 false 可阻止自动滚动。 |
| 小组件运行时 API | window.openai.uploadFile(file, { library?: boolean }) |
上传用户选择的文件并获取 fileId。如果用户可以使用 ChatGPT 文件库,传入 { library: true } 还会将上传的文件保存到其文件库中。 |
| 小组件运行时 API | window.openai.selectFiles() |
打开 ChatGPT 文件库选择器,以 { fileId, fileName, mimeType }[] 的形式返回当前插件已获授权访问的文件。由于部分用户可能无法使用文件库,请先检测此函数是否可用。 |
| 小组件运行时 API | window.openai.getFileDownloadUrl({ fileId }) |
获取文件的临时下载 URL。文件可以由小组件上传、从文件库选择、通过文件参数传入,也可以由工具以文件引用的形式返回。 |
| 小组件运行时 API | window.openai.requestDisplayMode(...) |
请求切换到画中画或全屏模式。 |
| 小组件运行时 API | window.openai.requestModal({ params, template }) |
打开由 ChatGPT 管理的模态窗口。省略 template 可使用当前模板,传入已注册的模板 URI 则可切换窗口内容。 |
| 小组件运行时 API | window.openai.requestClose() |
请求 ChatGPT 关闭当前小组件。 |
| 小组件运行时 API | window.openai.notifyIntrinsicHeight(...) |
在小组件高度变化时报告其高度,避免滚动内容被截断。 |
| 小组件运行时 API | window.openai.openExternal({ href, redirectUrl }) |
在用户的浏览器中打开经审核的外部链接。对于已获准使用的重定向目标,ChatGPT 默认会附加 ?redirectUrl=...。设置 redirectUrl: false 可跳过此操作。 |
| 小组件运行时 API | window.openai.setOpenInAppUrl({ href }) |
可覆盖全屏模式下显示的外部链接目标。如果未设置,ChatGPT 将按默认行为打开组件当前的 iframe 路径。 |
| 上下文 | window.openai.theme、window.openai.displayMode、window.openai.maxHeight、window.openai.safeArea、window.openai.view、window.openai.userAgent、window.openai.locale |
可通过 useOpenAiGlobal 读取或订阅这些环境信息,据此调整界面样式和文案。 |
useOpenAiGlobal 辅助函数
许多 ChatGPT UI 项目使用小型辅助函数封装对 window.openai 的访问,方便测试视图。以下辅助函数监听主机的 openai:set_globals 事件,让 React 组件可以订阅单个全局值。
import { useSyncExternalStore } from "react";
type WebplusGlobals = {
widgetState: { selectedId?: string | null; [key: string]: unknown } | null;
toolInput: Record<string, unknown>;
toolOutput: Record<string, unknown> | null;
theme: "light" | "dark";
};
const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
export function useOpenAiGlobal<K extends keyof WebplusGlobals>(
key: K
): WebplusGlobals[K] {
return useSyncExternalStore(
(onChange) => {
const handleSetGlobal = (event: Event) => {
if (!(event instanceof CustomEvent)) return;
const value = event.detail?.globals?.[key];
if (value === undefined) {
return;
}
onChange();
};
window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
passive: true,
});
return () => {
window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
};
},
() => {
const globals = (window as Window & { openai?: WebplusGlobals }).openai;
if (!globals) throw new Error("This hook requires a ChatGPT app host.");
return globals[key];
}
);
}关闭 UI
调用 window.openai.requestClose() 可请求 ChatGPT 关闭当前 UI。
请求切换显示模式
使用 window.openai.requestDisplayMode 可请求以内嵌、画中画或全屏模式显示。
await window.openai?.requestDisplayMode({ mode: "fullscreen" });
// On mobile, picture-in-picture may be presented as fullscreen.打开模态窗口
使用 window.openai.requestModal 可打开由主机控制的模态窗口。可提供同一 MCP 服务器注册的另一个 UI 模板的 URI,也可省略 template 以打开当前模板。
await window.openai.requestModal({
template: "ui://widget/details.html",
});文件 API
ChatGPT 通过可选的 window.openai 扩展提供文件上传和下载辅助函数。
| API | 用途 | 说明 |
|---|---|---|
window.openai.uploadFile(file, { library?: boolean }) |
上传用户选择的文件并获取 fileId。 |
如果当前用户可以使用 ChatGPT 文件库,传入 { library: true } 还会将上传的文件保存到其文件库中。 |
window.openai.selectFiles() |
打开文件库选择器,供用户选择已有文件。 | 返回 [{ fileId, fileName, mimeType }]。由于部分用户可能无法使用文件库,请先检测此函数是否可用。 |
window.openai.getFileDownloadUrl({ fileId }) |
请求文件的临时下载 URL。 | 适用于由小组件上传、从文件库选择、通过文件参数传入或由工具以文件引用形式返回的文件。 |
ChatGPT 文件库是可选功能,部分用户可能无法使用。如果 window.openai.selectFiles() 可用,当前插件已获授权访问该函数返回的文件。您可以将返回的 fileId 传给 window.openai.getFileDownloadUrl({ fileId }),也可以将其用于接受文件参数的工具输入。
上传用户选择的文件
const { fileId } = await window.openai.uploadFile(file, {
library: true,
});选择用户已上传到 ChatGPT 的文件
if (window.openai?.selectFiles) {
const files = await window.openai.selectFiles();
// [{ fileId, fileName, mimeType }]
}请检测 window.openai.selectFiles 是否可用。如果文件库不可用,请改用 window.openai.uploadFile。
请求临时下载 URL
const { downloadUrl } = await window.openai.getFileDownloadUrl({ fileId });定义文件输入
要让 ChatGPT 将文件传给工具,请在 _meta["openai/fileParams"] 中列出每个顶层文件输入字段。每个字段都必须能解析为一个文件对象或一个文件对象数组。
每个文件对象的模式都必须声明下表中的四个受支持的属性。
| 属性 | 类型 | 在 properties 中声明 |
列入 required |
|---|---|---|---|
download_url |
string |
是 | 是 |
file_id |
string |
是 | 是 |
mime_type |
string |
是 | 否 |
file_name |
string |
是 | 否 |
mime_type 和 file_name 的值可省略,但必须在模式中声明这两个属性。在扫描工具步骤和提交插件时,只要文件模式存在以下任一问题,就会被拒绝:缺少四个属性中的任意一个,未将 download_url 和 file_id 都设为必填,将任一可选属性设为必填,或将 download_url 和 file_id 以外的属性设为必填。您可以声明其他可选属性。
以下完整的工具描述符接受一个必填的文件输入。
{
"name": "analyze_file",
"title": "Analyze file",
"description": "Analyzes a user-provided file without modifying it.",
"inputSchema": {
"type": "object",
"$defs": {
"OpenAIFile": {
"type": "object",
"properties": {
"download_url": { "type": "string" },
"file_id": { "type": "string" },
"mime_type": { "type": "string" },
"file_name": { "type": "string" }
},
"required": ["download_url", "file_id"],
"additionalProperties": false
}
},
"properties": {
"file": { "$ref": "#/$defs/OpenAIFile" }
},
"required": ["file"]
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
},
"_meta": {
"openai/fileParams": ["file"]
}
}
要接受多个文件,请将顶层字段定义为数组,并在 items 中使用相同的文件对象模式。工具可以独立设置顶层文件字段是否必填,不受文件对象内部必填属性的影响。
在运行时,ChatGPT 传入的文件值使用小写字母和下划线命名字段。
{
"download_url": "https://...",
"file_id": "file_...",
"mime_type": "image/png",
"file_name": "input.png"
}
ChatGPT 始终提供 download_url 和 file_id,但可能省略 mime_type 和 file_name。如果小组件需要新的临时下载 URL,请将 file_id 作为 fileId 的值传给 window.openai.getFileDownloadUrl({ fileId })。
如果您希望模型在后续对话轮次中看到图像 ID,请在持久化小组件状态时使用结构化格式(modelContent、privateContent、imageIds)。
与主机同步导航
沙盒运行时会将 iframe 的导航历史同步到 ChatGPT 的 UI。使用 React Router 等标准路由 API,主机就会使其导航控件与您的 UI 保持同步。
使用 React Router 的 BrowserRouter 配置路由
import {
BrowserRouter,
Routes,
Route,
Link,
useParams,
} from "react-router-dom";
function PizzaListPlugin() {
const { placeId } = useParams();
return (
<main>
<Link to="/place/pizzeria">Example Pizzeria</Link>
<p>{placeId ?? "Choose a place"}</p>
</main>
);
}
export default function PizzaListRouter() {
return (
<BrowserRouter>
<Routes>
<Route path="/" element={<PizzaListPlugin />}>
<Route path="place/:placeId" element={<PizzaListPlugin />} />
</Route>
</Routes>
</BrowserRouter>
);
}通过代码导航
import { createElement } from "react";
import { BrowserRouter, useNavigate } from "react-router-dom";
function NavigationExample() {
const navigate = useNavigate();
function openDetails(placeId: string) {
navigate(`place/${placeId}`, { replace: false });
}
function closeDetails() {
navigate("..", { replace: true });
}
return createElement(
"div",
null,
createElement(
"button",
{ onClick: () => openDetails("pizzeria") },
"Open details"
),
createElement("button", { onClick: closeDetails }, "Close details")
);
}工具描述符参数
默认情况下,工具描述应包含 MCP 规范中列出的字段。
请声明 outputSchema,适用范围是所有返回 structuredContent 的工具。模式应准确描述工具返回的对象,以便客户端验证结果,模型也能据此判断如何进行后续工具调用。
工具描述符中的 _meta 字段
请在工具描述符中使用以下 _meta 字段。要将工具关联到 UI 模板,请优先使用 MCP Apps 标准键 _meta.ui.resourceUri。ChatGPT 也支持 OpenAI 专用元数据,用于兼容已有实现和提供可选扩展。
| 键 | 位置 | 类型 | 限制 | 用途 |
|---|---|---|---|---|
_meta["securitySchemes"] |
工具描述符 | array | 无 | 提供安全方案的副本,以向后兼容仅读取 _meta 的客户端。 |
_meta.ui.resourceUri |
工具描述符 | string(URI) | 无 | UI 模板的标准资源 URI。 |
_meta.ui.visibility |
工具描述符 | string[] | 默认为 ["model", "app"] |
控制工具可供模型、UI 还是两者使用。app 是 MCP Apps 协议中表示 UI 的标识符。 |
_meta["openai/outputTemplate"] |
工具描述符 | string(URI) | 无 | ChatGPT 中 _meta.ui.resourceUri 的 OpenAI 专用别名,可按需使用以保持兼容。 |
_meta["openai/profile"] |
工具描述符 | boolean | 可选,仅 true 表示这是个人资料工具 |
标识用于返回当前个人资料的只读工具,该工具需要身份验证。实现此工具可帮助用户识别和管理多个已连接的账号。即使没有此工具,用户也可以连接多个账号。请参阅支持多个账号。 |
_meta["openai/widgetAccessible"] |
工具描述符 | boolean | 默认为 false |
已有 UI 集成使用的 OpenAI 专用兼容字段。请优先结合使用 _meta.ui.visibility 和 tools/call。 |
_meta["openai/visibility"] |
工具描述符 | string | public(默认)或 private |
已有 UI 集成使用的 OpenAI 专用兼容字段。请优先使用 _meta.ui.visibility。 |
_meta["openai/toolInvocation/invoking"] |
工具描述符 | string | 最多 64 个字符 | 工具运行时显示的简短状态文本。 |
_meta["openai/toolInvocation/invoked"] |
工具描述符 | string | 最多 64 个字符 | 工具运行结束后显示的简短状态文本。 |
_meta["openai/fileParams"] |
工具描述符 | string[] | 无 | 表示文件的顶层输入字段列表。每个字段接收 { download_url, file_id, mime_type?, file_name? }。 |
Go 资源示例使用 github.com/modelcontextprotocol/go-sdk/mcp,版本为 v1.8.0。请将打包好的 MCP Apps 浏览器组件保存为项目目录中的 widget.js,然后从该目录启动 Go 服务器。
运行 Ruby 资源示例需要 mcp gem 的 1.10.0 版本。请将打包好的 MCP Apps 浏览器组件以 widget.js 为文件名保存到项目目录,并从该目录启动 Ruby 服务器。
示例
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });
// Local example data; replace this with your application data.
async function performSearch(query: string) {
const documents = [
{
id: "intro",
title: "Introduction to Acme",
url: "https://example.com/intro",
},
];
return documents.filter((document) =>
document.title.toLowerCase().includes(query.toLowerCase())
);
}
import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";
registerAppTool(
server,
"search",
{
title: "Public Search",
description: "Search public documents.",
inputSchema: { q: z.string() },
outputSchema: {
results: z.array(
z.object({
id: z.string(),
title: z.string(),
url: z.string(),
})
),
},
_meta: {
securitySchemes: [
{ type: "noauth" },
{ type: "oauth2", scopes: ["search.read"] },
],
ui: { resourceUri: "ui://widget/story.html" },
// Optional compatibility alias (ChatGPT only):
// "openai/outputTemplate": "ui://widget/story.html",
"openai/toolInvocation/invoking": "Searching…",
"openai/toolInvocation/invoked": "Results ready",
},
},
async ({ q }) => {
const results = await performSearch(q);
return {
structuredContent: { results },
content: [{ type: "text", text: `Found ${results.length} results.` }],
};
}
);注解
要将工具标记为“只读”,请在工具描述符中使用下表所列的 ToolAnnotations 字段。
| 键 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
readOnlyHint |
boolean | 必填 | 表示工具仅检索或计算信息,不会创建、更新或删除数据,也不会将数据发送到对话之外。 |
destructiveHint |
boolean | 必填 | 声明工具可能删除或覆盖用户数据,以便主机在执行前请求用户明确批准。 |
openWorldHint |
boolean | 必填 | 声明工具会访问公共互联网或范围不固定的外部实体,包括通过网页搜索等只读操作进行访问。对于访问范围明确的私有账号或工作空间,仅仅托管在外部并不意味着其属于开放环境。 |
idempotentHint |
boolean | 可选 | 声明使用相同参数重复调用工具不会对其环境产生额外影响。 |
这些提示仅影响 ChatGPT 或 Codex 向用户说明工具调用的方式。服务器仍须执行自身的授权逻辑。
示例
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });
// Local example data; replace this with your application data.
async function fetchSavedRecipes() {
return [{ id: "pasta", title: "Tomato pasta" }];
}
import { z } from "zod";
server.registerTool(
"list_saved_recipes",
{
title: "List saved recipes",
description: "Returns the user’s saved recipes without modifying them.",
inputSchema: {},
outputSchema: {
recipes: z.array(
z.object({
id: z.string(),
title: z.string(),
})
),
},
annotations: { readOnlyHint: true },
},
async () => ({
content: [],
structuredContent: { recipes: await fetchSavedRecipes() },
})
);组件资源的 _meta 字段
请在提供组件的资源模板(registerResource)上设置以下键。ChatGPT 可据此描述已渲染的 iframe 并确定其呈现方式,同时避免向其他客户端泄露元数据。
| 键 | 位置 | 类型 | 用途 |
|---|---|---|---|
_meta.ui.prefersBorder |
资源内容 | boolean | 提示主机在支持的情况下将组件渲染在带边框的卡片中。 |
_meta.ui.csp |
资源内容 | object | 设置小组件标准 CSP 字段的首选位置,包括 connectDomains、resourceDomains 和可选的 frameDomains。 |
_meta.ui.domain |
资源内容 | string(源) | 托管组件的专用源。提交带 UI 的插件时必须提供,且每个插件的源必须唯一。默认为 https://web-sandbox.oaiusercontent.com。 |
_meta["openai/ui"].availableDisplayModes |
资源内容 | string[] | 支持的显示模式包括 inline、fullscreen 和 pip。ChatGPT 可据此在加载组件前选择显示模式。 |
_meta["openai/widgetDescription"] |
资源内容 | string | 组件加载时提供给模型的易读摘要,可减少助手的重复说明。 |
_meta["openai/widgetPrefersBorder"] |
资源内容 | boolean | ChatGPT 中 _meta.ui.prefersBorder 的 OpenAI 专用兼容别名。 |
_meta["openai/widgetCSP"] |
资源内容 | object | 用于兼容旧版 ChatGPT 小组件 CSP 元数据的键。标准 CSP 字段已改用 _meta.ui.csp,但仍须通过 redirect_domains 指定 openExternal 的可信目标。 |
_meta["openai/widgetDomain"] |
资源内容 | string(源) | ChatGPT 中 _meta.ui.domain 的 OpenAI 专用兼容别名。 |
ChatGPT 支持旧版兼容键 _meta["openai/widgetCSP"]。该键的字段名采用小写字母加下划线的格式。
connect_domains:string[]resource_domains:string[]frame_domains?:string[]redirect_domains?:string[]。ChatGPT 扩展,用于指定window.openai.openExternal的重定向目标。
对于新 UI,通常优先使用标准对象 _meta.ui.csp。它支持以下字段。
connectDomains:string[]。小组件可以通过 fetch/XHR 访问的域名。resourceDomains:string[]。提供静态资源(图像、字体、脚本、样式)的域名。frameDomains?:string[]。可选列表,指定允许通过 iframe 嵌入的源。默认情况下,小组件无法渲染子框架。根据 iframe 政策,插件可以嵌入自己域名下的页面,包括已有的编辑器和管理界面。提交插件时必须说明理由。使用 iframe 可能需要额外审核,也可能延长审批时间。
不过,_meta.ui.csp 不支持通过 redirect_domains 指定 window.openai.openExternal(...) 链接的重定向目标。要将重定向目标加入允许列表,仍须设置 _meta["openai/widgetCSP"].redirect_domains。
在 UI 加载前声明显示模式
请在服务器返回的资源内容上设置 _meta["openai/ui"].availableDisplayModes。对于仅支持全屏的组件,ChatGPT 可据此直接以全屏模式打开组件,无需先以内嵌方式显示加载状态。
在资源的 contents 数组中返回以下对象,并将 html 设为组件的 HTML。
const resource = {
uri: "ui://widget/viewer.html",
mimeType: "text/html;profile=mcp-app",
text: html,
_meta: {
"openai/ui": {
availableDisplayModes: ["fullscreen"],
},
},
};
请列出组件支持的所有模式,例如 ["inline", "fullscreen"]。在 MCP Apps 初始化期间也应继续声明 availableDisplayModes。服务器端声明是对初始化流程的补充,该流程还支持动态显示模式。
工具结果
工具结果可以包含 MCP 规范列出的字段。下表列出了其中几个字段。
| 键 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
structuredContent |
object | 可选 | 提供给模型和组件。如果已声明 outputSchema,内容必须符合该模式。 |
content |
string 或 Content[] |
可选 | 提供给模型和组件。 |
_meta |
object | 可选 | 仅传递给组件,模型不可见。 |
只有 structuredContent 和 content 会出现在对话记录中。主机将 _meta 转发给组件,您可以用其中的数据填充 UI,而无需向模型公开这些数据。
下表列出主机提供的工具结果元数据。
| 键 | 位置 | 类型 | 用途 |
|---|---|---|---|
_meta["openai/widgetSessionId"] |
工具结果的 _meta(由主机提供) |
string | 当前已挂载的小组件实例的稳定 ID。在该实例卸载之前,可用此 ID 关联日志和工具调用。 |
示例
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });
// Local example data; replace this with your application data.
function generateZooAnimals(count: number) {
return Array.from({ length: count }, (_, index) => ({
id: `animal-${index + 1}`,
name: `Penguin ${index + 1}`,
species: "Penguin",
}));
}
import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";
registerAppTool(
server,
"get_zoo_animals",
{
title: "get_zoo_animals",
inputSchema: { count: z.number().int().min(1).max(20).optional() },
outputSchema: {
animals: z.array(
z.object({
id: z.string(),
name: z.string(),
species: z.string(),
})
),
},
_meta: { ui: { resourceUri: "ui://widget/widget.html" } },
},
async ({ count = 10 }) => {
const animals = generateZooAnimals(count);
return {
structuredContent: { animals },
content: [{ type: "text", text: `Here are ${animals.length} animals.` }],
_meta: {
allAnimalsById: Object.fromEntries(
animals.map((animal) => [animal.id, animal])
),
},
};
}
);工具返回的错误结果
要在工具结果中返回错误,请使用下表中的 _meta 键。
| 键 | 用途 | 类型 | 说明 |
|---|---|---|---|
_meta["mcp/www_authenticate"] |
错误结果 | string 或 string[] | 使用 RFC 7235 定义的 WWW-Authenticate 质询触发 OAuth 授权流程。 |
客户端提供的 _meta 字段
| 键 | 提供时机 | 类型 | 用途 |
|---|---|---|---|
_meta["openai/locale"] |
初始化和工具调用时 | string(BCP 47) | 请求使用的区域设置(旧版客户端可能发送 _meta["webplus/i18n"])。 |
_meta["openai/userAgent"] |
工具调用时 | string | 客户端会尽可能提供用户代理信息,可用于分析或调整格式。此字段为可选。 |
_meta["openai/userLocation"] |
工具调用时 | object | 大致位置信息(city、region、country、timezone、longitude、latitude)。 |
_meta["openai/subject"] |
工具调用时 | string | 发送给 MCP 服务器的匿名化用户 ID,用于实施速率限制和识别用户。 |
_meta["openai/session"] |
工具调用时 | string | 匿名化对话 ID,用于关联同一 ChatGPT 会话中的工具调用。 |
_meta["openai/organization"] |
工具调用时 | string | 与当前 ChatGPT 组织关联的匿名化组织 ID(如有)。 |
运行阶段提供的 _meta["openai/userAgent"] 和 _meta["openai/userLocation"] 仅供参考。服务器绝不能依赖这些字段做出授权决定,并且必须能在缺少这些字段时正常运行。_meta["openai/userAgent"] 是客户端尽可能提供的可选元数据,无法用它可靠地判断调用服务器的是哪个主机界面。
示例
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });
// Local example data; replace this with your application data.
async function findNearbyCafes(city: unknown) {
return city === "San Francisco"
? [{ name: "Example Cafe", address: "123 Example Street, San Francisco" }]
: [];
}
function formatIntro(locale: unknown, city: unknown) {
const location = typeof city === "string" ? city : "your area";
return locale === "es" ? `Cafés en ${location}` : `Cafes in ${location}`;
}
import { z } from "zod";
server.registerTool(
"recommend_cafe",
{
title: "Recommend a cafe",
inputSchema: {},
outputSchema: {
cafes: z.array(
z.object({
name: z.string(),
address: z.string(),
})
),
},
},
async (_args, { _meta }) => {
const locale = _meta?.["openai/locale"] ?? "en";
const userLocation = _meta?.["openai/userLocation"];
const location =
typeof userLocation === "object" &&
userLocation !== null &&
"city" in userLocation
? userLocation.city
: undefined;
const cafes = await findNearbyCafes(location);
return {
content: [{ type: "text", text: formatIntro(locale, location) }],
structuredContent: { cafes },
};
}
);