NitroStack

https://docs.nitrostack.ai
Admin
NitroStack is a decorator-based MCP framework for TypeScript, enabling the development of type-safe...
Tokens:192,698
Snippets:2,112
Trust Score:3.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Quick Start: Initialize, Develop, and Build

Source: https://docs.nitrostack.ai/cli/overview

A quick start guide to initialize a new project, install dependencies, and start the development server.

```bash
# Create a new project
nitrostack-cli init my-server --template typescript-auth

# Navigate to project
cd my-server

# Install dependencies
npm install

# Start development
nitrostack-cli dev
```

--------------------------------

### Quick Start: Install, Create, and Develop

Source: https://docs.nitrostack.ai/cli/installation

A quick start sequence to install the CLI, create a new project, and begin development.

```bash
# 1. Install CLI
npm install -g @nitrostack/cli

# 2. Create project
nitrostack-cli init my-project

# 3. Enter project
cd my-project

# 4. Start development
npm run dev

```

--------------------------------

### Example: Start Development Server on a Custom Port

Source: https://docs.nitrostack.ai/cli/overview

Example of starting the development server on port 8080.

```bash
nitrostack-cli dev --port 8080
```

--------------------------------

### Post-Initialization Project Setup

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Navigate into the project directory, set up the database for the 'typescript-auth' template, and start the development server.

```bash
cd my-project

# For typescript-auth template: setup database
npm run setup-db

# Start development
npm run dev

```

--------------------------------

### Deploy to Production

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Builds the project, copies files to the server, installs production dependencies, and starts the application.

```bash
# Build project
nitrostack-cli build

# Copy to server
scp -r dist/ user@server:/app/
scp -r src/widgets/.next/ user@server:/app/widgets/
scp package.json user@server:/app/
scp .env.production user@server:/app/.env

# On server
cd /app
npm install --production
node dist/index.js


```

--------------------------------

### Initialize TypeScript Starter Project

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Installs the CLI, initializes a new project with the TypeScript starter template, and starts the development server.

```bash
# Install CLI
npm install -g nitrostack

# Initialize project
nitrostack-cli init my-calculator --template typescript-starter
cd my-calculator

# Start development
npm run dev

# Open Studio
# http://localhost:3000


```

--------------------------------

### Get Help Example

Source: https://docs.nitrostack.ai/templates/starter

Shows how a user can ask for help and the AI responds by using a 'calculator_help' prompt.

```text
User: "How do I use the calculator?"
AI: Uses calculator_help prompt
Result: Complete usage instructions
```

--------------------------------

### Basic Install Command

Source: https://docs.nitrostack.ai/cli/install

Run the install command to install all project dependencies in the root and widget directories.

```bash
nitrostack-cli install
```

--------------------------------

### Initialize TypeScript Auth Project

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Installs the CLI, initializes a new project with the TypeScript auth template, sets up the database, and starts the development server.

```bash
# Install CLI
npm install -g nitrostack

# Initialize project
nitrostack-cli init my-shop --template typescript-auth
cd my-shop

# Setup database
npm run setup-db

# Start development
npm run dev

# Open Studio and login
# http://localhost:3000


```

--------------------------------

### Quick Start Widget Example

Source: https://docs.nitrostack.ai/sdk/typescript/ui/widget-sdk

A basic example of a React widget using the Widget SDK hooks to fetch data and apply theme styles. Ensure the necessary hooks are imported from '@nitrostack/widgets'.

```typescript
'use client';

import { useWidgetSDK, useTheme } from '@nitrostack/widgets';

export default function MyWidget() {
  const { isReady, callTool, getToolOutput } = useWidgetSDK();
  const theme = useTheme();
  
  if (!isReady) return <div>Loading...</div>;
  
  const data = getToolOutput();
  
  return (
    <div style={{ 
      background: theme === 'dark' ? '#000' : '#fff',
      color: theme === 'dark' ? '#fff' : '#000'
    }}>
      <h1>{data.title}</h1>
    </div>
  );
}

```

--------------------------------

### Start Development Server

Source: https://docs.nitrostack.ai/templates/pizzaz

Starts the development server with Studio enabled. Use this for local development and testing.

```bash
npm run dev              # Start dev server with Studio
```

--------------------------------

### Build and Start NitroStudio for Self-Hosting

Source: https://docs.nitrostack.ai/studio/overview

