@agentailor/create-mcp-server 0.2.0 → 0.3.0

package/README.md

@@ -10,24 +10,54 @@ npx @agentailor/create-mcp-server
 
 ## Features
 
-- **Two templates** — stateless or stateful with session management
-- **Optional OAuth** — OIDC-compliant authentication ([setup guide](docs/oauth-setup.md))
+- **Two frameworks** — Official MCP SDK or FastMCP
+- **Two server modes** — stateless or stateful with session management
+- **Optional OAuth** — OIDC-compliant authentication (SDK only) ([setup guide](docs/oauth-setup.md))
 - **Package manager choice** — npm, pnpm, or yarn
-- **TypeScript + Express.js** — ready to customize
+- **TypeScript ready** — ready to customize
 - **MCP Inspector** — built-in debugging with `npm run inspect`
 
-## Templates
+## Frameworks
+
+| Framework | Description |
+|-----------|-------------|
+| **Official MCP SDK** (default) | Full control with Express.js, supports OAuth |
+| **FastMCP** | Simpler API with less boilerplate |
+
+### FastMCP
+
+[FastMCP](https://github.com/punkpeye/fastmcp) is a TypeScript framework built on top of the official MCP SDK that provides a simpler, more intuitive API for building MCP servers.
+
+```typescript
+import { FastMCP } from "fastmcp";
+import { z } from "zod";
+
+const server = new FastMCP({ name: "My Server", version: "1.0.0" });
+
+server.addTool({
+  name: "add",
+  description: "Add two numbers",
+  parameters: z.object({ a: z.number(), b: z.number() }),
+  execute: async ({ a, b }) => String(a + b),
+});
+
+server.start({ transportType: "httpStream", httpStream: { port: 3000 } });
+```
+
+Learn more: [FastMCP Documentation](https://github.com/punkpeye/fastmcp)
+
+## Server Modes
 
 | Feature | Stateless (default) | Stateful |
 |---------|---------------------|----------|
 | Session management | — | ✓ |
 | SSE support | — | ✓ |
-| OAuth option | — | ✓ |
+| OAuth option (SDK only) | — | ✓ |
 | Endpoints | POST /mcp | POST, GET, DELETE /mcp |
 
 **Stateless**: Simple HTTP server — each request creates a new transport instance.
 
-**Stateful**: Session-based server with transport reuse, Server-Sent Events for real-time updates, and optional OAuth authentication.
+**Stateful**: Session-based server with transport reuse, Server-Sent Events for real-time updates, and optional OAuth authentication (SDK only).
 
 ## Generated Project
 

package/dist/index.js

@@ -7,21 +7,27 @@ 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 getStatelessServerTemplate, getIndexTemplate as getStatelessIndexTemplate, getReadmeTemplate as getStatelessReadmeTemplate, } from './templates/streamable-http/index.js';
-import { getServerTemplate as getStatefulServerTemplate, getIndexTemplate as getStatefulIndexTemplate, getReadmeTemplate as getStatefulReadmeTemplate, getAuthTemplate as getStatefulAuthTemplate, } from './templates/stateful-streamable-http/index.js';
-const templateFunctions = {
+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';
+const sdkTemplateFunctions = {
     stateless: {
-        getServerTemplate: getStatelessServerTemplate,
-        getIndexTemplate: getStatelessIndexTemplate,
-        getReadmeTemplate: getStatelessReadmeTemplate,
+        getServerTemplate: getSdkStatelessServerTemplate,
+        getIndexTemplate: getSdkStatelessIndexTemplate,
+        getReadmeTemplate: getSdkStatelessReadmeTemplate,
     },
     stateful: {
-        getServerTemplate: getStatefulServerTemplate,
-        getIndexTemplate: getStatefulIndexTemplate,
-        getReadmeTemplate: getStatefulReadmeTemplate,
-        getAuthTemplate: getStatefulAuthTemplate,
+        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' },
@@ -64,12 +70,33 @@ async function main() {
         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: 'Template type:',
+        message: 'Server mode:',
         choices: [
-            { title: 'Stateless', value: 'stateless', description: 'Simple stateless HTTP server' },
+            { title: 'Stateless', value: 'stateless', description: 'Simple HTTP server' },
             {
                 title: 'Stateful',
                 value: 'stateful',
@@ -79,9 +106,9 @@ async function main() {
         initial: 0,
     }, { onCancel });
     const templateType = templateTypeResponse.templateType || 'stateless';
-    // OAuth prompt - only for stateful template
+    // OAuth prompt - only for SDK stateful template
     let withOAuth = false;
-    if (templateType === 'stateful') {
+    if (framework === 'sdk' && templateType === 'stateful') {
         const oauthResponse = await prompts({
             type: 'confirm',
             name: 'withOAuth',
@@ -98,27 +125,34 @@ async function main() {
         initial: true,
     }, { onCancel });
     const withGitInit = gitInitResponse.withGitInit ?? false;
-    const templateOptions = { withOAuth };
-    const templates = templateFunctions[templateType];
+    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 = [
-            writeFile(join(srcPath, 'server.ts'), templates.getServerTemplate(projectName)),
-            writeFile(join(srcPath, 'index.ts'), templates.getIndexTemplate(templateOptions)),
-            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)),
-            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()));
+        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)));
         // Write all template files
         await Promise.all(filesToWrite);
         // Initialize git repository if requested
@@ -131,7 +165,8 @@ async function main() {
             }
         }
         const commands = packageManagerCommands[packageManager];
-        console.log(`\n✅ Created ${projectName} at ${projectPath}`);
+        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}`);

package/dist/templates/common/env.example.d.ts

@@ -1,4 +1,2 @@
-export interface TemplateOptions {
-    withOAuth?: boolean;
-}
-export declare function getEnvExampleTemplate(options?: TemplateOptions): string;
+import type { CommonTemplateOptions } from './types.js';
+export declare function getEnvExampleTemplate(options?: CommonTemplateOptions): string;

package/dist/templates/common/package.json.d.ts

@@ -1,4 +1,2 @@
-export interface TemplateOptions {
-    withOAuth?: boolean;
-}
-export declare function getPackageJsonTemplate(projectName: string, options?: TemplateOptions): string;
+import type { CommonTemplateOptions } from './types.js';
+export declare function getPackageJsonTemplate(projectName: string, options?: CommonTemplateOptions): string;

package/dist/templates/common/package.json.js

@@ -1,13 +1,39 @@
 export function getPackageJsonTemplate(projectName, options) {
     const withOAuth = options?.withOAuth ?? false;
-    const dependencies = {
-        '@modelcontextprotocol/sdk': '^1.25.1',
-        express: '^5.2.1',
-        zod: '^4.3.5',
+    const framework = options?.framework ?? 'sdk';
+    let dependencies;
+    let devDependencies;
+    const commonDevDependencies = {
+        typescript: '^5.9.3',
+        '@modelcontextprotocol/inspector': '^0.18.0',
     };
-    if (withOAuth) {
-        dependencies['dotenv'] = '^17.2.3';
-        dependencies['jose'] = '^6.1.3';
+    const zodDependency = { zod: '^4.3.5' };
+    if (framework === 'fastmcp') {
+        // FastMCP dependencies - simpler setup
+        dependencies = {
+            fastmcp: '^3.26.8',
+            ...zodDependency,
+        };
+        devDependencies = {
+            ...commonDevDependencies,
+        };
+    }
+    else {
+        // Official SDK dependencies
+        dependencies = {
+            '@modelcontextprotocol/sdk': '^1.25.1',
+            express: '^5.2.1',
+            ...zodDependency,
+        };
+        if (withOAuth) {
+            dependencies['dotenv'] = '^17.2.3';
+            dependencies['jose'] = '^6.1.3';
+        }
+        devDependencies = {
+            '@types/express': '^5.0.6',
+            '@types/node': '^25.0.3',
+            ...commonDevDependencies,
+        };
     }
     const packageJson = {
         name: projectName,
@@ -21,12 +47,7 @@ export function getPackageJsonTemplate(projectName, options) {
             inspect: 'mcp-inspector http://localhost:3000/mcp',
         },
         dependencies,
-        devDependencies: {
-            '@types/express': '^5.0.6',
-            '@types/node': '^25.0.3',
-            typescript: '^5.9.3',
-            '@modelcontextprotocol/inspector': '^0.18.0',
-        },
+        devDependencies,
         engines: {
             node: '>=20',
         },

package/dist/templates/common/templates.test.js

@@ -11,10 +11,34 @@ describe('common templates', () => {
             const pkg = JSON.parse(template);
             expect(pkg.name).toBe(projectName);
         });
-        it('should use correct SDK package', () => {
+        it('should use SDK package by default', () => {
             const template = getPackageJsonTemplate(projectName);
             const pkg = JSON.parse(template);
             expect(pkg.dependencies['@modelcontextprotocol/sdk']).toBeDefined();
+            expect(pkg.dependencies['express']).toBeDefined();
+        });
+        it('should use FastMCP package when framework is fastmcp', () => {
+            const template = getPackageJsonTemplate(projectName, { framework: 'fastmcp' });
+            const pkg = JSON.parse(template);
+            expect(pkg.dependencies['fastmcp']).toBeDefined();
+            expect(pkg.dependencies['@modelcontextprotocol/sdk']).toBeUndefined();
+            expect(pkg.dependencies['express']).toBeUndefined();
+        });
+        it('should include OAuth dependencies when withOAuth is true for SDK', () => {
+            const template = getPackageJsonTemplate(projectName, { framework: 'sdk', withOAuth: true });
+            const pkg = JSON.parse(template);
+            expect(pkg.dependencies['dotenv']).toBeDefined();
+            expect(pkg.dependencies['jose']).toBeDefined();
+        });
+        it('should not include @types/express for FastMCP', () => {
+            const template = getPackageJsonTemplate(projectName, { framework: 'fastmcp' });
+            const pkg = JSON.parse(template);
+            expect(pkg.devDependencies['@types/express']).toBeUndefined();
+        });
+        it('should include @types/express for SDK', () => {
+            const template = getPackageJsonTemplate(projectName, { framework: 'sdk' });
+            const pkg = JSON.parse(template);
+            expect(pkg.devDependencies['@types/express']).toBeDefined();
         });
         it('should include required scripts', () => {
             const template = getPackageJsonTemplate(projectName);

package/dist/templates/common/types.d.ts

@@ -0,0 +1,29 @@
+export type PackageManager = 'npm' | 'pnpm' | 'yarn';
+export type Framework = 'sdk' | 'fastmcp';
+/**
+ * Base template options shared across all templates
+ */
+export interface BaseTemplateOptions {
+    packageManager?: PackageManager;
+}
+/**
+ * Template options for SDK templates (stateless and stateful)
+ */
+export interface SdkTemplateOptions extends BaseTemplateOptions {
+    withOAuth?: boolean;
+}
+/**
+ * Template options for FastMCP templates
+ */
+export interface FastMCPTemplateOptions extends BaseTemplateOptions {
+    stateless?: boolean;
+}
+/**
+ * Template options for common templates (package.json, env.example)
+ * Includes all options since these are used across all frameworks
+ */
+export interface CommonTemplateOptions extends BaseTemplateOptions {
+    withOAuth?: boolean;
+    framework?: Framework;
+    stateless?: boolean;
+}

package/dist/templates/fastmcp/index.d.ts

@@ -0,0 +1,5 @@
+export type { FastMCPTemplateOptions as TemplateOptions } from '../common/types.js';
+import type { FastMCPTemplateOptions } from '../common/types.js';
+export declare function getIndexTemplate(options?: FastMCPTemplateOptions): string;
+export { getServerTemplate } from './server.js';
+export { getReadmeTemplate } from './readme.js';

package/dist/templates/fastmcp/index.js

@@ -0,0 +1,19 @@
+export function getIndexTemplate(options) {
+    const stateless = options?.stateless ?? false;
+    const statelessConfig = stateless ? '\n    stateless: true,' : '';
+    return `import { server } from './server.js';
+
+const PORT = Number(process.env.PORT) || 3000;
+
+server.start({
+  transportType: 'httpStream',
+  httpStream: {
+    port: PORT,${statelessConfig}
+  },
+});
+
+console.log(\`MCP Server listening on port \${PORT}\`);
+`;
+}
+export { getServerTemplate } from './server.js';
+export { getReadmeTemplate } from './readme.js';

package/dist/templates/fastmcp/readme.js

@@ -0,0 +1,82 @@
+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' },
+    };
+    const cmd = commands[packageManager];
+    const modeDescription = stateless
+        ? 'A stateless streamable HTTP MCP server built with FastMCP.'
+        : 'A stateful streamable HTTP MCP server built with FastMCP.';
+    return `# ${projectName}
+
+${modeDescription}
+
+## About
+
+This project was created with [@agentailor/create-mcp-server](https://www.npmjs.com/package/@agentailor/create-mcp-server) using [FastMCP](https://github.com/punkpeye/fastmcp).
+
+## Getting Started
+
+\`\`\`bash
+# Install dependencies
+${cmd.install}
+
+# Build and run in development
+${cmd.dev}
+
+# Or build and start separately
+${cmd.build}
+${cmd.start}
+\`\`\`
+
+The server will start on port 3000 by default. You can change this by setting the \`PORT\` environment variable.
+
+## API Endpoint
+
+- **POST /mcp** - Main MCP endpoint for JSON-RPC messages
+
+## Included Examples
+
+This server comes with example implementations to help you get started:
+
+### Prompts
+
+- **greeting-template** - A simple greeting prompt that takes a name parameter
+
+### Tools
+
+- **start-notification-stream** - Sends periodic notifications for testing. Parameters:
+  - \`interval\`: Milliseconds between notifications (default: 100)
+  - \`count\`: Number of notifications to send (default: 10, use 0 for unlimited)
+
+### Resources
+
+- **greeting-resource** - A simple text resource at \`https://example.com/greetings/default\`
+
+## Project Structure
+
+\`\`\`
+${projectName}/
+├── src/
+│   ├── server.ts     # FastMCP server definition (tools, prompts, resources)
+│   └── index.ts      # Server startup configuration
+├── package.json
+├── tsconfig.json
+└── README.md
+\`\`\`
+
+## Customization
+
+- Add new tools, prompts, and resources in \`src/server.ts\`
+- Modify transport configuration in \`src/index.ts\`
+
+## Learn More
+
+- [FastMCP](https://github.com/punkpeye/fastmcp) - The framework powering this server
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+`;
+}

