nitrostack 1.0.57 → 1.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitrostack",
-  "version": "1.0.57",
+  "version": "1.0.58",
   "description": "NitroStack - Build powerful MCP servers with TypeScript",
   "type": "module",
   "main": "dist/core/index.js",
@@ -25,6 +25,12 @@
       "types": "./dist/widgets/index.d.ts"
     }
   },
+  "files": [
+    "dist/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -108,4 +114,4 @@
     "url": "https://github.com/abhishekpanditofficial/nitrostack/issues"
   },
   "homepage": "https://nitrostack.vercel.app"
-}
+}

package/ARCHITECTURE.md

@@ -1,302 +0,0 @@
-# NitroStack Architecture
-
-## Overview
-
-NitroStack is a **framework** built on top of the official MCP SDK that provides a structured, decorator-based approach for building production-ready MCP servers with enterprise features.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      NitroStack Framework                    │
-├─────────────────────────────────────────────────────────────┤
-│  CLI Tools  │  Templates  │  Studio UI  │  Decorators      │
-├─────────────────────────────────────────────────────────────┤
-│          Core Server Layer (Module System)                   │
-├─────────────────────────────────────────────────────────────┤
-│   Auth    │  Guards   │  Interceptors  │  Pipes  │ Events  │
-├─────────────────────────────────────────────────────────────┤
-│              Transport Layer (HTTP/STDIO)                    │
-├─────────────────────────────────────────────────────────────┤
-│           Official MCP SDK (@modelcontextprotocol)          │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Core Architecture
-
-### 1. Module System (Inspired by NestJS)
-
-**Module** → Groups related components
-```typescript
-@Module({
-  components: [CalculatorComponent],
-  imports: [ConfigModule]
-})
-export class AppModule {}
-```
-
-**Component** → Contains tools, resources, prompts
-```typescript
-@Component()
-export class CalculatorComponent {
-  @Tool({ description: "Add numbers" })
-  add(@Param('a') a: number, @Param('b') b: number) {
-    return a + b;
-  }
-}
-```
-
-### 2. Decorator System
-
-**Purpose**: Declarative API for defining MCP primitives
-
-| Decorator | Purpose |
-|-----------|---------|
-| `@Tool()` | Define callable tools |
-| `@Resource()` | Expose data resources |
-| `@Prompt()` | Create prompt templates |
-| `@UseGuards()` | Apply authentication |
-| `@UseInterceptors()` | Add middleware logic |
-| `@UsePipes()` | Validate/transform input |
-| `@Subscribe()` | Handle events |
-
-### 3. Dependency Injection
-
-**Injectable Services** → Shared across components
-```typescript
-@Injectable()
-export class DatabaseService {
-  query(sql: string) { ... }
-}
-
-@Component()
-export class UserComponent {
-  constructor(private db: DatabaseService) {}
-}
-```
-
-## Component Flow
-
-```
-Request → Transport → Server → Guards → Pipes → Component Method → Interceptors → Response
-                                  ↓                      ↓
-                              Auth Check           Logging/Transform
-```
-
-1. **Transport** receives request (HTTP/STDIO)
-2. **Guards** check authentication/authorization
-3. **Pipes** validate and transform input
-4. **Component** executes business logic
-5. **Interceptors** transform response/add logging
-6. **Transport** sends response back
-
-## Key Features
-
-### 🔒 Built-in Authentication
-- **JWT**: Token-based auth
-- **API Key**: Simple key-based auth
-- **OAuth**: Full OAuth2/PKCE flow
-- **Guards**: Declarative protection
-
-### 🚀 Dual Transport
-- **STDIO**: For dev (MCP Inspector, Claude Desktop)
-- **HTTP SSE**: For production web clients
-- **Auto-switching**: Based on NODE_ENV
-
-### 🎨 NitroStudio (Admin UI)
-- Visual tool testing
-- Resource browsing
-- Prompt management
-- Real-time logs
-- Built with Next.js
-
-### 🧩 Widget System
-- React components for tool UIs
-- Auto-exported as static HTML
-- Embedded in tool responses
-- Custom rendering in clients
-
-### 📦 CLI Tooling
-```bash
-nitro init           # Scaffold new project
-nitro dev            # Run with hot-reload
-nitro build          # Production build
-nitro generate-types # Generate TypeScript types
-```
-
-### 🏗️ Templates
-- `typescript-starter` - Basic MCP server
-- `typescript-auth` - With JWT auth
-- `typescript-auth-api-key` - With API key auth
-- `typescript-oauth` - With OAuth flow
-
-## Architecture Comparison
-
-### Official MCP SDK
-```typescript
-// Manual setup, imperative
-const server = new Server({ name: "my-server" });
-
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: [{ name: "add", description: "...", inputSchema: {...} }]
-}));
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  if (request.params.name === "add") {
-    return { content: [{ type: "text", text: result }] };
-  }
-});
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-```
-
-### NitroStack
-```typescript
-// Declarative, structured
-@Component()
-export class CalculatorComponent {
-  @Tool({ description: "Add numbers" })
-  @UseGuards(JwtGuard)
-  @HealthCheck('add-operation')
-  async add(
-    @Param('a') a: number,
-    @Param('b') b: number
-  ): Promise<number> {
-    return a + b;
-  }
-}
-
-// Bootstrap
-await McpApplicationFactory.create(AppModule).start('dual');
-```
-
-## Advantages Over Raw SDK
-
-| Feature | MCP SDK | NitroStack |
-|---------|---------|------------|
-| **Structure** | Manual | Module-based |
-| **Tools** | Imperative handlers | Decorators |
-| **Auth** | DIY | Built-in (JWT/OAuth/API Key) |
-| **Validation** | Manual | Pipes with Zod |
-| **Transport** | Single | Dual (HTTP+STDIO) |
-| **UI** | None | NitroStudio |
-| **DI** | None | Full container |
-| **Guards** | DIY | Declarative |
-| **Events** | None | EventEmitter |
-| **Widgets** | None | React components |
-| **CLI** | None | Full toolchain |
-| **Templates** | None | 4+ ready templates |
-
-## Component Relationships
-
-```
-AppModule
-├── ConfigModule (Injectable)
-├── AuthModule (JWT/OAuth/API Key)
-└── Feature Modules
-    ├── CalculatorComponent
-    │   ├── Tools (@Tool decorator)
-    │   ├── Resources (@Resource decorator)
-    │   ├── Prompts (@Prompt decorator)
-    │   └── Dependencies (via DI)
-    └── DatabaseComponent
-        └── Shared via @Injectable
-```
-
-## Production Architecture
-
-```
-┌──────────────────────────────────────────┐
-│           Load Balancer (nginx)          │
-└─────────────┬────────────────────────────┘
-              │
-    ┌─────────┴─────────┐
-    │                   │
-┌───▼────┐         ┌───▼────┐
-│ Node 1 │         │ Node 2 │  (Multiple instances)
-│ :3000  │         │ :3001  │
-└───┬────┘         └───┬────┘
-    │                   │
-    │  HTTP SSE + STDIO │
-    │                   │
-┌───▼───────────────────▼────┐
-│      Shared Services        │
-│   (DB, Cache, Message Q)    │
-└─────────────────────────────┘
-```
-
-## Development Workflow
-
-```bash
-# 1. Scaffold
-nitro init my-server --template typescript-auth
-
-# 2. Develop
-cd my-server
-npm install
-npm run dev  # STDIO transport for Inspector
-
-# 3. Build
-npm run build  # Compiles TS + exports widgets
-
-# 4. Production
-NODE_ENV=production npm start  # Dual transport
-```
-
-## File Structure
-
-```
-my-server/
-├── src/
-│   ├── index.ts              # Bootstrap
-│   ├── app.module.ts         # Root module
-│   ├── modules/              # Feature modules
-│   │   └── calculator/
-│   │       ├── calculator.component.ts
-│   │       └── calculator.service.ts
-│   ├── guards/               # Auth guards
-│   ├── interceptors/         # Logging, transform
-│   ├── pipes/                # Validation
-│   └── widgets/              # React UIs
-│       ├── package.json
-│       └── components/
-└── dist/                     # Compiled output
-```
-
-## Key Design Principles
-
-1. **Convention over Configuration** - Sensible defaults, minimal boilerplate
-2. **Decorator-First** - Declarative, self-documenting code
-3. **Production-Ready** - Auth, validation, logging, health checks
-4. **Framework Agnostic** - Can integrate with Express, Fastify, etc.
-5. **Type-Safe** - Full TypeScript support with inference
-6. **Modular** - Each feature is a module, easy to add/remove
-
-## When to Use NitroStack vs Raw SDK
-
-### Use NitroStack When:
-- Building production servers
-- Need authentication
-- Want structured codebase
-- Multiple developers
-- Need admin UI
-- Building complex servers with many tools
-
-### Use Raw SDK When:
-- Simple, single-purpose servers
-- Prototyping/experimenting
-- Minimal dependencies preferred
-- Learning MCP basics
-- Custom architecture needed
-
-## Summary
-
-NitroStack = **MCP SDK** + **Structure** + **Enterprise Features** + **Developer Experience**
-
-It's not replacing the MCP SDK, it's enhancing it with:
-- 🏗️ **Architecture**: Modules, components, DI
-- 🔐 **Security**: Built-in auth strategies
-- 🎨 **UI**: Admin dashboard & widget system
-- 🛠️ **Tooling**: CLI, templates, hot-reload
-- 📦 **Deployment**: Dual transport, production-ready
-
-Think of it as **NestJS for MCP** - bringing enterprise patterns and developer ergonomics to MCP server development.

