ResourceContext

Class Definition

export abstract class ResourceContext<
  Params extends Record<string, string> = Record<string, string>,
  Out = unknown,
> extends ExecutionContextBase<Out>

Type Parameters

Parameter	Description
`Params`	URI template parameters type
`Out`	Output type

Properties

Property	Type	Description
`metadata`	`ResourceMetadata \| ResourceTemplateMetadata`	Resource metadata
`uri`	`string`	The actual resource URI being read
`params`	`Params`	Extracted URI template parameters
`output`	`Out \| undefined`	Resource content (after execution)
`resourceName`	`string`	Resource name
`resourceId`	`string`	Resource ID

Abstract Method

execute(uri, params)

The main execution method that must be implemented.

abstract execute(uri: string, params: Params): Promise<Out>

Return Format

Resources must return ReadResourceResult:

interface ReadResourceResult {
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;   // Text content
    blob?: string;   // Base64-encoded binary
  }>;
}

Methods

respond(value)

Set output and end execution immediately.

respond(value: Out): never

async execute(uri: string, params: Params) {
  const cached = await this.cache.get(uri);
  if (cached) {
    this.respond(cached); // Ends execution
  }
  // Continue with fetch...
}

outputHistory

History of output changes during execution. Entries are HistoryEntry records:

type HistoryEntry<T> = {
  at: number;
  stage?: string;
  value: T | undefined;
  note?: string;
};

get outputHistory(): ReadonlyArray<HistoryEntry<Out>>

Static Resource Example

import { Resource, ResourceContext } from '@frontmcp/sdk';

@Resource({
  name: 'app-config',
  uri: 'config://app',
  mimeType: 'application/json',
  description: 'Application configuration',
})
class AppConfigResource extends ResourceContext {
  async execute(uri: string) {
    const config = this.get(ConfigService);

    return {
      contents: [{
        uri,
        mimeType: 'application/json',
        text: JSON.stringify({
          version: config.get('APP_VERSION'),
          environment: config.get('NODE_ENV'),
          features: config.getObject('FEATURES'),
        }, null, 2),
      }],
    };
  }
}

Template Resource Example

import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';

@ResourceTemplate({
  name: 'user-profile',
  uriTemplate: 'users://{userId}/profile',
  mimeType: 'application/json',
  description: 'User profile by ID',
})
class UserProfileResource extends ResourceContext<{ userId: string }> {
  async execute(uri: string, params: { userId: string }) {
    this.mark('fetching');

    const userService = this.get(UserServiceToken);
    const user = await userService.findById(params.userId);

    if (!user) {
      this.fail(new ResourceNotFoundError(uri));
    }

    return {
      contents: [{
        uri,
        mimeType: 'application/json',
        text: JSON.stringify({
          id: user.id,
          name: user.name,
          email: user.email,
          createdAt: user.createdAt,
        }),
      }],
    };
  }
}

Binary Content Example

import { Resource, ResourceContext } from '@frontmcp/sdk';
import { readFile } from '@frontmcp/utils';

@Resource({
  name: 'logo',
  uri: 'assets://logo.png',
  mimeType: 'image/png',
})
class LogoResource extends ResourceContext {
  async execute(uri: string) {
    const logoPath = this.get(ConfigService).get('LOGO_PATH');
    const buffer = await readFile(logoPath);

    return {
      contents: [{
        uri,
        mimeType: 'image/png',
        blob: buffer.toString('base64'),
      }],
    };
  }
}

Multiple Parameters Example

import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';

interface RepoFileParams {
  owner: string;
  repo: string;
  branch: string;
  path: string;
}

@ResourceTemplate({
  name: 'github-file',
  uriTemplate: 'github://{owner}/{repo}/{branch}/{path}',
  mimeType: 'text/plain',
  description: 'File from GitHub repository',
})
class GitHubFileResource extends ResourceContext<RepoFileParams> {
  async execute(uri: string, params: RepoFileParams) {
    const { owner, repo, branch, path } = params;

    this.logger.info('Fetching GitHub file', { owner, repo, branch, path });

    const response = await this.fetch(
      `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`
    );

    if (!response.ok) {
      if (response.status === 404) {
        this.fail(new ResourceNotFoundError(uri));
      }
      this.fail(new ResourceReadError(uri, new Error(`HTTP ${response.status}`)));
    }

    const content = await response.text();
    const mimeType = this.detectMimeType(path);

    return {
      contents: [{
        uri,
        mimeType,
        text: content,
      }],
    };
  }

