resource-design

Create xmcp Resource

You are helping the user create a new xmcp resource. Follow this interactive workflow.

Step 1: Gather Information

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.

Step 2: Generate the Resource

Create the resource file in src/resources/ following the routing conventions:

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

Resource Structure Reference

Every xmcp resource has two main exports:

// 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 = { /* ... */ };

Quick Reference