nitrostack 1.0.55 → 1.0.57

package/templates/typescript-oauth/README.md

@@ -1,394 +1,314 @@
-# OAuth 2.1 MCP Server Template
+# NitroStack Starter Template
 
-Complete OAuth 2.1 authentication implementation for Model Context Protocol servers.
+**The simple starter template** - Learn NitroStack v3.0 fundamentals with a clean calculator example.
 
-## 🎯 What This Template Demonstrates
+## 🎯 What's Inside
 
-- ✅ **OAuth 2.1** authentication (MCP & OpenAI Apps SDK compliant)
-- ✅ **Token Audience Binding** (RFC 8707) - Critical security feature
-- ✅ **Protected Resource Metadata** (RFC 9728) - Auto-discovery
-- ✅ **PKCE Support** (RFC 7636) - Already handled by NitroStack Studio
-- ✅ **Scope-based Access Control** - Fine-grained permissions
-- ✅ **Multi-Provider Support** - Works with Auth0, Okta, Keycloak, etc.
+This template demonstrates core NitroStack v3.0 features:
+
+- **One Module** - Calculator module with all features
+- **One Tool** - `calculate` - Perform arithmetic operations
+- **One Resource** - `calculator://operations` - List of operations
+- **One Prompt** - `calculator_help` - Get usage help
+- **Two Widgets** - Beautiful UI for results and operations list
+- **No Authentication** - Focus on learning the basics
+- **No Database** - Pure computation example
 
 ## 🚀 Quick Start
 
-### 1. Install Dependencies
+### Prerequisites
 
 ```bash
-npm install
+# Install NitroStack CLI globally
+npm install -g nitrostack
+
+# Or use npx
+npx nitrostack --version
 ```
 
