TypeScriptResources
Options and Annotations
Every @Resource option, and hints about audience and priority
@Resource needs a URI and a name; the other options describe the content and how clients should treat it.
Options
Every @Resource needs a uri, a name, and a description; the rest are optional.
Options Reference
This interface lists every option @Resource accepts.
interface ResourceOptions {
/** URI template with optional parameters (required) */
uri: string;
/** Human-readable resource name (required) */
name: string;
/** Human-readable display title (optional) */
title?: string;
/** Description of what data the resource provides (required) */
description: string;
/** Content MIME type (default: 'text/plain') */
mimeType?: string;
/** Size of the resource in bytes (optional, for binary resources) */
size?: number;
/** Metadata hints for clients about how to use the resource */
annotations?: ResourceAnnotations;
/** Example response for documentation */
examples?: {
response?: unknown;
};
}Complete Example
A resource with a parameterized URI, annotations, and an example response that clients can preview.
@Resource({
uri: 'user://{userId}/profile',
name: 'User Profile',
title: 'User Profile Details',
description: 'Complete user profile including account settings, preferences, and activity summary',
mimeType: 'application/json',
annotations: {
audience: ['user', 'assistant'],
priority: 0.8,
lastModified: new Date().toISOString()
},
examples: {
response: {
id: 'usr_abc123',
email: 'jane.doe@example.com',
name: 'Jane Doe',
preferences: {
theme: 'dark',
language: 'en',
timezone: 'America/New_York'
},
stats: {
ordersPlaced: 42,
memberSince: '2023-01-15'
}
}
}
})
async getUserProfile(uri: string, ctx: ExecutionContext) {
const userId = this.extractParam(uri, /user:\/\/([^\/]+)\/profile/);
const profile = await this.userService.getProfile(userId);
return {
contents: [{
uri,
mimeType: 'application/json',
text: JSON.stringify(profile, null, 2)
}]
};
}Annotations
Resource annotations provide metadata hints to AI models and MCP clients about how to use or display resources.
Annotation Properties
Annotations tell clients who the content is for and how important it is. Clients may use them when choosing what to show or include in context.
interface ResourceAnnotations {
/**
* Who should see this resource.
* - 'user': For human consumption (UI display)
* - 'assistant': For AI model context
* Can include both for shared resources.
*/
audience?: ('user' | 'assistant')[];
/**
* Importance of this resource (0.0 to 1.0).
* Higher values indicate more important resources.
* Clients may use this to prioritize display or context inclusion.
*/
priority?: number;
/**
* ISO 8601 timestamp of when the resource was last modified.
* Helps clients cache and invalidate resources appropriately.
*/
lastModified?: string;
}Annotation Examples
High-Priority Configuration:
@Resource({
uri: 'config://application',
name: 'Application Configuration',
title: 'App Config',
description: 'Current application settings and feature flags',
mimeType: 'application/json',
annotations: {
audience: ['assistant'], // Primarily for AI context
priority: 1.0, // Highest priority
lastModified: '2024-01-15T10:30:00Z'
}
})
async getConfig(uri: string) {
// ...
}User-Facing Documentation:
@Resource({
uri: 'docs://api-reference',
name: 'API Reference',
title: 'API Documentation',
description: 'Complete API documentation for developers',
mimeType: 'text/markdown',
annotations: {
audience: ['user'], // For human reading
priority: 0.5, // Medium priority
lastModified: '2024-01-10T08:00:00Z'
}
})
async getApiDocs(uri: string) {
// ...
}Shared Context Resource:
@Resource({
uri: 'dashboard://metrics',
name: 'Dashboard Metrics',
title: 'Live Metrics Dashboard',
description: 'Real-time system metrics and KPIs',
mimeType: 'application/json',
annotations: {
audience: ['user', 'assistant'], // Both can use it
priority: 0.9,
lastModified: new Date().toISOString()
}
})
async getDashboardMetrics(uri: string) {
// ...
}