nitrostack 1.0.10 → 1.0.12

package/README.md

@@ -1,571 +1,172 @@
-# NitroStack v3.0 ⚡
+# NitroStack ⚡
 
-**A NestJS-inspired framework for building production-ready MCP (Model Context Protocol) servers**
+Build production‑ready MCP (Model Context Protocol) servers with TypeScript — fast.
 
 [![npm version](https://img.shields.io/npm/v/nitrostack.svg)](https://www.npmjs.com/package/nitrostack)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Website](https://img.shields.io/badge/Website-nitrostack.vercel.app-brightgreen)](https://nitrostack.vercel.app/)
 [![Docs](https://img.shields.io/badge/Docs-nitrostack--docs.vercel.app-blue)](https://nitrostack-docs.vercel.app/)
 
-NitroStack v3.0 brings a revolutionary decorator-based architecture inspired by NestJS, making MCP server development more intuitive, maintainable, and scalable than ever before.
-
-## 🌟 What's New in v3.0
-
-### Decorator-Based Architecture
-Write clean, declarative code with TypeScript decorators:
-
-```typescript
-@Tool({
-  name: 'get_weather',
-  description: 'Get current weather',
-  inputSchema: z.object({
-    city: z.string().describe('City name')
-  })
-})
-@Widget('weather-card')
-@UseGuards(JWTGuard)
-async getWeather(input: any, ctx: ExecutionContext) {
-  return await this.weatherService.fetch(input.city);
-}
-```
-
-### Modular Architecture
-Organize your code into logical, self-contained modules:
-
-```typescript
-@Module({
-  name: 'weather',
-  controllers: [WeatherTools],
-  providers: [WeatherService],
-  imports: [HttpModule]
-})
-export class WeatherModule {}
-```
-
-### Powerful Features Out of the Box
-
-- 🎨 **Decorator-Based Development** - `@Tool`, `@Widget`, `@Resource`, `@Prompt`, `@Module`
-- 🔐 **Guard System** - Declarative authentication with `@UseGuards`
-- 🔄 **Middleware & Interceptors** - Transform requests/responses
-- 🧪 **Pipes for Validation** - NestJS-style input processing
-- 💉 **Dependency Injection** - Built-in DI container for testability
-- ⚡ **Caching** - `@Cache()` decorator for tool responses
-- 🚦 **Rate Limiting** - `@RateLimit()` for API protection
-- 🎯 **Event System** - `@OnEvent()` for event-driven architecture
-- 🔍 **Studio** - Next.js-based visual testing environment
-- 🤖 **AI Integration** - Test with OpenAI GPT-4 or Gemini 2.0 Flash
-- 📦 **Type Generation** - Auto-generate types from tool definitions
-
-## 📦 Installation
-
-Install NitroStack globally:
+NitroStack is a batteries‑included toolkit for creating real, shippable MCP servers. It combines a clean, declarative programming model with a built‑in visual Studio, authentication modules, widget UI system, hot‑reload dev workflow, and production‑grade tooling — all focused on one goal: let you build great MCP servers with minimal ceremony.
+
+## Why NitroStack
+
+Developers typically struggle with:
+- **Boilerplate and wiring**: scattered logic, ad‑hoc conventions, manual glue code
+- **Auth and security**: JWT, OAuth 2.1 (PKCE), API keys, token validation, scopes, multi‑auth
+- **Testing UX**: no clean way to visually exercise tools, resources, prompts
+- **Performance & reliability**: caching, rate limiting, predictable runtime pipeline
+- **DX & iteration**: hot reload, consistent CLIs, starter templates, type generation
+
+NitroStack solves these pain points out of the box.
+
+## What you get (inbuilt capabilities)
+
+- **Declarative building blocks**
+  - `@Tool`, `@Widget`, `@Resource`, `@Prompt`, `@Module`
+  - `@UseGuards`, `@UseMiddleware`, `@UseInterceptors`, `@UsePipes`, `@UseFilters`
+- **Authentication modules (drop‑in)**
+  - `JWTModule` (simple JWT)
+  - `OAuthModule` (OAuth 2.1 with PKCE, discovery, scopes, dual transport ready)
+  - `ApiKeyModule` (service‑to‑service keys)
+  - Multi‑auth patterns (either/both) supported via guards
+- **Studio (built‑in visual test bench)**
+  - Run and debug tools, browse resources, test prompts, preview widgets
+  - AI chat integration and auto‑form generation from schemas
+- **Widgets UI system**
+  - Attach Next.js pages to tools with `@Widget` for instant interactive demos
+- **Runtime pipeline**
+  - Middleware, Interceptors, Pipes, Exception Filters for predictable request flow
+- **Performance controls**
+  - `@Cache()` and `@RateLimit()` decorators
+- **Type safety**
+  - CLI generates types from tool definitions for use across code and widgets
+- **Dev experience**
+  - Hot reload, templates, code generators, dual transport support for OAuth metadata
+
+## Install
 
 ```bash
-npm install -g nitrostack
+npm i -g nitrostack
 ```
 
-Or use with npx:
+Or use once without global install:
 
 ```bash
 npx nitrostack init my-mcp-server
 ```
 
-## 🚀 Quick Start
-
-### 1. Create a New Server
+## Quick Start (3 steps)
 
+1) Initialize a project
 ```bash
-nitrostack init my-ecommerce-server --template typescript-auth
-cd my-ecommerce-server
+nitrostack init my-server --template typescript-starter
+cd my-server
 npm install
 ```
 
-### 2. Define Your Tools
-
-```typescript
-// src/modules/products/products.tools.ts
-import { ToolDecorator as Tool, z, ExecutionContext } from 'nitrostack';
-
-export class ProductsTools {
-  @Tool({
-    name: 'browse_products',
-    description: 'Browse products by category',
-    inputSchema: z.object({
-      category: z.string().optional(),
-      limit: z.number().default(10)
-    })
-  })
-  @Widget('products-grid')
-  async browseProducts(input: any, ctx: ExecutionContext) {
-    const products = await this.db.query('SELECT * FROM products WHERE category = ?', [input.category]);
-    return { products, pagination: { total: products.length } };
-  }
-}
-```
-
-### 3. Create a Module
-
-```typescript
-// src/modules/products/products.module.ts
-import { Module } from 'nitrostack';
-import { ProductsTools } from './products.tools.js';
-import { ProductsResources } from './products.resources.js';
-import { ProductsPrompts } from './products.prompts.js';
-
-@Module({
-  name: 'products',
-  description: 'Product management module',
-  controllers: [ProductsTools, ProductsResources, ProductsPrompts]
-})
-export class ProductsModule {}
-```
-
-### 4. Bootstrap Your Application
-
-```typescript
-// src/app.module.ts
-import { McpApp, Module, ConfigModule, JWTModule } from 'nitrostack';
-import { ProductsModule } from './modules/products/products.module.js';
-
-@McpApp({
-  server: {
-    name: 'my-ecommerce-server',
-    version: '1.0.0'
-  },
-  logging: {
-    level: 'info'
-  }
-})
-@Module({
-  imports: [
-    ConfigModule.forRoot(),
-    JWTModule.forRoot({
-      secret: process.env.JWT_SECRET!
-    }),
-    ProductsModule
-  ]
-})
-export class AppModule {}
-```
-
-```typescript
-// src/index.ts
-import { McpApplicationFactory } from 'nitrostack';
-import { AppModule } from './app.module.js';
-
-McpApplicationFactory.create(AppModule);
-```
-
-### 5. Start Development
-
+2) Start the dev environment
 ```bash
 nitrostack dev
 ```
+Studio opens at `http://localhost:3000` (widgets at `http://localhost:3001`).
 
-Studio opens at `http://localhost:3000` - test your tools with AI chat! 🎉
-
-## 🎯 Core Concepts
-
-### Decorators
-
-NitroStack v3.0 uses decorators for clean, declarative code:
-
-| Decorator | Purpose | Example |
-|-----------|---------|---------|
-| `@Tool` | Define MCP tools | `@Tool({ name: 'get_user' })` |
-| `@Widget` | Attach UI component | `@Widget('user-card')` |
-| `@Resource` | Define data resources | `@Resource({ uri: 'user://{id}' })` |
-| `@Prompt` | Create prompt templates | `@Prompt({ name: 'review-code' })` |
-| `@Module` | Organize code | `@Module({ name: 'users' })` |
-| `@UseGuards` | Add authentication | `@UseGuards(JWTGuard)` |
-| `@UseMiddleware` | Apply middleware | `@UseMiddleware(LoggingMiddleware)` |
-| `@UseInterceptors` | Transform responses | `@UseInterceptors(TransformInterceptor)` |
-| `@UsePipes` | Validate inputs | `@UsePipes(ValidationPipe)` |
-| `@Cache` | Cache responses | `@Cache({ ttl: 300 })` |
-| `@RateLimit` | Limit requests | `@RateLimit({ requests: 10 })` |
-| `@Injectable` | Mark as service | `@Injectable()` |
-| `@OnEvent` | Listen to events | `@OnEvent('user.created')` |
-
-### Dependency Injection
-
-Use constructor injection for cleaner, testable code:
-
-```typescript
-@Injectable()
-export class UserService {
-  constructor(private db: DatabaseService) {}
-  
-  async findUser(id: string) {
-    return this.db.query('SELECT * FROM users WHERE id = ?', [id]);
-  }
-}
+3) Add your first tool
+```ts
+// src/modules/hello/hello.tools.ts
+import { Tool, z, ExecutionContext, Module } from 'nitrostack';
 
-export class UserTools {
-  constructor(private userService: UserService) {}
-  
-  @Tool({ name: 'get_user' })
-  async getUser(input: any) {
-    return this.userService.findUser(input.id);
-  }
-}
-```
-
-### Guards
-
-Declarative authentication:
-
-```typescript
-export class JWTGuard implements Guard {
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    const token = context.auth?.token;
-    if (!token) return false;
-    
-    const payload = verifyJWT(token);
-    context.auth = { subject: payload.sub };
-    return true;
-  }
-}
-
-@Tool({ name: 'create_order' })
-@UseGuards(JWTGuard)  // ← Auth required!
-async createOrder(input: any, ctx: ExecutionContext) {
-  const userId = ctx.auth?.subject;
-  // ...
-}
-```
-
-### Middleware
-
-Cross-cutting concerns:
-
-```typescript
-@Middleware()
-export class LoggingMiddleware implements MiddlewareInterface {
-  async use(context: ExecutionContext, next: () => Promise<any>) {
-    console.log(`[${context.toolName}] Started`);
-    const result = await next();
-    console.log(`[${context.toolName}] Completed`);
-    return result;
-  }
-}
-```
-
-### Interceptors
-
-Transform requests/responses:
-
-```typescript
-@Interceptor()
-export class TransformInterceptor implements InterceptorInterface {
-  async intercept(context: ExecutionContext, next: () => Promise<any>) {
-    const result = await next();
-    return {
-      success: true,
-      data: result,
-      timestamp: new Date().toISOString()
-    };
+export class HelloTools {
+  @Tool({
+    name: 'say_hello',
+    description: 'Greets a user',
+    inputSchema: z.object({ name: z.string() })
+  })
+  async sayHello(input: { name: string }, ctx: ExecutionContext) {
+    return { message: `Hello, ${input.name}!` };
   }
 }
-```
 
-### Widgets
-
-Create beautiful UIs for your tools:
-
-```typescript
-@Tool({
-  name: 'get_product',
-  description: 'Get product details',
-  inputSchema: z.object({
-    id: z.string()
-  }),
-  examples: {
-    response: {
-      id: 'prod-1',
-      name: 'Awesome Product',
-      price: 99.99
-    }
-  }
-})
-@Widget('product-card')
-async getProduct(input: any) {
-  return await this.db.getProduct(input.id);
-}
+@Module({ name: 'hello', controllers: [HelloTools] })
+export class HelloModule {}
 ```
+Register the module in `app.module.ts`, save — and call the tool in Studio.
 
-```tsx
-// src/widgets/app/product-card/page.tsx
-'use client';
-import { withToolData } from 'nitrostack/widgets';
-
-function ProductCard({ data }) {
-  return (
-    <div className="product-card">
-      <h2>{data.name}</h2>
-      <p className="price">${data.price}</p>
-    </div>
-  );
-}
+## Authentication (inbuilt)
 
-export default withToolData(ProductCard);
-```
+- **JWTModule**: Simple and fast token auth for user/session flows
+- **OAuthModule**: Full OAuth 2.1 with PKCE, discovery endpoints, scopes, and dual‑transport support (STDIO for MCP + HTTP for OAuth metadata)
+- **ApiKeyModule**: Issue and validate API keys for services and automations
+- **Multi‑auth**: compose guards so a tool can require one or multiple schemes
 
-## 🛠️ CLI Commands
+## Studio (visual workflow)
 
-### Initialize Project
+- AI chat to drive tools
+- Auto‑generated forms from schemas
+- Resource browser & prompt explorer
+- Widget previews connected to live tool outputs
 
-```bash
-nitrostack init <project-name> [--template typescript|typescript-auth]
-```
-
-### Development Mode
+## CLI highlights
 
 ```bash
-nitrostack dev [--port 3001]
-```
+# Create a project from templates
+nitrostack init <name> --template typescript-starter
+nitrostack init <name> --template typescript-auth
+nitrostack init <name> --template typescript-auth-api-key
+nitrostack init <name> --template typescript-oauth
 
-Starts Studio + MCP server with hot reload
-
-### Build for Production
-
-```bash
-nitrostack build
-```
-
-### Generate Code
-
-```bash
-# Generate types from tools
-nitrostack generate types [--output src/types/tools.ts]
-
-# Generate module
-nitrostack generate module payments
-
-# Generate tool
-nitrostack generate tool create-payment --module payments
-
-# Generate guard
-nitrostack generate guard admin
-
-# Generate middleware
-nitrostack generate middleware logging
-
-# Generate interceptor
-nitrostack generate interceptor transform
-
-# Generate pipe
-nitrostack generate pipe validation
-
-# Generate filter
-nitrostack generate filter exception
-
-# Generate service
-nitrostack generate service email
-```
-
-## 🔍 Studio
-
-NitroStack Studio is a Next.js-based testing environment:
-
-### Features
-
-- 🤖 **AI Chat** - Test with GPT-4 or Gemini 2.0 Flash
-- 🎨 **Widget Preview** - See UI components in action
-- 🔧 **Tool Testing** - Execute tools with dynamic forms
-- 📊 **Resource Browser** - View all resources
-- 🎯 **Prompt Explorer** - Test prompts with arguments
-- 🌓 **Dark/Light Theme** - Beautiful black & gold design
-
-### Supported LLMs
-
-- **OpenAI GPT-4** - Industry standard, excellent tool calling
-- **Gemini 2.0 Flash** - Free experimental, 1M token context
-
-### Usage
-
-```bash
+# Dev / Build
 nitrostack dev
-# Opens http://localhost:3000
-```
-
-## 🔐 Authentication
-
-NitroStack v3.0 supports multiple auth strategies:
-
-### JWT (Recommended)
-
-```typescript
-@Module({
-  imports: [
-    JWTModule.forRoot({
-      secret: process.env.JWT_SECRET!,
-      expiresIn: '1h'
-    })
-  ]
-})
-```
-
-### OAuth 2.1
-
-Full OAuth 2.1 compliance with PKCE for enterprise apps
-
-### API Keys
-
-Simple key-based authentication for service-to-service
-
-### Guards
-
-```typescript
-@Tool({ name: 'admin_tool' })
-@UseGuards(AdminGuard, JWTGuard)
-async adminTool() {
-  // Only admins can access
-}
-```
-
-## 📦 Type Safety
-
-Auto-generate TypeScript types from your tools:
-
-```bash
-nitrostack generate types
-```
-
-Generated output:
-
-```typescript
-// src/types/generated-tools.ts
-export type GetProductInput = {
-  id: string;
-};
-
-export type GetProductOutput = {
-  id: string;
-  name: string;
-  price: number;
-};
-
-export interface ToolInputs {
-  'get_product': GetProductInput;
-  // ...
-}
-
-export interface ToolOutputs {
-  'get_product': GetProductOutput;
-  // ...
-}
-```
-
-Use in widgets:
-
-```typescript
-import { GetProductOutput } from '../../types/generated-tools';
+nitrostack build
 
-function ProductCard({ data }: { data: GetProductOutput }) {
-  // Fully typed!
-}
-```
+# Generators
+nitrostack generate module <name>
+nitrostack generate tool <name> --module <module>
+nitrostack generate guard <name>
+nitrostack generate middleware <name>
+nitrostack generate interceptor <name>
+nitrostack generate pipe <name>
+nitrostack generate filter <name>
 
-## 🧪 Testing
-
-NitroStack includes testing utilities:
-
-```typescript
-import { TestingModule, createMockContext } from 'nitrostack/testing';
-
-describe('ProductsTools', () => {
-  let module: TestingModule;
-  
-  beforeAll(async () => {
-    module = await TestingModule.create({
-      controllers: [ProductsTools],
-      providers: [DatabaseService]
-    }).compile();
-  });
-  
-  it('should get product', async () => {
-    const tool = module.get(ProductsTools);
-    const ctx = createMockContext();
-    const result = await tool.getProduct({ id: '1' }, ctx);
-    expect(result.name).toBeDefined();
-  });
-});
+# Types from tools
+nitrostack generate types --output src/types/generated-tools.ts
 ```
 
-## 📚 Documentation
-
-**📖 Full documentation available at: [https://nitrostack-docs.vercel.app/](https://nitrostack-docs.vercel.app/)**
-
-Quick Links:
-- [Getting Started](https://nitrostack-docs.vercel.app/intro)
-- [Installation](https://nitrostack-docs.vercel.app/installation)
-- [Quick Start](https://nitrostack-docs.vercel.app/quick-start)
-- [Tools Guide](https://nitrostack-docs.vercel.app/sdk/typescript/tools)
-- [Widgets Guide](https://nitrostack-docs.vercel.app/sdk/typescript/ui/widgets)
-- [Authentication (JWT, OAuth, API Keys)](https://nitrostack-docs.vercel.app/sdk/typescript/auth/overview)
-- [CLI Reference](https://nitrostack-docs.vercel.app/cli/overview)
-- [API Reference](https://nitrostack-docs.vercel.app/api/decorators)
-- [Templates](https://nitrostack-docs.vercel.app/templates/starter)
-- [Deployment](https://nitrostack-docs.vercel.app/deployment/checklist)
+## Templates
 
+- `typescript-starter` — clean starter with widgets and example tools
+- `typescript-auth` — JWT auth flows and end‑to‑end examples
+- `typescript-auth-api-key` — API key auth patterns and multi‑auth
+- `typescript-oauth` — OAuth 2.1 (PKCE, discovery, scopes) with dual transport
 
+Use any template with `nitrostack init` and start iterating immediately.
 
-## 🚢 Deployment
-
-### Build
+## Production
 
 ```bash
 npm run build
-```
-
-### Run
-
-```bash
 NODE_ENV=production node dist/index.js
 ```
 
-### Docker
-
-```dockerfile
-FROM node:20-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --production
-COPY dist ./dist
-CMD ["node", "dist/index.js"]
-```
-
-## 🤝 Contributing
+Consider enabling caching, rate limits, structured logging, and health checks for production. See the docs for deployment recipes and checklists.
 
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+## Documentation
 
-By contributing, you agree that your contributions will be licensed under the Apache License 2.0.
+Full docs: `https://nitrostack-docs.vercel.app/`
+- Getting started, SDK guides, decorators, CLI reference, templates, deployment
 
-## 📝 License
+## License
 
-This project is licensed under the **Apache License 2.0** - see the [LICENSE](./LICENSE) file for details.
+Apache License 2.0 — see `LICENSE`. © 2025 Abhishek Pandit
 
-Copyright 2025 Abhishek Pandit
+## Links
 
-## 🔗 Links
-
-- **Website**: [https://nitrostack.vercel.app/](https://nitrostack.vercel.app/)
-- **Documentation**: [https://nitrostack-docs.vercel.app/](https://nitrostack-docs.vercel.app/)
-- **GitHub**: [https://github.com/abhishekpanditofficial/nitrostack](https://github.com/abhishekpanditofficial/nitrostack)
-- **npm Package**: [https://www.npmjs.com/package/nitrostack](https://www.npmjs.com/package/nitrostack)
-- **Model Context Protocol**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
-
-## 🙏 Acknowledgments
-
-Built with:
-- [Model Context Protocol SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
-- [Zod](https://zod.dev)
-- [Next.js](https://nextjs.org)
-- [React](https://react.dev)
-- [TypeScript](https://www.typescriptlang.org)
+- Website: `https://nitrostack.vercel.app/`
+- Docs: `https://nitrostack-docs.vercel.app/`
+- GitHub: `https://github.com/abhishekpanditofficial/nitrostack`
+- npm: `https://www.npmjs.com/package/nitrostack`
+- Model Context Protocol: `https://modelcontextprotocol.io`
 
 ---
 
-**Made with ⚡ by the NitroStack team**
-
-*Star us on GitHub!* ⭐
+Build boldly. Ship MCP servers people love. ⚡

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitrostack",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "NitroStack - Build powerful MCP servers with TypeScript",
   "type": "module",
   "main": "dist/core/index.js",

package/templates/typescript-auth/package.json

@@ -4,9 +4,10 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "node dist/index.js",
-    "build": "tsc",
-    "start": "NODE_ENV=production node dist/index.js"
+    "dev": "nitrostack dev",
+    "build": "nitrostack build",
+    "start": "nitrostack start",
+    "widget": "npm --prefix src/widgets"
   },
   "dependencies": {
     "nitrostack": "^1",

package/templates/typescript-auth-api-key/package.json

@@ -4,9 +4,10 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "node dist/index.js",
-    "build": "tsc",
-    "start": "NODE_ENV=production node dist/index.js"
+    "dev": "nitrostack dev",
+    "build": "nitrostack build",
+    "start": "nitrostack start",
+    "widget": "npm --prefix src/widgets"
   },
   "dependencies": {
     "nitrostack": "^1",

package/templates/typescript-oauth/package.json

@@ -4,9 +4,10 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "node dist/index.js",
-    "build": "tsc",
-    "start": "NODE_ENV=production node dist/index.js"
+    "dev": "nitrostack dev",
+    "build": "nitrostack build",
+    "start": "nitrostack start",
+    "widget": "npm --prefix src/widgets"
   },
   "dependencies": {
     "nitrostack": "^1",

package/templates/typescript-starter/package.json

@@ -4,9 +4,10 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "node dist/index.js",
-    "build": "tsc",
-    "start": "NODE_ENV=production node dist/index.js"
+    "dev": "nitrostack dev",
+    "build": "nitrostack build",
+    "start": "nitrostack start",
+    "widget": "npm --prefix src/widgets"
   },
   "dependencies": {
     "nitrostack": "^1",