@nitrostack/cli 1.0.10 → 1.0.13

package/README.md

@@ -1,78 +1,64 @@
-# @nitrostack/cli ⚡
+# @nitrostack/cli
 
-**The command-line powerhouse for NitroStack — Scaffold, generate, and develop MCP servers at the speed of light.**
+Official NitroStack CLI for scaffolding, developing, and maintaining MCP server
+projects.
 
-[![CLI Tool](https://img.shields.io/badge/NitroStack-CLI-orange?style=for-the-badge&logo=none)](https://nitrostack.ai)
-[![License](https://img.shields.io/badge/License-Apache%202.0-red?style=for-the-badge&logo=none)](https://opensource.org/licenses/Apache-2.0)
-[![Documentation](https://img.shields.io/badge/Docs-docs.nitrostack.ai-brightgreen?style=for-the-badge&logo=none)](https://docs.nitrostack.ai)
+[![npm version](https://img.shields.io/npm/v/@nitrostack/cli?style=flat-square)](https://www.npmjs.com/package/@nitrostack/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@nitrostack/cli?style=flat-square)](https://www.npmjs.com/package/@nitrostack/cli)
+[![license](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
 
-`@nitrostack/cli` is the official toolkit for managing the NitroStack development lifecycle. From bootstrapping new projects with enterprise-ready templates to generating code and types, the CLI is your best friend when building MCP servers.
-
----
-
-## ✨ Key Features
-
-- **🏗️ Instant Scaffolding**: Bootstrap new MCP servers from professional templates in seconds.
-- **🛠️ Code Generators**: Generate Modules, Tools, Guards, and Middleware with a single command.
-- **🔄 Live Reload**: Powerful dev server with hot-reloading for rapid development.
-- **🏷️ Type Generation**: Automatically generate TypeScript interfaces from your tool schemas.
-- **🎨 Visual Studio**: Launch the built-in NitroStudio to test inputs/outputs and preview widgets.
-
----
-
-## 📦 Installation
-
-We recommend installing the CLI globally to access the `nitrostack-cli` command anywhere:
+## Installation
 
 ```bash
 npm install -g @nitrostack/cli
 ```
 
----
-
-## 🚀 Commands Overview
+## Quick Start
 
-### Initialize a New Project
 ```bash
-nitrostack-cli init my-project
+nitrostack-cli init my-project --template typescript-starter
+cd my-project
+npm run dev
 ```
 
-![nitrocli init](./assets/gif/nitrocli.gif)
+## Core Commands
 
-### Start Development Server
 ```bash
+nitrostack-cli init <project-name> [--template <name>]
 nitrostack-cli dev
-```
-
-### Scaffold a New Tool
-```bash
-nitrostack-cli generate tool my-tool --module users
-```
-
-### Build for Production
-```bash
 nitrostack-cli build
+nitrostack-cli start
+nitrostack-cli generate <type> [name] [--module <name>]
+nitrostack-cli install
+nitrostack-cli upgrade
 ```
 
----
-
-## 🎨 NitroStudio
+## Templates
 
-NitroStudio works seamlessly with your projects. You don't even need to run a dev command—**opening your project in NitroStudio starts the server automatically.**
+- `typescript-starter`
+- `typescript-oauth`
+- `typescript-pizzaz`
 
-![NitroStudio](./assets/gif/nitrostudio-main.gif)
+## NitroStudio
 
-**[Download NitroStudio](https://nitrostack.ai/studio)**
+NitroStudio is the recommended companion app for testing and debugging MCP
+servers built with NitroStack.
 
----
+- Download: <https://nitrostack.ai/studio>
+- Studio: <https://nitrostack.ai/studio>
 
-## 📖 Useful Links
+## Links
 
-- **[GitHub Repository](https://github.com/nitrocloudofficial/nitrostack)**
-- **[Documentation](https://docs.nitrostack.ai)**
-- **[Blog & Tutorials](https://blog.nitrostack.ai)**
-- **[NPM Package](https://www.npmjs.com/package/@nitrostack/cli)**
+- CLI docs: <https://docs.nitrostack.ai/cli/overview>
+- Full docs: <https://docs.nitrostack.ai>
+- Source: <https://github.com/nitrocloudofficial/nitrostack>
+- npm: <https://www.npmjs.com/package/@nitrostack/cli>
+- Blog: <https://blog.nitrostack.ai>
 
----
+## Community
 
-Built with ⚡ by the **NitroStack Team**.
+- Discord: <https://discord.gg/uVWey6UhuD>
+- X: <https://x.com/nitrostackai>
+- YouTube: <https://www.youtube.com/@nitrostackai>
+- LinkedIn: <https://linkedin.com/company/nitrostack-ai/>
+- GitHub: <https://github.com/nitrostackai>

package/dist/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAmBA,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,iBAmOvD"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAmBA,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,iBAgPvD"}

package/dist/commands/build.js

@@ -76,6 +76,17 @@ export async function buildCommand(options) {
                 if (fs.existsSync(APP_DIR)) {
                     findWidgetPages(APP_DIR);
                 }
+                // Linked @nitrostack/widgets often has its own node_modules/react (e.g. v19) while this app
+                // uses v18. Esbuild resolves from the realpath of the symlinked package, so without aliases
+                // the widget bundle can contain two Reacts and render blank in MCP hosts. Next.js can use
+                // webpack aliases in next.config.js; production `nitrostack-cli build` mirrors that here.
+                const widgetsNm = path.join(widgetsPath, 'node_modules');
+                const widgetReactAliases = {
+                    react: path.join(widgetsNm, 'react'),
+                    'react-dom': path.join(widgetsNm, 'react-dom'),
+                    'react/jsx-runtime': path.join(widgetsNm, 'react', 'jsx-runtime.js'),
+                    'react/jsx-dev-runtime': path.join(widgetsNm, 'react', 'jsx-dev-runtime.js'),
+                };
                 // Bundle each widget
                 for (const widget of widgetPages) {
                     const tempEntry = path.join(OUT_DIR, `_temp_${widget.outputName}.jsx`);
@@ -118,7 +129,8 @@ function init() {
                         jsx: 'automatic',
                         jsxImportSource: 'react',
                         external: [],
-                        nodePaths: [path.join(widgetsPath, 'node_modules')],
+                        nodePaths: [widgetsNm],
+                        alias: widgetReactAliases,
                         define: {
                             'process.env.NODE_ENV': '"production"'
                         },

package/dist/commands/cursor.d.ts

@@ -0,0 +1,11 @@
+interface CursorOptions {
+    global?: boolean;
+    local?: boolean;
+    type?: string;
+    url?: string;
+    port?: string;
+    force?: boolean;
+}
+export declare function cursorCommand(options: CursorOptions): Promise<void>;
+export {};
+//# sourceMappingURL=cursor.d.ts.map

package/dist/commands/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/commands/cursor.ts"],"names":[],"mappings":"AAqBA,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAuBD,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAoOzE"}

package/dist/commands/cursor.js

@@ -0,0 +1,238 @@
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs-extra';
+import os from 'os';
+import inquirer from 'inquirer';
+import { createHeader, createSuccessBox, createErrorBox, NitroSpinner, log, spacer, nextSteps, showFooter, NITRO_BANNER_FULL } from '../ui/branding.js';
+import { trackEvent, shutdownAnalytics } from '../analytics/posthog.js';
+/** Normalize CLI --type values, including the deprecated `sse` alias. */
+function normalizeConnectionType(raw) {
+    if (!raw)
+        return undefined;
+    if (raw === 'sse')
+        return 'legacy-sse';
+    if (raw === 'command' || raw === 'legacy-sse' || raw === 'streamable-http') {
+        return raw;
+    }
+    return undefined;
+}
+function defaultHttpUrl(type, port) {
+    if (type === 'streamable-http') {
+        return `http://localhost:${port}/mcp`;
+    }
+    return `http://localhost:${port}/sse`;
+}
+function isHttpConnectionType(type) {
+    return type === 'legacy-sse' || type === 'streamable-http';
+}
+export async function cursorCommand(options) {
+    console.log(NITRO_BANNER_FULL);
+    console.log(createHeader('Cursor Integration', 'Configure MCP server in Cursor'));
+    const startTime = Date.now();
+    trackEvent('cli_command_invoked', {
+        command: 'cursor',
+        options: Object.keys(options).filter(k => options[k] !== undefined),
+    });
+    const projectRoot = process.cwd();
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    // Validate project
+    if (!fs.existsSync(packageJsonPath)) {
+        console.log(createErrorBox('Not a Valid Project', 'package.json not found in the current directory.'));
+        trackEvent('cli_cursor_failed', {
+            error: 'Not a valid project: package.json missing',
+        });
+        await shutdownAnalytics();
+        process.exit(1);
+    }
+    let packageJson;
+    try {
+        packageJson = await fs.readJson(packageJsonPath);
+    }
+    catch (error) {
+        console.log(createErrorBox('Invalid package.json', 'Could not parse project package.json.'));
+        trackEvent('cli_cursor_failed', {
+            error: 'Invalid package.json parsing error',
+        });
+        await shutdownAnalytics();
+        process.exit(1);
+    }
+    const rawName = packageJson.name || path.basename(projectRoot);
+    const serverName = rawName.includes('/') ? rawName.split('/').pop() : rawName;
+    let target;
+    if (options.global) {
+        target = 'global';
+    }
+    else if (options.local) {
+        target = 'local';
+    }
+    else {
+        const answers = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'target',
+                message: chalk.white('Where would you like to install the Cursor MCP configuration?'),
+                choices: [
+                    { name: `Project-level ${chalk.dim('(.cursor/mcp.json)')}`, value: 'local' },
+                    { name: `Global        ${chalk.dim('(~/.cursor/mcp.json)')}`, value: 'global' },
+                ],
+                default: 'local',
+            }
+        ]);
+        target = answers.target;
+    }
+    let type = normalizeConnectionType(options.type);
+    if (options.type && !type) {
+        console.log(createErrorBox('Invalid connection type', `Unknown --type "${options.type}". Use: command, legacy-sse, or streamable-http.`));
+        await shutdownAnalytics();
+        process.exit(1);
+    }
+    if (!type) {
+        const answers = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'type',
+                message: chalk.white('Choose the connection type for Cursor:'),
+                choices: [
+                    { name: `Command (Stdio)          ${chalk.dim('─ Starts subprocess (recommended for local dev)')}`, value: 'command' },
+                    { name: `Legacy SSE (/sse)        ${chalk.dim('─ Cursor and older HTTP clients (recommended for Cursor)')}`, value: 'legacy-sse' },
+                    { name: `Streamable HTTP (/mcp)   ${chalk.dim('─ MCP Inspector and modern Streamable HTTP clients')}`, value: 'streamable-http' },
+                ],
+                default: 'command',
+            }
+        ]);
+        type = answers.type;
+    }
+    if (!type) {
+        console.log(createErrorBox('Invalid connection type', 'No connection type selected.'));
+        await shutdownAnalytics();
+        process.exit(1);
+    }
+    const port = options.port || '3000';
+    let httpUrl = options.url;
+    if (isHttpConnectionType(type) && !httpUrl) {
+        const defaultUrl = defaultHttpUrl(type, port);
+        const urlHint = type === 'legacy-sse'
+            ? chalk.dim('Default /sse; /mcp also works for Cursor (legacy SSE fallback on GET).')
+            : chalk.dim('For MCP Inspector and clients that use POST initialize + mcp-session-id.');
+        const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'url',
+                message: chalk.white('HTTP connection URL:'),
+                default: defaultUrl,
+            }
+        ]);
+        httpUrl = answers.url;
+        if (urlHint) {
+            console.log(urlHint);
+        }
+    }
+    let configFilePath;
+    if (target === 'global') {
+        configFilePath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    }
+    else {
+        configFilePath = path.join(projectRoot, '.cursor', 'mcp.json');
+    }
+    let entry;
+    if (type === 'command') {
+        const absIndexPath = path.join(projectRoot, 'dist', 'index.js');
+        entry = {
+            command: 'node',
+            args: [absIndexPath],
+            env: {}
+        };
+    }
+    else {
+        entry = {
+            url: httpUrl
+        };
+    }
+    const spinner = new NitroSpinner(`Configuring Cursor MCP server...`).start();
+    try {
+        await fs.ensureDir(path.dirname(configFilePath));
+        let mcpConfig = { mcpServers: {} };
+        if (await fs.pathExists(configFilePath)) {
+            try {
+                mcpConfig = await fs.readJson(configFilePath);
+            }
+            catch (e) {
+                // Corrupted or empty file, initialize it
+                mcpConfig = { mcpServers: {} };
+            }
+        }
+        if (!mcpConfig.mcpServers) {
+            mcpConfig.mcpServers = {};
+        }
+        // Check if it already exists
+        if (mcpConfig.mcpServers[serverName] && !options.force) {
+            spinner.stop();
+            const { overwrite } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'overwrite',
+                    message: chalk.yellow(`MCP Server "${serverName}" is already registered in Cursor config. Overwrite?`),
+                    default: true,
+                }
+            ]);
+            if (!overwrite) {
+                log('Cancelled integration', 'warning');
+                trackEvent('cli_cursor_cancelled', {
+                    server_name: serverName,
+                    target,
+                    type,
+                });
+                await shutdownAnalytics();
+                return;
+            }
+            spinner.start();
+        }
+        mcpConfig.mcpServers[serverName] = entry;
+        await fs.writeJson(configFilePath, mcpConfig, { spaces: 2 });
+        spinner.succeed(`Registered "${serverName}" in Cursor config`);
+    }
+    catch (err) {
+        spinner.fail('Failed to update Cursor configuration');
+        console.log(createErrorBox('Integration Failed', err instanceof Error ? err.message : String(err)));
+        trackEvent('cli_cursor_failed', {
+            error: err instanceof Error ? err.message : String(err),
+            target,
+            type,
+        });
+        await shutdownAnalytics();
+        return;
+    }
+    // Summary
+    spacer();
+    console.log(createSuccessBox('Cursor Integration Successful', [
+        `Configured target: ${chalk.cyan(configFilePath)}`,
+        `Server registered: ${chalk.cyan(serverName)}`,
+        `Connection type:   ${chalk.cyan(type)}`,
+        type === 'command'
+            ? `Command path:      ${chalk.dim(path.join(projectRoot, 'dist', 'index.js'))}`
+            : `HTTP URL:          ${chalk.cyan(httpUrl)}`
+    ]));
+    if (type === 'command') {
+        // Check if dist/index.js exists
+        const distIndexPath = path.join(projectRoot, 'dist', 'index.js');
+        if (!fs.existsSync(distIndexPath)) {
+            log('Warning: dist/index.js not found. Remember to run "npm run build" first!', 'warning');
+            spacer();
+        }
+    }
+    if (type === 'legacy-sse') {
+        log('Tip: ensure the server is running in dual or http mode before connecting from Cursor.', 'info');
+    }
+    nextSteps([
+        'Restart/Reload your Cursor window to load the new MCP server',
+        'Check active MCP servers in Cursor under Settings > Tools > MCP',
+    ]);
+    showFooter();
+    trackEvent('cli_cursor_completed', {
+        target,
+        type,
+        server_name: serverName,
+        duration_ms: Date.now() - startTime,
+    });
+    await shutdownAnalytics();
+}

package/dist/commands/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAiUA,UAAU,eAAe;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwHvG"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAgUA,UAAU,eAAe;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwHvG"}

package/dist/commands/generate.js

@@ -17,13 +17,12 @@ const TEMPLATES = {
 @Middleware()
 export class ${name} implements MiddlewareInterface {
   async use(context: ExecutionContext, next: () => Promise<any>) {
-    // Before handler
-    console.log(\`[\${context.toolName}] Started\`);
-    
+    // Use context.logger instead of console.log — console breaks JSON-RPC over stdio in MCP mode
+    context.logger.info(\`[\${context.toolName}] Started\`);
+
     const result = await next();
-    
-    // After handler
-    console.log(\`[\${context.toolName}] Completed\`);
+
+    context.logger.info(\`[\${context.toolName}] Completed\`);
     
     return result;
   }

package/dist/commands/init.js

@@ -293,7 +293,7 @@ async function createProjectFromScratch(targetDir, projectName, answers) {
     };
     fs.writeJSONSync(path.join(targetDir, 'tsconfig.json'), tsconfig, { spaces: 2 });
     fs.mkdirSync(path.join(targetDir, 'src'), { recursive: true });
-    const indexTs = `import { createServer, createTool, z } from '@nitrostack/core';
+    const indexTs = `import { createServer, Tool, z } from '@nitrostack/core';
 
 const server = createServer({
   name: '${projectName}',
@@ -302,7 +302,7 @@ const server = createServer({
 });
 
 server.tool(
-  createTool({
+  new Tool({
     name: 'hello',
     description: 'Say hello to someone',
     inputSchema: z.object({
@@ -347,7 +347,7 @@ npm run build
 npm start
 \`\`\`
 
-Built with [NitroStack](https://nitrostack.dev) ⚡
+Built with [NitroStack](https://nitrostack.ai) ⚡
 `;
     fs.writeFileSync(path.join(targetDir, 'README.md'), readme);
 }

package/dist/commands/start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/commands/start.ts"],"names":[],"mappings":"AAiBA,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,iBAwFvD"}
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/commands/start.ts"],"names":[],"mappings":"AAiBA,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,iBA0FvD"}

package/dist/commands/start.js

@@ -35,6 +35,8 @@ export async function startCommand(options) {
         { label: 'Server', value: `http://localhost:${port}` },
         { label: 'Mode', value: 'Production' },
         { label: 'Transport', value: 'HTTP + STDIO (dual)' },
+        { label: 'Streamable HTTP', value: `http://localhost:${port}/mcp` },
+        { label: 'Legacy SDK SSE', value: `http://localhost:${port}/sse` },
         ...(hasBuiltWidgets ? [{ label: 'Widgets', value: 'Bundled' }] : []),
     ]));
     log('Starting server...', 'info');

package/dist/commands/upgrade.d.ts

@@ -2,6 +2,18 @@ interface UpgradeOptions {
     latest?: boolean;
     dryRun?: boolean;
 }
+/**
+ * Fetch a package's latest published version from NPM using standard https module.
+ */
+export declare function fetchLatestNpmVersion(packageName: string): Promise<string>;
+/**
+ * Compare two version strings
+ */
+export declare function compareVersions(v1: string, v2: string): number;
+/**
+ * Determine if a dependency refers to a local file or workspace link.
+ */
+export declare function isLocalDependency(version: string): boolean;
 /**
  * Main upgrade command handler
  */

package/dist/commands/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AA0BA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAwHD;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA2J3E"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AA2BA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAUD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgD1E;AA2BD;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAa9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAM1D;AAqED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAsI3E"}