package/dist/templates/fastmcp/server.js

@@ -0,0 +1,66 @@
+export function getServerTemplate(projectName) {
+    return `import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+
+const server = new FastMCP({
+  name: '${projectName}',
+  version: '1.0.0',
+});
+
+// Register a simple prompt
+server.addPrompt({
+  name: 'greeting-template',
+  description: 'A simple greeting prompt template',
+  arguments: [
+    {
+      name: 'name',
+      description: 'Name to include in greeting',
+      required: true,
+    },
+  ],
+  load: async ({ name }) => {
+    return \`Please greet \${name} in a friendly manner.\`;
+  },
+});
+
+// Register a tool for testing resumability
+server.addTool({
+  name: 'start-notification-stream',
+  description: 'Starts sending periodic notifications for testing resumability',
+  parameters: z.object({
+    interval: z
+      .number()
+      .describe('Interval in milliseconds between notifications')
+      .default(100),
+    count: z.number().describe('Number of notifications to send (0 for 100)').default(10),
+  }),
+  execute: async ({ interval, count }) => {
+    const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+    let counter = 0;
+
+    while (count === 0 || counter < count) {
+      counter++;
+      console.log(\`Periodic notification #\${counter} at \${new Date().toISOString()}\`);
+      await sleep(interval);
+    }
+
+    return \`Sent \${counter} periodic notifications every \${interval}ms\`;
+  },
+});
+
+// Create a simple resource at a fixed URI
+server.addResource({
+  uri: 'https://example.com/greetings/default',
+  name: 'greeting-resource',
+  description: 'A simple greeting resource',
+  mimeType: 'text/plain',
+  load: async () => {
+    return {
+      text: 'Hello, world!',
+    };
+  },
+});
+
+export { server };
+`;
+}

