nitrostack 1.0.55 → 1.0.57

package/templates/typescript-pizzaz/README.md

@@ -0,0 +1,233 @@
+# 🍕 Pizzaz - Pizza Shop Finder
+
+A comprehensive NitroStack template showcasing interactive pizza shop discovery with maps, lists, and detailed views. This template demonstrates the NitroStack Widget SDK for building interactive widgets.
+
+## Features
+
+### 🎨 **Widget SDK Features**
+- ✅ `useTheme()` - Automatic dark mode support
+- ✅ `useWidgetState()` - Persistent favorites and view preferences
+- ✅ `useMaxHeight()` - Responsive height-aware layouts
+- ✅ `useDisplayMode()` - Fullscreen mode adaptation
+- ✅ `useWidgetSDK()` - Tool calling, navigation, and external links
+- ✅ `<WidgetLayout>` - Automatic RPC setup
+
+### 🗺️ **Three Interactive Widgets**
+1. **Pizza Map** - Interactive Mapbox map with markers and shop selection
+2. **Pizza List** - Grid/list view with sorting, filtering, and favorites
+3. **Pizza Shop** - Detailed shop information with contact actions
+
+### 📊 **MCP Tools**
+- `show_pizza_map` - Display shops on an interactive map
+- `show_pizza_list` - Show filterable list of shops
+- `show_pizza_shop` - Display detailed shop information
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install
+cd src/widgets && npm install && cd ../..
+```
+
+### 2. Configure Mapbox (Optional)
+
+The map widget uses Mapbox GL. To use it:
+
+1. Get a free API key from [Mapbox](https://www.mapbox.com/)
+2. Create `.env` file:
+```bash
+NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token_here
+```
+
+> **Note**: The template works without Mapbox, but the map widget will show an error. You can still use the list and shop widgets.
+
+### 3. Run Development Server
+
+```bash
+npm run dev
+```
+
+The MCP server will start on `http://localhost:3000`
+
+### 4. Run Widget Dev Server
+
+In a separate terminal:
+
+```bash
+npm run widget dev
+```
+
+Widgets will be available on `http://localhost:3001`
+
+### 5. Test in NitroStudio
+
+1. Open NitroStudio
+2. Connect to your MCP server
+3. Try these prompts:
+   - "Show me pizza shops on a map"
+   - "List all pizza shops"
+   - "Show me details for Tony's New York Pizza"
+
+## Project Structure
+
+```
+typescript-pizzaz/
+├── src/
+│   ├── index.ts                 # Main server entry
+│   ├── app.module.ts            # App module
+│   └── modules/
+│       └── pizzaz/
+│           ├── pizzaz.data.ts   # Pizza shop data
+│           ├── pizzaz.service.ts # Business logic
+│           ├── pizzaz.tools.ts  # MCP tools
+│           └── pizzaz.module.ts # Module definition
+│   └── widgets/
+│       ├── app/
+│       │   ├── pizza-map/       # Map widget
+│       │   ├── pizza-list/      # List widget
+│       │   └── pizza-shop/      # Shop detail widget
+│       └── components/
+│           └── PizzaCard.tsx    # Reusable card component
+├── package.json
+└── README.md
+```
+
+## Widget Features
+
+### Pizza Map Widget
+- **Interactive Mapbox map** with custom markers
+- **Shop sidebar** with quick selection
+- **Fullscreen mode** for better exploration
+- **Persistent favorites** using `useWidgetState()`
+- **Theme-aware** map styles (light/dark)
+
+### Pizza List Widget
+- **Grid/List view toggle** with state persistence
+- **Sorting** by rating, name, or price
+- **Favorites tracking** across sessions
+- **Responsive layout** using `useMaxHeight()`
+- **Filter panel** for advanced search
+
+### Pizza Shop Widget
+- **Hero image** with overlay information
+- **Contact actions** (call, directions, website)
+- **Specialties showcase**
+- **Related shops** recommendations
+- **External link handling** via `useWidgetSDK()`
+
+## Customization
+
+### Adding More Shops
+
+Edit `src/modules/pizzaz/pizzaz.data.ts`:
+
+```typescript
+export const PIZZA_SHOPS: PizzaShop[] = [
+  {
+    id: 'my-pizza-shop',
+    name: 'My Pizza Shop',
+    description: 'Amazing pizza!',
+    address: '123 Main St, City, State 12345',
+    coords: [-122.4194, 37.7749], // [lng, lat]
+    rating: 4.5,
+    reviews: 100,
+    priceLevel: 2,
+    cuisine: ['Italian', 'Pizza'],
+    hours: { open: '11:00 AM', close: '10:00 PM' },
+    phone: '(555) 123-4567',
+    website: 'https://example.com',
+    image: 'https://images.unsplash.com/photo-...',
+    specialties: ['Margherita', 'Pepperoni'],
+    openNow: true,
+  },
+  // ... more shops
+];
+```
+
+### Changing Map Style
+
+Edit `src/widgets/app/pizza-map/page.tsx`:
+
+```typescript
+style: isDark 
+  ? 'mapbox://styles/mapbox/dark-v11'  // Dark mode style
+  : 'mapbox://styles/mapbox/streets-v12' // Light mode style
+```
+
+### Adding New Filters
+
+Edit `src/modules/pizzaz/pizzaz.service.ts` to add more filter options.
+
+## Deployment
+
+### Build for Production
+
+```bash
+npm run build
+```
+
+### Deploy to OpenAI ChatGPT
+
+1. Build widgets:
+```bash
+cd src/widgets && npm run build
+```
+
+2. Widget HTML files will be in `src/widgets/out/`
+
+3. Upload to your MCP server
+
+4. **Zero code changes needed!** Widgets work identically in OpenAI ChatGPT.
+
+## SDK Features Demonstrated
+
+### Theme Awareness
+```typescript
+const theme = useTheme(); // 'light' | 'dark'
+const bgColor = theme === 'dark' ? '#000' : '#fff';
+```
+
+### State Persistence
+```typescript
+const [state, setState] = useWidgetState(() => ({
+  favorites: [],
+  viewMode: 'grid',
+}));
+
+// State persists across widget reloads
+setState({ ...state, favorites: [...state.favorites, shopId] });
+```
+
+### Responsive Layouts
+```typescript
+const maxHeight = useMaxHeight();
+return <div style={{ maxHeight }}>{content}</div>;
+```
+
+### Display Mode Adaptation
+```typescript
+const displayMode = useDisplayMode(); // 'inline' | 'pip' | 'fullscreen'
+const showSidebar = displayMode === 'fullscreen';
+```
+
+### External Links
+```typescript
+const { openExternal } = useWidgetSDK();
+openExternal('https://example.com');
+```
+
+## Learn More
+
+- [NitroStack Documentation](https://nitrostack.dev)
+- [Widget Development Guide](../../WIDGET_DEVELOPMENT.md)
+- [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/)
+
+## License
+
+MIT
+
+---
+
+**Built with ❤️ using NitroStack**

package/templates/typescript-pizzaz/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "nitrostack-pizzaz",
+    "version": "1.0.0",
+    "private": true,
+    "type": "module",
+    "description": "Pizza shop finder with interactive map - NitroStack template showcasing Widget SDK features",
+    "scripts": {
+        "dev": "nitrostack dev",
+        "build": "nitrostack build",
+        "start": "npm run build && nitrostack start",
+        "start:prod": "nitrostack start",
+        "widget": "npm --prefix src/widgets"
+    },
+    "keywords": [
+        "nitrostack",
+        "mcp",
+        "pizza",
+        "map",
+        "widgets"
+    ],
+    "author": "",
+    "license": "MIT",
+    "dependencies": {
+        "nitrostack": "^1",
+        "zod": "^3.22.4",
+        "dotenv": "^16.3.1"
+    },
+    "devDependencies": {
+        "typescript": "^5.3.3"
+    }
+}

