@agentailor/create-mcp-server 0.4.1 → 0.5.1

package/README.md

@@ -1,13 +1,59 @@
 # @agentailor/create-mcp-server
 
+[![npm version](https://img.shields.io/npm/v/@agentailor/create-mcp-server.svg)](https://www.npmjs.com/package/@agentailor/create-mcp-server)
+[![Test](https://github.com/agentailor/create-mcp-server/actions/workflows/test.yml/badge.svg)](https://github.com/agentailor/create-mcp-server/actions/workflows/test.yml)
+[![npm downloads](https://img.shields.io/npm/dt/@agentailor/create-mcp-server.svg)](https://www.npmjs.com/package/@agentailor/create-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@agentailor/create-mcp-server.svg)](https://nodejs.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/agentailor/create-mcp-server/pulls)
+
 Scaffold production-ready MCP servers in seconds.
 
 ## Quick Start
 
+**Interactive mode** (guided prompts):
+
 ```bash
 npx @agentailor/create-mcp-server
 ```
 
+**CLI mode** (all options via arguments):
+
+```bash
+npx @agentailor/create-mcp-server --name=my-server
+```
+
+## CLI Options
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--name` | `-n` | — | Project name (required in CLI mode) |
+| `--package-manager` | `-p` | `npm` | Package manager: npm, pnpm, yarn |
+| `--framework` | `-f` | `sdk` | Framework: sdk, fastmcp |
+| `--template` | `-t` | `stateless` | Server mode: stateless, stateful |
+| `--oauth` | — | `false` | Enable OAuth (sdk+stateful only) |
+| `--no-git` | — | `false` | Skip git initialization |
+| `--help` | `-h` | — | Show help |
+| `--version` | `-V` | — | Show version |
+
+**Examples:**
+
+```bash
+# Minimal - uses all defaults
+npx @agentailor/create-mcp-server --name=my-server
+
+# Full options
+npx @agentailor/create-mcp-server \
+  --name=my-auth-server \
+  --package-manager=pnpm \
+  --framework=sdk \
+  --template=stateful \
+  --oauth
+
+# Short flags
+npx @agentailor/create-mcp-server -n my-server -p yarn -f fastmcp
+```
+
 ## Features
 
 - **Two frameworks** — Official MCP SDK or FastMCP
@@ -80,6 +126,25 @@ my-mcp-server/
 - `npm run dev` — build and start the server
 - `npm run inspect` — open MCP Inspector (update URL in `package.json` if needed)
 
+## Learning Resources
+
+| Guide | Description |
+|-------|-------------|
+| [Create Your First MCP Server in 5 Minutes](https://blog.agentailor.com/posts/create-your-first-mcp-server-in-5-minutes?utm_source=github&utm_medium=readme&utm_campaign=create-mcp-server) | Build your first production-ready MCP server. A complete beginner guide to scaffolding a Fetch MCP server with TypeScript. |
+| [Securing MCP Servers with Keycloak](https://blog.agentailor.com/posts/oauth-for-mcp-servers-practical-guide-keycloak?utm_source=github&utm_medium=readme&utm_campaign=create-mcp-server) | Learn how to secure your MCP servers with OAuth authentication using Keycloak. |
+| [Getting Started with FastMCP](https://blog.agentailor.com/posts/getting-started-with-fastmcp?utm_source=github&utm_medium=readme&utm_campaign=create-mcp-server) | Build MCP servers faster with FastMCP — the TypeScript framework inspired by Python's most popular MCP library. |
+| [OAuth for MCP Clients (Next.js + LangGraph.js)](https://blog.agentailor.com/posts/mcp-client-oauth-nextjs-langgraph?utm_source=github&utm_medium=readme&utm_campaign=create-mcp-server) | Implement OAuth authentication in your MCP client using Next.js and the MCP SDK. |
+
+## Need help building MCP servers or agent infrastructure?
+
+I help teams design and ship production-ready AI agent systems (MCP, LangGraph, RAG, memory, performance).
+
+If you’re building something serious on top of this:
+
+→ [DM me on LinkedIn](https://www.linkedin.com/in/ali-ibrahim-junior/)
+
+Happy to jump on a short call.
+
 ## What is MCP?
 
 The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open protocol that enables AI assistants to interact with external tools, data sources, and services.

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+import type { PackageManager, Framework } from './templates/common/types.js';
+export type TemplateType = 'stateless' | 'stateful';
+export interface CLIOptions {
+    name: string;
+    packageManager: PackageManager;
+    framework: Framework;
+    template: TemplateType;
+    oauth: boolean;
+    git: boolean;
+}
+export interface ParseResult {
+    mode: 'interactive' | 'cli';
+    options?: CLIOptions;
+}
+export declare function parseArguments(): ParseResult;

package/dist/cli.js

@@ -0,0 +1,60 @@
+import { Command, Option, InvalidArgumentError } from 'commander';
+const NAME_REGEX = /^[a-z0-9-_]+$/i;
+const VERSION = '0.4.1';
+function validateName(value) {
+    if (!NAME_REGEX.test(value)) {
+        throw new InvalidArgumentError('Project name can only contain letters, numbers, hyphens, and underscores');
+    }
+    return value;
+}
+export function parseArguments() {
+    const program = new Command();
+    program
+        .name('create-mcp-server')
+        .description('Create a new MCP (Model Context Protocol) server project')
+        .version(VERSION)
+        .option('-n, --name <name>', 'Project name', validateName)
+        .addOption(new Option('-p, --package-manager <manager>', 'Package manager')
+        .choices(['npm', 'pnpm', 'yarn'])
+        .default('npm'))
+        .addOption(new Option('-f, --framework <framework>', 'Framework to use')
+        .choices(['sdk', 'fastmcp'])
+        .default('sdk'))
+        .addOption(new Option('-t, --template <type>', 'Template type')
+        .choices(['stateless', 'stateful'])
+        .default('stateless'))
+        .option('--oauth', 'Enable OAuth authentication (sdk+stateful only)', false)
+        .option('--no-git', 'Skip git repository initialization');
+    program.parse();
+    const opts = program.opts();
+    // Detect mode based on whether any option was explicitly provided
+    // Check for CLI args (excluding node, script path, --help, --version)
+    const cliArgs = process.argv.slice(2);
+    const hasExplicitArgs = cliArgs.some((arg) => arg.startsWith('-') && !['--help', '-h', '--version', '-V'].includes(arg));
+    if (!hasExplicitArgs) {
+        return { mode: 'interactive' };
+    }
+    // CLI mode - validate required args
+    if (!opts.name) {
+        console.error('\nError: --name is required when using CLI arguments\n');
+        console.error('Usage: create-mcp-server --name=my-server [options]\n');
+        console.error('Run with --help for all options.\n');
+        process.exit(1);
+    }
+    // Validate OAuth constraint
+    if (opts.oauth && (opts.framework !== 'sdk' || opts.template !== 'stateful')) {
+        console.error('\nError: --oauth is only valid with --framework=sdk and --template=stateful\n');
+        process.exit(1);
+    }
+    return {
+        mode: 'cli',
+        options: {
+            name: opts.name,
+            packageManager: opts.packageManager,
+            framework: opts.framework,
+            template: opts.template,
+            oauth: opts.oauth,
+            git: opts.git, // Commander handles --no-git -> git: false
+        },
+    };
+}

package/dist/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.test.js

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// We need to test the CLI argument parsing logic
+// Commander modifies process.argv, so we need to mock it carefully
+describe('CLI argument parsing', () => {
+    const originalArgv = process.argv;
+    const originalExit = process.exit;
+    beforeEach(() => {
+        // Reset modules to clear commander's state
+        vi.resetModules();
+    });
+    afterEach(() => {
+        process.argv = originalArgv;
+        process.exit = originalExit;
+    });
+    it('returns interactive mode when no arguments provided', async () => {
+        process.argv = ['node', 'create-mcp-server'];
+        const { parseArguments } = await import('./cli.js');
+        const result = parseArguments();
+        expect(result.mode).toBe('interactive');
+        expect(result.options).toBeUndefined();
+    });
+    it('returns cli mode with valid arguments', async () => {
+        process.argv = ['node', 'create-mcp-server', '--name=my-server'];
+        const { parseArguments } = await import('./cli.js');
+        const result = parseArguments();
+        expect(result.mode).toBe('cli');
+        expect(result.options?.name).toBe('my-server');
+    });
+    it('uses defaults for optional arguments', async () => {
+        process.argv = ['node', 'create-mcp-server', '--name=my-server'];
+        const { parseArguments } = await import('./cli.js');
+        const result = parseArguments();
+        expect(result.options?.packageManager).toBe('npm');
+        expect(result.options?.framework).toBe('sdk');
+        expect(result.options?.template).toBe('stateless');
+        expect(result.options?.oauth).toBe(false);
+        expect(result.options?.git).toBe(true);
+    });
+    it('parses all arguments correctly', async () => {
+        process.argv = [
+            'node',
+            'create-mcp-server',
+            '--name=test-project',
+            '--package-manager=pnpm',
+            '--framework=fastmcp',
+            '--template=stateful',
+            '--no-git',
+        ];
+        const { parseArguments } = await import('./cli.js');
+        const result = parseArguments();
+        expect(result.options).toEqual({
+            name: 'test-project',
+            packageManager: 'pnpm',
+            framework: 'fastmcp',
+            template: 'stateful',
+            oauth: false,
+            git: false,
+        });
+    });
+    it('parses short flags correctly', async () => {
+        process.argv = [
+            'node',
+            'create-mcp-server',
+            '-n',
+            'my-project',
+            '-p',
+            'yarn',
+            '-f',
+            'sdk',
+            '-t',
+            'stateful',
+        ];
+        const { parseArguments } = await import('./cli.js');
+        const result = parseArguments();
+        expect(result.options?.name).toBe('my-project');
+        expect(result.options?.packageManager).toBe('yarn');
+        expect(result.options?.framework).toBe('sdk');
+        expect(result.options?.template).toBe('stateful');
+    });
+    it('parses oauth flag correctly for sdk+stateful', async () => {
+        process.argv = [
+            'node',
+            'create-mcp-server',
+            '--name=my-auth-server',
+            '--framework=sdk',
+            '--template=stateful',
+            '--oauth',
+        ];
+        const { parseArguments } = await import('./cli.js');
+        const result = parseArguments();
+        expect(result.options?.oauth).toBe(true);
+        expect(result.options?.framework).toBe('sdk');
+        expect(result.options?.template).toBe('stateful');
+    });
+    it('exits with error when --name is missing in CLI mode', async () => {
+        process.argv = ['node', 'create-mcp-server', '--package-manager=npm'];
+        let exitCode;
+        process.exit = vi.fn((code) => {
+            exitCode = code;
+            throw new Error('process.exit called');
+        });
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const { parseArguments } = await import('./cli.js');
+        expect(() => parseArguments()).toThrow('process.exit called');
+        expect(exitCode).toBe(1);
+        expect(consoleError).toHaveBeenCalledWith(expect.stringContaining('--name is required when using CLI arguments'));
+        consoleError.mockRestore();
+    });
+    it('exits with error when --oauth used without sdk+stateful', async () => {
+        process.argv = ['node', 'create-mcp-server', '--name=test', '--oauth', '--framework=fastmcp'];
+        let exitCode;
+        process.exit = vi.fn((code) => {
+            exitCode = code;
+            throw new Error('process.exit called');
+        });
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const { parseArguments } = await import('./cli.js');
+        expect(() => parseArguments()).toThrow('process.exit called');
+        expect(exitCode).toBe(1);
+        expect(consoleError).toHaveBeenCalledWith(expect.stringContaining('--oauth is only valid with --framework=sdk and --template=stateful'));
+        consoleError.mockRestore();
+    });
+    it('exits with error for invalid project name', async () => {
+        process.argv = ['node', 'create-mcp-server', '--name=invalid name!'];
+        let exitCode;
+        process.exit = vi.fn((code) => {
+            exitCode = code;
+            throw new Error('process.exit called');
+        });
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const { parseArguments } = await import('./cli.js');
+        expect(() => parseArguments()).toThrow('process.exit called');
+        expect(exitCode).toBe(1);
+        consoleError.mockRestore();
+    });
+    it('treats --help flag as interactive mode (does not require --name)', async () => {
+        // When --help is the only flag, commander handles it and exits
+        // We just verify that --help alone doesn't trigger CLI mode validation
+        process.argv = ['node', 'create-mcp-server'];
+        const { parseArguments } = await import('./cli.js');
+        const result = parseArguments();
+        // No args = interactive mode
+        expect(result.mode).toBe('interactive');
+    });
+});

package/dist/index.js

@@ -1,189 +1,30 @@
 #!/usr/bin/env node
-import prompts from 'prompts';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-import { getPackageJsonTemplate } from './templates/common/package.json.js';
-import { getTsconfigTemplate } from './templates/common/tsconfig.json.js';
-import { getGitignoreTemplate } from './templates/common/gitignore.js';
-import { getEnvExampleTemplate } from './templates/common/env.example.js';
-import { getServerTemplate as getSdkStatelessServerTemplate, getIndexTemplate as getSdkStatelessIndexTemplate, getReadmeTemplate as getSdkStatelessReadmeTemplate, } from './templates/sdk/stateless/index.js';
-import { getServerTemplate as getSdkStatefulServerTemplate, getIndexTemplate as getSdkStatefulIndexTemplate, getReadmeTemplate as getSdkStatefulReadmeTemplate, getAuthTemplate as getSdkAuthTemplate, } from './templates/sdk/stateful/index.js';
-import { getServerTemplate as getFastMCPServerTemplate, getIndexTemplate as getFastMCPIndexTemplate, getReadmeTemplate as getFastMCPReadmeTemplate, } from './templates/fastmcp/index.js';
-import { getDockerfileTemplate, getDockerignoreTemplate } from './templates/deployment/index.js';
-const sdkTemplateFunctions = {
-    stateless: {
-        getServerTemplate: getSdkStatelessServerTemplate,
-        getIndexTemplate: getSdkStatelessIndexTemplate,
-        getReadmeTemplate: getSdkStatelessReadmeTemplate,
-    },
-    stateful: {
-        getServerTemplate: getSdkStatefulServerTemplate,
-        getIndexTemplate: getSdkStatefulIndexTemplate,
-        getReadmeTemplate: getSdkStatefulReadmeTemplate,
-        getAuthTemplate: getSdkAuthTemplate,
-    },
-};
-const fastmcpTemplateFunctions = {
-    getServerTemplate: getFastMCPServerTemplate,
-    getIndexTemplate: getFastMCPIndexTemplate,
-    getReadmeTemplate: getFastMCPReadmeTemplate,
-};
-const packageManagerCommands = {
-    npm: { install: 'npm install', dev: 'npm run dev' },
-    pnpm: { install: 'pnpm install', dev: 'pnpm dev' },
-    yarn: { install: 'yarn', dev: 'yarn dev' },
-};
+import { parseArguments } from './cli.js';
+import { runInteractiveMode } from './interactive.js';
+import { generateProject } from './project-generator.js';
 async function main() {
-    console.log('\n🚀 Create MCP Server\n');
-    const onCancel = () => {
-        console.log('\n❌ Operation cancelled\n');
-        process.exit(0);
-    };
-    const projectNameResponse = await prompts({
-        type: 'text',
-        name: 'projectName',
-        message: 'Project name:',
-        initial: 'my-mcp-server',
-        validate: (value) => {
-            if (!value)
-                return 'Project name is required';
-            if (!/^[a-z0-9-_]+$/i.test(value)) {
-                return 'Project name can only contain letters, numbers, hyphens, and underscores';
-            }
-            return true;
-        },
-    }, { onCancel });
-    const { projectName } = projectNameResponse;
-    if (!projectName) {
-        console.log('\n❌ Project name is required\n');
-        process.exit(1);
+    const { mode, options } = parseArguments();
+    if (mode === 'interactive') {
+        await runInteractiveMode();
     }
-    const packageManagerResponse = await prompts({
-        type: 'select',
-        name: 'packageManager',
-        message: 'Package manager:',
-        choices: [
-            { title: 'npm', value: 'npm' },
-            { title: 'pnpm', value: 'pnpm' },
-            { title: 'yarn', value: 'yarn' },
-        ],
-        initial: 0,
-    }, { onCancel });
-    const packageManager = packageManagerResponse.packageManager || 'npm';
-    // Framework selection
-    const frameworkResponse = await prompts({
-        type: 'select',
-        name: 'framework',
-        message: 'Framework:',
-        choices: [
-            {
-                title: 'Official MCP SDK',
-                value: 'sdk',
-                description: 'Full control with Express.js',
-            },
-            {
-                title: 'FastMCP',
-                value: 'fastmcp',
-                description: 'Simpler API, less boilerplate',
-            },
-        ],
-        initial: 0,
-    }, { onCancel });
-    const framework = frameworkResponse.framework || 'sdk';
-    // Server mode selection
-    const templateTypeResponse = await prompts({
-        type: 'select',
-        name: 'templateType',
-        message: 'Server mode:',
-        choices: [
-            { title: 'Stateless', value: 'stateless', description: 'Simple HTTP server' },
-            {
-                title: 'Stateful',
-                value: 'stateful',
-                description: 'Session-based server with SSE support',
-            },
-        ],
-        initial: 0,
-    }, { onCancel });
-    const templateType = templateTypeResponse.templateType || 'stateless';
-    // OAuth prompt - only for SDK stateful template
-    let withOAuth = false;
-    if (framework === 'sdk' && templateType === 'stateful') {
-        const oauthResponse = await prompts({
-            type: 'confirm',
-            name: 'withOAuth',
-            message: 'Enable OAuth authentication?',
-            initial: false,
-        }, { onCancel });
-        withOAuth = oauthResponse.withOAuth ?? false;
+    else {
+        // CLI mode - options is guaranteed to be defined
+        await generateProject({
+            projectName: options.name,
+            packageManager: options.packageManager,
+            framework: options.framework,
+            templateType: options.template,
+            withOAuth: options.oauth,
+            withGitInit: options.git,
+        });
     }
-    // Git init prompt
-    const gitInitResponse = await prompts({
-        type: 'confirm',
-        name: 'withGitInit',
-        message: 'Initialize git repository?',
-        initial: true,
-    }, { onCancel });
-    const withGitInit = gitInitResponse.withGitInit ?? false;
-    const templateOptions = {
-        withOAuth,
-        packageManager,
-        framework,
-        stateless: templateType === 'stateless',
-    };
-    const projectPath = join(process.cwd(), projectName);
-    const srcPath = join(projectPath, 'src');
-    try {
-        // Create directories
-        await mkdir(srcPath, { recursive: true });
-        // Build list of files to write
-        const filesToWrite = [];
-        if (framework === 'fastmcp') {
-            // FastMCP templates
-            filesToWrite.push(writeFile(join(srcPath, 'server.ts'), fastmcpTemplateFunctions.getServerTemplate(projectName)), writeFile(join(srcPath, 'index.ts'), fastmcpTemplateFunctions.getIndexTemplate(templateOptions)), writeFile(join(projectPath, 'README.md'), fastmcpTemplateFunctions.getReadmeTemplate(projectName, templateOptions)));
-        }
-        else {
-            // SDK templates
-            const templates = sdkTemplateFunctions[templateType];
-            filesToWrite.push(writeFile(join(srcPath, 'server.ts'), templates.getServerTemplate(projectName)), writeFile(join(srcPath, 'index.ts'), templates.getIndexTemplate(templateOptions)), writeFile(join(projectPath, 'README.md'), templates.getReadmeTemplate(projectName, templateOptions)));
-            // Conditionally add auth.ts for OAuth-enabled stateful template
-            if (withOAuth && templates.getAuthTemplate) {
-                filesToWrite.push(writeFile(join(srcPath, 'auth.ts'), templates.getAuthTemplate()));
-            }
-        }
-        // Common files for all templates
-        filesToWrite.push(writeFile(join(projectPath, 'package.json'), getPackageJsonTemplate(projectName, templateOptions)), writeFile(join(projectPath, 'tsconfig.json'), getTsconfigTemplate()), writeFile(join(projectPath, '.gitignore'), getGitignoreTemplate()), writeFile(join(projectPath, '.env.example'), getEnvExampleTemplate(templateOptions)));
-        // Deployment files for all templates
-        filesToWrite.push(writeFile(join(projectPath, 'Dockerfile'), getDockerfileTemplate(templateOptions)), writeFile(join(projectPath, '.dockerignore'), getDockerignoreTemplate()));
-        // Write all template files
-        await Promise.all(filesToWrite);
-        // Initialize git repository if requested
-        if (withGitInit) {
-            try {
-                execSync('git init', { cwd: projectPath, stdio: 'ignore' });
-            }
-            catch {
-                console.log('\n⚠️  Could not initialize git repository (is git installed?)');
-            }
-        }
-        const commands = packageManagerCommands[packageManager];
-        const frameworkName = framework === 'fastmcp' ? 'FastMCP' : 'MCP SDK';
-        console.log(`\n✅ Created ${projectName} with ${frameworkName} at ${projectPath}`);
-        console.log(`\nNext steps:`);
-        console.log(`  cd ${projectName}`);
-        console.log(`  ${commands.install}`);
-        console.log(`  ${commands.dev}`);
-        console.log(`\n`);
+}
+main().catch((error) => {
+    if (error instanceof Error) {
+        console.error(`\nError: ${error.message}\n`);
     }
-    catch (error) {
-        if (error instanceof Error) {
-            console.error(`\n❌ Error: ${error.message}\n`);
-        }
-        else {
-            console.error('\n❌ An unexpected error occurred\n');
-        }
-        process.exit(1);
+    else {
+        console.error('\nAn unexpected error occurred\n');
     }
-}
-main();
+    process.exit(1);
+});

package/dist/interactive.d.ts

@@ -0,0 +1 @@
+export declare function runInteractiveMode(): Promise<void>;

package/dist/interactive.js

@@ -0,0 +1,103 @@
+import prompts from 'prompts';
+import { generateProject } from './project-generator.js';
+export async function runInteractiveMode() {
+    console.log('\nCreate MCP Server\n');
+    const onCancel = () => {
+        console.log('\nOperation cancelled\n');
+        process.exit(0);
+    };
+    const projectNameResponse = await prompts({
+        type: 'text',
+        name: 'projectName',
+        message: 'Project name:',
+        initial: 'my-mcp-server',
+        validate: (value) => {
+            if (!value)
+                return 'Project name is required';
+            if (!/^[a-z0-9-_]+$/i.test(value)) {
+                return 'Project name can only contain letters, numbers, hyphens, and underscores';
+            }
+            return true;
+        },
+    }, { onCancel });
+    const { projectName } = projectNameResponse;
+    if (!projectName) {
+        console.log('\nProject name is required\n');
+        process.exit(1);
+    }
+    const packageManagerResponse = await prompts({
+        type: 'select',
+        name: 'packageManager',
+        message: 'Package manager:',
+        choices: [
+            { title: 'npm', value: 'npm' },
+            { title: 'pnpm', value: 'pnpm' },
+            { title: 'yarn', value: 'yarn' },
+        ],
+        initial: 0,
+    }, { onCancel });
+    const packageManager = packageManagerResponse.packageManager || 'npm';
+    // Framework selection
+    const frameworkResponse = await prompts({
+        type: 'select',
+        name: 'framework',
+        message: 'Framework:',
+        choices: [
+            {
+                title: 'Official MCP SDK',
+                value: 'sdk',
+                description: 'Full control with Express.js',
+            },
+            {
+                title: 'FastMCP',
+                value: 'fastmcp',
+                description: 'Simpler API, less boilerplate',
+            },
+        ],
+        initial: 0,
+    }, { onCancel });
+    const framework = frameworkResponse.framework || 'sdk';
+    // Server mode selection
+    const templateTypeResponse = await prompts({
+        type: 'select',
+        name: 'templateType',
+        message: 'Server mode:',
+        choices: [
+            { title: 'Stateless', value: 'stateless', description: 'Simple HTTP server' },
+            {
+                title: 'Stateful',
+                value: 'stateful',
+                description: 'Session-based server with SSE support',
+            },
+        ],
+        initial: 0,
+    }, { onCancel });
+    const templateType = templateTypeResponse.templateType || 'stateless';
+    // OAuth prompt - only for SDK stateful template
+    let withOAuth = false;
+    if (framework === 'sdk' && templateType === 'stateful') {
+        const oauthResponse = await prompts({
+            type: 'confirm',
+            name: 'withOAuth',
+            message: 'Enable OAuth authentication?',
+            initial: false,
+        }, { onCancel });
+        withOAuth = oauthResponse.withOAuth ?? false;
+    }
+    // Git init prompt
+    const gitInitResponse = await prompts({
+        type: 'confirm',
+        name: 'withGitInit',
+        message: 'Initialize git repository?',
+        initial: true,
+    }, { onCancel });
+    const withGitInit = gitInitResponse.withGitInit ?? false;
+    await generateProject({
+        projectName,
+        packageManager,
+        framework,
+        templateType,
+        withOAuth,
+        withGitInit,
+    });
+}

package/dist/project-generator.d.ts

@@ -0,0 +1,15 @@
+import type { Framework, PackageManager } from './templates/common/types.js';
+import type { TemplateType } from './cli.js';
+export declare const packageManagerCommands: Record<PackageManager, {
+    install: string;
+    dev: string;
+}>;
+export interface ProjectConfig {
+    projectName: string;
+    packageManager: PackageManager;
+    framework: Framework;
+    templateType: TemplateType;
+    withOAuth: boolean;
+    withGitInit: boolean;
+}
+export declare function generateProject(config: ProjectConfig): Promise<void>;

package/dist/project-generator.js

@@ -0,0 +1,85 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { getPackageJsonTemplate } from './templates/common/package.json.js';
+import { getTsconfigTemplate } from './templates/common/tsconfig.json.js';
+import { getGitignoreTemplate } from './templates/common/gitignore.js';
+import { getEnvExampleTemplate } from './templates/common/env.example.js';
+import { getServerTemplate as getSdkStatelessServerTemplate, getIndexTemplate as getSdkStatelessIndexTemplate, getReadmeTemplate as getSdkStatelessReadmeTemplate, } from './templates/sdk/stateless/index.js';
+import { getServerTemplate as getSdkStatefulServerTemplate, getIndexTemplate as getSdkStatefulIndexTemplate, getReadmeTemplate as getSdkStatefulReadmeTemplate, getAuthTemplate as getSdkAuthTemplate, } from './templates/sdk/stateful/index.js';
+import { getServerTemplate as getFastMCPServerTemplate, getIndexTemplate as getFastMCPIndexTemplate, getReadmeTemplate as getFastMCPReadmeTemplate, } from './templates/fastmcp/index.js';
+import { getDockerfileTemplate, getDockerignoreTemplate } from './templates/deployment/index.js';
+const sdkTemplateFunctions = {
+    stateless: {
+        getServerTemplate: getSdkStatelessServerTemplate,
+        getIndexTemplate: getSdkStatelessIndexTemplate,
+        getReadmeTemplate: getSdkStatelessReadmeTemplate,
+    },
+    stateful: {
+        getServerTemplate: getSdkStatefulServerTemplate,
+        getIndexTemplate: getSdkStatefulIndexTemplate,
+        getReadmeTemplate: getSdkStatefulReadmeTemplate,
+        getAuthTemplate: getSdkAuthTemplate,
+    },
+};
+const fastmcpTemplateFunctions = {
+    getServerTemplate: getFastMCPServerTemplate,
+    getIndexTemplate: getFastMCPIndexTemplate,
+    getReadmeTemplate: getFastMCPReadmeTemplate,
+};
+export const packageManagerCommands = {
+    npm: { install: 'npm install', dev: 'npm run dev' },
+    pnpm: { install: 'pnpm install', dev: 'pnpm dev' },
+    yarn: { install: 'yarn', dev: 'yarn dev' },
+};
+export async function generateProject(config) {
+    const { projectName, packageManager, framework, templateType, withOAuth, withGitInit } = config;
+    const templateOptions = {
+        withOAuth,
+        packageManager,
+        framework,
+        stateless: templateType === 'stateless',
+    };
+    const projectPath = join(process.cwd(), projectName);
+    const srcPath = join(projectPath, 'src');
+    // Create directories
+    await mkdir(srcPath, { recursive: true });
+    // Build list of files to write
+    const filesToWrite = [];
+    if (framework === 'fastmcp') {
+        // FastMCP templates
+        filesToWrite.push(writeFile(join(srcPath, 'server.ts'), fastmcpTemplateFunctions.getServerTemplate(projectName)), writeFile(join(srcPath, 'index.ts'), fastmcpTemplateFunctions.getIndexTemplate(templateOptions)), writeFile(join(projectPath, 'README.md'), fastmcpTemplateFunctions.getReadmeTemplate(projectName, templateOptions)));
+    }
+    else {
+        // SDK templates
+        const templates = sdkTemplateFunctions[templateType];
+        filesToWrite.push(writeFile(join(srcPath, 'server.ts'), templates.getServerTemplate(projectName)), writeFile(join(srcPath, 'index.ts'), templates.getIndexTemplate(templateOptions)), writeFile(join(projectPath, 'README.md'), templates.getReadmeTemplate(projectName, templateOptions)));
+        // Conditionally add auth.ts for OAuth-enabled stateful template
+        if (withOAuth && templates.getAuthTemplate) {
+            filesToWrite.push(writeFile(join(srcPath, 'auth.ts'), templates.getAuthTemplate()));
+        }
+    }
+    // Common files for all templates
+    filesToWrite.push(writeFile(join(projectPath, 'package.json'), getPackageJsonTemplate(projectName, templateOptions)), writeFile(join(projectPath, 'tsconfig.json'), getTsconfigTemplate()), writeFile(join(projectPath, '.gitignore'), getGitignoreTemplate()), writeFile(join(projectPath, '.env.example'), getEnvExampleTemplate(templateOptions)));
+    // Deployment files for all templates
+    filesToWrite.push(writeFile(join(projectPath, 'Dockerfile'), getDockerfileTemplate(templateOptions)), writeFile(join(projectPath, '.dockerignore'), getDockerignoreTemplate()));
+    // Write all template files
+    await Promise.all(filesToWrite);
+    // Initialize git repository if requested
+    if (withGitInit) {
+        try {
+            execSync('git init', { cwd: projectPath, stdio: 'ignore' });
+        }
+        catch {
+            console.log('\n  Could not initialize git repository (is git installed?)');
+        }
+    }
+    const commands = packageManagerCommands[packageManager];
+    const frameworkName = framework === 'fastmcp' ? 'FastMCP' : 'MCP SDK';
+    console.log(`\nCreated ${projectName} with ${frameworkName} at ${projectPath}`);
+    console.log(`\nNext steps:`);
+    console.log(`  cd ${projectName}`);
+    console.log(`  ${commands.install}`);
+    console.log(`  ${commands.dev}`);
+    console.log(`\n`);
+}

package/dist/templates/fastmcp/readme.js

@@ -2,9 +2,27 @@ export function getReadmeTemplate(projectName, options) {
     const packageManager = options?.packageManager ?? 'npm';
     const stateless = options?.stateless ?? false;
     const commands = {
-        npm: { install: 'npm install', dev: 'npm run dev', build: 'npm run build', start: 'npm start' },
-        pnpm: { install: 'pnpm install', dev: 'pnpm dev', build: 'pnpm build', start: 'pnpm start' },
-        yarn: { install: 'yarn', dev: 'yarn dev', build: 'yarn build', start: 'yarn start' },
+        npm: {
+            install: 'npm install',
+            dev: 'npm run dev',
+            build: 'npm run build',
+            start: 'npm start',
+            inspect: 'npm run inspect',
+        },
+        pnpm: {
+            install: 'pnpm install',
+            dev: 'pnpm dev',
+            build: 'pnpm build',
+            start: 'pnpm start',
+            inspect: 'pnpm inspect',
+        },
+        yarn: {
+            install: 'yarn',
+            dev: 'yarn dev',
+            build: 'yarn build',
+            start: 'yarn start',
+            inspect: 'yarn inspect',
+        },
     };
     const cmd = commands[packageManager];
     const modeDescription = stateless
@@ -34,6 +52,22 @@ ${cmd.start}
 
 The server will start on port 3000 by default. You can change this by setting the \`PORT\` environment variable.
 
+## Testing with MCP Inspector
+
+This project includes [MCP Inspector](https://github.com/modelcontextprotocol/inspector) as a dev dependency for testing and debugging.
+
+First, start the server in one terminal:
+
+\`\`\`bash
+${cmd.dev}
+\`\`\`
+
+Then, in another terminal, launch the inspector:
+
+\`\`\`bash
+${cmd.inspect}
+\`\`\`
+
 ## API Endpoints
 
 - **POST /mcp** - Main MCP endpoint for JSON-RPC messages

package/dist/templates/sdk/stateful/readme.js

@@ -2,9 +2,27 @@ export function getReadmeTemplate(projectName, options) {
     const withOAuth = options?.withOAuth ?? false;
     const packageManager = options?.packageManager ?? 'npm';
     const commands = {
-        npm: { install: 'npm install', dev: 'npm run dev', build: 'npm run build', start: 'npm start' },
-        pnpm: { install: 'pnpm install', dev: 'pnpm dev', build: 'pnpm build', start: 'pnpm start' },
-        yarn: { install: 'yarn', dev: 'yarn dev', build: 'yarn build', start: 'yarn start' },
+        npm: {
+            install: 'npm install',
+            dev: 'npm run dev',
+            build: 'npm run build',
+            start: 'npm start',
+            inspect: 'npm run inspect',
+        },
+        pnpm: {
+            install: 'pnpm install',
+            dev: 'pnpm dev',
+            build: 'pnpm build',
+            start: 'pnpm start',
+            inspect: 'pnpm inspect',
+        },
+        yarn: {
+            install: 'yarn',
+            dev: 'yarn dev',
+            build: 'yarn build',
+            start: 'yarn start',
+            inspect: 'yarn inspect',
+        },
     }[packageManager];
     const description = withOAuth
         ? 'A stateful streamable HTTP MCP (Model Context Protocol) server with session management and OAuth authentication.'
@@ -116,6 +134,22 @@ ${commands.start}
 \`\`\`
 
 The server will start on port 3000 by default. You can change this by setting the \`PORT\` environment variable.
+
+## Testing with MCP Inspector
+
+This project includes [MCP Inspector](https://github.com/modelcontextprotocol/inspector) as a dev dependency for testing and debugging.
+
+First, start the server in one terminal:
+
+\`\`\`bash
+${commands.dev}
+\`\`\`
+
+Then, in another terminal, launch the inspector:
+
+\`\`\`bash
+${commands.inspect}
+\`\`\`
 ${oauthSection}
 ## API Endpoints
 

package/dist/templates/sdk/stateless/readme.js

@@ -1,9 +1,27 @@
 export function getReadmeTemplate(projectName, options) {
     const packageManager = options?.packageManager ?? 'npm';
     const commands = {
-        npm: { install: 'npm install', dev: 'npm run dev', build: 'npm run build', start: 'npm start' },
-        pnpm: { install: 'pnpm install', dev: 'pnpm dev', build: 'pnpm build', start: 'pnpm start' },
-        yarn: { install: 'yarn', dev: 'yarn dev', build: 'yarn build', start: 'yarn start' },
+        npm: {
+            install: 'npm install',
+            dev: 'npm run dev',
+            build: 'npm run build',
+            start: 'npm start',
+            inspect: 'npm run inspect',
+        },
+        pnpm: {
+            install: 'pnpm install',
+            dev: 'pnpm dev',
+            build: 'pnpm build',
+            start: 'pnpm start',
+            inspect: 'pnpm inspect',
+        },
+        yarn: {
+            install: 'yarn',
+            dev: 'yarn dev',
+            build: 'yarn build',
+            start: 'yarn start',
+            inspect: 'yarn inspect',
+        },
     }[packageManager];
     return `# ${projectName}
 
@@ -29,6 +47,22 @@ ${commands.start}
 
 The server will start on port 3000 by default. You can change this by setting the \`PORT\` environment variable.
 
+## Testing with MCP Inspector
+
+This project includes [MCP Inspector](https://github.com/modelcontextprotocol/inspector) as a dev dependency for testing and debugging.
+
+First, start the server in one terminal:
+
+\`\`\`bash
+${commands.dev}
+\`\`\`
+
+Then, in another terminal, launch the inspector:
+
+\`\`\`bash
+${commands.inspect}
+\`\`\`
+
 ## API Endpoints
 
 - **POST /mcp** - Main MCP endpoint for JSON-RPC messages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentailor/create-mcp-server",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Create a new MCP (Model Context Protocol) server project",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "commander": "^14.0.3",
     "prompts": "^2.4.2"
   },
   "devDependencies": {