Decorators API Reference

import { ToolDecorator as Tool, z, ExecutionContext } from '@nitrostack/core';

@Tool(options: ToolOptions)

@Tool({
  name: 'create_user',
  title: 'Create User Account',
  description: 'Create a new user account with email and profile information',
  inputSchema: z.object({
    email: z.string().email().describe('User email address'),
    name: z.string().min(2).describe('Full name'),
    role: z.enum(['user', 'admin']).optional().describe('User role')
  }),
  outputSchema: z.object({
    id: z.string(),
    email: z.string(),
    name: z.string()
  }),
  annotations: {
    destructiveHint: false,
    idempotentHint: false,
    readOnlyHint: false,
    openWorldHint: false
  },
  examples: {
    request: { email: 'user@example.com', name: 'Jane Doe' },
    response: { id: 'usr_123', email: 'user@example.com', name: 'Jane Doe' }
  }
})
async createUser(input: CreateUserInput, ctx: ExecutionContext) {
  return this.userService.create(input);
}

import { ResourceDecorator as Resource, ExecutionContext } from '@nitrostack/core';

@Resource(options: ResourceOptions)

@Resource({
  uri: 'user://{userId}/profile',
  name: 'User Profile',
  title: 'User Profile Details',
  description: 'Complete user profile with preferences and settings',
  mimeType: 'application/json',
  annotations: {
    audience: ['user', 'assistant'],
    priority: 0.8,
    lastModified: '2024-01-15T10:30:00Z'
  }
})
async getUserProfile(uri: string, ctx: ExecutionContext) {
  const userId = uri.match(/user:\/\/([^\/]+)/)?.[1];
  const profile = await this.userService.getProfile(userId);
  return {
    contents: [{
      uri,
      mimeType: 'application/json',
      text: JSON.stringify(profile, null, 2)
    }]
  };
}

import { PromptDecorator as Prompt, ExecutionContext } from '@nitrostack/core';

@Prompt(options: PromptOptions)

@Prompt({
  name: 'code_review',
  title: 'Code Review Assistant',
  description: 'Generate a code review request with best practices checklist',
  arguments: [
    { name: 'language', description: 'Programming language', required: true },
    { name: 'focus', description: 'Review focus areas', required: false }
  ]
})
async getCodeReviewPrompt(args: { language: string; focus?: string }, ctx: ExecutionContext) {
  return [{
    role: 'user' as const,
    content: `Review this ${args.language} code focusing on: ${args.focus || 'general best practices'}`
  }];
}

import { Module } from '@nitrostack/core';

@Module(options: ModuleOptions)

@Module({
  name: 'users',
  description: 'User management module',
  controllers: [UserTools, UserResources],
  providers: [UserService, UserRepository],
  imports: [DatabaseModule],
  exports: [UserService]
})
export class UsersModule {}

import { McpApp, Module } from '@nitrostack/core';

@McpApp(options: McpAppOptions)

@McpApp({
  module: AppModule,
  server: {
    name: 'my-mcp-server',
    version: '1.0.0'
  },
  logging: {
    level: 'info'
  }
})
@Module({
  imports: [ConfigModule.forRoot(), UsersModule]
})
export class AppModule {}

import { UseGuards } from '@nitrostack/core';

@UseGuards(...guards: GuardConstructor[])

@Tool({ name: 'admin_action' })
@UseGuards(JWTGuard, AdminGuard)
async adminAction(input: AdminInput, ctx: ExecutionContext) {
  // Only authenticated admins can access
}

import { UseMiddleware } from '@nitrostack/core';

@UseMiddleware(...middleware: MiddlewareConstructor[])

@Tool({ name: 'tracked_operation' })
@UseMiddleware(LoggingMiddleware, TimingMiddleware)
async trackedOperation(input: OperationInput, ctx: ExecutionContext) {
  // Middleware runs before and after
}

import { UseInterceptors } from '@nitrostack/core';

@UseInterceptors(...interceptors: InterceptorConstructor[])

@Tool({ name: 'get_data' })
@UseInterceptors(ResponseWrapperInterceptor, DataMaskingInterceptor)
async getData(input: DataInput, ctx: ExecutionContext) {
  return { sensitiveField: 'value' };
  // Response transformed and masked by interceptors
}

import { UsePipes } from '@nitrostack/core';

@UsePipes(...pipes: PipeConstructor[])

@Tool({ name: 'search' })
@UsePipes(TrimPipe, ValidationPipe)
async search(input: { query: string }, ctx: ExecutionContext) {
  // Input is trimmed and validated
}