package/templates/typescript-pizzaz/src/app.module.ts

@@ -0,0 +1,28 @@
+import { McpApp, Module, ConfigModule } from 'nitrostack';
+import { PizzazModule } from './modules/pizzaz/pizzaz.module.js';
+
+/**
+ * Root Application Module
+ * 
+ * Pizza shop finder with interactive maps.
+ * Showcases NitroStack Widget SDK features.
+ */
+@McpApp({
+    module: AppModule,
+    server: {
+        name: 'pizzaz-finder',
+        version: '1.0.0'
+    },
+    logging: {
+        level: 'info'
+    }
+})
+@Module({
+    name: 'pizzaz',
+    description: 'Pizza shop finder with interactive maps',
+    imports: [
+        ConfigModule.forRoot(),
+        PizzazModule
+    ],
+})
+export class AppModule { }

package/templates/typescript-pizzaz/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Pizzaz MCP Server
+ * 
+ * Pizza shop finder with interactive map widgets.
+ * Showcases NitroStack Widget SDK features including:
+ * - useTheme() for dark mode
+ * - useWidgetState() for persistent favorites
+ * - useDisplayMode() for fullscreen support
+ * - useMaxHeight() for responsive layouts
+ * - useWidgetSDK() for tool calling and navigation
+ */
+
+import 'dotenv/config';
+import { McpApplicationFactory } from 'nitrostack';
+import { AppModule } from './app.module.js';
+
+/**
+ * Bootstrap the application
+ */
+async function bootstrap() {
+    // Create and start the MCP server
+    const server = await McpApplicationFactory.create(AppModule);
+    await server.start();
+}
+
+// Start the application
+bootstrap().catch((error) => {
+    console.error('❌ Failed to start server:', error);
+    process.exit(1);
+});

