nitrostack-mcp-app-architecture

When to Use

Use this skill whenever you are bootstrapping a new NitroStack MCP server, creating modules, injecting services, or handling application lifecycle events.

Bootstrapping a NitroStack App

A NitroStack application is initialized with the @McpApp decorator on a root class, accompanied by a root @Module.

import { McpApp, Module } from '@nitrostack/core';
import { DatabaseModule } from './database/database.module.js';
import { UsersModule } from './users/users.module.js';

@McpApp({
  module: AppModule,
  server: {
    name: 'user-management-server',
    version: '1.0.0',
  },
})
@Module({
  imports: [DatabaseModule, UsersModule],
})
export class AppModule {}

Modules

Modules organize your application structure. Use the @Module decorator to define imports, exports, and providers.

• imports: Other modules whose exported providers should be available in this module.
• providers: Services, tools, resources, or prompts that should be instantiated and managed by the DI container within this module.
• exports: Providers defined in this module that should be visible to other modules importing this one.

import { Module } from '@nitrostack/core';
import { UsersService } from './users.service.js';
import { UsersTools } from './users.tools.js';

@Module({
  providers: [UsersService, UsersTools],
  exports: [UsersService],
})

## Controllers
Use the `@ControllerDecorator` (or alias it as `@Controller`) to group tools, resources, and prompts together. Controllers are automatically registered as singletons in the DI container.

### Key Controller Options:
* **`prefix`**: A string prefix applied to every `@Tool` defined in this controller. For example, `@ControllerDecorator('github')` prefixing a tool named `create_issue` exposes it to MCP clients as `github_create_issue`.

```typescript
import { ControllerDecorator as Controller, Tool, ExecutionContext } from '@nitrostack/core';

@Controller('github')
export class GitHubController {
  @Tool({
    name: 'create_issue',
    description: 'Create an issue in a repository',
    inputSchema: z.object({ /* ... */ })
  })
  async createIssue(input: any, ctx: ExecutionContext) {
    // Exposed to clients as "github_create_issue"
  }
}

Dependency Injection (DI)

NitroStack uses a robust dependency injection container to manage class instances and lifecycles.

Injection Lifecycles

1. Singleton (Default): A single instance is shared across the entire application.
2. Transient: A new instance is created every time it is resolved/injected.
3. Scoped: A new instance is created per incoming request or context.

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