resource-design

xmcp リソースの作成

ユーザーが新しい xmcp リソースを作成できるよう支援します。次の対話型ワークフローに従ってください。

ステップ 1：情報を収集する

コードを生成する前に、AskUserQuestion を使って次の質問をユーザーに尋ねてください。

1. リソース名（指定されていない場合）：リソース名は何にしますか？（ケバブケースを使用します）

2. リソースタイプ：必要なリソースのタイプを尋ねます。

   • 静的 - 変更されない固定コンテンツ（設定、ドキュメント）
   • 動的 - パラメーターに依存するコンテンツ（ユーザープロフィール、レポート）
   • ファイルベース - ファイルから読み込むコンテンツ（ログ、データファイル）

3. URI パターン：リソースにどのようにアクセスしますか？

   • シンプル：config://app または docs://readme
   • パラメーター付き：users://[userId]/profile
   • ネスト：reports://[year]/[month]/summary

4. コンテンツの詳細：

   • コンテンツの内容は何ですか？

5. ウィジェットのサポート（任意）：OpenAI ウィジェットのレンダリングが必要かどうかを尋ねます。

ステップ 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 リソースには、主なエクスポートが 2 つあります。

// 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. スキーマのすべてのパラメーターに .describe() が使用されている（動的な場合）
4. ハンドラーが適切なコンテンツタイプを返す
5. ファイルパスが意図した URI パターンと一致している

リソースが正しくコンパイルされることを確認するため、pnpm build の実行を提案してください。