package/templates/typescript-pizzaz/src/modules/pizzaz/pizzaz.data.ts

@@ -0,0 +1,106 @@
+export interface PizzaShop {
+    id: string;
+    name: string;
+    description: string;
+    address: string;
+    coords: [number, number]; // [lng, lat]
+    rating: number;
+    reviews: number;
+    priceLevel: 1 | 2 | 3;
+    cuisine: string[];
+    hours: {
+        open: string;
+        close: string;
+    };
+    phone: string;
+    website?: string;
+    image: string;
+    specialties: string[];
+    openNow: boolean;
+}
+
+export const PIZZA_SHOPS: PizzaShop[] = [
+    {
+        id: 'tonys-pizza',
+        name: "Tony's New York Pizza",
+        description: "Authentic New York-style pizza with a crispy thin crust and fresh toppings",
+        address: "123 Main St, San Francisco, CA 94102",
+        coords: [-122.4194, 37.7749],
+        rating: 4.5,
+        reviews: 342,
+        priceLevel: 2,
+        cuisine: ['Italian', 'Pizza', 'New York Style'],
+        hours: { open: '11:00 AM', close: '10:00 PM' },
+        phone: '(415) 555-0123',
+        website: 'https://tonyspizza.example.com',
+        image: 'https://images.unsplash.com/photo-1513104890138-7c749659a591',
+        specialties: ['Margherita', 'Pepperoni', 'White Pizza'],
+        openNow: true,
+    },
+    {
+        id: 'bella-napoli',
+        name: 'Bella Napoli',
+        description: "Traditional Neapolitan pizza baked in a wood-fired oven",
+        address: "456 Market St, San Francisco, CA 94103",
+        coords: [-122.4089, 37.7858],
+        rating: 4.8,
+        reviews: 521,
+        priceLevel: 3,
+        cuisine: ['Italian', 'Pizza', 'Neapolitan'],
+        hours: { open: '12:00 PM', close: '11:00 PM' },
+        phone: '(415) 555-0456',
+        website: 'https://bellanapoli.example.com',
+        image: 'https://images.unsplash.com/photo-1574071318508-1cdbab80d002',
+        specialties: ['Marinara', 'Quattro Formaggi', 'Diavola'],
+        openNow: true,
+    },
+    {
+        id: 'slice-house',
+        name: 'The Slice House',
+        description: "Casual spot for creative pizza slices and craft beer",
+        address: "789 Valencia St, San Francisco, CA 94110",
+        coords: [-122.4216, 37.7599],
+        rating: 4.3,
+        reviews: 289,
+        priceLevel: 1,
+        cuisine: ['Pizza', 'American', 'Casual'],
+        hours: { open: '11:30 AM', close: '9:00 PM' },
+        phone: '(415) 555-0789',
+        image: 'https://images.unsplash.com/photo-1565299624946-b28f40a0ae38',
+        specialties: ['BBQ Chicken', 'Hawaiian', 'Veggie Supreme'],
+        openNow: true,
+    },
+    {
+        id: 'pizzeria-delfina',
+        name: 'Pizzeria Delfina',
+        description: "Upscale pizzeria with seasonal ingredients and house-made mozzarella",
+        address: "3611 18th St, San Francisco, CA 94110",
+        coords: [-122.4252, 37.7615],
+        rating: 4.6,
+        reviews: 678,
+        priceLevel: 3,
+        cuisine: ['Italian', 'Pizza', 'Fine Dining'],
+        hours: { open: '5:00 PM', close: '10:00 PM' },
+        phone: '(415) 555-3611',
+        website: 'https://pizzeriadelfina.example.com',
+        image: 'https://images.unsplash.com/photo-1571997478779-2adcbbe9ab2f',
+        specialties: ['Salsiccia', 'Funghi', 'Prosciutto e Rucola'],
+        openNow: false,
+    },
+    {
+        id: 'golden-boy',
+        name: 'Golden Boy Pizza',
+        description: "North Beach institution serving thick Sicilian-style squares",
+        address: "542 Green St, San Francisco, CA 94133",
+        coords: [-122.4102, 37.7999],
+        rating: 4.4,
+        reviews: 445,
+        priceLevel: 1,
+        cuisine: ['Pizza', 'Sicilian', 'Italian'],
+        hours: { open: '11:30 AM', close: '11:30 PM' },
+        phone: '(415) 555-0542',
+        image: 'https://images.unsplash.com/photo-1628840042765-356cda07504e',
+        specialties: ['Clam & Garlic', 'Pesto', 'Classic Cheese'],
+        openNow: true,
+    },
+];