  private detectMimeType(path: string): string {
    if (path.endsWith('.json')) return 'application/json';
    if (path.endsWith('.md')) return 'text/markdown';
    if (path.endsWith('.ts') || path.endsWith('.js')) return 'text/javascript';
    return 'text/plain';
  }
}

Full Example with Error Handling

import { ResourceTemplate, ResourceContext, App, FrontMcp } from '@frontmcp/sdk';
import { ResourceNotFoundError, ResourceReadError } from '@frontmcp/sdk';

@ResourceTemplate({
  name: 'document',
  uriTemplate: 'docs://{category}/{documentId}',
  title: 'Document',
  description: 'Fetch documents by category and ID',
  mimeType: 'application/json',
})
class DocumentResource extends ResourceContext<{ category: string; documentId: string }> {
  async execute(uri: string, params: { category: string; documentId: string }) {
    const { category, documentId } = params;

    this.mark('validation');
    if (!this.isValidCategory(category)) {
      this.fail(new InvalidResourceUriError(uri, `Invalid category: ${category}`));
    }

    this.mark('fetching');
    const docService = this.get(DocumentServiceToken);

    try {
      const doc = await docService.find(category, documentId);

      if (!doc) {
        this.fail(new ResourceNotFoundError(uri));
      }

      this.mark('serializing');
      return {
        contents: [{
          uri,
          mimeType: 'application/json',
          text: JSON.stringify({
            id: doc.id,
            title: doc.title,
            category,
            content: doc.content,
            metadata: {
              author: doc.author,
              createdAt: doc.createdAt,
              updatedAt: doc.updatedAt,
            },
          }, null, 2),
        }],
      };
    } catch (error) {
      this.logger.error('Failed to read document', { uri, error });
      this.fail(new ResourceReadError(uri, error as Error));
    }
  }

  private isValidCategory(category: string): boolean {
    return ['guides', 'api', 'tutorials'].includes(category);
  }
}

@App({
  name: 'docs',
  resources: [DocumentResource],
})
class DocsApp {}

@FrontMcp({
  info: { name: 'Documentation Server', version: '1.0.0' },
  apps: [DocsApp],
})
export default class DocServer {}

Argument Autocompletion

Resource templates can provide autocompletion for their URI parameters. There are two approaches, both with full DI access via this.get():

Convention-Based (Preferred)

Define a method named ${argName}Completer on your resource class. The framework discovers it automatically.

@ResourceTemplate({
  name: 'user-profile',
  uriTemplate: 'users://{userId}/profile',
  mimeType: 'application/json',
})
class UserProfileResource extends ResourceContext<{ userId: string }> {
  async execute(uri: string, params: { userId: string }) {
    const user = await this.get(UserService).findById(params.userId);
    return { id: user.id, name: user.name };
  }

  async userIdCompleter(partial: string) {
    const users = await this.get(UserService).search(partial);
    return { values: users.map(u => u.id), total: users.length };
  }
}

Override-Based

Override getArgumentCompleter(argName) for dynamic dispatch across multiple parameters.

getArgumentCompleter(argName: string): ResourceArgumentCompleter | null {
  if (argName === 'userId') {
    return async (partial) => {
      const users = await this.get(UserService).search(partial);
      return { values: users.map(u => u.id) };
    };
  }
  return null;
}

Convention-based completers take priority when both are present.

@Resource

Resource decorator

@ResourceTemplate

Template decorator

ResourceRegistry

Resource registry

Resource Errors

Resource errors

Decorators

API

Errors

Class Definition

Type Parameters

Properties

Abstract Method

execute(uri, params)

Return Format

Methods

respond(value)

outputHistory

Static Resource Example

Template Resource Example

Binary Content Example

Multiple Parameters Example

Full Example with Error Handling

Argument Autocompletion

Convention-Based (Preferred)

Override-Based

@Resource

@ResourceTemplate

ResourceRegistry

Resource Errors

​Class Definition

​Type Parameters

​Properties

​Abstract Method

​execute(uri, params)

​Return Format

​Methods

​respond(value)

​outputHistory

​Static Resource Example

​Template Resource Example

​Binary Content Example

​Multiple Parameters Example

​Full Example with Error Handling

​Argument Autocompletion

​Convention-Based (Preferred)

​Override-Based

​Related

@Resource

@ResourceTemplate

ResourceRegistry

Resource Errors

Class Definition

Type Parameters

Properties

Abstract Method

execute(uri, params)

Return Format

Methods

respond(value)

outputHistory

Static Resource Example

Template Resource Example

Binary Content Example

Multiple Parameters Example

Full Example with Error Handling

Argument Autocompletion

Convention-Based (Preferred)

Override-Based

Related