Space Station Management System

NitroStack Feature Showcase

This project demonstrates ALL NitroStack features using a fun space station management theme.

🚀 Features Demonstrated

Feature	Description	Files
Tools	MCP tool definitions with Zod schemas	space-station.tools.ts
Resources	Static data endpoints	space-station.resources.ts
Prompts	AI prompt templates	space-station.prompts.ts
Middleware	Request/response pipeline	common/middleware/
Interceptors	Response transformation	common/interceptors/
Pipes	Input validation	common/pipes/
Exception Filters	Centralized error handling	common/filters/
Guards	Access control	common/guards/
Dependency Injection	Services with @Injectable	space-station.service.ts
Events	Event emission and handling	common/events/
Caching	Response caching with @Cache	Applied to tools
Rate Limiting	Request throttling with @RateLimit	Applied to tools
Health Checks	System monitoring	space-station.health.ts
Config Module	Configuration management	app.module.ts
Widget SDK	Interactive UI widgets	src/widgets/app/

🎨 Widget SDK Features

The @nitrostack/widgets package provides React hooks and utilities for building interactive tool widgets. This project showcases all Widget SDK features across 6 widgets.

SDK Features Reference

Feature	Description	Why Use It	Test In Widget
useWidgetSDK	Primary hook for all SDK functionality	Single hook for tool output, actions, and controls	All widgets
useTheme	Get current theme (light/dark)	Create theme-aware UIs that match the host app	All widgets
useWidgetState	Persistent state with auto-sync	Maintain widget state across re-renders	All widgets
useDisplayMode	Get current mode (inline/fullscreen/pip)	Adapt layout based on display context	station-status, system-diagnostic
useMaxHeight	Get max height constraint	Constrain scrollable content properly	station-status, mission-control
useOpenAiGlobal	Subscribe to window.openai properties	Access locale, userAgent, safeArea reactively	mission-control
callTool	Call other MCP tools from widget	Chain tools, fetch additional data interactively	crew-list, system-diagnostic, alerts-dashboard
sendFollowUpMessage	Send message to chat	Let users continue conversation from widget	crew-list, mission-control, system-diagnostic
openExternal	Open URL in browser	Link to external resources safely	mission-control
requestFullscreen	Switch to fullscreen mode	Expand widget for detailed views	station-status
requestInline	Switch to inline mode	Collapse back to inline view	station-status
requestPip	Switch to picture-in-picture	Float widget while browsing	station-status
requestClose	Close the widget	Let users dismiss when done	crew-list
getToolInput	Get tool input parameters	Access original request data	Any widget
getToolOutput	Get tool response data	Render the tool's result	All widgets
getLocale	Get user's locale	Format dates/numbers for locale	mission-control
getSafeArea	Get safe area insets	Handle notches, dynamic islands	mission-control, alerts-dashboard
getUserAgent	Get device/browser info	Adapt UI for device type	alerts-dashboard
prefersReducedMotion	Check motion preference	Disable animations when needed	alerts-dashboard
isPrimarilyTouchDevice	Check if touch device	Increase touch targets	alerts-dashboard
isHoverAvailable	Check hover support	Show/hide hover effects	alerts-dashboard
prefersDarkColorScheme	Check system dark mode	Match system preference	alerts-dashboard

Widget Files

Widget	Tool	Features Showcased
station-status	station_status	Theme, state, display mode, max height, fullscreen/pip controls
crew-list	list_crew	callTool, sendFollowUpMessage, requestClose, interactive actions
mission-control	list_missions	openExternal, useOpenAiGlobal, getLocale, getSafeArea
alerts-dashboard	get_alerts	Media queries, getUserAgent, touch/hover detection
system-diagnostic	list_systems	Interactive callTool with loading, error handling, sequential calls
calculator-result	calculate	Basic widget with tool output display

🛠️ Available Tools

Crew Management

• list_crew - List all crew members (with caching, data masking)
• get_crew_member - Get crew details (with validation pipes)
• update_crew_status - Update status (requires Officer clearance)

Mission Control

• list_missions - List missions (with custom cache keys)
• get_mission - Get mission details (with validation)
• create_mission - Create mission (requires Commander clearance)
• update_mission_status - Update status (with guards)

Station Systems

• station_status - Get station overview
• list_systems - List all systems
• run_diagnostic - Run diagnostic (rate limited)

Alerts

• create_alert - Create station alert
• get_alerts - Get active alerts

📚 Available Resources

• station://manifest - Complete crew manifest
• station://operations-manual - Standard operating procedures
• station://dashboard-data - Real-time dashboard data
• station://emergency-contacts - Emergency contact information

💬 Available Prompts