Build the NitroStudio application for deployment and then start the self-hosted instance.

```bash
npm run build
npm start

```

--------------------------------

### Using npm Script for Installation

Source: https://docs.nitrostack.ai/cli/install

Execute the 'npm run install:all' script as a shortcut for the 'nitrostack-cli install' command.

```bash
npm run install:all
```

--------------------------------

### Start Production Server

Source: https://docs.nitrostack.ai/api/cli-commands

Starts the production server on a specified port.

```bash
nitrostack-cli start [options]

```

```bash
nitrostack-cli start --port 8080

```

--------------------------------

### Example: Initialize Project with TypeScript Auth Template

Source: https://docs.nitrostack.ai/cli/overview

Example of initializing a new project named 'ecommerce' using the 'typescript-auth' template.

```bash
nitrostack-cli init ecommerce --template typescript-auth
```

--------------------------------

### Start Studio for Local Development (STDIO)

Source: https://docs.nitrostack.ai/guides/dual-transport

Instructions to start the Studio in local development mode, which uses STDIO by default.

```bash
# Terminal 1: Start Studio
cd nitrostack/src/studio
npm run dev

# Studio will use STDIO by default (via MCP_COMMAND/MCP_ARGS)

```

--------------------------------

### Generate and Sync Widget Examples with CLI

Source: https://docs.nitrostack.ai/guides/widget-examples

Use the CLI to generate widget examples and synchronize them. Ensure the 'nitrostack' command is available in your PATH.

```bash
nitrostack generate widget my-widget
nitrostack sync widget-examples

```

--------------------------------

### Examples: Generating Code Components

Source: https://docs.nitrostack.ai/cli/overview

Examples demonstrating how to generate types, a module, a tool, and a guard using the 'generate' command.

```bash
# Generate types
nitrostack-cli generate types

# Generate module
nitrostack-cli generate module payments

# Generate tool
nitrostack-cli generate tool create-payment --module payments

# Generate guard
nitrostack-cli generate guard admin
```

--------------------------------

### Install Nitrostack OAuth Server Template

Source: https://docs.nitrostack.ai/sdk/typescript/auth/oauth

Installs the Nitrostack CLI and initializes a new project with the TypeScript OAuth template. Navigate into the project directory and install dependencies.

```bash
npx @nitrostack/cli init my-oauth-server
# Select: typescript-oauth
cd my-oauth-server
npm install

```

--------------------------------

### Install Command with Options

Source: https://docs.nitrostack.ai/cli/install

Use the --skip-widgets option to install only root dependencies, excluding the src/widgets directory.

```bash
nitrostack-cli install --skip-widgets
```

--------------------------------

### Complete Tool Example

Source: https://docs.nitrostack.ai/sdk/typescript/tools

An example demonstrating how to use the `@Tool` decorator with various options to define a `createUser` function.

```APIDOC
## createUser Function with Tool Decorator

### Description
This example shows a `createUser` function decorated with `@Tool`, specifying its name, title, description, input and output schemas, annotations, and examples.

### Method
`@Tool` decorator applied to an `async` function.

### Endpoint
N/A (SDK method)

### Parameters (Tool Decorator Options)
- **name** (string) - Required - 'create_user'
- **title** (string) - Optional - 'Create User Account'
- **description** (string) - Required - 'Create a new user account with the provided details. Returns the created user object with generated ID.'
- **inputSchema** (zod.ZodObject) - Required - Schema for input validation.
  - **email** (string) - Required - Valid email address for the account.
  - **name** (string) - Required - Full name of the user (min 2, max 100 chars).
  - **role** (string) - Optional - User role (user, admin, moderator), defaults to 'user'.
  - **metadata** (Record<string, unknown>) - Optional - Additional key-value pairs for custom attributes.
- **outputSchema** (zod.ZodObject) - Optional - Schema for output validation.
  - **id** (string) - Generated user ID.
  - **email** (string) - User's email.
  - **name** (string) - User's name.
  - **role** (string) - User's role.
  - **createdAt** (string) - Timestamp of creation.
- **annotations** (object) - Behavioral hints.
  - **destructiveHint** (boolean) - false (Creates new data).
  - **idempotentHint** (boolean) - false (Creates new user each time).
  - **readOnlyHint** (boolean) - false (Modifies system state).
  - **openWorldHint** (boolean) - false (Closed system operation).
- **examples** (object) - Example request/response.
  - **request** (object) - Example request body.
    - **email**: 'jane.doe@example.com'
    - **name**: 'Jane Doe'
    - **role**: 'user'
  - **response** (object) - Example response body.
    - **id**: 'usr_abc123'
    - **email**: 'jane.doe@example.com'
    - **name**: 'Jane Doe'
    - **role**: 'user'
    - **createdAt**: '2024-01-15T10:30:00Z'

### Parameters (Function Arguments)
- **input** (CreateUserInput) - The input object conforming to the inputSchema.
- **ctx** (ExecutionContext) - The execution context.

### Request Example
(See `examples.request` in Tool Decorator Options)

### Response
#### Success Response
Returns the created user object, conforming to the `outputSchema`.

#### Response Example
(See `examples.response` in Tool Decorator Options)
```

