frontmcp 0.1.2 → 0.1.4

package/dist/cli.js

@@ -74,7 +74,9 @@ ${c('bold', 'Commands')}
   dev                 Start in development mode (tsx --watch <entry>)
   build               Compile entry with TypeScript (tsc)
   init                Create or fix a tsconfig.json suitable for FrontMCP
-  doctor              Check Node/npm versions and tsconfig presence
+  doctor              Check Node/npm versions and tsconfig requirements
+  inspector           Launch MCP Inspector (npx @modelcontextprotocol/inspector)
+  create <name>       Scaffold a new FrontMCP project in ./<name>
   help                Show this help message
 
 ${c('bold', 'Options')}
@@ -86,6 +88,8 @@ ${c('bold', 'Examples')}
   frontmcp build --out-dir build
   frontmcp init
   frontmcp doctor
+  frontmcp inspector
+  npx frontmcp create my-mcp
 `);
 }
 function parseArgs(argv) {
@@ -125,6 +129,11 @@ function readJSON(jsonPath) {
         }
     });
 }
+function writeJSON(p, obj) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield fs_1.promises.writeFile(p, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+    });
+}
 function tryCandidates(base) {
     const exts = ['', '.ts', '.tsx', '.js', '.mjs', '.cjs'];
     return exts.map((ext) => base + ext);
@@ -137,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.'),
             '',
@@ -182,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* () {
@@ -192,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);
 }
@@ -220,17 +267,25 @@ 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)}`));
     });
 }
+/* --------------------------- tsconfig management --------------------------- */
+const REQUIRED_DECORATOR_FIELDS = {
+    target: 'es2021',
+    module: 'esnext',
+    emitDecoratorMetadata: true,
+    experimentalDecorators: true,
+};
 const RECOMMENDED_TSCONFIG = {
     compilerOptions: {
-        target: 'ES2020',
-        module: 'CommonJS',
-        moduleResolution: 'Node',
+        target: REQUIRED_DECORATOR_FIELDS.target,
+        module: REQUIRED_DECORATOR_FIELDS.module,
+        emitDecoratorMetadata: REQUIRED_DECORATOR_FIELDS.emitDecoratorMetadata,
+        experimentalDecorators: REQUIRED_DECORATOR_FIELDS.experimentalDecorators,
+        moduleResolution: 'NodeNext',
         strict: true,
         esModuleInterop: true,
         resolveJsonModule: true,
@@ -255,22 +310,58 @@ function deepMerge(base, patch) {
     }
     return out;
 }
-function runInit() {
+function ensureRequiredTsOptions(obj) {
+    const next = Object.assign({}, obj);
+    next.compilerOptions = Object.assign({}, (next.compilerOptions || {}));
+    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;
+}
+function normalizeStr(x) {
+    return typeof x === 'string' ? x.toLowerCase() : undefined;
+}
+function checkRequiredTsOptions(compilerOptions) {
+    const issues = [];
+    const ok = [];
+    const target = normalizeStr(compilerOptions === null || compilerOptions === void 0 ? void 0 : compilerOptions.target);
+    const moduleVal = normalizeStr(compilerOptions === null || compilerOptions === void 0 ? void 0 : compilerOptions.module);
+    const edm = compilerOptions === null || compilerOptions === void 0 ? void 0 : compilerOptions.emitDecoratorMetadata;
+    const ed = compilerOptions === null || compilerOptions === void 0 ? void 0 : compilerOptions.experimentalDecorators;
+    if (target === REQUIRED_DECORATOR_FIELDS.target)
+        ok.push(`compilerOptions.target = "${REQUIRED_DECORATOR_FIELDS.target}"`);
+    else
+        issues.push(`compilerOptions.target should be "${REQUIRED_DECORATOR_FIELDS.target}"`);
+    if (moduleVal === REQUIRED_DECORATOR_FIELDS.module)
+        ok.push(`compilerOptions.module = "${REQUIRED_DECORATOR_FIELDS.module}"`);
+    else
+        issues.push(`compilerOptions.module should be "${REQUIRED_DECORATOR_FIELDS.module}"`);
+    if (edm === REQUIRED_DECORATOR_FIELDS.emitDecoratorMetadata)
+        ok.push(`compilerOptions.emitDecoratorMetadata = true`);
+    else
+        issues.push(`compilerOptions.emitDecoratorMetadata should be true`);
+    if (ed === REQUIRED_DECORATOR_FIELDS.experimentalDecorators)
+        ok.push(`compilerOptions.experimentalDecorators = true`);
+    else
+        issues.push(`compilerOptions.experimentalDecorators should be true`);
+    return { ok, issues };
+}
+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.'));
-            yield fs_1.promises.writeFile(tsconfigPath, JSON.stringify(RECOMMENDED_TSCONFIG, null, 2) + '\n', 'utf8');
-            console.log(c('green', '✅ Created tsconfig.json'));
+            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;
         }
-        // We want to ADD missing recommended fields but NOT override user's existing choices.
-        // So recommended (base) merged with existing (patch) -> existing wins.
-        const fixed = deepMerge(RECOMMENDED_TSCONFIG, existing);
-        yield fs_1.promises.writeFile(tsconfigPath, JSON.stringify(fixed, null, 2) + '\n', 'utf8');
-        console.log(c('green', '✅ tsconfig.json verified/updated'));
+        let merged = deepMerge(RECOMMENDED_TSCONFIG, existing);
+        merged = ensureRequiredTsOptions(merged);
+        yield writeJSON(tsconfigPath, merged);
+        console.log(c('green', '✅ tsconfig.json verified and updated (required decorator settings enforced).'));
     });
 }
 function cmpSemver(a, b) {
@@ -287,11 +378,10 @@ function cmpSemver(a, b) {
 function runDoctor() {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c;
-        const MIN_NODE = '18.0.0';
-        const MIN_NPM = '8.0.0';
+        const MIN_NODE = '22.0.0';
+        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})`);
@@ -300,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) => {
@@ -323,16 +412,24 @@ function runDoctor() {
             ok = false;
             console.log('❌ npm not found in PATH');
         }
-        // tsconfig.json presence
         const tsconfigPath = path.join(cwd, 'tsconfig.json');
         if (yield fileExists(tsconfigPath)) {
             console.log(`✅ tsconfig.json found`);
+            const tsconfig = yield readJSON(tsconfigPath);
+            const { ok: oks, issues } = checkRequiredTsOptions(tsconfig === null || tsconfig === void 0 ? void 0 : tsconfig.compilerOptions);
+            for (const line of oks)
+                console.log(c('green', `  ✓ ${line}`));
+            if (issues.length) {
+                ok = false;
+                for (const line of issues)
+                    console.log(c('yellow', `  • ${line}`));
+                console.log(c('cyan', `  -> Run "frontmcp init" to apply the required settings.`));
+            }
         }
         else {
             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)}`);