• station-briefing - Generate daily briefing
• mission-planning - Mission planning assistance
• system-diagnostics - System analysis
• emergency-response - Emergency guidance
• crew-wellness - Crew wellness check

🏗️ Architecture

src/
├── app.module.ts                    # Root module
├── index.ts                         # Entry point
├── common/
│   ├── middleware/                  # Middleware classes
│   │   ├── logging.middleware.ts
│   │   ├── timing.middleware.ts
│   │   └── request-id.middleware.ts
│   ├── interceptors/               # Interceptor classes
│   │   ├── response-wrapper.interceptor.ts
│   │   ├── data-masking.interceptor.ts
│   │   └── transform.interceptor.ts
│   ├── pipes/                      # Pipe classes
│   │   ├── trim.pipe.ts
│   │   ├── validation.pipe.ts
│   │   └── uppercase.pipe.ts
│   ├── filters/                    # Exception filters
│   │   └── station-exception.filter.ts
│   ├── guards/                     # Guard classes
│   │   ├── clearance.guard.ts
│   │   └── emergency-protocol.guard.ts
│   └── events/                     # Event handlers
│       └── station-events.handler.ts
├── modules/
│   ├── calculator/                  # Calculator module
│   │   └── calculator.tools.ts
│   └── space-station/
│       ├── space-station.module.ts
│       ├── space-station.data.ts    # Mock data
│       ├── space-station.service.ts # DI Services
│       ├── space-station.tools.ts   # Tools
│       ├── space-station.resources.ts
│       ├── space-station.prompts.ts
│       └── space-station.health.ts  # Health checks
└── widgets/                         # Next.js widget app
    ├── app/
    │   ├── calculator-result/       # Calculator widget
    │   ├── station-status/          # Station status widget
    │   ├── crew-list/               # Crew management widget
    │   ├── mission-control/         # Mission control widget
    │   ├── alerts-dashboard/        # Alerts widget
    │   └── system-diagnostic/       # System diagnostic widget
    └── out/                         # Compiled widgets (HTML)

🚀 Running the Server

# Development
npm run dev

# Build
npm run build

# Production
npm run start

🧪 Testing Features

Test Middleware (Logging, Timing)

Any tool call will show logging and timing in the console.

Test Caching

Call list_crew or station_status multiple times - you'll see cached responses.

Test Rate Limiting

Call run_diagnostic more than 3 times per minute to see rate limiting.

Test Data Masking

Call get_crew_member to see SSN and medical records masked.

Test Guards

The create_mission tool requires Commander clearance (simulated).

Test Exception Filters

Try get_crew_member with an invalid ID like crew-999.

Test Pipes

Try get_crew_member with an invalid ID format like invalid-id.

🎨 Testing Widget SDK Features

Test Theme Support

1. Call station_status tool
2. Toggle host app between light/dark mode
3. Widget colors adapt automatically via useTheme

Test Display Mode Controls

1. Call station_status tool
2. Click "Fullscreen", "PiP", or "Inline" buttons in the widget
3. Widget requests display mode change via SDK

Test Widget State

1. Call station_status tool
2. Click different tabs (Overview, Systems, Alerts)
3. Widget persists selected tab via useWidgetState

Test callTool (Tool Chaining)

1. Call list_crew tool
2. Click "View Details" on any crew member
3. Widget calls get_crew_member tool via callTool
4. Or click "Update Status" to call update_crew_status

Test sendFollowUpMessage

1. Call list_crew tool
2. Click "Ask About [Crew Name]" button
3. Widget sends message to chat via sendFollowUpMessage

Test openExternal

1. Call list_missions tool
2. Click "View Documentation" link
3. Opens URL in external browser via openExternal

Test Media Query Utilities

1. Call get_alerts tool
2. Toggle "Show Device Info" in the widget
3. See prefersReducedMotion, isPrimarilyTouchDevice, isHoverAvailable, prefersDarkColorScheme values

Test Interactive Diagnostics

1. Call list_systems tool
2. Select a system and click "Run Diagnostic"
3. Widget shows loading state, then calls run_diagnostic tool
4. Error handling shown if rate limit exceeded

Test Safe Area & Locale

1. Call list_missions tool
2. Widget displays locale and safe area insets from SDK
3. Useful for devices with notches/dynamic islands

🔧 Tool Decorator Features

Tools with widgets use special decorator options:

@Tool({
  name: 'station_status',
  description: 'Get station status',
  // Status messages during execution
  invocation: {
    invoking: 'Loading station status...',
    invoked: 'Status loaded'
  },
  // Example data for widget preview (REQUIRED!)
  examples: {
    request: {},
    response: { stationName: 'ISS-Alpha', stats: {...} }
  }
})
@Widget('station-status')

Note: The examples.response is required for widget previews to render in the client.

📝 License

MIT