package/templates/typescript-pizzaz/src/modules/pizzaz/pizzaz.module.ts

@@ -0,0 +1,11 @@
+import { Module } from 'nitrostack';
+import { PizzazService } from './pizzaz.service.js';
+import { PizzazTools } from './pizzaz.tools.js';
+
+@Module({
+    name: 'pizzaz',
+    description: 'Pizza shop finder module',
+    controllers: [PizzazTools],
+    providers: [PizzazService],
+})
+export class PizzazModule { }

package/templates/typescript-pizzaz/src/modules/pizzaz/pizzaz.service.ts

@@ -0,0 +1,60 @@
+import { Injectable } from 'nitrostack';
+import { PIZZA_SHOPS, type PizzaShop } from './pizzaz.data.js';
+
+@Injectable()
+export class PizzazService {
+    /**
+     * Get all pizza shops
+     */
+    getAllShops(): PizzaShop[] {
+        return PIZZA_SHOPS;
+    }
+
+    /**
+     * Get a specific pizza shop by ID
+     */
+    getShopById(id: string): PizzaShop | undefined {
+        return PIZZA_SHOPS.find(shop => shop.id === id);
+    }
+
+    /**
+     * Get pizza shops filtered by criteria
+     */
+    getShopsFiltered(filters: {
+        openNow?: boolean;
+        minRating?: number;
+        maxPrice?: number;
+        cuisine?: string;
+    }): PizzaShop[] {
+        let shops = [...PIZZA_SHOPS];
+
+        if (filters.openNow) {
+            shops = shops.filter(shop => shop.openNow);
+        }
+
+        if (filters.minRating !== undefined) {
+            shops = shops.filter(shop => shop.rating >= filters.minRating!);
+        }
+
+        if (filters.maxPrice !== undefined) {
+            shops = shops.filter(shop => shop.priceLevel <= filters.maxPrice!);
+        }
+
+        if (filters.cuisine) {
+            shops = shops.filter(shop =>
+                shop.cuisine.some(c => c.toLowerCase().includes(filters.cuisine!.toLowerCase()))
+            );
+        }
+
+        return shops;
+    }
+
+    /**
+     * Get shops sorted by rating
+     */
+    getTopRatedShops(limit: number = 5): PizzaShop[] {
+        return [...PIZZA_SHOPS]
+            .sort((a, b) => b.rating - a.rating)
+            .slice(0, limit);
+    }
+}