--------------------------------

### Complete Tool Decorator Example

Source: https://docs.nitrostack.ai/sdk/typescript/tools

An example demonstrating how to use the @Tool decorator with all its options, including input/output schemas, annotations, and example request/response pairs.

```typescript
@Tool({
  name: 'create_user',
  title: 'Create User Account',
  description: 'Create a new user account with the provided details. Returns the created user object with generated ID.',
  inputSchema: z.object({
    email: z.string().email().describe('Valid email address for the account'),
    name: z.string().min(2).max(100).describe('Full name of the user'),
    role: z.enum(['user', 'admin', 'moderator']).default('user')
      .describe('User role determining access permissions'),
    metadata: z.record(z.string()).optional()
      .describe('Additional key-value pairs for custom attributes')
  }),
  outputSchema: z.object({
    id: z.string().describe('Generated user ID'),
    email: z.string(),
    name: z.string(),
    role: z.string(),
    createdAt: z.string()
  }),
  annotations: {
    destructiveHint: false,  // Creates new data, doesn't destroy
    idempotentHint: false,   // Creates new user each time
    readOnlyHint: false,     // Modifies system state
    openWorldHint: false     // Closed system operation
  },
  examples: {
    request: {
      email: 'jane.doe@example.com',
      name: 'Jane Doe',
      role: 'user'
    },
    response: {
      id: 'usr_abc123',
      email: 'jane.doe@example.com',
      name: 'Jane Doe',
      role: 'user',
      createdAt: '2024-01-15T10:30:00Z'
    }
  }
})
async createUser(input: CreateUserInput, ctx: ExecutionContext) {
  return this.userService.create(input);
}


```

--------------------------------

### Start NitroStack Project

Source: https://docs.nitrostack.ai/studio/overview

Navigate to your project directory and run this command to start the MCP and widget servers.

```bash
cd your-project
npm run dev

```

--------------------------------

### Run Production Server with npm

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Start the production-ready server using npm.

```bash
npm start
```

--------------------------------

### Start Development Server

Source: https://docs.nitrostack.ai/api/cli-commands

Starts the development server with hot reload capabilities. Does not open the browser by default.

```bash
nitrostack-cli dev [options]

```

```bash
nitrostack-cli dev

```

--------------------------------

### Install Dependencies

Source: https://docs.nitrostack.ai/api/cli-commands

Installs dependencies in the project root and optionally in widget directories.

```bash
nitrostack-cli install [options]

```

```bash
# Install all dependencies
nitrostack-cli install

# Install root only
nitrostack-cli install --skip-widgets

```

--------------------------------

### Documenting Resources with Examples

Source: https://docs.nitrostack.ai/sdk/typescript/resources

Provide example responses within decorator options to clearly document resource behavior. This helps consumers understand the expected output format.

```typescript
@Resource({
  uri: 'product://{id}',
  name: 'Product Details',
  description: 'Complete product information including pricing, inventory, and metadata',
  mimeType: 'application/json',
  examples: {
    response: {
      id: 'prod_abc123',
      name: 'Premium Widget',
      price: 49.99,
      currency: 'USD',
      inventory: { available: 150, reserved: 12 },
      metadata: { category: 'electronics', weight: '0.5kg' }
    }
  }
})
```

--------------------------------

### Connect Tool to Widget with Examples

Source: https://docs.nitrostack.ai/guides/widget-examples

Connects a backend tool to a frontend widget using the Tool decorator. It demonstrates how to define tool-specific examples that can override widget examples.

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

