frontmcp 0.1.2 → 0.1.3

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              Scaffold a new FrontMCP project in the current directory
   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
 `);
 }
 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);
@@ -226,11 +235,20 @@ function runBuild(opts) {
         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,6 +273,44 @@ function deepMerge(base, patch) {
     }
     return out;
 }
+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;
+    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() {
     return __awaiter(this, void 0, void 0, function* () {
         const cwd = process.cwd();
@@ -262,15 +318,15 @@ function runInit() {
         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'));
+            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'));
+        // 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);
+        console.log(c('green', '✅ tsconfig.json verified and updated (required decorator settings enforced).'));
     });
 }
 function cmpSemver(a, b) {
@@ -287,8 +343,8 @@ 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
@@ -323,10 +379,20 @@ function runDoctor() {
             ok = false;
             console.log('❌ npm not found in PATH');
         }
-        // tsconfig.json presence
+        // tsconfig.json presence + required fields
         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;
@@ -349,6 +415,137 @@ function runDoctor() {
         }
     });
 }
+/* ------------------------------- 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) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+        const pkgPath = path.join(cwd, 'package.json');
+        const existing = yield readJSON(pkgPath);
+        const base = {
+            name: 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: 'latest',
+            },
+            devDependencies: {
+                typescript: 'latest',
+                tsx: 'latest',
+            },
+        };
+        if (!existing) {
+            yield writeJSON(pkgPath, base);
+            console.log(c('green', '✅ Created package.json (with scripts: dev, build, inspect, doctor)'));
+            return;
+        }
+        // Merge, preserving user fields; ensure our requirements exist
+        const merged = Object.assign(Object.assign({}, base), existing);
+        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({}, 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 });
+        yield writeJSON(pkgPath, merged);
+        console.log(c('green', '✅ Updated package.json (ensured scripts, engines, deps)'));
+    });
+}
+function scaffoldFileIfMissing(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`));
+            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)}`));
+    });
+}
+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() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const cwd = process.cwd();
+        console.log(c('cyan', '[create]'), 'Scaffolding FrontMCP project in', c('bold', cwd));
+        // 1) tsconfig
+        yield runInit();
+        // 2) package.json
+        yield upsertPackageJson(cwd);
+        // 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
+        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'));
+    });
+}
 /* --------------------------------- Main ----------------------------------- */
 function main() {
     return __awaiter(this, void 0, void 0, function* () {
@@ -374,6 +571,12 @@ function main() {
                 case 'doctor':
                     yield runDoctor();
                     break;
+                case 'inspector':
+                    yield runInspector();
+                    break;
+                case 'create':
+                    yield runCreate();
+                    break;
                 case 'help':
                     showHelp();
                     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontmcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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              Scaffold a new FrontMCP project in the current directory
   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
 `);
 }
 
@@ -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);
@@ -195,11 +203,23 @@ async function runBuild(opts: ParsedArgs): Promise<void> {
   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,6 +244,47 @@ function deepMerge<T extends Record<string, any>, U extends Record<string, any>>
   return out as T & U;
 }
 
+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;
+}
+
+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(): Promise<void> {
   const cwd = process.cwd();
   const tsconfigPath = path.join(cwd, 'tsconfig.json');
@@ -231,16 +292,17 @@ async function runInit(): Promise<void> {
 
   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'));
+    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'));
+  // Merge user config on top of recommended, then force required decorator options
+  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,8 +316,8 @@ 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;
@@ -290,10 +352,19 @@ async function runDoctor(): Promise<void> {
     console.log('❌ npm not found in PATH');
   }
 
-  // tsconfig.json presence
+  // 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;
+      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')}`);
@@ -315,6 +386,171 @@ async function runDoctor(): Promise<void> {
   }
 }
 
+/* ------------------------------- 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) {
+  const pkgPath = path.join(cwd, 'package.json');
+  const existing = await readJSON<Record<string, any>>(pkgPath);
+
+  const base = {
+    name: 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: 'latest',
+    },
+    devDependencies: {
+      typescript: 'latest',
+      tsx: 'latest',
+    },
+  };
+
+  if (!existing) {
+    await writeJSON(pkgPath, base);
+    console.log(c('green', '✅ Created package.json (with scripts: dev, build, inspect, doctor)'));
+    return;
+  }
+
+  // Merge, preserving user fields; ensure our requirements exist
+  const merged = {...base, ...existing};
+
+  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 = {
+    ...existing.dependencies,
+    '@frontmcp/sdk': existing.dependencies?.['@frontmcp/sdk'] || base.dependencies['@frontmcp/sdk'],
+    zod: existing.dependencies?.zod || base.dependencies.zod,
+  };
+
+  merged.devDependencies = {
+    ...existing.devDependencies,
+    typescript: existing.devDependencies?.typescript || base.devDependencies.typescript,
+    tsx: existing.devDependencies?.tsx || base.devDependencies.tsx,
+  };
+
+  await writeJSON(pkgPath, merged);
+  console.log(c('green', '✅ Updated package.json (ensured scripts, engines, deps)'));
+}
+
+async function scaffoldFileIfMissing(p: string, content: string) {
+  if (await fileExists(p)) {
+    console.log(c('gray', `skip: ${path.relative(process.cwd(), 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)}`));
+}
+
+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(): Promise<void> {
+  const cwd = process.cwd();
+
+  console.log(c('cyan', '[create]'), 'Scaffolding FrontMCP project in', c('bold', cwd));
+
+  // 1) tsconfig
+  await runInit();
+
+  // 2) package.json
+  await upsertPackageJson(cwd);
+
+  // 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);
+
+  // 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'));
+}
+
 /* --------------------------------- Main ----------------------------------- */
 
 async function main(): Promise<void> {
@@ -342,6 +578,12 @@ async function main(): Promise<void> {
       case 'doctor':
         await runDoctor();
         break;
+      case 'inspector':
+        await runInspector();
+        break;
+      case 'create':
+        await runCreate();
+        break;
       case 'help':
         showHelp();
         break;