Back to Details

resource-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create xmcp Resource

创建xmcp资源

You are helping the user create a new xmcp resource. Follow this interactive workflow.
你正在协助用户创建新的xmcp资源，请遵循以下交互式工作流程。

Step 1: Gather Information

步骤1：收集信息

Before generating any code, ask the user these questions using AskUserQuestion:
  1. Resource name (if not provided): What should the resource be named? (Use kebab-case)
  2. Resource type: Ask which type of resource they need:
    • Static - Fixed content that doesn't change (configuration, documentation)
    • Dynamic - Content that depends on parameters (user profiles, reports)
    • File-based - Content read from files (logs, data files)
  3. URI pattern: How should the resource be accessed?
    • Simple: 
      config://app
      or 
      docs://readme
    • With parameters: 
      users://[userId]/profile
    • Nested: 
      reports://[year]/[month]/summary
  4. Content details:
    • What is the content about?
  5. Widget support (optional): Ask if they need OpenAI widget rendering.
在生成任何代码之前，使用AskUserQuestion向用户询问以下问题：
  1. 资源名称（若未提供）：资源应命名为什么？（使用短横线分隔命名法kebab-case）
  2. 资源类型：询问用户需要哪种类型的资源：
    • 静态资源 - 内容固定不变（配置文件、文档）
    • 动态资源 - 内容依赖参数（用户配置文件、报告）
    • 基于文件的资源 - 从文件读取内容（日志、数据文件）
  3. URI模式：资源应如何被访问？
    • 简单模式：
      config://app
      或 
      docs://readme
    • 带参数模式：
      users://[userId]/profile
    • 嵌套模式：
      reports://[year]/[month]/summary
  4. 内容详情：
    • 资源内容涉及什么主题？
  5. 组件支持（可选）：询问用户是否需要OpenAI组件渲染支持。

Step 2: Generate the Resource

步骤2：生成资源

Create the resource file in 
src/resources/
following the routing conventions:
按照路由约定在
src/resources/
目录下创建资源文件：

File Location & Routing

文件位置与路由

Resources use file-based routing similar to 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
Routing conventions:
  • (folder)
    - Route group, excluded from URI path
  • [param]
    - Dynamic parameter segment
  • Filename becomes the final URI segment
资源采用与Next.js类似的基于文件的路由机制：
src/resources/
├── (config)/              # 路由组（不会出现在URI中）
│   └── app.ts            # → config://app
├── (users)/
│   └── [userId]/         # 动态分段
│       └── profile.ts    # → users://[userId]/profile
└── docs/
    └── readme.ts         # → docs://readme
路由约定：
  • (folder)
    - 路由组，不会包含在URI路径中
  • [param]
    - 动态参数分段
  • 文件名会成为URI的最终分段

Resource Structure Reference

资源结构参考

Every xmcp resource has two main exports:
typescript
// 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 = { /* ... */ };
每个xmcp资源都包含两个主要导出项：
typescript
// 1. 元数据（可选）- 资源配置
export const metadata: ResourceMetadata = { /* ... */ };

// 2. 处理器（必填）- 默认导出函数
export default function handler(params?) { /* ... */ }

// 3.  Schema（可选）- 适用于带参数的动态资源
export const schema = { /* ... */ };

Quick Reference

快速参考

Essential Imports

必要导入

typescript
import { type ResourceMetadata } from "xmcp";

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

// 针对动态资源
import { z } from "zod";
import { type InferSchema, type ResourceMetadata } from "xmcp";

Metadata Fields

元数字段

FieldTypeRequiredDescription
name
stringNo*Unique resource identifier
title
stringNoHuman-readable title
description
stringNoWhat this resource provides
mimeType
stringNoContent type (default: text/plain)
size
numberNoContent size in bytes
_meta
objectNoVendor extensions (OpenAI, etc.)
*When metadata is omitted, xmcp uses the filename as the resource name.
字段类型是否必填说明
name
string否*唯一资源标识符
title
string否易读的标题
description
string否资源提供的内容说明
mimeType
string否内容类型（默认值：text/plain）
size
number否内容大小（字节）
_meta
object否厂商扩展（如OpenAI等）
*当省略元数据时，xmcp会将文件名作为资源名称。

Handler Return Types

处理器返回类型

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

Detailed Templates

详细模板

For complete code templates including:
  • Static resource patterns
  • Dynamic resource with parameters
  • File-based resources
  • Nested routing examples
  • OpenAI metadata examples
Read: 
references/patterns.md
如需完整的代码模板，包括：
  • 静态资源模式
  • 带参数的动态资源
  • 基于文件的资源
  • 嵌套路由示例
  • OpenAI元数据示例
阅读：
references/patterns.md

Checklist After Generation

生成后的检查清单

  1. File created in correct 
    src/resources/
    location
  2. If using metadata, ensure it has descriptive 
    name
    and 
    description
  3. Schema uses 
    .describe()
    for all parameters (if dynamic)
  4. Handler returns appropriate content type
  5. File path matches intended URI pattern
Suggest running 
pnpm build
to verify the resource compiles correctly.
  1. 文件已创建在正确的
    src/resources/
    目录下
  2. 若使用元数据，确保其包含描述性的
    name
    和
    description
  3. 若为动态资源，Schema中所有参数都使用
    .describe()
    进行说明
  4. 处理器返回了合适的内容类型
  5. 文件路径与预期的URI模式匹配
建议运行
pnpm build
来验证资源是否能正确编译。