export class MyTools {
  @Tool({
    name: 'my_tool',
    description: 'Does something cool',
    inputSchema: z.object({
      input: z.string()
    }),
    // Connect to widget
    widget: {
      uri: '/my-widget',
      transform: (output) => ({
        title: output.title,
        count: output.count
      })
    },
    // Optional: Override widget examples with tool-specific ones
    examples: {
      request: { input: 'test' },
      response: { title: 'Result', count: 10 }
    }
  })
  async myTool({ input }: { input: string }, ctx: ExecutionContext) {
    return { title: 'Result', count: input.length };
  }
}

```

--------------------------------

### Book Flight Example

Source: https://docs.nitrostack.ai/templates/oauth

Example of a user booking a flight. The AI calls the create_order function, and the result is a booking confirmation widget.

```text
User: "Book this flight for 2 passengers"
AI: Calls create_order
Result: Widget with booking confirmation

```

--------------------------------

### MCP Resource for Widget Examples

Source: https://docs.nitrostack.ai/guides/widget-examples

Access all registered widgets and their examples through the `widget://examples` MCP resource.

```APIDOC
## MCP Resource

### Description
The SDK exposes widget examples via the `widget://examples` MCP resource. This resource returns JSON with all registered widgets and their examples.

### Endpoint
`widget://examples`

### Response
#### Success Response
- **widgets** (array): An array of widget metadata objects.
  - **uri** (string): Widget route/URI
  - **name** (string): Display name
  - **description** (string): Widget description
  - **examples** (array): Array of example objects
    - **name** (string): Example name
    - **description** (string): Example description
    - **data** (object): Example data matching widget interface
  - **tags** (array, optional): Tags for categorization
```

--------------------------------

### Widget Examples Resource URI

Source: https://docs.nitrostack.ai/guides/widget-examples

The URI used to access registered widget examples. This resource returns JSON containing all registered widgets and their associated examples.

```uri
widget://examples

```

--------------------------------

### Start Nitrostack Development Mode

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Start the development server, which includes the server, Studio, and widgets. The `--port` flag allows specifying a custom port for Studio.

```bash
nitrostack-cli dev
```

```bash
nitrostack-cli dev --port <n>
```

--------------------------------

### Realistic Product Data Example

Source: https://docs.nitrostack.ai/sdk/typescript/ui/widget-manifest

Use actual product data in your manifest examples to accurately represent how the widget will function. This includes specific names, prices, and image URLs.

```JSON
{
  "data": {
    "product": {
      "name": "Wireless Bluetooth Headphones",
      "price": 79.99,
      "image_url": "https://cdn.example.com/headphones.jpg"
    }
  }
}
```

--------------------------------

### Install OAuth Dependencies

Source: https://docs.nitrostack.ai/sdk/typescript/oauth-2.1

Install the necessary OAuth 2.1 library using npm. This is the first step before configuring OAuth.

```bash
npm install @panva/oauth4webapi

```

--------------------------------

### Provide Realistic Tool Examples

Source: https://docs.nitrostack.ai/sdk/typescript/tools

Include realistic examples for tool requests and responses to aid AI model understanding. This helps in predicting expected inputs and outputs.

```typescript
@Tool({
  name: 'create_invoice',
  examples: {
    request: {
      customerId: 'cust_abc123',
      lineItems: [
        { description: 'Consulting services', amount: 5000, quantity: 1 }
      ],
      dueDate: '2024-02-15'
    },
    response: {
      id: 'inv_xyz789',
      number: 'INV-2024-0042',
      status: 'draft',
      total: 5000,
      createdAt: '2024-01-15T10:30:00Z'
    }
  }
})


```

--------------------------------

### Start Development Services

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Use this command to start all Nitrostack services in development mode. You can specify a custom port for the Studio interface.

```bash
# Start all services
nitrostack-cli dev

# Custom port for Studio
nitrostack-cli dev --port 3002

```

--------------------------------

### Install Dependencies in Existing Projects

Source: https://docs.nitrostack.ai/installation

Install all root and widget dependencies for an existing NitroStack project using the CLI.

```bash
# Install all dependencies in root and widgets
nitrostack-cli install

```

--------------------------------

### Install and Deploy with NitroStack CLI

Source: https://docs.nitrostack.ai/deployment/cloud

Quickly deploy your server using the NitroStack CLI. This involves installing the CLI, logging into your NitroCloud account, and initiating the deployment process.

```Bash
# Install NitroStack CLI
npm install -g @nitrostack/cli

