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.

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:

Select AI provider (OpenAI or Gemini)
Enter API key
Chat naturally
Tools called automatically
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:

Browse available tools
View tool descriptions
Click Execute
Fill dynamic form
Submit
View response
See widget preview

Resources

Browse and test resources:

View all resources
See URIs and descriptions
Execute resource handlers
Preview data
Widget rendering if available

Getting Started

Start Studio

cd your-project
nitrostack dev

Studio opens at http://localhost:3000

Configure AI Provider

OpenAI

Get API key from OpenAI Platform
Click settings icon in Studio
Select OpenAI
Enter API key
Start chatting!

Gemini

Get API key from Google AI Studio
Click settings icon in Studio
Select Gemini
Enter API key
Start chatting!

Test Your First Tool

Go to Chat tab
Try: "What product categories do you have?"
AI calls get_categories tool
Widget renders with categories
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:

Tool has @Widget decorator
Tool has examples.response data
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

Studio Version: 3.0.0