Flow Hooks

Hook Types

Decorator	Timing	Use Case
`@Stage`	Define execution stage	Custom flow steps
`@Will`	Before stage executes	Pre-processing, validation
`@Did`	After stage executes	Post-processing, logging
`@Around`	Wraps stage execution	Caching, error handling

FlowHooksOf

Create typed hook decorators for a specific flow:

import { FlowHooksOf } from '@frontmcp/sdk';

const { Stage, Will, Did, Around } = FlowHooksOf('tools:call-tool');

class MyHooks {
  @Will('execute')
  async beforeExecute(ctx: ToolFlowContext) {
    console.log('Before tool execution');
  }

  @Did('execute')
  async afterExecute(ctx: ToolFlowContext) {
    console.log('After tool execution');
  }
}

Available Flows

Flow Name	Description
`tools:call-tool`	Tool execution
`tools:list-tools`	List tools
`resources:read-resource`	Read resource
`resources:list-resources`	List resources
`prompts:get-prompt`	Get prompt
`prompts:list-prompts`	List prompts
`http:request`	HTTP request handling

@Will (Before Hook)

Execute before a flow stage:

const { Will } = FlowHooksOf('tools:call-tool');

class ValidationHooks {
  @Will('execute', { priority: 10 })
  async validateInput(ctx: ToolFlowContext) {
    const input = ctx.state.get('input');
    if (!input) {
      throw new Error('Input is required');
    }
  }

  @Will('execute', { priority: 20 })
  async logStart(ctx: ToolFlowContext) {
    console.log(`Starting tool: ${ctx.state.get('toolName')}`);
  }
}

Priority

Lower priority values execute first:

@Will('execute', { priority: 10 }) // Executes first
@Will('execute', { priority: 20 }) // Executes second

Filter

Conditionally execute hooks:

@Will('execute', {
  filter: (ctx) => ctx.state.get('toolName') === 'sensitive_tool'
})
async logSensitiveAccess(ctx) {
  console.log('Accessing sensitive tool');
}

@Did (After Hook)

Execute after a flow stage:

const { Did } = FlowHooksOf('tools:call-tool');

class AuditHooks {
  @Did('execute')
  async auditToolCall(ctx: ToolFlowContext) {
    const toolName = ctx.state.get('toolName');
    const output = ctx.state.get('output');
    await this.auditService.log({
      tool: toolName,
      timestamp: new Date(),
      success: !ctx.state.get('error'),
    });
  }
}

@Around (Wrapper Hook)

Wrap stage execution for full control. The stage’s Will hooks run first, next() runs the stage itself, and its Did hooks run after the Around hook returns. An Around hook that does not call next() skips the stage. With several Around hooks on one stage, each next() runs the next one, and the innermost runs the stage. For tools:call-tool, the tool’s result is ctx.state.required.toolContext.output.

const { Around } = FlowHooksOf('tools:call-tool');

class CachingHooks {
  @Around('execute')
  async cacheResults(ctx: ToolFlowContext, next: () => Promise<void>) {
    const cacheKey = this.getCacheKey(ctx);
    const cached = await this.cache.get(cacheKey);

    if (cached) {
      ctx.state.required.toolContext.output = cached;
      return; // Skip actual execution
    }

    await next(); // Execute the stage

    await this.cache.set(cacheKey, ctx.state.required.toolContext.output);
  }
}

@Stage (Custom Stage)

Define custom flow stages:

const { Stage, Will, Did } = FlowHooksOf('tools:call-tool');

class CustomFlow {
  @Stage('preProcess')
  async preProcess(ctx: ToolFlowContext) {
    // Custom pre-processing stage
    const input = ctx.state.get('input');
    ctx.state.set('processedInput', transform(input));
  }

  @Will('preProcess')
  async beforePreProcess(ctx) {
    console.log('About to pre-process');
  }

  @Did('preProcess')
  async afterPreProcess(ctx) {
    console.log('Pre-processing complete');
  }
}