# Login to NitroCloud
nitrostack login

# Deploy your server
nitrostack deploy

```

--------------------------------

### Widget Manifest with Multiple Product Card Examples

Source: https://docs.nitrostack.ai/sdk/typescript/ui/widget-manifest

This JSON demonstrates a widget manifest entry for a product card, showcasing different UI states with varying example data for in-stock, low-stock, and out-of-stock scenarios.

```json
{
  "uri": "/product-card",
  "name": "Product Card",
  "description": "Displays product details",
  "examples": [
    {
      "name": "In Stock Product",
      "description": "Product with high stock",
      "data": {
        "product": { "name": "Laptop", "price": 999, "stock": 50 },
        "availability": "In Stock"
      }
    },
    {
      "name": "Low Stock Product",
      "description": "Product with low stock",
      "data": {
        "product": { "name": "Laptop", "price": 999, "stock": 2 },
        "availability": "In Stock",
        "stockMessage": "Only 2 left!"
      }
    },
    {
      "name": "Out of Stock",
      "description": "Unavailable product",
      "data": {
        "product": { "name": "Laptop", "price": 999, "stock": 0 },
        "availability": "Out of Stock"
      }
    }
  ],
  "tags": ["products", "details"]
}

```

--------------------------------

### Example Dependency Versioning

Source: https://docs.nitrostack.ai/cli/upgrade

Illustrates the use of caret versioning for dependencies in package.json.

```json
{
  "dependencies": {
    "@nitrostack/core": "^1.2.0"
  }
}

```

--------------------------------

### Start Application with PM2

Source: https://docs.nitrostack.ai/deployment/checklist

Use PM2, a production process manager for Node.js, to start and manage your application. PM2 provides features like clustering and log management.

```bash
pm2 start dist/index.js --name mcp-server

```

--------------------------------

### Best Practice: Initialize with Template

Source: https://docs.nitrostack.ai/cli/overview

Start new projects using a template to ensure adherence to best practices.

```bash
nitrostack-cli init my-project --template typescript-auth
```

--------------------------------

### Install tsx Globally

Source: https://docs.nitrostack.ai/quick-start

Install the tsx package globally to manage Node.js versions. This is a prerequisite for the project setup.

```bash
npm i tsx -g
```

--------------------------------

### Tool Design with Examples

Source: https://docs.nitrostack.ai/sdk/typescript/best-practices

Include examples within your tool definitions to illustrate expected request and response formats. This serves as valuable documentation for users of the tool.

```typescript
@Tool({
  name: 'get_product',
  examples: {
    request: { product_id: 'prod-1' },
    response: { id: 'prod-1', name: 'Product', price: 99.99 }
  }
})


```

--------------------------------

### Manual Major Version Upgrade

Source: https://docs.nitrostack.ai/cli/upgrade

Installs a specific major version of a Nitrostack package, typically after reviewing migration guides.

```bash
npm install @nitrostack/core@2

```

--------------------------------

### Initialize Database with npm

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Initialize the database, specifically for the authentication template, using npm.

```bash
npm run setup-db
```

--------------------------------

### npm Scripts for NitroStack CLI

Source: https://docs.nitrostack.ai/api/cli-commands

Defines common npm scripts that wrap NitroStack CLI commands for development, building, starting, upgrading, and installing.

```json
{
  "scripts": {
    "dev": "nitrostack-cli dev",
    "build": "nitrostack-cli build",
    "start": "nitrostack-cli start",
    "upgrade": "nitrostack-cli upgrade",
    "install:all": "nitrostack-cli install"
  }
}

```

--------------------------------

### Initialize a new project

Source: https://docs.nitrostack.ai/cli/init

Basic usage of the init command to create a new project with a default configuration.

```bash
nitrostack-cli init my-project

```

--------------------------------

### Programmatic HTTP Client Setup

Source: https://docs.nitrostack.ai/guides/dual-transport

Use this code to programmatically set up an HTTP transport and connect an MCP client. Ensure the transport is started before connecting the client. The Authorization header is optional.

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { HttpClientTransport } from './http-client-transport.js';

// Create HTTP transport
const transport = new HttpClientTransport({
  baseUrl: 'http://localhost:3000',
  basePath: '/mcp',
  headers: {
    'Authorization': 'Bearer your-token', // Optional
  },
});

// Start transport (establishes SSE connection)
await transport.start();

// Create and connect client
const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(transport);

// Use the client
const tools = await client.listTools();
console.log('Available tools:', tools);

```

