frontmcp 0.1.3 → 0.1.4

package/dist/cli.js

@@ -76,7 +76,7 @@ ${c('bold', 'Commands')}
   init                Create or fix a tsconfig.json suitable for FrontMCP
   doctor              Check Node/npm versions and tsconfig requirements
   inspector           Launch MCP Inspector (npx @modelcontextprotocol/inspector)
-  create              Scaffold a new FrontMCP project in the current directory
+  create <name>       Scaffold a new FrontMCP project in ./<name>
   help                Show this help message
 
 ${c('bold', 'Options')}
@@ -89,7 +89,7 @@ ${c('bold', 'Examples')}
   frontmcp init
   frontmcp doctor
   frontmcp inspector
-  npx frontmcp create
+  npx frontmcp create my-mcp
 `);
 }
 function parseArgs(argv) {
@@ -146,30 +146,24 @@ function resolveEntry(cwd, explicit) {
                 return full;
             throw new Error(`Entry override not found: ${explicit}`);
         }
-        // 1) package.json main
         const pkgPath = path.join(cwd, 'package.json');
         if (yield fileExists(pkgPath)) {
             const pkg = yield readJSON(pkgPath);
             if (pkg && typeof pkg.main === 'string' && pkg.main.trim()) {
                 const mainCandidates = tryCandidates(path.resolve(cwd, pkg.main));
-                for (const p of mainCandidates) {
+                for (const p of mainCandidates)
                     if (yield fileExists(p))
                         return p;
-                }
-                // If "main" is a directory-like path, try index.* within it
                 const asDir = path.resolve(cwd, pkg.main);
                 const idxCandidates = tryCandidates(path.join(asDir, 'index'));
-                for (const p of idxCandidates) {
+                for (const p of idxCandidates)
                     if (yield fileExists(p))
                         return p;
-                }
             }
         }
-        // 2) src/main.ts
         const fallback = path.join(cwd, 'src', 'main.ts');
         if (yield fileExists(fallback))
             return fallback;
-        // 3) Not found
         const msg = [
             c('red', 'No entry file found.'),
             '',
@@ -191,6 +185,55 @@ function runCmd(cmd, args, opts = {}) {
         child.on('error', reject);
     });
 }
+function ensureDir(p) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield fs_1.promises.mkdir(p, { recursive: true });
+    });
+}
+function isDirEmpty(dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const items = yield fs_1.promises.readdir(dir);
+            return items.length === 0;
+        }
+        catch (e) {
+            if ((e === null || e === void 0 ? void 0 : e.code) === 'ENOENT')
+                return true;
+            throw e;
+        }
+    });
+}
+function sanitizeForFolder(name) {
+    const seg = name.startsWith('@') && name.includes('/') ? name.split('/')[1] : name;
+    return seg.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase() || 'frontmcp-app';
+}
+function sanitizeForNpm(name) {
+    if (name.startsWith('@') && name.includes('/')) {
+        const [scope, pkg] = name.split('/');
+        const s = scope.replace(/[^a-z0-9-]/gi, '').toLowerCase();
+        const p = pkg.replace(/[^a-z0-9._-]/gi, '-').toLowerCase();
+        return `@${s}/${p || 'frontmcp-app'}`;
+    }
+    return name.replace(/[^a-z0-9._-]/gi, '-').toLowerCase() || 'frontmcp-app';
+}
+/* ------------------------ Self-version detection -------------------------- */
+function getSelfVersion() {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Best-effort: find our own package.json near the executed bin.
+        const binPath = process.argv[1] || __filename;
+        const candidates = [
+            path.resolve(path.dirname(binPath), '../package.json'),
+            path.resolve(path.dirname(binPath), '../../package.json'),
+        ];
+        for (const p of candidates) {
+            const j = yield readJSON(p);
+            if (j === null || j === void 0 ? void 0 : j.version)
+                return j.version;
+        }
+        // Fallback if not found; still satisfies the "has field" requirement.
+        return '0.0.0';
+    });
+}
 /* --------------------------------- Actions -------------------------------- */
 function runDev(opts) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -201,11 +244,6 @@ function runDev(opts) {
         yield runCmd('npx', ['-y', 'tsx', '--watch', entry]);
     });
 }
-function ensureDir(p) {
-    return __awaiter(this, void 0, void 0, function* () {
-        yield fs_1.promises.mkdir(p, { recursive: true });
-    });
-}
 function isTsLike(p) {
     return /\.tsx?$/i.test(p);
 }
@@ -229,7 +267,6 @@ function runBuild(opts) {
         if (yield fileExists(tsconfigPath)) {
             console.log(c('gray', `[build] tsconfig.json detected (project options will be respected where applicable)`));
         }
-        // Compile the single entry file
         yield runCmd('npx', ['-y', 'tsc', entry, ...args]);
         console.log(c('green', '✅ Build completed.'));
         console.log(c('gray', `Output placed in ${path.relative(cwd, outDir)}`));
@@ -276,7 +313,6 @@ function deepMerge(base, patch) {
 function ensureRequiredTsOptions(obj) {
     const next = Object.assign({}, obj);
     next.compilerOptions = Object.assign({}, (next.compilerOptions || {}));
-    // Force the required values
     next.compilerOptions.target = REQUIRED_DECORATOR_FIELDS.target;
     next.compilerOptions.module = REQUIRED_DECORATOR_FIELDS.module;
     next.compilerOptions.emitDecoratorMetadata = REQUIRED_DECORATOR_FIELDS.emitDecoratorMetadata;
@@ -311,18 +347,17 @@ function checkRequiredTsOptions(compilerOptions) {
         issues.push(`compilerOptions.experimentalDecorators should be true`);
     return { ok, issues };
 }
-function runInit() {
+function runInit(baseDir) {
     return __awaiter(this, void 0, void 0, function* () {
-        const cwd = process.cwd();
+        const cwd = baseDir !== null && baseDir !== void 0 ? baseDir : process.cwd();
         const tsconfigPath = path.join(cwd, 'tsconfig.json');
         const existing = yield readJSON(tsconfigPath);
         if (!existing) {
-            console.log(c('yellow', 'tsconfig.json not found — creating one.'));
+            console.log(c('yellow', `tsconfig.json not found — creating one in ${path.relative(process.cwd(), cwd) || '.'}.`));
             yield writeJSON(tsconfigPath, RECOMMENDED_TSCONFIG);
             console.log(c('green', '✅ Created tsconfig.json with required decorator settings.'));
             return;
         }
-        // Merge user config on top of recommended, then force required decorator options
         let merged = deepMerge(RECOMMENDED_TSCONFIG, existing);
         merged = ensureRequiredTsOptions(merged);
         yield writeJSON(tsconfigPath, merged);
@@ -347,7 +382,6 @@ function runDoctor() {
         const MIN_NPM = '10.0.0';
         const cwd = process.cwd();
         let ok = true;
-        // Node
         const nodeVer = process.versions.node;
         if (cmpSemver(nodeVer, MIN_NODE) >= 0) {
             console.log(`✅ Node ${nodeVer} (min ${MIN_NODE})`);
@@ -356,7 +390,6 @@ function runDoctor() {
             ok = false;
             console.log(`❌ Node ${nodeVer} — please upgrade to >= ${MIN_NODE}`);
         }
-        // npm
         let npmVer = 'unknown';
         try {
             npmVer = yield new Promise((resolve, reject) => {
@@ -379,7 +412,6 @@ function runDoctor() {
             ok = false;
             console.log('❌ npm not found in PATH');
         }
-        // tsconfig.json presence + required fields
         const tsconfigPath = path.join(cwd, 'tsconfig.json');
         if (yield fileExists(tsconfigPath)) {
             console.log(`✅ tsconfig.json found`);
@@ -398,7 +430,6 @@ function runDoctor() {
             ok = false;
             console.log(`❌ tsconfig.json not found — run ${c('cyan', 'frontmcp init')}`);
         }
-        // Entry check (nice to have)
         try {
             const entry = yield resolveEntry(cwd);
             console.log(`✅ entry detected: ${path.relative(cwd, entry)}`);
@@ -407,12 +438,10 @@ function runDoctor() {
             const firstLine = (_c = (_b = (_a = e === null || e === void 0 ? void 0 : e.message) === null || _a === void 0 ? void 0 : _a.split('\n')) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : 'entry not found';
             console.log(`❌ entry not detected — ${firstLine}`);
         }
-        if (ok) {
+        if (ok)
             console.log(c('green', '\nAll checks passed. You are ready to go!'));
-        }
-        else {
+        else
             console.log(c('yellow', '\nSome checks failed. See above for fixes.'));
-        }
     });
 }
 /* ------------------------------- Inspector -------------------------------- */
@@ -426,13 +455,13 @@ function runInspector() {
 function pkgNameFromCwd(cwd) {
     return path.basename(cwd).replace(/[^a-zA-Z0-9._-]/g, '-').toLowerCase() || 'frontmcp-app';
 }
-function upsertPackageJson(cwd) {
+function upsertPackageJson(cwd, nameOverride, selfVersion) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         const pkgPath = path.join(cwd, 'package.json');
         const existing = yield readJSON(pkgPath);
         const base = {
-            name: pkgNameFromCwd(cwd),
+            name: nameOverride !== null && nameOverride !== void 0 ? nameOverride : pkgNameFromCwd(cwd),
             version: '0.1.0',
             private: true,
             type: 'module',
@@ -449,39 +478,45 @@ function upsertPackageJson(cwd) {
             },
             dependencies: {
                 '@frontmcp/sdk': 'latest',
-                zod: 'latest',
+                zod: '^3.23.8',
+                'reflect-metadata': '^0.2.2',
             },
             devDependencies: {
-                typescript: 'latest',
-                tsx: 'latest',
+                frontmcp: selfVersion, // exact version used by npx
+                tsx: '^4.20.6',
+                typescript: '^5.5.3',
             },
         };
         if (!existing) {
             yield writeJSON(pkgPath, base);
-            console.log(c('green', '✅ Created package.json (with scripts: dev, build, inspect, doctor)'));
+            console.log(c('green', '✅ Created package.json (pinned tsx/typescript/zod/reflect-metadata, exact frontmcp)'));
             return;
         }
-        // Merge, preserving user fields; ensure our requirements exist
         const merged = Object.assign(Object.assign({}, base), existing);
+        merged.name = existing.name || base.name;
         merged.main = existing.main || base.main;
         merged.type = existing.type || base.type;
-        merged.scripts = Object.assign(Object.assign(Object.assign({}, base.scripts), (existing.scripts || {})), { dev: ((_b = (_a = existing.scripts) === null || _a === void 0 ? void 0 : _a.dev) !== null && _b !== void 0 ? _b : base.scripts.dev), build: ((_d = (_c = existing.scripts) === null || _c === void 0 ? void 0 : _c.build) !== null && _d !== void 0 ? _d : base.scripts.build), inspect: ((_f = (_e = existing.scripts) === null || _e === void 0 ? void 0 : _e.inspect) !== null && _f !== void 0 ? _f : base.scripts.inspect), doctor: ((_h = (_g = existing.scripts) === null || _g === void 0 ? void 0 : _g.doctor) !== null && _h !== void 0 ? _h : base.scripts.doctor) });
+        merged.scripts = Object.assign(Object.assign(Object.assign({}, base.scripts), (existing.scripts || {})), { dev: (_b = (_a = existing.scripts) === null || _a === void 0 ? void 0 : _a.dev) !== null && _b !== void 0 ? _b : base.scripts.dev, build: (_d = (_c = existing.scripts) === null || _c === void 0 ? void 0 : _c.build) !== null && _d !== void 0 ? _d : base.scripts.build, inspect: (_f = (_e = existing.scripts) === null || _e === void 0 ? void 0 : _e.inspect) !== null && _f !== void 0 ? _f : base.scripts.inspect, doctor: (_h = (_g = existing.scripts) === null || _g === void 0 ? void 0 : _g.doctor) !== null && _h !== void 0 ? _h : base.scripts.doctor });
         merged.engines = Object.assign(Object.assign({}, (existing.engines || {})), { node: ((_j = existing.engines) === null || _j === void 0 ? void 0 : _j.node) || base.engines.node, npm: ((_k = existing.engines) === null || _k === void 0 ? void 0 : _k.npm) || base.engines.npm });
-        merged.dependencies = Object.assign(Object.assign({}, existing.dependencies), { '@frontmcp/sdk': ((_l = existing.dependencies) === null || _l === void 0 ? void 0 : _l['@frontmcp/sdk']) || base.dependencies['@frontmcp/sdk'], zod: ((_m = existing.dependencies) === null || _m === void 0 ? void 0 : _m.zod) || base.dependencies.zod });
-        merged.devDependencies = Object.assign(Object.assign({}, existing.devDependencies), { typescript: ((_o = existing.devDependencies) === null || _o === void 0 ? void 0 : _o.typescript) || base.devDependencies.typescript, tsx: ((_p = existing.devDependencies) === null || _p === void 0 ? void 0 : _p.tsx) || base.devDependencies.tsx });
+        merged.dependencies = Object.assign(Object.assign(Object.assign({}, base.dependencies), (existing.dependencies || {})), { 
+            // ensure pins
+            zod: '^3.23.8', 'reflect-metadata': '^0.2.2' });
+        merged.devDependencies = Object.assign(Object.assign(Object.assign({}, base.devDependencies), (existing.devDependencies || {})), { 
+            // ensure pins
+            frontmcp: selfVersion, tsx: '^4.20.6', typescript: '^5.5.3' });
         yield writeJSON(pkgPath, merged);
-        console.log(c('green', '✅ Updated package.json (ensured scripts, engines, deps)'));
+        console.log(c('green', '✅ Updated package.json (ensured exact frontmcp and pinned versions)'));
     });
 }
-function scaffoldFileIfMissing(p, content) {
+function scaffoldFileIfMissing(baseDir, p, content) {
     return __awaiter(this, void 0, void 0, function* () {
         if (yield fileExists(p)) {
-            console.log(c('gray', `skip: ${path.relative(process.cwd(), p)} already exists`));
+            console.log(c('gray', `skip: ${path.relative(baseDir, p)} already exists`));
             return;
         }
         yield ensureDir(path.dirname(p));
         yield fs_1.promises.writeFile(p, content.replace(/^\n/, ''), 'utf8');
-        console.log(c('green', `✓ created ${path.relative(process.cwd(), p)}`));
+        console.log(c('green', `✓ created ${path.relative(baseDir, p)}`));
     });
 }
 const TEMPLATE_MAIN_TS = `