Hook Options

interface HookOptions<Ctx = unknown> {
  priority?: number;                              // Execution order (lower = first)
  filter?: (ctx: Ctx) => boolean | Promise<boolean>; // Conditional execution
  appliesTo?: 'own-app' | 'uncovered-apps';        // Reach of an app plugin's hook (default 'own-app')
}

A hook of a plugin installed on an app runs, in tools/call, resources/read, prompts/get and completion/complete, only for that app’s entries. With appliesTo: 'uncovered-apps' it also runs for the entries of any app that has no instance of the same hook (same class and method) of its own or from a server-level plugin. Use it for gates that an entry’s metadata asks for, so the entry is not left ungated when the plugin sits on another app.

Registering Hooks

In Apps

@App({
  name: 'my-app',
  providers: [AuditHooks, CachingHooks],
  tools: [MyTool],
})
class MyApp {}

In Plugins

@Plugin({
  name: 'audit-plugin',
  providers: [AuditHooks],
})
class AuditPlugin {}

On an Entry Class

A hook declared on a @Tool, @Resource, @Prompt or @Agent class runs only for that entry, on the instance created for each call:

@Tool({ name: 'get_ticket', inputSchema: {} })
class GetTicketTool extends ToolContext {
  @Will('execute')
  async recordAccess() {
    this.logger.info('get_ticket called');
  }

  async execute() {
    return { ok: true };
  }
}

Hooks from an app’s providers, and from the plugins (including plugins nested inside them) and plugin providers it lists, run only for that app’s tools, resources and prompts (tools:call-tool, resources:read-resource, prompts:get-prompt, completion:complete), including the ones its adapters and plugins provide, such as the tools an OpenAPI adapter generates. Plugins registered on the server (@FrontMcp({ plugins })) apply to every app. Resources and prompts the server serves outside every app, such as the SEP-2640 skill:// resources, run every app’s hooks.

Hook Context

Hooks receive flow context with access to:

interface FlowContext {
  state: FlowState;           // Flow state (input, output, metadata)
  logger: FrontMcpLogger;     // Logger instance
  providers: ProviderRegistry; // Dependency injection
}

// Access state
const input = ctx.state.get('input');
ctx.state.set('output', result);

// Access providers
const service = ctx.providers.get(ServiceToken);

// Access logger
ctx.logger.info('Processing');

Error Handling

A hook that throws stops the flow, and the error reaches the client like an error from the stage itself. An Around hook sees a failing stage as a rejected next(). It can rethrow, retry by calling next() again, or catch the rejection and return normally. Returning normally handles the failure: the stage counts as successful, so set the output the stage would have produced first. An Around hook skipped by its filter still runs the stage:

@Will('execute')
async validateInput(ctx) {
  // Throwing stops execution and reports error
  throw new InvalidInputError('Validation failed');
}

@Around('execute')
async errorHandler(ctx, next) {
  try {
    await next();
  } catch (error) {
    ctx.logger.error('Execution failed', { error });
    // Rethrow to keep the failure; returning instead would handle it
    throw error;
  }
}

Full Example

import { FlowHooksOf, Provider, Plugin, App, FrontMcp, Tool, ToolContext } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

const { Will, Did, Around } = FlowHooksOf('tools:call-tool');

// Audit hook provider
@Provider()
class AuditHooks {
  private auditLog: Array<{ tool: string; timestamp: Date; duration: number }> = [];

  @Will('execute', { priority: 0 })
  async recordStart(ctx) {
    ctx.state.set('_auditStartTime', Date.now());
  }

  @Did('execute', { priority: 1000 })
  async recordEnd(ctx) {
    const startTime = ctx.state.get('_auditStartTime');
    const duration = Date.now() - startTime;
    const toolName = ctx.state.get('toolName');

    this.auditLog.push({
      tool: toolName,
      timestamp: new Date(),
      duration,
    });

    ctx.logger.info(`Tool ${toolName} completed in ${duration}ms`);
  }

