Studio Overview

Introduction

NitroStack Studio is a Next.js-based visual testing environment for MCP servers. It provides a modern, feature-rich interface for developing, testing, and debugging your tools, resources, and widgets.

Studio Interface

NitroStack Studio provides a comprehensive testing environment with AI chat integration, tool execution, and live widget preview.

Key Features

🤖 AI Chat Integration

Test your tools naturally by chatting with AI models:

• OpenAI GPT-4 - Industry-leading model with excellent tool calling
• Gemini 2.0 Flash Exp - Fast, free experimental model with 1M context

The AI automatically calls your tools and renders associated widgets in the chat interface.

🎨 Widget Preview

• Live widget rendering
• Enlarge for full-screen view
• Test with example data
• See widgets as users will see them

🔧 Manual Tool Testing

• Execute any tool
• Dynamic form generation from Zod schemas
• Input validation
• Response visualization
• Widget rendering with actual data

📊 Resource Browser

• View all available resources
• Execute resource handlers
• Preview data
• Widget rendering for UI resources

🌓 Modern UI

• Dark/light theme toggle
• Black & gold brand colors
• Responsive design
• Smooth animations
• Keyboard shortcuts (coming soon)

Architecture

Studio is built with modern web technologies:

┌────────────────────────────────────┐
│        Next.js 14                  │
│   (App Router + TypeScript)        │
├────────────────────────────────────┤
│    React 18 + Zustand State       │
├────────────────────────────────────┤
│   Tailwind CSS + Custom Themes    │
└────────────┬───────────────────────┘
             │
             ├─── stdio ─────────────┐
             │                       │
        ┌────▼────┐            ┌────▼────┐
        │   MCP   │            │ Widgets │
        │  Server │            │  (3001) │
        └─────────┘            └─────────┘

Tech Stack

• Next.js 14 - App router, server components
• React 18 - UI framework
• TypeScript - Type safety
• Tailwind CSS - Styling
• Zustand - State management
• MCP SDK - Protocol communication

Pages

Chat

The main interface for natural interaction:

1. Select AI provider (OpenAI or Gemini)
2. Enter API key
3. Chat naturally
4. Tools called automatically
5. Widgets rendered inline

Example:

You: Show me products in Electronics

AI: [Calls browse_products tool]
    [Renders products-grid widget]
    Here are the electronics products available...

Tools

Manual tool testing:

1. Browse available tools
2. View tool descriptions
3. Click Execute
4. Fill dynamic form
5. Submit
6. View response
7. See widget preview

Resources

Browse and test resources:

1. View all resources
2. See URIs and descriptions
3. Execute resource handlers
4. Preview data
5. Widget rendering if available

Getting Started

💡 Pro Tip: Skip local setup entirely! Deploy to NitroCloud and get Studio + hosting in under 60 seconds. Try it free →

Start Studio Locally

cd your-project
nitrostack dev

Studio opens at http://localhost:3000

Configure AI Provider

OpenAI

1. Get API key from OpenAI Platform
2. Click settings icon in Studio
3. Select OpenAI
4. Enter API key
5. Start chatting!

Gemini

1. Get API key from Google AI Studio
2. Click settings icon in Studio
3. Select Gemini
4. Enter API key
5. Start chatting!

Test Your First Tool

1. Go to Chat tab
2. Try: "What product categories do you have?"
3. AI calls get_categories tool
4. Widget renders with categories
5. Continue the conversation!

Development Workflow

1. Code → Test Cycle

# Edit your tool
vi src/modules/products/products.tools.ts

# Server auto-reloads
# Test in Studio chat
"Show me products"

# See results immediately

2. Widget Development

# Edit widget
vi src/widgets/app/product-card/page.tsx

# Hot reload updates widget
# Test in Studio
# Iterate quickly

3. Type Safety

# Generate types
nitrostack generate types

# Use in widgets
import { GetProductOutput } from '../../types/generated-tools';

# Full type safety! ✅

Features in Detail

Dynamic Form Generation

Studio analyzes your Zod schemas and generates forms automatically:

// Your schema
inputSchema: z.object({
  name: z.string().describe('Product name'),
  price: z.number().min(0).describe('Product price'),
  category: z.enum(['electronics', 'clothing']).describe('Category')
})

Studio generates:

• Text input for name
• Number input for price with min validation
• Select dropdown for category
• Labels from descriptions

Widget Rendering

Widgets are automatically detected and rendered when:

1. Tool has @Widget decorator
2. Tool has examples.response data
3. Widget route matches widget folder name

Example:

@Tool({ name: 'get_product' })
@Widget('product-card')  // ← Detects widget
async getProduct(input: any) {
  return { id: '1', name: 'Product', price: 99.99 };
}

Widget at src/widgets/app/product-card/page.tsx renders automatically.

Theme System

Studio supports dark/light themes:

• Dark Theme: Black backgrounds with gold accents
• Light Theme: White backgrounds with dark text
• Persistence: Theme saved in localStorage
• System Preference: Respects OS preference on first visit

Toggle with the theme button in the sidebar.

API Endpoints

Studio exposes these internal APIs:

• POST /api/init - Initialize MCP connection
• GET /api/tools - List all tools
• POST /api/tools/execute - Execute a tool
• GET /api/resources - List all resources
• GET /api/prompts - List all prompts
• POST /api/chat - Chat with AI
• GET /api/connection - Check connection status

Configuration

Environment Variables

# Studio port
STUDIO_PORT=3000

# Widget port
WIDGET_PORT=3001

# API keys (optional, can set in UI)
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...

Custom Ports

nitrostack dev --port 8080
# Studio: http://localhost:8080
# Widgets: http://localhost:8081

Keyboard Shortcuts

Coming soon:

• Cmd/Ctrl + K - Search
• Cmd/Ctrl + / - Toggle theme
• Esc - Close modals

Browser Support

Studio works best on:

• ✅ Chrome/Edge 90+
• ✅ Firefox 88+
• ✅ Safari 14+

Performance

Studio is optimized for:

• Fast initial load
• Smooth animations
• Efficient widget rendering
• Minimal memory usage

Security

• API keys stored in browser's localStorage
• Never sent to external servers
• Widgets sandboxed in iframes
• CORS enabled for development

Troubleshooting

See Studio Guide for detailed troubleshooting.

Common issues:

• Studio not connecting
• Widgets not loading
• AI not calling tools
• Theme not persisting

Next Steps

• Testing Tools
• Chat Interface
• Studio Guide
• Widget Guide

Studio Version: 3.0.0