@@ -526,24 +561,43 @@ const AddTool = tool({
 
 export default AddTool;
 `;
-function runCreate() {
+function runCreate(projectArg) {
     return __awaiter(this, void 0, void 0, function* () {
-        const cwd = process.cwd();
-        console.log(c('cyan', '[create]'), 'Scaffolding FrontMCP project in', c('bold', cwd));
+        if (!projectArg) {
+            console.error(c('red', 'Error: project name is required.\n'));
+            console.log(`Usage: ${c('bold', 'npx frontmcp create <project-name>')}`);
+            process.exit(1);
+        }
+        const folder = sanitizeForFolder(projectArg);
+        const pkgName = sanitizeForNpm(projectArg);
+        const targetDir = path.resolve(process.cwd(), folder);
+        if (yield fileExists(targetDir)) {
+            if (!(yield isDirEmpty(targetDir))) {
+                console.error(c('red', `Refusing to scaffold into non-empty directory: ${path.relative(process.cwd(), targetDir)}`));
+                console.log(c('gray', 'Pick a different name or start with an empty folder.'));
+                process.exit(1);
+            }
+        }
+        else {
+            yield ensureDir(targetDir);
+        }
+        console.log(`${c('cyan', '[create]')} Creating project in ${c('bold', './' + path.relative(process.cwd(), targetDir))}`);
+        process.chdir(targetDir);
         // 1) tsconfig
-        yield runInit();
-        // 2) package.json
-        yield upsertPackageJson(cwd);
+        yield runInit(targetDir);
+        // 2) package.json (with pinned deps and exact frontmcp version)
+        const selfVersion = yield getSelfVersion();
+        yield upsertPackageJson(targetDir, pkgName, selfVersion);
         // 3) files
-        yield scaffoldFileIfMissing(path.join(cwd, 'src', 'main.ts'), TEMPLATE_MAIN_TS);
-        yield scaffoldFileIfMissing(path.join(cwd, 'src', 'calc.app.ts'), TEMPLATE_CALC_APP_TS);
-        yield scaffoldFileIfMissing(path.join(cwd, 'src', 'tools', 'add.tool.ts'), TEMPLATE_ADD_TOOL_TS);
-        // 4) final tips
+        yield scaffoldFileIfMissing(targetDir, path.join(targetDir, 'src', 'main.ts'), TEMPLATE_MAIN_TS);
+        yield scaffoldFileIfMissing(targetDir, path.join(targetDir, 'src', 'calc.app.ts'), TEMPLATE_CALC_APP_TS);
+        yield scaffoldFileIfMissing(targetDir, path.join(targetDir, 'src', 'tools', 'add.tool.ts'), TEMPLATE_ADD_TOOL_TS);
         console.log('\nNext steps:');
-        console.log('  1) npm install');
-        console.log('  2) npm run dev   ', c('gray', '# starts tsx watcher via frontmcp dev'));
-        console.log('  3) npm run inspect', c('gray', '# launch MCP Inspector'));
-        console.log('  4) npm run build ', c('gray', '# compile with tsc via frontmcp build'));
+        console.log(`  1) cd ${folder}`);
+        console.log('  2) npm install');
+        console.log('  3) npm run dev     ', c('gray', '# starts tsx watcher via frontmcp dev'));
+        console.log('  4) npm run inspect ', c('gray', '# launch MCP Inspector'));
+        console.log('  5) npm run build   ', c('gray', '# compile with tsc via frontmcp build'));
     });
 }
 /* --------------------------------- Main ----------------------------------- */
@@ -574,9 +628,11 @@ function main() {
                 case 'inspector':
                     yield runInspector();
                     break;
-                case 'create':
-                    yield runCreate();
+                case 'create': {
+                    const projectName = parsed._[1]; // require a name
+                    yield runCreate(projectName);
                     break;
+                }
                 case 'help':
                     showHelp();
                     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontmcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "FrontMCP command line interface",
   "main": "dist/index.js",
   "bin": {

package/src/cli.ts

@@ -47,7 +47,7 @@ ${c('bold', 'Commands')}
   init                Create or fix a tsconfig.json suitable for FrontMCP
   doctor              Check Node/npm versions and tsconfig requirements
   inspector           Launch MCP Inspector (npx @modelcontextprotocol/inspector)
-  create              Scaffold a new FrontMCP project in the current directory
+  create <name>       Scaffold a new FrontMCP project in ./<name>
   help                Show this help message
 
 ${c('bold', 'Options')}
@@ -60,7 +60,7 @@ ${c('bold', 'Examples')}
   frontmcp init
   frontmcp doctor
   frontmcp inspector
-  npx frontmcp create
+  npx frontmcp create my-mcp
 `);
 }
 
