nitrostack 1.0.0

package/README.md

@@ -0,0 +1,571 @@
+# NitroStack v3.0 ⚡
+
+**A NestJS-inspired framework for building production-ready MCP (Model Context Protocol) servers**
+
+[![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:
+
+```bash
+npm install -g nitrostack
+```
+
+Or use with npx:
+
+```bash
+npx nitrostack init my-mcp-server
+```
+
+## 🚀 Quick Start
+
+### 1. Create a New Server
+
+```bash
+nitrostack init my-ecommerce-server --template typescript-auth
+cd my-ecommerce-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
+
+```bash
+nitrostack dev
+```
+
+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]);
+  }
+}
+
+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()
+    };
+  }
+}
+```
+
+### 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);
+}
+```
+
+```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>
+  );
+}
+
+export default withToolData(ProductCard);
+```
+
+## 🛠️ CLI Commands
+
+### Initialize Project
+
+```bash
+nitrostack init <project-name> [--template typescript|typescript-auth]
+```
+
+### Development Mode
+
+```bash
+nitrostack dev [--port 3001]
+```
+
+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
+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';
+
+function ProductCard({ data }: { data: GetProductOutput }) {
+  // Fully typed!
+}
+```
+
+## 🧪 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();
+  });
+});
+```
+
+## 📚 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)
+
+
+
+## 🚢 Deployment
+
+### Build
+
+```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
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0.
+
+## 📝 License
+
+This project is licensed under the **Apache License 2.0** - see the [LICENSE](./LICENSE) file for details.
+
+Copyright 2025 Abhishek Pandit
+
+## 🔗 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)
+
+---
+
+**Made with ⚡ by the NitroStack team**
+
+*Star us on GitHub!* ⭐

package/dist/auth/api-key.d.ts

@@ -0,0 +1,118 @@
+import { RequestHandler } from 'express';
+/**
+ * API Key Authentication
+ *
+ * Simple authentication for basic scenarios.
+ * Perfect for service-to-service communication or development.
+ */
+export interface APIKeyConfig {
+    /**
+     * Array of valid API keys
+     * Can be plain strings or hashed values
+     */
+    keys: string[];
+    /**
+     * If true, keys are stored as SHA-256 hashes (recommended)
+     */
+    hashed?: boolean;
+    /**
+     * Header name to extract API key from
+     * Default: 'X-API-Key'
+     */
+    headerName?: string;
+    /**
+     * Also accept API key in query parameter?
+     * Default: false (not recommended for production)
+     */
+    allowQueryParam?: boolean;
+    /**
+     * Query parameter name
+     * Default: 'api_key'
+     */
+    queryParamName?: string;
+    /**
+     * Custom key validation
+     */
+    customValidation?: (key: string) => Promise<boolean> | boolean;
+}
+/**
+ * Create API Key authentication middleware
+ *
+ * @example
+ * ```typescript
+ * const server = createServer({...});
+ *
+ * // Simple API key auth
+ * server.app.use('/mcp', createAPIKeyAuth({
+ *   keys: [
+ *     process.env.API_KEY_1!,
+ *     process.env.API_KEY_2!,
+ *   ],
+ *   headerName: 'X-API-Key',
+ * }));
+ *
+ * server.start();
+ *
+ * // Client usage:
+ * // curl -H "X-API-Key: your-api-key" https://mcp.example.com/mcp/tools
+ * ```
+ */
+export declare function createAPIKeyAuth(config: APIKeyConfig): RequestHandler;
+/**
+ * Generate a secure API key
+ *
+ * @example
+ * ```typescript
+ * const apiKey = generateAPIKey();
+ * console.log('API Key:', apiKey);
+ * // Save to .env: API_KEY_1=sk_...
+ * ```
+ */
+export declare function generateAPIKey(prefix?: string): string;
+/**
+ * Hash an API key (SHA-256)
+ * Use this to store hashed keys instead of plain text
+ *
+ * @example
+ * ```typescript
+ * const apiKey = 'sk_abc123...';
+ * const hashed = hashAPIKey(apiKey);
+ * // Store hashed in database
+ *
+ * // In config:
+ * createAPIKeyAuth({
+ *   keys: [hashed],
+ *   hashed: true,
+ * });
+ * ```
+ */
+export declare function hashAPIKey(key: string): string;
+/**
+ * Validate API key format
+ */
+export declare function isValidAPIKeyFormat(key: string, prefix?: string): boolean;
+/**
+ * Create API key with metadata (advanced)
+ */
+export interface APIKeyWithMetadata {
+    key: string;
+    hashed: string;
+    name: string;
+    createdAt: Date;
+    expiresAt?: Date;
+    scopes?: string[];
+}
+export declare function generateAPIKeyWithMetadata(options: {
+    name: string;
+    prefix?: string;
+    expiresIn?: number;
+    scopes?: string[];
+}): APIKeyWithMetadata;
+/**
+ * Validate API key with metadata (expiration, scopes)
+ */
+export declare function validateAPIKeyWithMetadata(key: string, metadata: Omit<APIKeyWithMetadata, 'key'>, requiredScopes?: string[]): {
+    valid: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=api-key.d.ts.map

package/dist/auth/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../../src/auth/api-key.ts"],"names":[],"mappings":"AACA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1E;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAChE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CA2ErE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,MAAa,GAAG,MAAM,CAI5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAKzE;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,kBAAkB,CAmBrB;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,EACzC,cAAc,CAAC,EAAE,MAAM,EAAE,GACxB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAiBrC"}