--------------------------------

### Dockerize NitroStudio for Self-Hosting

Source: https://docs.nitrostack.ai/studio/standalone

A Dockerfile to containerize NitroStudio for deployment. It sets up a Node.js environment, copies the project, installs dependencies, builds the application, exposes port 3000, and starts the production server.

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

```

--------------------------------

### Install NitroStack CLI

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Install the NitroStack CLI globally for end-user access or use npx for temporary execution without installation.

```bash
# Global install (recommended for end users)
npm install -g nitrostack

# Or use npx (no installation)
npx nitrostack --version

```

--------------------------------

### Install Nitrostack CLI

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Install the Nitrostack CLI globally using npm or use npx to run commands without global installation.

```bash
# Install globally
npm install -g nitrostack
```

```bash
# Or use npx
npx nitrostack-cli init my-project
```

--------------------------------

### Tool Decorator Example

Source: https://docs.nitrostack.ai/api/decorators

Example of the @Tool decorator used to define a 'create_user' tool. It includes input and output schemas, annotations, and example request/response pairs.

```typescript
@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);
}
```

--------------------------------

### Start NitroStack Project

Source: https://docs.nitrostack.ai/studio/standalone

Navigate to your project directory and run the development server using npm.

```Bash
cd my-project
npm run dev
```

--------------------------------

### List Available Operations Example

Source: https://docs.nitrostack.ai/templates/starter

Illustrates how to query available operations by fetching the 'calculator://operations' resource.

```text
User: "What operations are available?"
AI: Fetches calculator://operations resource
Result: Widget showing all 4 operations
```

--------------------------------

### Start Development Server with npm

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Run the development server using npm, which automatically handles the MCP server, Studio, and widgets with auto-build capabilities.

```bash
npm run dev
```

--------------------------------

### Install NitroStack CLI

Source: https://docs.nitrostack.ai/api/cli-commands

Installs the NitroStack CLI globally using npm.

```bash
npm install -g @nitrostack/cli

```

--------------------------------

### Chat Interface Example

Source: https://docs.nitrostack.ai/studio/standalone

Demonstrates how to interact with the Studio's chat interface to test tools and view rendered widgets.

```Text
You: Search for flights from London to Tokyo

AI: [Calls search_flights tool]
    [Renders flight-results widget]
    Here are the available flights...
```

--------------------------------

### Install Jest Dependencies

Source: https://docs.nitrostack.ai/sdk/typescript/testing

Install Jest, @types/jest, and ts-jest for testing. These are development dependencies.

```bash
npm install --save-dev jest @types/jest ts-jest

```

--------------------------------

### Development Cycle Commands

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Starts the development server, manages widget dependencies, generates types, and builds for production.

```bash
# Start dev server (auto-detects and builds everything)
npm run dev

# The CLI automatically:
# - Installs dependencies (if needed)
# - Builds widgets (on first run)
# - Starts TypeScript watch mode
# - Starts Studio
# - Starts widget dev server
# - Hot reloads everything

# Edit code (auto-reloads)
# - Edit src/modules/**/*.ts (MCP server hot reloads)
# - Edit src/widgets/app/**/* (Widget dev server hot reloads)

# Test in Studio
# - Execute tools manually
# - Test with AI chat
# - Preview widgets

# Add widget dependencies
npm run widget add <package-name>

# Generate types for widgets
nitrostack-cli generate types

# Build for production
npm run build

# Test production build
npm start


```

--------------------------------

### Verify CLI Installation

Source: https://docs.nitrostack.ai/cli/installation

Verify that the NitroStack CLI has been installed correctly by checking its version.

```bash
nitrostack-cli --version

```

--------------------------------

### Custom Pipe Implementation Example

Source: https://docs.nitrostack.ai/api/pipes

An example of a custom pipe that trims whitespace from a value.

```typescript
@Pipe()
export class MyPipe implements PipeInterface {
  transform(value: any): any {
    return value.trim();
  }
}
```

--------------------------------

### Navigate to Project Directory

Source: https://docs.nitrostack.ai/quick-start

Change the current directory to the newly created 'my-server' project folder.

```bash
cd my-server
```

--------------------------------

### Development and Production Commands

Source: https://docs.nitrostack.ai/templates/oauth

Commands to start the development server with Studio, build for production, or run the production server.

```bash
npm run dev              # Start dev server with Studio
npm run build            # Build for production
npm start                # Run production server
```

--------------------------------

### Start Docker Compose Services

Source: https://docs.nitrostack.ai/deployment/docker

Starts all services defined in the `docker-compose.yml` file in detached mode.

```bash
docker-compose up -d