package/dist/templates/fastmcp/templates.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { getServerTemplate, getIndexTemplate, getReadmeTemplate } from './index.js';
+describe('fastmcp templates', () => {
+    const projectName = 'test-project';
+    describe('getServerTemplate', () => {
+        it('should include project name in server config', () => {
+            const template = getServerTemplate(projectName);
+            expect(template).toContain(`name: '${projectName}'`);
+        });
+        it('should import FastMCP', () => {
+            const template = getServerTemplate(projectName);
+            expect(template).toContain("from 'fastmcp'");
+            expect(template).toContain('FastMCP');
+        });
+        it('should include example prompt', () => {
+            const template = getServerTemplate(projectName);
+            expect(template).toContain('greeting-template');
+            expect(template).toContain('addPrompt');
+        });
+        it('should include example tool', () => {
+            const template = getServerTemplate(projectName);
+            expect(template).toContain('start-notification-stream');
+            expect(template).toContain('addTool');
+        });
+        it('should include example resource', () => {
+            const template = getServerTemplate(projectName);
+            expect(template).toContain('greeting-resource');
+            expect(template).toContain('addResource');
+        });
+        it('should use zod for parameter validation', () => {
+            const template = getServerTemplate(projectName);
+            expect(template).toContain("from 'zod'");
+            expect(template).toContain('z.object');
+        });
+    });
+    describe('getIndexTemplate', () => {
+        it('should import server from server.ts', () => {
+            const template = getIndexTemplate();
+            expect(template).toContain("from './server.js'");
+        });
+        it('should use httpStream transport', () => {
+            const template = getIndexTemplate();
+            expect(template).toContain("transportType: 'httpStream'");
+        });
+        it('should use PORT from environment variable', () => {
+            const template = getIndexTemplate();
+            expect(template).toContain('process.env.PORT');
+        });
+        it('should NOT include stateless option by default', () => {
+            const template = getIndexTemplate();
+            expect(template).not.toContain('stateless: true');
+        });
+        it('should include stateless option when specified', () => {
+            const template = getIndexTemplate({ stateless: true });
+            expect(template).toContain('stateless: true');
+        });
+    });
+    describe('getReadmeTemplate', () => {
+        it('should include project name', () => {
+            const template = getReadmeTemplate(projectName);
+            expect(template).toContain(`# ${projectName}`);
+        });
+        it('should mention FastMCP', () => {
+            const template = getReadmeTemplate(projectName);
+            expect(template).toContain('FastMCP');
+            expect(template).toContain('github.com/punkpeye/fastmcp');
+        });
+        it('should include npm commands by default', () => {
+            const template = getReadmeTemplate(projectName);
+            expect(template).toContain('npm install');
+            expect(template).toContain('npm run dev');
+        });
+        it('should use pnpm commands when specified', () => {
+            const template = getReadmeTemplate(projectName, { packageManager: 'pnpm' });
+            expect(template).toContain('pnpm install');
+            expect(template).toContain('pnpm dev');
+        });
+        it('should describe stateful mode by default', () => {
+            const template = getReadmeTemplate(projectName);
+            expect(template).toContain('stateful');
+        });
+        it('should describe stateless mode when specified', () => {
+            const template = getReadmeTemplate(projectName, { stateless: true });
+            expect(template).toContain('stateless');
+        });
+    });
+});

