resource-design

创建 xmcp 资源

你将帮助用户创建新的 xmcp 资源。请遵循此交互式工作流。

步骤 1：收集信息

生成任何代码之前，使用 AskUserQuestion 询问用户以下问题：

1. 资源名称（如果尚未提供）：资源应该叫什么？（使用 kebab-case）

2. 资源类型：询问用户需要哪种类型的资源：

   • 静态 - 固定不变的内容（配置、文档）
   • 动态 - 取决于参数的内容（用户资料、报告）
   • 基于文件 - 从文件中读取的内容（日志、数据文件）

3. URI 模式：应该如何访问资源？

   • 简单：config://app 或 docs://readme
   • 带参数：users://[userId]/profile
   • 嵌套：reports://[year]/[month]/summary

4. 内容详情：

   • 内容是关于什么的？

5. Widget 支持（可选）：询问用户是否需要 OpenAI Widget 渲染。

步骤 2：生成资源

按照路由约定，在 src/resources/ 中创建资源文件：

文件位置与路由

资源使用类似 Next.js 的基于文件的路由：

src/resources/
├── (config)/              # Route group (not in URI)
│   └── app.ts            # → config://app
├── (users)/
│   └── [userId]/         # Dynamic segment
│       └── profile.ts    # → users://[userId]/profile
└── docs/
    └── readme.ts         # → docs://readme

路由约定：

• (folder) - 路由组，不包含在 URI 路径中
• [param] - 动态参数段
• 文件名会成为 URI 的最后一段

资源结构参考

每个 xmcp 资源都有两个主要导出：

// 1. Metadata (optional) - Resource configuration
export const metadata: ResourceMetadata = { /* ... */ };

// 2. Handler (required) - Default export function
export default function handler(params?) { /* ... */ }

// 3. Schema (optional) - For dynamic resources with parameters
export const schema = { /* ... */ };

快速参考

必要导入

import { type ResourceMetadata } from "xmcp";

// For dynamic resources
import { z } from "zod";
import { type InferSchema, type ResourceMetadata } from "xmcp";

元数据字段

字段	类型	必填	说明
name	string	否*	唯一的资源标识符
title	string	否	便于阅读的标题
description	string	否	此资源提供的内容
mimeType	string	否	内容类型（默认值：text/plain）
size	number	否	内容大小，单位为字节
_meta	object	否	供应商扩展（OpenAI 等）

*省略元数据时，xmcp 会使用文件名作为资源名称。

处理程序返回类型

返回类型	使用场景
string	简单文本内容
{ text: string }	显式文本内容
{ blob: Uint8Array, mimeType: string }	二进制内容
JSON.stringify(data)	JSON 内容

详细模板

如需完整代码模板，包括：

• 静态资源模式
• 带参数的动态资源
• 基于文件的资源
• 嵌套路由示例
• OpenAI 元数据示例

请阅读：references/patterns.md

---

生成后检查清单

1. 文件已在正确的 src/resources/ 位置创建
2. 如果使用元数据，请确保其中包含描述性的 name 和 description
3. Schema 的所有参数都使用 .describe()（如果是动态资源）
4. 处理程序返回适当的内容类型
5. 文件路径符合预期的 URI 模式

建议运行 pnpm build，以验证资源能否正确编译。