```

--------------------------------

### Install Dependencies and Build Project

Source: https://docs.nitrostack.ai/quick-start

Resolve TypeScript compilation errors by installing dependencies and rebuilding the project.

```bash
npm install
npm run build
```

--------------------------------

### Development and Build Commands

Source: https://docs.nitrostack.ai/quick-start

Run development server with hot reload, build for production, or start the production server.

```bash
# Development
npm run dev              # Start development server with hot reload

# Building
npm run build            # Build for production
npm start                # Run production server
```

--------------------------------

### Manual Root Dependency Installation

Source: https://docs.nitrostack.ai/installation

Manually install root dependencies for a NitroStack project using npm.

```bash
# Root dependencies
npm install @nitrostack/core zod dotenv
npm install -D @nitrostack/cli @types/node typescript

```

--------------------------------

### Troubleshooting Cache Issues

Source: https://docs.nitrostack.ai/cli/install

Clear the npm cache forcefully and then run the install command if installation fails.

```bash
npm cache clean --force
nitrostack-cli install
```

--------------------------------

### Generate Module (Best Practice)

Source: https://docs.nitrostack.ai/cli/generate

Demonstrates the recommended way to generate a new module using the CLI for consistency and organization.

```bash
# Good
nitrostack-cli generate module users

# Avoid
# Manually creating files

```

--------------------------------

### Complete Resource Decorator Example

Source: https://docs.nitrostack.ai/sdk/typescript/resources

Demonstrates how to use the Resource decorator with various options to define a user profile resource and its retrieval logic.

```typescript
@Resource({
  uri: 'user://{userId}/profile',
  name: 'User Profile',
  title: 'User Profile Details',
  description: 'Complete user profile including account settings, preferences, and activity summary',
  mimeType: 'application/json',
  annotations: {
    audience: ['user', 'assistant'],
    priority: 0.8,
    lastModified: new Date().toISOString()
  },
  examples: {
    response: {
      id: 'usr_abc123',
      email: 'jane.doe@example.com',
      name: 'Jane Doe',
      preferences: {
        theme: 'dark',
        language: 'en',
        timezone: 'America/New_York'
      },
      stats: {
        ordersPlaced: 42,
        memberSince: '2023-01-15'
      }
    }
  }
})
async getUserProfile(uri: string, ctx: ExecutionContext) {
  const userId = this.extractParam(uri, /user:\/\/([^\/]+)\/profile/);
  const profile = await this.userService.getProfile(userId);

  return {
    contents: [{
      uri,
      mimeType: 'application/json',
      text: JSON.stringify(profile, null, 2)
    }]
  };
}

```

--------------------------------

### Interceptor Example

Source: https://docs.nitrostack.ai/api/interceptors

An example demonstrating how to create a custom interceptor by implementing the `InterceptorInterface` and using the `@Interceptor()` decorator.

```APIDOC
## Example Interceptor

### Description
This example shows a concrete implementation of an interceptor named `MyInterceptor`. It wraps the result of the `next` function to indicate success and include the data.

### Class
```typescript
@Interceptor()
export class MyInterceptor implements InterceptorInterface {
  async intercept(context: ExecutionContext, next: () => Promise<any>): Promise<any> {
    const result = await next();
    return { success: true, data: result };
  }
}
```

### Usage
Decorate a class with `@Interceptor()` and implement the `InterceptorInterface` to create a custom interceptor.
```

--------------------------------

### Manual Widget Dependency Installation

Source: https://docs.nitrostack.ai/installation

Manually install widget dependencies for a NitroStack project after navigating to the widgets directory.

```bash
# Widget dependencies (if using widgets)
cd src/widgets
npm install @nitrostack/widgets next react react-dom