import { UseFilters } from '@nitrostack/core';

@UseFilters(...filters: ExceptionFilterConstructor[])

@Tool({ name: 'risky_operation' })
@UseFilters(GlobalExceptionFilter)
async riskyOperation(input: RiskyInput, ctx: ExecutionContext) {
  // Errors caught and formatted by filter
}

import { Cache } from '@nitrostack/core';

@Cache(options: CacheOptions)

@Tool({ name: 'get_product' })
@Cache({
  ttl: 300,
  key: (input) => `product:${input.productId}`,
  invalidateOn: ['product.updated']
})
async getProduct(input: { productId: string }, ctx: ExecutionContext) {
  return this.productService.findById(input.productId);
}

import { RateLimit } from '@nitrostack/core';

@RateLimit(options: RateLimitOptions)

@Tool({ name: 'send_email' })
@RateLimit({
  requests: 10,
  window: '1m',
  key: (ctx) => ctx.auth?.subject || 'anonymous',
  message: 'Email rate limit exceeded. Please wait.'
})
async sendEmail(input: EmailInput, ctx: ExecutionContext) {
  return this.emailService.send(input);
}

import { Injectable } from '@nitrostack/core';

@Injectable()

@Injectable()
export class UserService {
  constructor(
    private db: DatabaseService,
    private cache: CacheService
  ) {}

  async findById(id: string): Promise<User | null> {
    return this.db.query('SELECT * FROM users WHERE id = $1', [id]);
  }
}

import { Middleware, MiddlewareInterface } from '@nitrostack/core';

@Middleware()
export class LoggingMiddleware implements MiddlewareInterface {
  async use(context: ExecutionContext, next: () => Promise<any>): Promise<any> {
    // Implementation
  }
}

import { Interceptor, InterceptorInterface } from '@nitrostack/core';

@Interceptor()
export class TransformInterceptor implements InterceptorInterface {
  async intercept(context: ExecutionContext, next: () => Promise<any>): Promise<any> {
    // Implementation
  }
}

import { Pipe, PipeInterface } from '@nitrostack/core';

@Pipe()
export class ValidationPipe implements PipeInterface {
  transform(value: any, metadata?: ArgumentMetadata): any {
    // Implementation
  }
}

import { ExceptionFilter, ExceptionFilterInterface } from '@nitrostack/core';

@ExceptionFilter()
export class HttpExceptionFilter implements ExceptionFilterInterface {
  catch(exception: unknown, context: ExecutionContext): any {
    // Implementation
  }
}

import { Widget } from '@nitrostack/core';

@Widget(routePath: string)

@Tool({ name: 'get_chart_data' })
@Widget('chart-visualization')
async getChartData(input: ChartInput, ctx: ExecutionContext) {
  return this.chartService.getData(input);
  // Widget at src/widgets/app/chart-visualization/page.tsx renders result
}

@Tool({
  name: 'get_dashboard',
  title: 'User Dashboard',
  description: 'Get user dashboard with stats',
  inputSchema: z.object({ userId: z.string() }),
  // Status messages shown during execution
  invocation: {
    invoking: 'Loading dashboard...',
    invoked: 'Dashboard ready'
  },
  // Example data for widget preview (IMPORTANT!)
  examples: {
    request: { userId: 'user-123' },
    response: {
      user: { name: 'John', email: 'john@example.com' },
      stats: { orders: 42, totalSpent: 1234.56 }
    }
  }
})
@Widget('user-dashboard')
async getDashboard(input: { userId: string }, ctx: ExecutionContext) {
  return { user: {...}, stats: {...} };
}

import { HealthCheck, HealthCheckInterface } from '@nitrostack/core';

@HealthCheck(options: HealthCheckOptions)

@HealthCheck({
  name: 'database',
  description: 'Database connectivity check',
  interval: 30
})
export class DatabaseHealthCheck implements HealthCheckInterface {
  async check(): Promise<HealthCheckResult> {
    const isHealthy = await this.db.ping();
    return {
      status: isHealthy ? 'up' : 'down',
      message: isHealthy ? 'Database connected' : 'Database unreachable'
    };
  }
}

import { OnEvent } from '@nitrostack/core';

@OnEvent(eventName: string)

@Injectable()
export class NotificationService {
  @OnEvent('order.created')
  async handleOrderCreated(data: OrderCreatedEvent): Promise<void> {
    await this.emailService.sendOrderConfirmation(data.userId, data.orderId);
  }
}