package/dist/templates/sdk/stateful/index.d.ts

@@ -0,0 +1,6 @@
+export type { SdkTemplateOptions as TemplateOptions } from '../../common/types.js';
+import type { SdkTemplateOptions } from '../../common/types.js';
+export declare function getIndexTemplate(options?: SdkTemplateOptions): string;
+export { getServerTemplate } from './server.js';
+export { getReadmeTemplate } from './readme.js';
+export { getAuthTemplate } from './auth.js';

package/dist/templates/{stateful-streamable-http → sdk/stateful}/index.js

@@ -29,10 +29,6 @@ import { getServer } from './server.js';`;
     const deleteRoute = withOAuth
         ? `app.delete('/mcp', authMiddleware, async (req: Request, res: Response) => {`
         : `app.delete('/mcp', async (req: Request, res: Response) => {`;
-    const startupLog = withOAuth
-        ? `console.log(\`MCP Stateful HTTP Server listening on port \${PORT}\`);
-    console.log(\`OAuth metadata available at \${getOAuthMetadataUrl()}\`);`
-        : `console.log(\`MCP Stateful HTTP Server listening on port \${PORT}\`);`;
     return `${imports}
 
 ${appSetup}
@@ -144,6 +140,24 @@ ${withOAuth
         ? `// Start the server
 const PORT = process.env.PORT || 3000;
 
+function startServer(port: number | string): void {
+  const server = app.listen(port, () => {
+    console.log(\`MCP Stateful HTTP Server listening on port \${port}\`);
+    console.log(\`OAuth metadata available at \${getOAuthMetadataUrl()}\`);
+  });
+
+  server.on('error', (error: NodeJS.ErrnoException) => {
+    if (error.code === 'EADDRINUSE') {
+      const randomPort = Math.floor(Math.random() * (65535 - 49152) + 49152);
+      console.log(\`Port \${port} is in use, trying port \${randomPort}...\`);
+      startServer(randomPort);
+    } else {
+      console.error('Failed to start server:', error);
+      process.exit(1);
+    }
+  });
+}
+
 async function main() {
   // Validate OAuth configuration and fetch OIDC discovery document
   await validateOAuthConfig();
@@ -151,9 +165,7 @@ async function main() {
   // Setup OAuth metadata routes (must be after validateOAuthConfig)
   setupAuthMetadataRouter(app);
 
-  app.listen(PORT, () => {
-    ${startupLog}
-  });
+  startServer(PORT);
 }
 
 main().catch((error) => {
@@ -162,9 +174,25 @@ main().catch((error) => {
 });`
         : `// Start the server
 const PORT = process.env.PORT || 3000;
-app.listen(PORT, () => {
-  ${startupLog}
-});`}
+
+function startServer(port: number | string): void {
+  const server = app.listen(port, () => {
+    console.log(\`MCP Stateful HTTP Server listening on port \${port}\`);
+  });
+
+  server.on('error', (error: NodeJS.ErrnoException) => {
+    if (error.code === 'EADDRINUSE') {
+      const randomPort = Math.floor(Math.random() * (65535 - 49152) + 49152);
+      console.log(\`Port \${port} is in use, trying port \${randomPort}...\`);
+      startServer(randomPort);
+    } else {
+      console.error('Failed to start server:', error);
+      process.exit(1);
+    }
+  });
+}
+
+startServer(PORT);`}
 
 // Handle server shutdown
 process.on('SIGINT', async () => {

package/dist/templates/{stateful-streamable-http → sdk/stateful}/readme.js

@@ -1,5 +1,11 @@
 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' },
+    }[packageManager];
     const description = withOAuth
         ? 'A stateful streamable HTTP MCP (Model Context Protocol) server with session management and OAuth authentication.'
         : 'A stateful streamable HTTP MCP (Model Context Protocol) server with session management.';
@@ -85,14 +91,14 @@ This project was created with [@agentailor/create-mcp-server](https://www.npmjs.
 
 \`\`\`bash
 # Install dependencies
-npm install
+${commands.install}
 
 # Build and run in development
-npm run dev
+${commands.dev}
 
 # Or build and start separately
-npm run build
-npm start
+${commands.build}
+${commands.start}
 \`\`\`
 
 The server will start on port 3000 by default. You can change this by setting the \`PORT\` environment variable.

package/dist/templates/sdk/stateful/server.d.ts

@@ -0,0 +1 @@
+export { getServerTemplate } from '../stateless/server.js';

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

@@ -0,0 +1,2 @@
+// Re-export from stateless template - server logic is identical
+export { getServerTemplate } from '../stateless/server.js';

package/dist/templates/sdk/stateful/templates.test.d.ts

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

package/dist/templates/{stateful-streamable-http → sdk/stateful}/templates.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { getServerTemplate, getIndexTemplate, getReadmeTemplate } from './index.js';
-describe('stateful-streamable-http templates', () => {
+describe('sdk/stateful templates', () => {
     const projectName = 'test-project';
     describe('getServerTemplate', () => {
         it('should include project name in server config', () => {
@@ -83,10 +83,12 @@ describe('stateful-streamable-http templates', () => {
             const template = getReadmeTemplate(projectName);
             expect(template).toContain(`# ${projectName}`);
         });
-        it('should include getting started instructions', () => {
+        it('should include getting started instructions with npm by default', () => {
             const template = getReadmeTemplate(projectName);
             expect(template).toContain('npm install');
             expect(template).toContain('npm run dev');
+            expect(template).toContain('npm run build');
+            expect(template).toContain('npm start');
         });
         it('should document the /mcp endpoint', () => {
             const template = getReadmeTemplate(projectName);
@@ -108,6 +110,31 @@ describe('stateful-streamable-http templates', () => {
             expect(template).toContain('DELETE /mcp');
         });
     });
+    describe('getReadmeTemplate with package manager', () => {
+        it('should use npm commands when packageManager is npm', () => {
+            const template = getReadmeTemplate(projectName, { packageManager: 'npm' });
+            expect(template).toContain('npm install');
+            expect(template).toContain('npm run dev');
+            expect(template).toContain('npm run build');
+            expect(template).toContain('npm start');
+        });
+        it('should use pnpm commands when packageManager is pnpm', () => {
+            const template = getReadmeTemplate(projectName, { packageManager: 'pnpm' });
+            expect(template).toContain('pnpm install');
+            expect(template).toContain('pnpm dev');
+            expect(template).toContain('pnpm build');
+            expect(template).toContain('pnpm start');
+            expect(template).not.toContain('npm run');
+        });
+        it('should use yarn commands when packageManager is yarn', () => {
+            const template = getReadmeTemplate(projectName, { packageManager: 'yarn' });
+            expect(template).toContain('yarn\n');
+            expect(template).toContain('yarn dev');
+            expect(template).toContain('yarn build');
+            expect(template).toContain('yarn start');
+            expect(template).not.toContain('npm run');
+        });
+    });
     describe('getIndexTemplate with OAuth', () => {
         it('should include auth imports when OAuth enabled', () => {
             const template = getIndexTemplate({ withOAuth: true });

package/dist/templates/sdk/stateless/index.d.ts

@@ -0,0 +1,5 @@
+export type { SdkTemplateOptions as TemplateOptions } from '../../common/types.js';
+import type { SdkTemplateOptions } from '../../common/types.js';
+export declare function getIndexTemplate(options?: SdkTemplateOptions): string;
+export { getServerTemplate } from './server.js';
+export { getReadmeTemplate } from './readme.js';

package/dist/templates/{streamable-http → sdk/stateless}/index.js

@@ -66,13 +66,25 @@ app.delete('/mcp', async (req: Request, res: Response) => {
 
 // Start the server
 const PORT = process.env.PORT || 3000;
-app.listen(PORT, (error) => {
-  if (error) {
-    console.error('Failed to start server:', error);
-    process.exit(1);
-  }
-  console.log(\`MCP Streamable HTTP Server listening on port \${PORT}\`);
-});
+
+function startServer(port: number | string): void {
+  const server = app.listen(port, () => {
+    console.log(\`MCP Streamable HTTP Server listening on port \${port}\`);
+  });
+
+  server.on('error', (error: NodeJS.ErrnoException) => {
+    if (error.code === 'EADDRINUSE') {
+      const randomPort = Math.floor(Math.random() * (65535 - 49152) + 49152);
+      console.log(\`Port \${port} is in use, trying port \${randomPort}...\`);
+      startServer(randomPort);
+    } else {
+      console.error('Failed to start server:', error);
+      process.exit(1);
+    }
+  });
+}
+
+startServer(PORT);
 
 // Handle server shutdown
 process.on('SIGINT', async () => {

package/dist/templates/sdk/stateless/readme.d.ts

@@ -0,0 +1,2 @@
+import type { TemplateOptions } from './index.js';
+export declare function getReadmeTemplate(projectName: string, options?: TemplateOptions): string;

package/dist/templates/{streamable-http → sdk/stateless}/readme.js

@@ -1,6 +1,10 @@
-// Options parameter added for type consistency with stateful template (OAuth not supported in stateless)
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 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' },
+    }[packageManager];
     return `# ${projectName}
 
 A stateless streamable HTTP MCP (Model Context Protocol) server.
@@ -13,14 +17,14 @@ This project was created with [@agentailor/create-mcp-server](https://www.npmjs.
 
 \`\`\`bash
 # Install dependencies
-npm install
+${commands.install}
 
 # Build and run in development
-npm run dev
+${commands.dev}
 
 # Or build and start separately
-npm run build
-npm start
+${commands.build}
+${commands.start}
 \`\`\`
 
 The server will start on port 3000 by default. You can change this by setting the \`PORT\` environment variable.

package/dist/templates/sdk/stateless/server.d.ts

@@ -0,0 +1 @@
+export declare function getServerTemplate(projectName: string): string;

package/dist/templates/sdk/stateless/templates.test.d.ts

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

package/dist/templates/{streamable-http → sdk/stateless}/templates.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { getServerTemplate, getIndexTemplate, getReadmeTemplate } from './index.js';
-describe('streamable-http templates', () => {
+describe('sdk/stateless templates', () => {
     const projectName = 'test-project';
     describe('getServerTemplate', () => {
         it('should include project name in server config', () => {
@@ -63,10 +63,12 @@ describe('streamable-http templates', () => {
             const template = getReadmeTemplate(projectName);
             expect(template).toContain(`# ${projectName}`);
         });
-        it('should include getting started instructions', () => {
+        it('should include getting started instructions with npm by default', () => {
             const template = getReadmeTemplate(projectName);
             expect(template).toContain('npm install');
             expect(template).toContain('npm run dev');
+            expect(template).toContain('npm run build');
+            expect(template).toContain('npm start');
         });
         it('should document the /mcp endpoint', () => {
             const template = getReadmeTemplate(projectName);
@@ -77,4 +79,29 @@ describe('streamable-http templates', () => {
             expect(template).toContain('stateless');
         });
     });
+    describe('getReadmeTemplate with package manager', () => {
+        it('should use npm commands when packageManager is npm', () => {
+            const template = getReadmeTemplate(projectName, { packageManager: 'npm' });
+            expect(template).toContain('npm install');
+            expect(template).toContain('npm run dev');
+            expect(template).toContain('npm run build');
+            expect(template).toContain('npm start');
+        });
+        it('should use pnpm commands when packageManager is pnpm', () => {
+            const template = getReadmeTemplate(projectName, { packageManager: 'pnpm' });
+            expect(template).toContain('pnpm install');
+            expect(template).toContain('pnpm dev');
+            expect(template).toContain('pnpm build');
+            expect(template).toContain('pnpm start');
+            expect(template).not.toContain('npm run');
+        });
+        it('should use yarn commands when packageManager is yarn', () => {
+            const template = getReadmeTemplate(projectName, { packageManager: 'yarn' });
+            expect(template).toContain('yarn\n');
+            expect(template).toContain('yarn dev');
+            expect(template).toContain('yarn build');
+            expect(template).toContain('yarn start');
+            expect(template).not.toContain('npm run');
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentailor/create-mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Create a new MCP (Model Context Protocol) server project",
   "type": "module",
   "bin": {

package/dist/templates/stateful-streamable-http/index.d.ts

@@ -1,7 +0,0 @@
-export interface TemplateOptions {
-    withOAuth?: boolean;
-}
-export declare function getIndexTemplate(options?: TemplateOptions): string;
-export { getServerTemplate } from './server.js';
-export { getReadmeTemplate } from './readme.js';
-export { getAuthTemplate } from './auth.js';

package/dist/templates/stateful-streamable-http/server.d.ts

@@ -1 +0,0 @@
-export { getServerTemplate } from '../streamable-http/server.js';

package/dist/templates/stateful-streamable-http/server.js

@@ -1,2 +0,0 @@
-// Re-export from stateless template - server logic is identical
-export { getServerTemplate } from '../streamable-http/server.js';

package/dist/templates/streamable-http/index.d.ts

@@ -1,6 +0,0 @@
-export interface TemplateOptions {
-    withOAuth?: boolean;
-}
-export declare function getIndexTemplate(options?: TemplateOptions): string;
-export { getServerTemplate } from './server.js';
-export { getReadmeTemplate } from './readme.js';