```

--------------------------------

### Already Up to Date Example

Source: https://docs.nitrostack.ai/cli/upgrade

Shows the output when the NitroStack packages are already at the latest version. The command confirms that no updates are needed.

```bash
nitrostack-cli upgrade
```

```text
┌──────────────────────────────────────────────────────────────────┐
│  NITROSTACK ━━ Upgrade                                           │
│  Checking for updates                                            │
└──────────────────────────────────────────────────────────────────┘

✔ Already up to date (1.2.0)


```

--------------------------------

### Build Project for Production with npm

Source: https://docs.nitrostack.ai/ai-agents/cli-reference

Build the MCP server and widgets for production using npm.

```bash
npm run build
```

--------------------------------

### Run Production Server

Source: https://docs.nitrostack.ai/templates/pizzaz

Runs the production-ready server. Use this after building the project for deployment.

```bash
npm start                # Run production server
```

--------------------------------

### CI/CD Integration - GitHub Actions

Source: https://docs.nitrostack.ai/cli/install

Integrate the NitroStack CLI install command into GitHub Actions workflows to install dependencies.

```yaml
- name: Install dependencies
  run: npx @nitrostack/cli install
```

--------------------------------

### Start MCP Server for Remote Development (HTTP)

Source: https://docs.nitrostack.ai/guides/dual-transport

Steps to start the MCP server on a specific port for remote connections.

```bash
# Terminal 1: Start MCP Server
cd my-mcp-project
PORT=3001 npm run dev

# Terminal 2: Connect from anywhere
# Open Studio → Settings → HTTP Transport
# URL: http://localhost:3001

```

--------------------------------

### Basic Upgrade Example

Source: https://docs.nitrostack.ai/cli/upgrade

Executes the upgrade command to update NitroStack packages to the latest version. Shows the output indicating successful updates.

```bash
nitrostack-cli upgrade
```

```text
┌──────────────────────────────────────────────────────────────────┐
│  NITROSTACK ━━ Upgrade                                           │
│  Updating NitroStack packages                                    │
└──────────────────────────────────────────────────────────────────┘

✔ Fetched latest version: 1.2.0
✔ Root: nitrostack 1.1.0 → 1.2.0
✔ Widgets: @nitrostack/widgets 1.1.0 → 1.2.0

┌──────────────────────────────────────────────────────────────────┐
│  ✓ Upgrade Complete                                              │
│                                                                  │
│  Updated to nitrostack@1.2.0                                     │
└──────────────────────────────────────────────────────────────────┘

```

--------------------------------

### Create NitroStack Project

Source: https://docs.nitrostack.ai/templates/starter

Use the NitroStack CLI to initialize a new project with the TypeScript starter template. Navigate into the project directory and run the development server.

```bash
npx nitrostack@latest init my-calculator --template typescript-starter
cd my-calculator
npm run dev

```

--------------------------------

### Example Custom Interceptor Implementation

Source: https://docs.nitrostack.ai/api/interceptors

Demonstrates how to create a custom interceptor by implementing the InterceptorInterface. This example wraps the result of the next handler.

```typescript
@Interceptor()
export class MyInterceptor implements InterceptorInterface {
  async intercept(context: ExecutionContext, next: () => Promise<any>): Promise<any> {
    const result = await next();
    return { success: true, data: result };
  }
}
```

--------------------------------

### Dynamically Add Prompts and Notify Clients

Source: https://docs.nitrostack.ai/sdk/typescript/prompts

Demonstrates how to create an application, get the server instance, and notify clients after dynamically adding new prompts.

```typescript
import { McpApplicationFactory } from '@nitrostack/core';

const app = await McpApplicationFactory.create(AppModule);
const server = app.getServer();

// After adding new prompts dynamically
server.notifyPromptsListChanged();

```

--------------------------------

### Best Practice: Test in Studio

Source: https://docs.nitrostack.ai/cli/overview

Always test your application features within the Studio environment before deploying.

```bash
nitrostack-cli dev
# Test with AI chat
# Test manual execution
```

--------------------------------

### Example Tagging

Source: https://docs.nitrostack.ai/guides/widget-examples

Utilize tags to categorize widgets, filter in the Resources tab, and enable searching across examples. This improves organization and discoverability.

```typescript
tags: ['display', 'product', 'inventory', 'critical']


```

--------------------------------

### Initialize a new project with a specific template

Source: https://docs.nitrostack.ai/cli/init

Use the `--template` option to specify a project template, such as `typescript-auth`.

```bash
nitrostack-cli init my-project --template typescript-auth

```
Tokens:
Raw