package/templates/typescript-pizzaz/src/modules/pizzaz/pizzaz.tools.ts

@@ -0,0 +1,197 @@
+import { ToolDecorator as Tool, Widget, ExecutionContext, Injectable, z } from 'nitrostack';
+import { PizzazService } from './pizzaz.service.js';
+
+const ShowMapSchema = z.object({
+    filter: z.enum(['open_now', 'top_rated', 'all']).optional().describe('Filter to apply'),
+});
+
+const ShowListSchema = z.object({
+    openNow: z.boolean().optional().describe('Show only shops that are currently open'),
+    minRating: z.number().min(1).max(5).optional().describe('Minimum rating (1-5)'),
+    maxPrice: z.number().min(1).max(3).optional().describe('Maximum price level (1-3)'),
+});
+
+const ShowShopSchema = z.object({
+    shopId: z.string().describe('ID of the pizza shop to display'),
+});
+
+@Injectable()
+export class PizzazTools {
+    constructor(private readonly pizzazService: PizzazService) { }
+
+    @Tool({
+        name: 'show_pizza_map',
+        description: 'Display an interactive map of pizza shops in San Francisco',
+        inputSchema: ShowMapSchema,
+        examples: {
+            request: { filter: 'all' },
+            response: {
+                shops: [
+                    {
+                        id: 'tonys-pizza',
+                        name: "Tony's New York Pizza",
+                        description: "Authentic New York-style pizza with a crispy thin crust",
+                        address: "123 Main St, San Francisco, CA 94102",
+                        coords: [-122.4194, 37.7749],
+                        rating: 4.5,
+                        reviews: 342,
+                        priceLevel: 2,
+                        cuisine: ['Italian', 'Pizza'],
+                        hours: { open: '11:00 AM', close: '10:00 PM' },
+                        phone: '(415) 555-0123',
+                        website: 'https://tonyspizza.example.com',
+                        image: 'https://images.unsplash.com/photo-1513104890138-7c749659a591',
+                        specialties: ['Margherita', 'Pepperoni'],
+                        openNow: true
+                    },
+                    {
+                        id: 'bella-napoli',
+                        name: 'Bella Napoli',
+                        description: "Traditional Neapolitan pizza baked in a wood-fired oven",
+                        address: "456 Market St, San Francisco, CA 94103",
+                        coords: [-122.4089, 37.7858],
+                        rating: 4.8,
+                        reviews: 521,
+                        priceLevel: 3,
+                        cuisine: ['Italian', 'Pizza'],
+                        hours: { open: '12:00 PM', close: '11:00 PM' },
+                        phone: '(415) 555-0456',
+                        image: 'https://images.unsplash.com/photo-1574071318508-1cdbab80d002',
+                        specialties: ['Marinara', 'Quattro Formaggi'],
+                        openNow: true
+                    }
+                ],
+                filter: 'all',
+                totalShops: 2
+            }
+        }
+    })
+    @Widget('pizza-map')
+    async showPizzaMap(args: z.infer<typeof ShowMapSchema>, ctx: ExecutionContext) {
+        let shops;
+
+        switch (args.filter) {
+            case 'open_now':
+                shops = this.pizzazService.getShopsFiltered({ openNow: true });
+                break;
+            case 'top_rated':
+                shops = this.pizzazService.getTopRatedShops();
+                break;
+            default:
+                shops = this.pizzazService.getAllShops();
+        }
+
+        ctx.logger.info('Showing pizza map', { filter: args.filter, totalShops: shops.length });
+
+        return {
+            shops,
+            filter: args.filter || 'all',
+            totalShops: shops.length,
+        };
+    }
+
+    @Tool({
+        name: 'show_pizza_list',
+        description: 'Display a list of pizza shops with filtering and sorting options',
+        inputSchema: ShowListSchema,
+        examples: {
+            request: { openNow: true },
+            response: {
+                shops: [
+                    {
+                        id: 'tonys-pizza',
+                        name: "Tony's New York Pizza",
+                        description: "Authentic New York-style pizza with a crispy thin crust",
+                        address: "123 Main St, San Francisco, CA 94102",
+                        coords: [-122.4194, 37.7749],
+                        rating: 4.5,
+                        reviews: 342,
+                        priceLevel: 2,
+                        cuisine: ['Italian', 'Pizza'],
+                        hours: { open: '11:00 AM', close: '10:00 PM' },
+                        phone: '(415) 555-0123',
+                        website: 'https://tonyspizza.example.com',
+                        image: 'https://images.unsplash.com/photo-1513104890138-7c749659a591',
+                        specialties: ['Margherita', 'Pepperoni'],
+                        openNow: true
+                    }
+                ],
+                filters: { openNow: true },
+                totalShops: 1
+            }
+        }
+    })
+    @Widget('pizza-list')
+    async showPizzaList(args: z.infer<typeof ShowListSchema>, ctx: ExecutionContext) {
+        const shops = this.pizzazService.getShopsFiltered(args);
+
+        ctx.logger.info('Showing pizza list', { filters: args, totalShops: shops.length });
+
+        return {
+            shops,
+            filters: args,
+            totalShops: shops.length,
+        };
+    }
+
+    @Tool({
+        name: 'show_pizza_shop',
+        description: 'Display detailed information about a specific pizza shop',
+        inputSchema: ShowShopSchema,
+        examples: {
+            request: { shopId: 'tonys-pizza' },
+            response: {
+                shop: {
+                    id: 'tonys-pizza',
+                    name: "Tony's New York Pizza",
+                    description: "Authentic New York-style pizza with a crispy thin crust and fresh toppings",
+                    address: "123 Main St, San Francisco, CA 94102",
+                    coords: [-122.4194, 37.7749],
+                    rating: 4.5,
+                    reviews: 342,
+                    priceLevel: 2,
+                    cuisine: ['Italian', 'Pizza', 'New York Style'],
+                    hours: { open: '11:00 AM', close: '10:00 PM' },
+                    phone: '(415) 555-0123',
+                    website: 'https://tonyspizza.example.com',
+                    image: 'https://images.unsplash.com/photo-1513104890138-7c749659a591',
+                    specialties: ['Margherita', 'Pepperoni', 'White Pizza'],
+                    openNow: true
+                },
+                relatedShops: [
+                    {
+                        id: 'bella-napoli',
+                        name: 'Bella Napoli',
+                        description: "Traditional Neapolitan pizza baked in a wood-fired oven",
+                        address: "456 Market St, San Francisco, CA 94103",
+                        coords: [-122.4089, 37.7858],
+                        rating: 4.8,
+                        reviews: 521,
+                        priceLevel: 3,
+                        cuisine: ['Italian', 'Pizza'],
+                        hours: { open: '12:00 PM', close: '11:00 PM' },
+                        phone: '(415) 555-0456',
+                        image: 'https://images.unsplash.com/photo-1574071318508-1cdbab80d002',
+                        specialties: ['Marinara', 'Quattro Formaggi'],
+                        openNow: true
+                    }
+                ]
+            }
+        }
+    })
+    @Widget('pizza-shop')
+    async showPizzaShop(args: z.infer<typeof ShowShopSchema>, ctx: ExecutionContext) {
+        const shop = this.pizzazService.getShopById(args.shopId);
+
+        if (!shop) {
+            throw new Error(`Pizza shop not found: ${args.shopId}`);
+        }
+
+        ctx.logger.info('Showing pizza shop', { shopId: args.shopId, shopName: shop.name });
+
+        return {
+            shop,
+            relatedShops: this.pizzazService.getTopRatedShops(3).filter(s => s.id !== shop.id),
+        };
+    }
+}