@@ -341,12 +438,166 @@ 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
+            console.log(c('yellow', '\nSome checks failed. See above for fixes.'));
+    });
+}
+/* ------------------------------- Inspector -------------------------------- */
+function runInspector() {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log(`${c('cyan', '[inspector]')} launching MCP Inspector...`);
+        yield runCmd('npx', ['-y', '@modelcontextprotocol/inspector']);
+    });
+}
+/* --------------------------------- Create --------------------------------- */
+function pkgNameFromCwd(cwd) {
+    return path.basename(cwd).replace(/[^a-zA-Z0-9._-]/g, '-').toLowerCase() || 'frontmcp-app';
+}
+function upsertPackageJson(cwd, nameOverride, selfVersion) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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: nameOverride !== null && nameOverride !== void 0 ? nameOverride : pkgNameFromCwd(cwd),
+            version: '0.1.0',
+            private: true,
+            type: 'module',
+            main: 'src/main.ts',
+            scripts: {
+                dev: 'frontmcp dev',
+                build: 'frontmcp build',
+                inspect: 'frontmcp inspector',
+                doctor: 'frontmcp doctor',
+            },
+            engines: {
+                node: '>=22',
+                npm: '>=10',
+            },
+            dependencies: {
+                '@frontmcp/sdk': 'latest',
+                zod: '^3.23.8',
+                'reflect-metadata': '^0.2.2',
+            },
+            devDependencies: {
+                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 (pinned tsx/typescript/zod/reflect-metadata, exact frontmcp)'));
+            return;
+        }
+        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.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(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 exact frontmcp and pinned versions)'));
+    });
+}
+function scaffoldFileIfMissing(baseDir, p, content) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (yield fileExists(p)) {
+            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(baseDir, p)}`));
+    });
+}
+const TEMPLATE_MAIN_TS = `
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { CalcApp } from './calc.app';
+
+@FrontMcp({
+  info: { name: 'Demo 🚀', version: '0.1.0' },
+  apps: [CalcApp],
+  auth: {
+    type: 'remote',
+    name: 'my-remote-auth',
+    baseUrl: 'https://idp.example.com',
+  },
+})
+export default class Server {}
+`;
+const TEMPLATE_CALC_APP_TS = `
+import { App } from '@frontmcp/sdk';
+import AddTool from './tools/add.tool';
+
+@App({
+  id: 'calc',
+  name: 'Calculator',
+  tools: [AddTool],
+})
+export class CalcApp {}
+`;
+const TEMPLATE_ADD_TOOL_TS = `
+import { tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const AddTool = tool({
+  name: 'add',
+  description: 'Add two numbers',
+  inputSchema: z.object({ a: z.number(), b: z.number() }),
+  outputSchema: z.object({ result: z.number() }),
+})((input, _ctx) => {
+  return { result: input.a + input.b };
+});
+
+export default AddTool;
+`;
+function runCreate(projectArg) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 {
-            console.log(c('yellow', '\nSome checks failed. See above for fixes.'));
+            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(targetDir);
+        // 2) package.json (with pinned deps and exact frontmcp version)
+        const selfVersion = yield getSelfVersion();
+        yield upsertPackageJson(targetDir, pkgName, selfVersion);
+        // 3) files
+        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) 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 ----------------------------------- */
@@ -374,6 +625,14 @@ function main() {
                 case 'doctor':
                     yield runDoctor();
                     break;
+                case 'inspector':
+                    yield runInspector();
+                    break;
+                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.2",
+  "version": "0.1.4",
   "description": "FrontMCP command line interface",
   "main": "dist/index.js",
   "bin": {
@@ -12,14 +12,15 @@
     "prepare": "npm run build"
   },
   "dependencies": {
-    "@frontmcp/sdk": "0.1.2",
-    "@frontmcp/core": "0.1.2",
-    "@frontmcp/plugins": "0.1.2",
-    "@frontmcp/adapters": "0.1.2",
+    "@frontmcp/sdk": "0.1.3",
+    "@frontmcp/core": "0.1.3",
+    "@frontmcp/plugins": "0.1.3",
+    "@frontmcp/adapters": "0.1.3",
     "tsx": "^4.20.6",
     "typescript": "^5.5.3"
   },
   "devDependencies": {
-    "@types/node": "20.19.9"
+    "@types/node": "20.19.9",
+    "@modelcontextprotocol/inspector": "^0.17.2"
   }
 }

package/src/cli.ts

@@ -11,7 +11,7 @@ import {spawn} from 'child_process';
 
 /* ----------------------------- Types & Helpers ---------------------------- */
 
-type Command = 'dev' | 'build' | 'init' | 'doctor' | 'help';
+type Command = 'dev' | 'build' | 'init' | 'doctor' | 'inspector' | 'create' | 'help';
 
 interface ParsedArgs {
   _: string[];
@@ -45,7 +45,9 @@ ${c('bold', 'Commands')}
   dev                 Start in development mode (tsx --watch <entry>)
   build               Compile entry with TypeScript (tsc)
   init                Create or fix a tsconfig.json suitable for FrontMCP
-  doctor              Check Node/npm versions and tsconfig presence
+  doctor              Check Node/npm versions and tsconfig requirements
+  inspector           Launch MCP Inspector (npx @modelcontextprotocol/inspector)
+  create <name>       Scaffold a new FrontMCP project in ./<name>
   help                Show this help message
 
 ${c('bold', 'Options')}
@@ -57,6 +59,8 @@ ${c('bold', 'Examples')}
   frontmcp build --out-dir build
   frontmcp init
   frontmcp doctor
+  frontmcp inspector
+  npx frontmcp create my-mcp
 `);
 }
 