package/CHANGELOG.md

@@ -1,49 +0,0 @@
-# Changelog
-
-All notable changes to NitroStack will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.15] - 2025-10-28
-
-### Fixed
-- **Node.js Compatibility**: Fixed compatibility issues with Node.js versions 18.x and 20.x (< 20.10.0)
-  - Downgraded `ora` from v9.0.0 to v8.1.1 to avoid `import ... with {type: 'json'}` syntax
-  - Downgraded `inquirer` from v12.10.0 to v9.3.7 for broader Node.js compatibility
-  - Added `@types/inquirer` v9.0.7 as dev dependency for TypeScript support
-  - Resolved `SyntaxError: Unexpected token 'with'` error on older Node.js versions
-
-### Added
-- `NODE_COMPATIBILITY.md` - Comprehensive guide for Node.js version compatibility
-- Updated README with Node.js version requirements
-
-### Changed
-- Improved developer experience for users on different Node.js versions
-- Package now works reliably on Node.js 18.0.0 and later
-
-## [1.0.14] - 2025-10-27
-
-### Added
-- Initial public release to npm
-- Full MCP server framework with decorators
-- Built-in Studio for visual testing
-- Authentication modules (JWT, OAuth 2.1, API Keys)
-- Widget system for interactive UIs
-- CLI with project generation and hot reload
-- Multiple starter templates
-- Comprehensive documentation
-
-### Features
-- Declarative programming model with decorators
-- Runtime pipeline (Guards, Middleware, Interceptors, Pipes, Filters)
-- Type generation from tool definitions
-- Caching and rate limiting support
-- Hot reload development workflow
-- Production-grade tooling
-
----
-
-## Version History
-
-For older versions and detailed changes, see [GitHub Releases](https://github.com/abhishekpanditofficial/nitrostack/releases).

package/CONTRIBUTING.md

@@ -1,182 +0,0 @@
-# Contributing to NitroStack
-
-Thank you for your interest in contributing to NitroStack! This document provides guidelines and instructions for contributing.
-
-## 📝 Contributor License Agreement
-
-By contributing to NitroStack, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE). This means:
-
-- You have the right to contribute the code
-- You agree to license your contributions under Apache 2.0
-- Your contributions will be made available to the community
-
-## Getting Started
-
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/yourusername/nitrostack.git`
-3. Create a branch: `git checkout -b feature/your-feature-name`
-4. Make your changes
-5. Add Apache 2.0 license header to new files (see below)
-6. Run tests: `npm test`
-7. Commit your changes: `git commit -am 'Add some feature'`
-8. Push to the branch: `git push origin feature/your-feature-name`
-9. Create a Pull Request
-
-## 📄 License Headers
-
-All new source files must include the Apache 2.0 license header:
-
-```typescript
-/**
- * Copyright 2025 Abhishek Pandit
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-```
-
-## Development Setup
-
-```bash
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run in development mode
-npm run dev
-
-# Run tests
-npm test
-
-# Lint code
-npm run lint
-
-# Format code
-npm run format
-```
-
-## Project Structure
-
-```
-nitrostack/
-├── src/
-│   ├── core/           # Core framework
-│   │   ├── server.ts   # Main server class
-│   │   ├── tool.ts     # Tool abstraction
-│   │   ├── resource.ts # Resource abstraction
-│   │   ├── prompt.ts   # Prompt abstraction
-│   │   ├── logger.ts   # Logging utilities
-│   │   ├── errors.ts   # Error classes
-│   │   └── types.ts    # Type definitions
-│   └── cli/            # CLI tool
-│       ├── index.ts    # CLI entry point
-│       └── commands/   # CLI commands
-├── templates/          # Project templates
-│   ├── basic/
-│   ├── typescript/
-│   └── advanced/
-└── examples/           # Example projects
-
-## Code Style
-
-We use ESLint and Prettier for code formatting. Please ensure your code passes linting:
-
-```bash
-npm run lint
-npm run format
-```
-
-## Testing
-
-- Write tests for new features
-- Ensure all tests pass before submitting PR
-- Aim for good test coverage
-
-```bash
-npm test
-```
-
-## Commit Messages
-
-Follow conventional commit format:
-
-- `feat:` New feature
-- `fix:` Bug fix
-- `docs:` Documentation changes
-- `style:` Code style changes (formatting, etc.)
-- `refactor:` Code refactoring
-- `test:` Test changes
-- `chore:` Build process or auxiliary tool changes
-
-Example:
-```
-feat: add rate limiting support for tools
-```
-
-## Pull Request Process
-
-1. Update the README.md with details of changes if applicable
-2. Update the CHANGELOG.md with a note describing your changes
-3. Ensure all tests pass and linting is clean
-4. Request review from maintainers
-5. Address any feedback
-
-## Reporting Bugs
-
-When reporting bugs, please include:
-
-- Your operating system and version
-- Node.js version
-- NitroStack version
-- Steps to reproduce the bug
-- Expected behavior
-- Actual behavior
-- Any error messages or logs
-
-## Feature Requests
-
-We welcome feature requests! Please:
-
-- Check if the feature has already been requested
-- Clearly describe the feature and its use case
-- Provide examples of how it would be used
-
-## Code of Conduct
-
-- Be respectful and inclusive
-- Welcome newcomers
-- Focus on constructive feedback
-- Maintain professional communication
-
-## Questions?
-
-Feel free to:
-- Open an issue for discussion
-- Join our community discussions
-- Reach out to maintainers
-
-## 🔗 Resources
-
-- **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)
-
----
-
-Thank you for contributing to NitroStack! 🎉
-
-**By submitting a pull request, you represent that you have the right to license your contribution to NitroStack and the community, and agree by submitting the patch that your contributions are licensed under the Apache License 2.0.**
-
-

package/NOTICE

@@ -1,153 +0,0 @@
-NitroStack
-Copyright 2025 Abhishek Pandit
-
-This product includes software developed by Abhishek Pandit for NitroStack (https://nitrostack.vercel.app/).
-
-This project contains code and dependencies from various open source projects:
-
-================================================================================
-
-@modelcontextprotocol/sdk
-Copyright (c) Anthropic PBC
-Licensed under the MIT License
-
-@google/generative-ai
-Copyright (c) Google LLC
-Licensed under the Apache License, Version 2.0
-
-express
-Copyright (c) 2009-2014 TJ Holowaychuk <tj@vision-media.ca>
-Copyright (c) 2013-2014 Roman Shtylman <shtylman+expressjs@gmail.com>
-Copyright (c) 2014-2015 Douglas Christopher Wilson <doug@somethingdoug.com>
-Licensed under the MIT License
-
-zod
-Copyright (c) 2020 Colin McDonnell
-Licensed under the MIT License
-
-reflect-metadata
-Copyright (c) Microsoft Corporation
-Licensed under the Apache License, Version 2.0
-
-winston
-Copyright (c) 2010 Charlie Robbins
-Licensed under the MIT License
-
-jsonwebtoken
-Copyright (c) 2015 Auth0, Inc. <support@auth0.com> (http://auth0.com)
-Licensed under the MIT License
-
-jose
-Copyright (c) 2020 Filip Skokan
-Licensed under the MIT License
-
-better-sqlite3
-Copyright (c) 2016 Joshua Wise
-Licensed under the MIT License
-
-bcryptjs
-Copyright (c) 2012 Nevins Bartolomeo
-Licensed under the MIT License
-
-inquirer
-Copyright (c) 2012 Simon Boudrias
-Licensed under the MIT License
-
-commander
-Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
-Licensed under the MIT License
-
-chokidar
-Copyright (c) 2012-2019 Paul Miller (https://paulmillr.com)
-Copyright (c) 2014-2019 Elan Shanker
-Licensed under the MIT License
-
-openai
-Copyright (c) OpenAI
-Licensed under the Apache License, Version 2.0
-
-fs-extra
-Copyright (c) 2011-2017 JP Richardson
-Licensed under the MIT License
-
-dotenv
-Copyright (c) 2015, Scott Motte
-Licensed under the BSD 2-Clause License
-
-ora
-Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
-Licensed under the MIT License
-
-open
-Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
-Licensed under the MIT License
-
-uuid
-Copyright (c) 2010-2020 Robert Kieffer and other contributors
-Licensed under the MIT License
-
-ws
-Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>
-Licensed under the MIT License
-
-cors
-Copyright (c) 2013 Troy Goode <troygoode@gmail.com>
-Licensed under the MIT License
-
-http-proxy-middleware
-Copyright (c) 2015 Steven Chim
-Licensed under the MIT License
-
-zod-to-json-schema
-Copyright (c) 2021 Stefan Terdell
-Licensed under the ISC License
-
-================================================================================
-
-For the full license texts of these dependencies, please refer to their
-respective package directories in node_modules or their source repositories.
-
-================================================================================
-
-The HyperMCP project also includes documentation and examples that reference
-various standards and specifications:
-
-- Model Context Protocol (MCP) Specification
-  https://modelcontextprotocol.io/
-
-- OAuth 2.1 (draft-ietf-oauth-v2-1-13)
-  https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13
-
-- RFC 9728 - OAuth 2.0 Protected Resource Metadata
-  https://datatracker.ietf.org/doc/html/rfc9728
-
-- RFC 8707 - Resource Indicators for OAuth 2.0
-  https://datatracker.ietf.org/doc/html/rfc8707
-
-- RFC 7662 - OAuth 2.0 Token Introspection
-  https://datatracker.ietf.org/doc/html/rfc7662
-
-- RFC 8414 - OAuth 2.0 Authorization Server Metadata
-  https://datatracker.ietf.org/doc/html/rfc8414
-
-- RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol
-  https://datatracker.ietf.org/doc/html/rfc7591
-
-- RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)
-  https://datatracker.ietf.org/doc/html/rfc7636
-
-================================================================================
-
-TRADEMARKS
-
-NitroStack, the NitroStack logo, and related marks are trademarks of the NitroStack
-project. Use of these trademarks is subject to the trademark policy available
-at https://nitrostack.vercel.app/.
-
-================================================================================
-
-For more information, visit:
-- Website: https://nitrostack.vercel.app/
-- Documentation: https://nitrostack-docs.vercel.app/
-- GitHub: https://github.com/abhishekpanditofficial/nitrostack
-