alepha@docs:~/docs/.content/release/framework/docs/reference/primitives$
cat $resourceTemplate.md | pretty
2 min read

#$resourceTemplate

#Import

typescript 
1import { $resourceTemplate } from "alepha/mcp";

#Overview

Creates an MCP resource template - a resource addressed by a pattern rather than a fixed URI.

$resource covers data that lives at one known address. A template covers a family of them: every folio, every user, every file under a root. Without it, parameterized data can only be exposed as a tool call, and the client loses the ability to address it by URI or embed it as a resource_link.

URI templates (RFC 6570)

Two forms are supported, which is what MCP servers use in practice:

  • {var}: simple expansion. Matches one segment; will not span /. The captured value is percent-decoded.
  • {+var}: reserved expansion. Matches greedily, / included. Use it for trailing paths (file:///{+path}).

Any other operator (#, ., /, ;, ?, &) or modifier (*, :3) throws at registration rather than compiling into a pattern that quietly never matches.

#Options

Option Type Required Description
uriTemplate string Yes The RFC 6570 URI template this resource answers for.
name string No Human-readable name
title string No Human-friendly display title (spec 2025-11-25)
description string No Description of what this family of resources contains.
mimeType string No MIME type of the resource content.
size number No The raw content's size in bytes, before any encoding, when known
icons McpIcon[] No Optional icons surfaced in client UIs (spec 2025-11-25 / SEP-973).
annotations McpAnnotations No Audience / priority / lastModified hints (spec 2025-03-26+).
_meta Record<string, unknown> No Arbitrary metadata passed through to clients on the descriptor (spec 2025-06-18+).
cache Partial<McpCacheHints> No Caching hints for a resources/read this template serves, sent to modern clients only (spec 2026-07-28 ttlMs / cacheScope; a legacy client never sees them)
variables T No Zod schema validating the variables extracted from a concrete URI
handler Object Yes Handler returning the content for one concrete URI.
complete CompletionHandler No Optional autocompletion for the template's URI variables, served over completion/complete

#Examples

ts 
 1class FolioResources { 2  folio = $resourceTemplate({ 3    uriTemplate: "folio://{projectId}/{shortId}", 4    description: "A folio, by project and short id", 5    mimeType: "text/markdown", 6    variables: z.object({ 7      projectId: z.text(), 8      shortId: z.text(), 9    }),10    handler: async ({ variables }) => ({11      text: await this.folios.read(variables.projectId, variables.shortId),12    }),13  });14}