-### 2. Setup Auth0 (Recommended for Quick Testing)
-
-**⚠️ IMPORTANT:** Follow the steps in **exact order** to avoid common issues!
-
-#### Create Auth0 API (Do This First!)
-
-1. Auth0 Dashboard → **Applications** → **APIs** → **Create API**
-2. **Settings:**
-   - **Name**: `MCP Server API`
-   - **Identifier**: `https://mcplocal` (your RESOURCE_URI - can be any unique URI)
-   - **Signing Algorithm**: **RS256**
-   - **JWT Profile**: **RFC 9068** (OAuth 2.0 Access Token JWT Profile)
-3. **Permissions** tab → **Add Scopes:**
-   - `read` - Read access to resources
-   - `write` - Write/modify resources  
-   - `admin` - Administrative operations
-4. **Save**
-
-#### Create Auth0 Application
-
-1. Go to [Auth0 Dashboard](https://manage.auth0.com/)
-2. **Applications** → **Create Application**
-3. Choose **"Regular Web Application"** ← **CRITICAL!** (Not SPA or M2M)
-4. **Application Settings:**
-   - **Name**: `MCP Server OAuth`
-   - **Allowed Callback URLs**: `http://localhost:3005/auth/callback,http://localhost:3000/auth/callback`
-   - **Allowed Logout URLs**: `http://localhost:3005,http://localhost:3000`
-   - **Allowed Web Origins**: `http://localhost:3005,http://localhost:3000`
-   - **Advanced Settings → Grant Types**: 
-     - ✅ Authorization Code
-     - ✅ Refresh Token
-     - ❌ Implicit (disable)
-   - **Advanced Settings → ID Token Tab**:
-     - ❌ ID Token Encryption: **DISABLED** or **NONE**
-5. **Save** and copy:
-   - **Domain** (e.g., `dev-xxx.us.auth0.com`)
-   - **Client ID**
-   - **Client Secret**
-
-#### Link Application to API
-
-1. Go to **Applications** → **APIs** → **MCP Server API**
-2. Click **"Machine to Machine Applications"** tab
-3. Find your `MCP Server OAuth` application
-4. Toggle to **"Authorized"** (green)
-5. Expand and select all scopes (`read`, `write`, `admin`)
-6. Click **"Update"**
-
-### 3. Configure Environment Variables
-
-Edit `.env` with your Auth0 settings:
+### Setup Your Project
 
 ```bash
-# Your MCP server's resource URI (MUST match Auth0 API Identifier EXACTLY)
-RESOURCE_URI=https://mcplocal
-
-# Your Auth0 domain (with https://)
-AUTH_SERVER_URL=https://YOUR-TENANT.auth0.com
-
-# Token audience (MUST match RESOURCE_URI)
-TOKEN_AUDIENCE=https://mcplocal
-
-# Token issuer (Auth0 domain with trailing slash - don't forget the /)
-TOKEN_ISSUER=https://YOUR-TENANT.auth0.com/
+nitrostack init my-calculator --template typescript-starter
+cd my-calculator
 ```
 
-**⚠️ Replace `YOUR-TENANT` with your actual Auth0 domain!**
+That's it! The CLI automatically:
+- ✅ Installs all dependencies  
+- ✅ Installs widget dependencies
+- ✅ Builds the widgets
+- ✅ Sets up the project structure
 
-**See `OAUTH_SETUP.md` for other providers** (Okta, Keycloak, Azure AD).
-
-### 4. Start the Server
+### Run the Project
 
 ```bash
 npm run dev
 ```
 
-You should see:
-```
-🚀 OAuth discovery server running at http://localhost:3005
-NITRO_LOG::{"level":"info","message":"🔐 OAuth 2.1 enabled"}
-NITRO_LOG::{"level":"info","message":"   Resource URI: https://mcplocal"}
-NITRO_LOG::{"level":"info","message":"   Auth Servers: https://YOUR-TENANT.auth0.com"}
-🚀 Server started successfully (DUAL: STDIO + HTTP)
-📡 MCP Protocol: STDIO (for Studio/Claude)
-🌐 OAuth Metadata: HTTP (port 3005)
-```
-
-**Note:** The server runs in **DUAL mode**:
-- **STDIO**: For MCP protocol communication
-- **HTTP (port 3005)**: For OAuth discovery in dev mode
-- **HTTP (port 3000)**: For OAuth discovery in prod mode
+This starts:
+- **MCP Server** (dual transport: STDIO + HTTP on port 3002) - Hot reloads on code changes
+- **Studio** on http://localhost:3000 - Visual testing environment
+- **Widget Dev Server** on http://localhost:3001 - Hot module replacement
 
-### 5. Complete OAuth Flow in Studio
+> 💡 **Dual Transport**: Your server exposes tools via both STDIO (for direct connections) and HTTP (for remote access on port 3002). Switch between transports in Studio → Settings.
 
-#### Open NitroStack Studio
-Navigate to `http://localhost:3000`
+The `nitrostack dev` command handles everything automatically:
+- ✅ Auto-detects widget directory
+- ✅ Installs dependencies (if needed)
+- ✅ Builds widgets (on first run)
+- ✅ Starts all services concurrently
+- ✅ Hot reload for TypeScript and widgets
 
-#### Step 1: Discover OAuth Server
-1. Go to **Auth → OAuth 2.1** tab
-2. Enter Server URL: `http://localhost:3005` (dev mode uses port 3005)
-3. Click **"Discover Auth Config"**
-4. ✅ Should show: **Discovery Successful**
-5. You'll see the discovered metadata (resource URI, auth server, scopes)
-6. ✅ Check browser console for: `🎯 Setting audience parameter: https://mcplocal`
+## 📁 Project Structure
 
-#### Step 2: Enter Client Credentials  
-1. Scroll to **"2a. Use Existing Client"** section
-2. **Client ID**: Paste your Auth0 Client ID
-3. **Client Secret**: Paste your Auth0 Client Secret
-4. Click **"Save Client Credentials"**
-5. ✅ Should show: **Client credentials saved!**
-
-#### Step 3: Start OAuth Flow
-1. Click **"Start Authorization Flow"**
-2. ✅ You'll be redirected to Auth0 login page
-3. **Login** with your Auth0 account
-4. **Authorize** the application (grant requested scopes)
-5. ✅ You'll be redirected back to Studio with a JWT token!
-6. ✅ Token is automatically saved and ready to use
-
-#### Step 4: Test Protected Tools
-1. Go to **Tools** tab
-2. Try any protected tool (e.g., `get_user_profile`, `list_resources`)
-3. ✅ Your JWT token is automatically included in requests!
-4. Tools will show your authenticated user info
-
-**Congratulations! 🎉** Your OAuth 2.1 server is working!
-
-## 📋 Available Tools
-
-### Public Tools (No Auth)
+```
+src/
+├── modules/
+│   └── calculator/
+│       ├── calculator.module.ts       # @Module definition
+│       ├── calculator.tools.ts        # @Tool with examples
+│       ├── calculator.resources.ts    # @Resource
+│       └── calculator.prompts.ts      # @Prompt
+├── widgets/                           # Next.js UI widgets
+│   └── app/
+│       ├── calculator-result/         # Tool result widget
+│       └── calculator-operations/     # Resource widget
+├── app.module.ts                      # Root @McpApp module
+└── index.ts                           # Application bootstrap
+```
 
-| Tool | Description |
-|------|-------------|
-| `get_server_info` | Get server information |
+## 🛠️ Available Features
 
-### Protected Tools (OAuth Required)
+### Health Check: `system`
 
-| Tool | Required Scopes | Description |
-|------|-----------------|-------------|
-| `get_user_profile` | _(any valid token)_ | Get authenticated user info |
-| `list_resources` | `read` | List available resources |
-| `create_resource` | `write` | Create a new resource |
-| `admin_statistics` | `read`, `admin` | Get admin statistics |
+Monitors server health and resources:
 
-## 🏗️ Project Structure
+- **Uptime**: Server running time
+- **Memory Usage**: Heap memory consumption
+- **Process Info**: PID and Node.js version
+- **Status**: `up`, `degraded`, or `down`
 
-```
-typescript-oauth/
-├── src/
-│   ├── guards/
-│   │   └── oauth.guard.ts          # OAuth token validation
-│   ├── modules/demo/
-│   │   ├── demo.module.ts
-│   │   └── demo.tools.ts           # Example tools
-│   ├── app.module.ts               # OAuthModule configuration
-│   └── index.ts                    # Entry point
-├── .env.example                    # Environment template
-├── OAUTH_SETUP.md                  # Provider setup guides
-└── README.md
-```
+Check health status in Studio's Health Checks tab!
 
-## 🔐 OAuth 2.1 Implementation
+### Tool: `calculate`
 
-### OAuthModule Configuration
+Perform basic arithmetic operations:
 
 ```typescript
-// src/app.module.ts
-OAuthModule.forRoot({
-  resourceUri: process.env.RESOURCE_URI!,
-  authorizationServers: [process.env.AUTH_SERVER_URL!],
-  scopesSupported: ['read', 'write', 'admin'],
-  tokenIntrospectionEndpoint: process.env.INTROSPECTION_ENDPOINT,
-  audience: process.env.TOKEN_AUDIENCE,
-  issuer: process.env.TOKEN_ISSUER,
+@Tool({
+  name: 'calculate',
+  description: 'Perform basic arithmetic calculations',
+  inputSchema: z.object({
+    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+    a: z.number(),
+    b: z.number()
+  }),
+  examples: {
+    request: { operation: 'add', a: 5, b: 3 },
+    response: { result: 8, expression: '5 + 3 = 8' }
+  }
 })
 ```
 
-### OAuth Guard
-
-```typescript
-// Protect a tool with OAuth
-@Tool({ name: 'protected_tool' })
-@UseGuards(OAuthGuard)
-async protectedTool() {
-  // Only accessible with valid OAuth token
-}
+**Usage:**
 ```
-
-### Scope-Based Access
-
-```typescript
-// Require specific scopes
-@Tool({ name: 'admin_tool' })
-@UseGuards(OAuthGuard, createScopeGuard(['admin']))
-async adminTool() {
-  // Requires 'admin' scope
-}
+User: "Calculate 5 + 3"
+AI: [Calls calculate tool]
+Result: Beautiful widget showing "5 + 3 = 8"
 ```
 
-## 🔑 Key Security Features
+### Resource: `calculator://operations`
 
-### 1. Token Audience Binding (RFC 8707)
+Lists all available operations with examples.
 
-**Critical for security!** Tokens are validated to ensure they were issued **specifically for your MCP server**.
+### Prompt: `calculator_help`
 
-```typescript
-// Tokens MUST include your RESOURCE_URI in the audience claim
-{
-  "aud": "https://mcp.yourapp.com",  // ← Must match RESOURCE_URI
-  "sub": "user123",
-  "scope": "read write"
-}
-```
-
-### 2. No Token Passthrough
+Get help on how to use the calculator.
 
-**Never forward OAuth tokens to other services!** Each service must have its own token.
-
-```typescript
-// ❌ WRONG - Don't do this
-await upstreamAPI.call(headers: { Authorization: clientToken });
+## 🎨 Widgets
 
-// ✅ CORRECT - Use separate token
-const upstreamToken = await getTokenForUpstream();
-await upstreamAPI.call(headers: { Authorization: upstreamToken });
-```
+### Calculator Result Widget
+- Gradient background
+- Operation icon
+- Breakdown of numbers
+- Beautiful animations
 
-### 3. Scope Validation
+### Calculator Operations Widget
+- Grid of all operations
+- Color-coded by type
+- Examples for each operation
 
-Fine-grained access control based on OAuth scopes:
+## 💡 Learning Path
 
-```typescript
-// Automatically validates scopes
-@UseGuards(OAuthGuard, createScopeGuard(['read', 'write']))
-```
+This template is perfect for learning:
 
-## 🧪 Testing with Studio
+1. **Module Organization** - How to structure a feature module
+2. **Tools** - How to create a tool with `@Tool` decorator
+3. **Resources** - How to expose data with `@Resource`
+4. **Prompts** - How to create conversation templates
+5. **Widgets** - How to build UI components
+6. **Examples** - How to include request/response examples
+7. **Validation** - How to use Zod schemas
 
-### Step 1: Start OAuth Flow
+## 🔧 Commands
 
-1. **Auth Tab** → **OAuth 2.1**
-2. Enter your MCP server URL
-3. Click **"Discover & Register"**
+```bash
+# Development
+npm run dev              # Start dev server with Studio (auto-builds everything)
+npm run build            # Build TypeScript and widgets for production
+npm start                # Run production server
+
+# Widget Management
+npm run widget <command> # Run npm command in widgets directory
+npm run widget add <pkg> # Add a widget dependency (e.g., @mui/material)
+```
 
-### Step 2: Complete Authorization
+**Note:** The NitroStack CLI automatically handles building, installing dependencies, and hot reload. You don't need separate commands for widgets anymore!
 
-1. Studio redirects to your OAuth provider
-2. Login with your credentials
-3. Grant requested scopes
-4. Studio receives and stores the token
+## 📝 Example Interactions
 
-### Step 3: Test Tools
+### Basic Calculation
+```
+User: "What's 12 times 8?"
+AI: Calls calculate(operation="multiply", a=12, b=8)
+Result: Widget showing "12 × 8 = 96"
+```
 
-1. **Tools Tab** → Select a protected tool
-2. Execute - Token is automatically included!
-3. Try tools with different scope requirements
+### Get Help
+```
+User: "How do I use the calculator?"
+AI: Uses calculator_help prompt
+Result: Complete usage instructions
+```
 
-## 📚 Standards Compliance
+### List Operations
+```
+User: "What operations are available?"
+AI: Fetches calculator://operations resource
+Result: Widget showing all 4 operations with examples
+```
 
-This template implements:
+## 🎓 Code Walkthrough
 
-- ✅ **OAuth 2.1** ([draft-ietf-oauth-v2-1-13](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13))
-- ✅ **RFC 9728** - Protected Resource Metadata
-- ✅ **RFC 8414** - Authorization Server Metadata
-- ✅ **RFC 7591** - Dynamic Client Registration  
-- ✅ **RFC 8707** - Resource Indicators (Token Audience Binding)
-- ✅ **RFC 7636** - PKCE
-- ✅ **RFC 7662** - Token Introspection
+### 1. Tool Definition
 
-Compatible with:
-- ✅ [MCP Specification](https://modelcontextprotocol.io/specification/draft/basic/authorization)
-- ✅ [OpenAI Apps SDK](https://developers.openai.com/apps-sdk/build/auth)
+```typescript
+@Tool({
+  name: 'calculate',
+  description: 'Perform basic arithmetic calculations',
+  inputSchema: z.object({...}),
+  examples: {...}
+})
+@Widget('calculator-result')  // Link UI widget
+async calculate(input: any, ctx: ExecutionContext) {
+  // Your logic here
+  return { result, expression };
+}
+```
 
-## 🔧 Configuration Options
+**Key Points:**
+- `@Tool` decorator defines the tool
+- `inputSchema` validates input with Zod
+- `examples` help AI understand usage
+- `@Widget` links the UI component
+- `ExecutionContext` provides logger, metadata
 
-### Required
+### 2. Resource Definition
 
-- `RESOURCE_URI` - Your MCP server's public URL
-- `AUTH_SERVER_URL` - Your OAuth provider's base URL
+```typescript
+@Resource({
+  uri: 'calculator://operations',
+  name: 'Calculator Operations',
+  mimeType: 'application/json',
+  examples: {...}
+})
+@Widget('calculator-operations')
+async getOperations(uri: string, ctx: ExecutionContext) {
+  return { contents: [{...}] };
+}
+```
 
-### Optional
+### 3. Prompt Definition
 
-- `TOKEN_AUDIENCE` - Expected audience (defaults to RESOURCE_URI)
-- `TOKEN_ISSUER` - Expected issuer (recommended for security)
-- `INTROSPECTION_ENDPOINT` - For opaque token validation
-- `INTROSPECTION_CLIENT_ID` - Introspection client credentials
-- `INTROSPECTION_CLIENT_SECRET` - Introspection client secret
+```typescript
+@Prompt({
+  name: 'calculator_help',
+  arguments: [...]
+})
+async getHelp(args: any, ctx: ExecutionContext) {
+  return { messages: [...] };
+}
+```
 
-## 🌐 Supported OAuth Providers
+### 4. Module Definition
 
-This template works with any RFC-compliant OAuth 2.1 provider:
+```typescript
+@Module({
+  name: 'calculator',
+  controllers: [CalculatorTools, CalculatorResources, CalculatorPrompts]
+})
+export class CalculatorModule {}
+```
 
-- ✅ **Auth0** - Easiest for testing
-- ✅ **Okta** - Enterprise-ready
-- ✅ **Keycloak** - Self-hosted
-- ✅ **Azure AD / Entra ID**
-- ✅ **Google Identity Platform**
-- ✅ **Custom OAuth servers**
+### 5. Root Module
 
-**See `OAUTH_SETUP.md` for provider-specific configuration guides.**
+```typescript
+@McpApp({
+  server: { name: 'calculator-server', version: '1.0.0' }
+})
+@Module({
+  imports: [ConfigModule.forRoot(), CalculatorModule]
+})
+export class AppModule {}
+```
 
-## 🚨 Common Issues
+## 🚀 Extend This Template
 
-### "Received JWE (encrypted) token instead of JWT!"
+### Add More Operations
 
-**Symptoms:** Server logs show:
-```
-[DEBUG] Token header: {"alg":"dir","enc":"A256GCM",...}
-[ERROR] Received JWE (encrypted) token instead of JWT!
-```
+Edit `calculator.tools.ts` and add new operations to the enum and switch statement.
 
-**Fix:** 
-1. Go to Applications → Your Application → Settings → Advanced Settings
-2. Click "ID Token" tab
-3. Disable "ID Token Encryption" or set to "None"
-4. Save and re-authorize in Studio
+### Add History Feature
 
-### "OAuth token validation failed: Token audience mismatch"
+1. Create a service to store calculations
+2. Add a `get_history` tool
+3. Create a history widget
 
-**Fix:** Ensure `RESOURCE_URI` and `TOKEN_AUDIENCE` in `.env` match the Auth0 API Identifier **EXACTLY**.
+### Add More Modules
 
 ```bash
-# .env
-RESOURCE_URI=https://mcplocal
-TOKEN_AUDIENCE=https://mcplocal
-
-# Token will have:
-{
-  "aud": "https://mcplocal"  # ← Must match exactly
-}
+nitrostack generate module converter
 ```
 
-### "Application doesn't show in API's Machine to Machine tab"
-
-**Fix:** Application type must be "Regular Web Application", not "Single Page Application". Delete and recreate the application with correct type.
+## 📚 Next Steps
 
-### "Missing required environment variables"
-
-**Fix:** Copy `.env.example` to `.env` and configure all required variables.
-
-```bash
-cp .env.example .env
-# Edit .env with your OAuth provider settings
-```
+Once you understand this template:
 
-### "Insufficient scope"
+1. Try the [E-commerce Template](/templates/ecommerce) - Advanced features with auth
+2. Read [Server Concepts](/sdk/typescript/server) - Deep dive into modules
+3. Read [Tools Guide](/sdk/typescript/tools) - Advanced tool patterns
+4. Read [Widgets Guide](/sdk/typescript/ui/widgets) - Build better UIs
 
-**Fix:** Request the required scopes when authorizing in Studio:
+## 💡 Tips
 
-1. Auth Tab → OAuth 2.1
-2. Check required scopes for the tool
-3. Re-authorize with correct scopes
+- **Keep it Simple** - This template shows the minimum needed
+- **Study the Code** - Each file has clear examples
+- **Test in Studio** - Use the chat to test your tools
+- **Check Examples** - The `examples` field helps AI understand your tools
 
-## 📖 Learn More
+## 🎉 What to Build
 
-- [MCP OAuth Specification](https://modelcontextprotocol.io/specification/draft/basic/authorization)
-- [OpenAI Apps SDK Auth](https://developers.openai.com/apps-sdk/build/auth)
-- [OAuth 2.1 Draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13)
-- [RFC 8707 - Resource Indicators](https://datatracker.ietf.org/doc/html/rfc8707)
-- [OAUTH_SETUP.md](./OAUTH_SETUP.md) - Provider setup guides
+Use this as a starting point for:
 
-## 🎉 Ready to Build!
+- **Unit Converters** - Temperature, currency, etc.
+- **Text Tools** - String manipulation, formatting
+- **Data Processors** - JSON, CSV, XML parsing
+- **Simple APIs** - Weather, jokes, facts
+- **Utilities** - Date/time, UUID generation
 
-This template provides a production-ready OAuth 2.1 implementation. Customize it for your needs:
+---
 
-1. Add your own tools with appropriate scopes
-2. Integrate with your user database
-3. Add custom token validation logic
-4. Deploy with your chosen OAuth provider
+**Happy Learning! 📖**
 
-**Happy coding! 🚀**
+Start simple, learn the patterns, then build something amazing!