NitroStack Documentation

Welcome to NitroStack - A professional-grade framework for building MCP (Model Context Protocol) servers with beautiful UI widgets.

Package Architecture

NitroStack is organized as a monorepo with multiple packages:

@nitrostack/
├── nitrostack          # Core SDK - Server framework, decorators, DI, transports
├── @nitrostack/cli     # CLI tools - Project creation, dev server, build
└── @nitrostack/widgets # Widget SDK - React hooks and utilities for widgets

Package Overview

NitroStudio (Standalone)

NitroStudio is a standalone visual testing environment for MCP servers. It can be:

• Run as a web application
• Packaged as a desktop app (Electron)
• Self-hosted

Documentation Structure

docs/
├── README.md                    # This file
│
├── getting-started/             # Quick start guides
│   ├── 00-introduction.md
│   ├── 01-installation.md
│   └── 02-quick-start.md
│
├── cli/                         # CLI Documentation
│   ├── 01-introduction.md
│   ├── 02-installation.md
│   ├── 03-init-command.md
│   ├── 04-dev-command.md
│   ├── 05-build-command.md
│   ├── 06-configuration.md
│   ├── 07-install-command.md   # Package installation
│   ├── 08-generate-command.md
│   └── 09-upgrade-command.md   # Package upgrades
│
├── sdk/                         # SDK Documentation
│   └── typescript/
│       ├── 03-server-concepts.md
│       ├── 04-tools-guide.md
│       ├── 05-resources-guide.md
│       ├── 06-prompts-guide.md
│       ├── 07-middleware-guide.md
│       ├── 08-interceptors-guide.md
│       ├── 09-authentication-overview.md
│       ├── 10-api-key-authentication.md
│       ├── 11-oauth-authentication.md
│       ├── 12-dependency-injection.md
│       ├── 13-error-handling.md
│       ├── 14-testing-guide.md
│       ├── 15-events-guide.md
│       ├── 16-ui-widgets-guide.md
│       ├── 17-best-practices.md
│       ├── 18-widget-sdk-reference.md
│       └── 19-file-upload-guide.md  # File handling
│
├── studio/                      # NitroStudio Documentation
│   ├── 01-overview.md
│   ├── 02-testing-tools.md
│   ├── 03-chat-interface.md
│   └── 04-standalone-setup.md   # Running Studio independently
│
├── templates/                   # Project Templates
│   ├── 01-starter-template.md
│   ├── 02-oauth-template.md
│   └── 03-pizzaz-template.md
│
├── deployment/                  # Deployment Guides
│   ├── 01-checklist.md
│   ├── 02-docker-guide.md
│   └── 03-cloud-platforms.md
│
├── guides/                      # How-to Guides
│   ├── dual-transport.md
│   ├── verify-transport.md
│   └── widget-sdk-migration.md
│
└── api-reference/               # API Reference
    ├── cli-commands.md
    ├── decorators.md
    ├── execution-context.md
    ├── guards.md
    ├── interceptors.md
    ├── middleware.md
    └── pipes.md

Quick Start

1. Install CLI

npm install -g @nitrostack/cli

2. Create Project

nitrostack-cli init my-project
cd my-project

3. Start Development

npm run dev

4. Open Studio (Separate)

Download and run NitroStudio, then connect to your project.

Key Features

• 🎯 Decorator-Based Tools - Define MCP tools with TypeScript decorators
• 🔌 Multiple Transports - stdio, HTTP, WebSocket, or dual mode
• 🎨 UI Widgets - Build beautiful React widgets for tool outputs
• 🔐 Authentication - Built-in OAuth 2.1, JWT, and API Key support
• 💉 Dependency Injection - Full DI container with providers
• 🛡️ Guards & Middleware - Request validation and processing
• 📡 Real-time Events - Event emitter for async operations
• 🔄 Hot Reload - Fast development with automatic reloading

Documentation Guidelines

1. Code Examples: Every major concept includes runnable code examples
2. API Reference: Full parameter lists, return types, and examples
3. Best Practices: Common pitfalls and recommended patterns
4. Cross-links: Related concepts are linked for easy navigation

Contributing

When adding new documentation:

1. Update this README with the new file location
2. Follow the existing markdown style
3. Include code examples
4. Add cross-references to related docs