  getAuditLog() {
    return this.auditLog;
  }
}

// Rate limiting hook
@Provider()
class RateLimitHooks {
  private calls = new Map<string, number[]>();
  private maxCallsPerMinute = 60;

  @Will('execute', { priority: 5 })
  async checkRateLimit(ctx) {
    const toolName = ctx.state.get('toolName');
    const now = Date.now();
    const oneMinuteAgo = now - 60000;

    const recentCalls = (this.calls.get(toolName) || [])
      .filter(t => t > oneMinuteAgo);

    if (recentCalls.length >= this.maxCallsPerMinute) {
      throw new RateLimitError(60);
    }

    recentCalls.push(now);
    this.calls.set(toolName, recentCalls);
  }
}

// Caching hook
@Provider()
class CacheHooks {
  private cache = new Map<string, { value: unknown; expires: number }>();
  private ttl = 60000; // 1 minute

  @Around('execute', {
    filter: (ctx) => ctx.state.tool?.metadata.annotations?.idempotentHint === true
  })
  async cacheIdempotent(ctx, next) {
    const { name: toolName, arguments: toolArguments } = ctx.state.required.input;
    const cacheKey = `${toolName}:${JSON.stringify(toolArguments)}`;
    const toolContext = ctx.state.required.toolContext;

    const cached = this.cache.get(cacheKey);
    if (cached && cached.expires > Date.now()) {
      ctx.logger.debug('Cache hit', { toolName });
      toolContext.output = cached.value;
      return;
    }

    await next();

    this.cache.set(cacheKey, {
      value: toolContext.output,
      expires: Date.now() + this.ttl,
    });
  }
}

// Plugin bundling hooks
@Plugin({
  name: 'observability',
  description: 'Audit logging, rate limiting, and caching',
  providers: [AuditHooks, RateLimitHooks, CacheHooks],
})
class ObservabilityPlugin {}

// Sample tool
@Tool({
  name: 'get_data',
  inputSchema: { key: z.string() },
  annotations: { idempotentHint: true },
})
class GetDataTool extends ToolContext {
  async execute(input: { key: string }) {
    return { data: `Value for ${input.key}` };
  }
}

// App using plugin
@App({
  name: 'data-app',
  plugins: [ObservabilityPlugin],
  tools: [GetDataTool],
})
class DataApp {}

@FrontMcp({
  info: { name: 'Observable Server', version: '1.0.0' },
  apps: [DataApp],
})
export default class ObservableServer {}

HookRegistry

Hook registry API

Flow Types

Flow type definitions

@Plugin

Create plugins

Customize Flows

Flow customization guide

Decorators

API

Errors

Hook Types

FlowHooksOf

Available Flows

@Will (Before Hook)

Priority

Filter

@Did (After Hook)

@Around (Wrapper Hook)

@Stage (Custom Stage)

Hook Options

Registering Hooks

In Apps

In Plugins

On an Entry Class

Hook Context

Error Handling

Full Example

HookRegistry

Flow Types

@Plugin

Customize Flows

​Hook Types

​FlowHooksOf

​Available Flows

​@Will (Before Hook)

​Priority

​Filter

​@Did (After Hook)

​@Around (Wrapper Hook)

​@Stage (Custom Stage)

​Hook Options

​Registering Hooks

​In Apps

​In Plugins

​On an Entry Class

​Hook Context

​Error Handling

​Full Example

​Related

HookRegistry

Flow Types

@Plugin

Customize Flows

Hook Types

FlowHooksOf

Available Flows

@Will (Before Hook)

Priority

Filter

@Did (After Hook)

@Around (Wrapper Hook)

@Stage (Custom Stage)

Hook Options

Registering Hooks

In Apps

In Plugins

On an Entry Class

Hook Context

Error Handling

Full Example

Related