@@ -109,30 +109,20 @@ async function resolveEntry(cwd: string, explicit?: string): Promise<string> {
     if (await fileExists(full)) return full;
     throw new Error(`Entry override not found: ${explicit}`);
   }
-
-  // 1) package.json main
   const pkgPath = path.join(cwd, 'package.json');
   if (await fileExists(pkgPath)) {
     const pkg = await readJSON<any>(pkgPath);
     if (pkg && typeof pkg.main === 'string' && pkg.main.trim()) {
       const mainCandidates = tryCandidates(path.resolve(cwd, pkg.main));
-      for (const p of mainCandidates) {
-        if (await fileExists(p)) return p;
-      }
-      // If "main" is a directory-like path, try index.* within it
+      for (const p of mainCandidates) if (await fileExists(p)) return p;
       const asDir = path.resolve(cwd, pkg.main);
       const idxCandidates = tryCandidates(path.join(asDir, 'index'));
-      for (const p of idxCandidates) {
-        if (await fileExists(p)) return p;
-      }
+      for (const p of idxCandidates) if (await fileExists(p)) return p;
     }
   }
-
-  // 2) src/main.ts
   const fallback = path.join(cwd, 'src', 'main.ts');
   if (await fileExists(fallback)) return fallback;
 
-  // 3) Not found
   const msg = [
     c('red', 'No entry file found.'),
     '',
@@ -155,6 +145,52 @@ function runCmd(cmd: string, args: string[], opts: { cwd?: string } = {}): Promi
   });
 }
 