@@ -90,6 +94,10 @@ async function readJSON<T = any>(jsonPath: string): Promise<T | null> {
   }
 }
 
+async function writeJSON(p: string, obj: any) {
+  await fsp.writeFile(p, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+}
+
 function tryCandidates(base: string): string[] {
   const exts = ['', '.ts', '.tsx', '.js', '.mjs', '.cjs'];
   return exts.map((ext) => base + ext);
@@ -101,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.'),
     '',
@@ -147,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> {
@@ -157,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);
 }
@@ -189,17 +229,28 @@ 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)}`));
 }
 
+/* --------------------------- tsconfig management --------------------------- */
+
+const REQUIRED_DECORATOR_FIELDS = {
+  target: 'es2021',
+  module: 'esnext',
+  emitDecoratorMetadata: true,
+  experimentalDecorators: true,
+} as const;
+
 const RECOMMENDED_TSCONFIG = {
   compilerOptions: {
-    target: 'ES2020',
-    module: 'CommonJS',
-    moduleResolution: 'Node',
+    target: REQUIRED_DECORATOR_FIELDS.target,
+    module: REQUIRED_DECORATOR_FIELDS.module,
+    emitDecoratorMetadata: REQUIRED_DECORATOR_FIELDS.emitDecoratorMetadata,
+    experimentalDecorators: REQUIRED_DECORATOR_FIELDS.experimentalDecorators,
+
+    moduleResolution: 'NodeNext',
     strict: true,
     esModuleInterop: true,
     resolveJsonModule: true,
@@ -224,23 +275,61 @@ function deepMerge<T extends Record<string, any>, U extends Record<string, any>>
   return out as T & U;
 }
 
-async function runInit(): Promise<void> {
-  const cwd = process.cwd();
+function ensureRequiredTsOptions(obj: Record<string, any>): Record<string, any> {
+  const next = {...obj};
+  next.compilerOptions = {...(next.compilerOptions || {})};
+  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;
+}
+
+function normalizeStr(x: unknown): string | undefined {
+  return typeof x === 'string' ? x.toLowerCase() : undefined;
+}
+
+function checkRequiredTsOptions(compilerOptions: Record<string, any> | undefined) {
+  const issues: string[] = [];
+  const ok: string[] = [];
+
+  const target = normalizeStr(compilerOptions?.target);
+  const moduleVal = normalizeStr(compilerOptions?.module);
+  const edm = compilerOptions?.emitDecoratorMetadata;
+  const ed = compilerOptions?.experimentalDecorators;
+
+  if (target === REQUIRED_DECORATOR_FIELDS.target) ok.push(`compilerOptions.target = "${REQUIRED_DECORATOR_FIELDS.target}"`);
+  else issues.push(`compilerOptions.target should be "${REQUIRED_DECORATOR_FIELDS.target}"`);
+
+  if (moduleVal === REQUIRED_DECORATOR_FIELDS.module) ok.push(`compilerOptions.module = "${REQUIRED_DECORATOR_FIELDS.module}"`);
+  else issues.push(`compilerOptions.module should be "${REQUIRED_DECORATOR_FIELDS.module}"`);
+
+  if (edm === REQUIRED_DECORATOR_FIELDS.emitDecoratorMetadata) ok.push(`compilerOptions.emitDecoratorMetadata = true`);
+  else issues.push(`compilerOptions.emitDecoratorMetadata should be true`);
+
+  if (ed === REQUIRED_DECORATOR_FIELDS.experimentalDecorators) ok.push(`compilerOptions.experimentalDecorators = true`);
+  else issues.push(`compilerOptions.experimentalDecorators should be true`);
+
+  return {ok, issues};
+}
+
+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.'));
-    await fsp.writeFile(tsconfigPath, JSON.stringify(RECOMMENDED_TSCONFIG, null, 2) + '\n', 'utf8');
-    console.log(c('green', '✅ Created tsconfig.json'));
+    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;
   }
 
-  // We want to ADD missing recommended fields but NOT override user's existing choices.
-  // So recommended (base) merged with existing (patch) -> existing wins.
-  const fixed = deepMerge(RECOMMENDED_TSCONFIG as any, existing);
-  await fsp.writeFile(tsconfigPath, JSON.stringify(fixed, null, 2) + '\n', 'utf8');
-  console.log(c('green', '✅ tsconfig.json verified/updated'));
+  let merged = deepMerge(RECOMMENDED_TSCONFIG as any, existing);
+  merged = ensureRequiredTsOptions(merged);
+
+  await writeJSON(tsconfigPath, merged);
+  console.log(c('green', '✅ tsconfig.json verified and updated (required decorator settings enforced).'));
 }
 
 function cmpSemver(a: string, b: string): number {
@@ -254,13 +343,12 @@ function cmpSemver(a: string, b: string): number {
 }
 
 async function runDoctor(): Promise<void> {
-  const MIN_NODE = '18.0.0';
-  const MIN_NPM = '8.0.0';
+  const MIN_NODE = '22.0.0';
+  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})`);
@@ -269,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) => {
@@ -290,16 +377,22 @@ async function runDoctor(): Promise<void> {
     console.log('❌ npm not found in PATH');
   }
 
-  // tsconfig.json presence
   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;
+      for (const line of issues) console.log(c('yellow', `  • ${line}`));
+      console.log(c('cyan', `  -> Run "frontmcp init" to apply the required settings.`));
+    }
   } else {
     ok = false;
     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)}`);
@@ -308,11 +401,200 @@ 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!'));
+  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 -------------------------------- */
+
+async function runInspector(): Promise<void> {
+  console.log(`${c('cyan', '[inspector]')} launching MCP Inspector...`);
+  await runCmd('npx', ['-y', '@modelcontextprotocol/inspector']);
+}
+
+/* --------------------------------- Create --------------------------------- */
+
+function pkgNameFromCwd(cwd: string) {
+  return path.basename(cwd).replace(/[^a-zA-Z0-9._-]/g, '-').toLowerCase() || 'frontmcp-app';
+}
+
+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: nameOverride ?? pkgNameFromCwd(cwd),
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+    main: 'src/main.ts',
+    scripts: {
+      dev: 'frontmcp dev',
+      build: 'frontmcp build',
+      inspect: 'frontmcp inspector',
+      doctor: 'frontmcp doctor',
+    },
+    engines: {
+      node: '>=22',
+      npm: '>=10',
+    },
+    dependencies: {
+      '@frontmcp/sdk': 'latest',
+      zod: '^3.23.8',
+      'reflect-metadata': '^0.2.2',
+    },
+    devDependencies: {
+      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 (pinned tsx/typescript/zod/reflect-metadata, exact frontmcp)'));
+    return;
+  }
+
+  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,
+  };
+
+  merged.engines = {
+    ...(existing.engines || {}),
+    node: existing.engines?.node || base.engines.node,
+    npm: existing.engines?.npm || base.engines.npm,
+  };
+
+  merged.dependencies = {
+    ...base.dependencies,
+    ...(existing.dependencies || {}),
+    // ensure pins
+    zod: '^3.23.8',
+    'reflect-metadata': '^0.2.2',
+  };
+
+  merged.devDependencies = {
+    ...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 exact frontmcp and pinned versions)'));
+}
+
+async function scaffoldFileIfMissing(baseDir: string, p: string, content: string) {
+  if (await fileExists(p)) {
+    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(baseDir, p)}`));
+}
+
+const TEMPLATE_MAIN_TS = `
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { CalcApp } from './calc.app';
+
+@FrontMcp({
+  info: { name: 'Demo 🚀', version: '0.1.0' },
+  apps: [CalcApp],
+  auth: {
+    type: 'remote',
+    name: 'my-remote-auth',
+    baseUrl: 'https://idp.example.com',
+  },
+})
+export default class Server {}
+`;
+
+const TEMPLATE_CALC_APP_TS = `
+import { App } from '@frontmcp/sdk';
+import AddTool from './tools/add.tool';
+
+@App({
+  id: 'calc',
+  name: 'Calculator',
+  tools: [AddTool],
+})
+export class CalcApp {}
+`;
+
+const TEMPLATE_ADD_TOOL_TS = `
+import { tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const AddTool = tool({
+  name: 'add',
+  description: 'Add two numbers',
+  inputSchema: z.object({ a: z.number(), b: z.number() }),
+  outputSchema: z.object({ result: z.number() }),
+})((input, _ctx) => {
+  return { result: input.a + input.b };
+});
+
+export default AddTool;
+`;
+
+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);
+
+  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 {
-    console.log(c('yellow', '\nSome checks failed. See above for fixes.'));
+    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(targetDir);
+
+  // 2) package.json (with pinned deps and exact frontmcp version)
+  const selfVersion = await getSelfVersion();
+  await upsertPackageJson(targetDir, pkgName, selfVersion);
+
+  // 3) files
+  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);
+
+  console.log('\nNext steps:');
+  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 ----------------------------------- */
@@ -342,6 +624,14 @@ async function main(): Promise<void> {
       case 'doctor':
         await runDoctor();
         break;
+      case 'inspector':
+        await runInspector();
+        break;
+      case 'create': {
+        const projectName = parsed._[1]; // require a name
+        await runCreate(projectName);
+        break;
+      }
       case 'help':
         showHelp();
         break;