+async function ensureDir(p: string): Promise<void> {
+  await fsp.mkdir(p, {recursive: true});
+}
+
+async function isDirEmpty(dir: string): Promise<boolean> {
+  try {
+    const items = await fsp.readdir(dir);
+    return items.length === 0;
+  } catch (e: any) {
+    if (e?.code === 'ENOENT') return true;
+    throw e;
+  }
+}
+
+function sanitizeForFolder(name: string): string {
+  const seg = name.startsWith('@') && name.includes('/') ? name.split('/')[1] : name;
+  return seg.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase() || 'frontmcp-app';
+}
+
+function sanitizeForNpm(name: string): string {
+  if (name.startsWith('@') && name.includes('/')) {
+    const [scope, pkg] = name.split('/');
+    const s = scope.replace(/[^a-z0-9-]/gi, '').toLowerCase();
+    const p = pkg.replace(/[^a-z0-9._-]/gi, '-').toLowerCase();
+    return `@${s}/${p || 'frontmcp-app'}`;
+  }
+  return name.replace(/[^a-z0-9._-]/gi, '-').toLowerCase() || 'frontmcp-app';
+}
+
+/* ------------------------ Self-version detection -------------------------- */
+
+async function getSelfVersion(): Promise<string> {
+  // Best-effort: find our own package.json near the executed bin.
+  const binPath = process.argv[1] || __filename;
+  const candidates = [
+    path.resolve(path.dirname(binPath), '../package.json'),
+    path.resolve(path.dirname(binPath), '../../package.json'),
+  ];
+  for (const p of candidates) {
+    const j = await readJSON<any>(p);
+    if (j?.version) return j.version;
+  }
+  // Fallback if not found; still satisfies the "has field" requirement.
+  return '0.0.0';
+}
+
 /* --------------------------------- Actions -------------------------------- */
 
 async function runDev(opts: ParsedArgs): Promise<void> {
@@ -165,10 +201,6 @@ async function runDev(opts: ParsedArgs): Promise<void> {
   await runCmd('npx', ['-y', 'tsx', '--watch', entry]);
 }
 
-async function ensureDir(p: string): Promise<void> {
-  await fsp.mkdir(p, {recursive: true});
-}
-
 function isTsLike(p: string): boolean {
   return /\.tsx?$/i.test(p);
 }
@@ -197,7 +229,6 @@ async function runBuild(opts: ParsedArgs): Promise<void> {
     console.log(c('gray', `[build] tsconfig.json detected (project options will be respected where applicable)`));
   }
 
-  // Compile the single entry file
   await runCmd('npx', ['-y', 'tsc', entry, ...args]);
   console.log(c('green', '✅ Build completed.'));
   console.log(c('gray', `Output placed in ${path.relative(cwd, outDir)}`));
@@ -247,13 +278,10 @@ function deepMerge<T extends Record<string, any>, U extends Record<string, any>>
 function ensureRequiredTsOptions(obj: Record<string, any>): Record<string, any> {
   const next = {...obj};
   next.compilerOptions = {...(next.compilerOptions || {})};
-
-  // Force the required values
   next.compilerOptions.target = REQUIRED_DECORATOR_FIELDS.target;
   next.compilerOptions.module = REQUIRED_DECORATOR_FIELDS.module;
   next.compilerOptions.emitDecoratorMetadata = REQUIRED_DECORATOR_FIELDS.emitDecoratorMetadata;
   next.compilerOptions.experimentalDecorators = REQUIRED_DECORATOR_FIELDS.experimentalDecorators;
-
   return next;
 }
 
@@ -285,19 +313,18 @@ function checkRequiredTsOptions(compilerOptions: Record<string, any> | undefined
   return {ok, issues};
 }
 
-async function runInit(): Promise<void> {
-  const cwd = process.cwd();
+async function runInit(baseDir?: string): Promise<void> {
+  const cwd = baseDir ?? process.cwd();
   const tsconfigPath = path.join(cwd, 'tsconfig.json');
   const existing = await readJSON<Record<string, any>>(tsconfigPath);
 
   if (!existing) {
-    console.log(c('yellow', 'tsconfig.json not found — creating one.'));
+    console.log(c('yellow', `tsconfig.json not found — creating one in ${path.relative(process.cwd(), cwd) || '.'}.`));
     await writeJSON(tsconfigPath, RECOMMENDED_TSCONFIG);
     console.log(c('green', '✅ Created tsconfig.json with required decorator settings.'));
     return;
   }
 
-  // Merge user config on top of recommended, then force required decorator options
   let merged = deepMerge(RECOMMENDED_TSCONFIG as any, existing);
   merged = ensureRequiredTsOptions(merged);
 
@@ -322,7 +349,6 @@ async function runDoctor(): Promise<void> {
 
   let ok = true;
 
-  // Node
   const nodeVer = process.versions.node;
   if (cmpSemver(nodeVer, MIN_NODE) >= 0) {
     console.log(`✅ Node ${nodeVer} (min ${MIN_NODE})`);
@@ -331,7 +357,6 @@ async function runDoctor(): Promise<void> {
     console.log(`❌ Node ${nodeVer} — please upgrade to >= ${MIN_NODE}`);
   }
 
-  // npm
   let npmVer = 'unknown';
   try {
     npmVer = await new Promise<string>((resolve, reject) => {
@@ -352,13 +377,11 @@ async function runDoctor(): Promise<void> {
     console.log('❌ npm not found in PATH');
   }
 
-  // tsconfig.json presence + required fields
   const tsconfigPath = path.join(cwd, 'tsconfig.json');
   if (await fileExists(tsconfigPath)) {
     console.log(`✅ tsconfig.json found`);
     const tsconfig = await readJSON<Record<string, any>>(tsconfigPath);
     const {ok: oks, issues} = checkRequiredTsOptions(tsconfig?.compilerOptions);
-
     for (const line of oks) console.log(c('green', `  ✓ ${line}`));
     if (issues.length) {
       ok = false;
@@ -370,7 +393,6 @@ async function runDoctor(): Promise<void> {
     console.log(`❌ tsconfig.json not found — run ${c('cyan', 'frontmcp init')}`);
   }
 
-  // Entry check (nice to have)
   try {
     const entry = await resolveEntry(cwd);
     console.log(`✅ entry detected: ${path.relative(cwd, entry)}`);
@@ -379,11 +401,8 @@ async function runDoctor(): Promise<void> {
     console.log(`❌ entry not detected — ${firstLine}`);
   }
 
-  if (ok) {
-    console.log(c('green', '\nAll checks passed. You are ready to go!'));
-  } else {
-    console.log(c('yellow', '\nSome checks failed. See above for fixes.'));
-  }
+  if (ok) console.log(c('green', '\nAll checks passed. You are ready to go!'));
+  else console.log(c('yellow', '\nSome checks failed. See above for fixes.'));
 }
 
 /* ------------------------------- Inspector -------------------------------- */
@@ -399,12 +418,12 @@ function pkgNameFromCwd(cwd: string) {
   return path.basename(cwd).replace(/[^a-zA-Z0-9._-]/g, '-').toLowerCase() || 'frontmcp-app';
 }
 
-async function upsertPackageJson(cwd: string) {
+async function upsertPackageJson(cwd: string, nameOverride: string | undefined, selfVersion: string) {
   const pkgPath = path.join(cwd, 'package.json');
   const existing = await readJSON<Record<string, any>>(pkgPath);
 
   const base = {
-    name: pkgNameFromCwd(cwd),
+    name: nameOverride ?? pkgNameFromCwd(cwd),
     version: '0.1.0',
     private: true,
     type: 'module',
@@ -421,33 +440,35 @@ async function upsertPackageJson(cwd: string) {
     },
     dependencies: {
       '@frontmcp/sdk': 'latest',
-      zod: 'latest',
+      zod: '^3.23.8',
+      'reflect-metadata': '^0.2.2',
     },
     devDependencies: {
-      typescript: 'latest',
-      tsx: 'latest',
+      frontmcp: selfVersion,       // exact version used by npx
+      tsx: '^4.20.6',
+      typescript: '^5.5.3',
     },
   };
 
   if (!existing) {
     await writeJSON(pkgPath, base);
-    console.log(c('green', '✅ Created package.json (with scripts: dev, build, inspect, doctor)'));
+    console.log(c('green', '✅ Created package.json (pinned tsx/typescript/zod/reflect-metadata, exact frontmcp)'));
     return;
   }
 
-  // Merge, preserving user fields; ensure our requirements exist
   const merged = {...base, ...existing};
 
+  merged.name = existing.name || base.name;
   merged.main = existing.main || base.main;
   merged.type = existing.type || base.type;
 
   merged.scripts = {
     ...base.scripts,
     ...(existing.scripts || {}),
-    dev: (existing.scripts?.dev ?? base.scripts.dev),
-    build: (existing.scripts?.build ?? base.scripts.build),
-    inspect: (existing.scripts?.inspect ?? base.scripts.inspect),
-    doctor: (existing.scripts?.doctor ?? base.scripts.doctor),
+    dev: existing.scripts?.dev ?? base.scripts.dev,
+    build: existing.scripts?.build ?? base.scripts.build,
+    inspect: existing.scripts?.inspect ?? base.scripts.inspect,
+    doctor: existing.scripts?.doctor ?? base.scripts.doctor,
   };
 
   merged.engines = {
@@ -457,29 +478,34 @@ async function upsertPackageJson(cwd: string) {
   };
 
   merged.dependencies = {
-    ...existing.dependencies,
-    '@frontmcp/sdk': existing.dependencies?.['@frontmcp/sdk'] || base.dependencies['@frontmcp/sdk'],
-    zod: existing.dependencies?.zod || base.dependencies.zod,
+    ...base.dependencies,
+    ...(existing.dependencies || {}),
+    // ensure pins
+    zod: '^3.23.8',
+    'reflect-metadata': '^0.2.2',
   };
 
   merged.devDependencies = {
-    ...existing.devDependencies,
-    typescript: existing.devDependencies?.typescript || base.devDependencies.typescript,
-    tsx: existing.devDependencies?.tsx || base.devDependencies.tsx,
+    ...base.devDependencies,
+    ...(existing.devDependencies || {}),
+    // ensure pins
+    frontmcp: selfVersion,
+    tsx: '^4.20.6',
+    typescript: '^5.5.3',
   };
 
   await writeJSON(pkgPath, merged);
-  console.log(c('green', '✅ Updated package.json (ensured scripts, engines, deps)'));
+  console.log(c('green', '✅ Updated package.json (ensured exact frontmcp and pinned versions)'));
 }
 
-async function scaffoldFileIfMissing(p: string, content: string) {
+async function scaffoldFileIfMissing(baseDir: string, p: string, content: string) {
   if (await fileExists(p)) {
-    console.log(c('gray', `skip: ${path.relative(process.cwd(), p)} already exists`));
+    console.log(c('gray', `skip: ${path.relative(baseDir, p)} already exists`));
     return;
   }
   await ensureDir(path.dirname(p));
   await fsp.writeFile(p, content.replace(/^\n/, ''), 'utf8');
-  console.log(c('green', `✓ created ${path.relative(process.cwd(), p)}`));
+  console.log(c('green', `✓ created ${path.relative(baseDir, p)}`));
 }
 
 const TEMPLATE_MAIN_TS = `
@@ -527,28 +553,48 @@ const AddTool = tool({
 export default AddTool;
 `;
 
-async function runCreate(): Promise<void> {
-  const cwd = process.cwd();
+async function runCreate(projectArg?: string): Promise<void> {
+  if (!projectArg) {
+    console.error(c('red', 'Error: project name is required.\n'));
+    console.log(`Usage: ${c('bold', 'npx frontmcp create <project-name>')}`);
+    process.exit(1);
+  }
+
+  const folder = sanitizeForFolder(projectArg);
+  const pkgName = sanitizeForNpm(projectArg);
+  const targetDir = path.resolve(process.cwd(), folder);
 
-  console.log(c('cyan', '[create]'), 'Scaffolding FrontMCP project in', c('bold', cwd));
+  if (await fileExists(targetDir)) {
+    if (!(await isDirEmpty(targetDir))) {
+      console.error(c('red', `Refusing to scaffold into non-empty directory: ${path.relative(process.cwd(), targetDir)}`));
+      console.log(c('gray', 'Pick a different name or start with an empty folder.'));
+      process.exit(1);
+    }
+  } else {
+    await ensureDir(targetDir);
+  }
+
+  console.log(`${c('cyan', '[create]')} Creating project in ${c('bold', './' + path.relative(process.cwd(), targetDir))}`);
+  process.chdir(targetDir);
 
   // 1) tsconfig
-  await runInit();
+  await runInit(targetDir);
 
-  // 2) package.json
-  await upsertPackageJson(cwd);
+  // 2) package.json (with pinned deps and exact frontmcp version)
+  const selfVersion = await getSelfVersion();
+  await upsertPackageJson(targetDir, pkgName, selfVersion);
 
   // 3) files
-  await scaffoldFileIfMissing(path.join(cwd, 'src', 'main.ts'), TEMPLATE_MAIN_TS);
-  await scaffoldFileIfMissing(path.join(cwd, 'src', 'calc.app.ts'), TEMPLATE_CALC_APP_TS);
-  await scaffoldFileIfMissing(path.join(cwd, 'src', 'tools', 'add.tool.ts'), TEMPLATE_ADD_TOOL_TS);
+  await scaffoldFileIfMissing(targetDir, path.join(targetDir, 'src', 'main.ts'), TEMPLATE_MAIN_TS);
+  await scaffoldFileIfMissing(targetDir, path.join(targetDir, 'src', 'calc.app.ts'), TEMPLATE_CALC_APP_TS);
+  await scaffoldFileIfMissing(targetDir, path.join(targetDir, 'src', 'tools', 'add.tool.ts'), TEMPLATE_ADD_TOOL_TS);
 
-  // 4) final tips
   console.log('\nNext steps:');
-  console.log('  1) npm install');
-  console.log('  2) npm run dev   ', c('gray', '# starts tsx watcher via frontmcp dev'));
-  console.log('  3) npm run inspect', c('gray', '# launch MCP Inspector'));
-  console.log('  4) npm run build ', c('gray', '# compile with tsc via frontmcp build'));
+  console.log(`  1) cd ${folder}`);
+  console.log('  2) npm install');
+  console.log('  3) npm run dev     ', c('gray', '# starts tsx watcher via frontmcp dev'));
+  console.log('  4) npm run inspect ', c('gray', '# launch MCP Inspector'));
+  console.log('  5) npm run build   ', c('gray', '# compile with tsc via frontmcp build'));
 }
 
 /* --------------------------------- Main ----------------------------------- */
@@ -581,9 +627,11 @@ async function main(): Promise<void> {
       case 'inspector':
         await runInspector();
         break;
-      case 'create':
-        await runCreate();
+      case 'create': {
+        const projectName = parsed._[1]; // require a name
+        await runCreate(projectName);
         break;
+      }
       case 'help':
         showHelp();
         break;