swallowkit 2.0.0-alpha.3 → 2.0.0-alpha.4

package/src/core/scaffold/ui-generator.ts

@@ -3,7 +3,7 @@
  * CRUD 画面（一覧、詳細、新規作成、編集）を生成する
  */
 
-import { ModelInfo, toCamelCase, toKebabCase } from "./model-parser";
+import { FieldInfo, ModelInfo, toCamelCase, toKebabCase } from "./model-parser";
 import { ModelAuthPolicy } from "../../types";
 
 /** auth が有効かつ authPolicy が存在する場合に渡されるオプション */
@@ -18,6 +18,21 @@ export interface UIAuthOptions {
 /**
  * 認証付きCRUDルートを、ページ側のuseAuthと同じAuthProviderで囲むレイアウトを生成する。
  */
+/** Lookup state and fetches are per referenced model; several fields may reference the same model. */
+function uniqueByReferencedModel(fields: FieldInfo[]): FieldInfo[] {
+  const seen = new Set<string>();
+  return fields.filter((field) => {
+    if (!field.referencedModel || seen.has(field.referencedModel)) return false;
+    seen.add(field.referencedModel);
+    return true;
+  });
+}
+
+/** Untyped or inline z.object fields (not references to another model) are edited and shown as JSON. */
+function isJsonField(f: FieldInfo): boolean {
+  return f.type === "object" && !f.isNestedSchema;
+}
+
 export function generateAuthLayout(model: ModelInfo, authOptions?: UIAuthOptions): string | undefined {
   if (!authOptions) return undefined;
 
@@ -59,14 +74,14 @@ export function generateListPage(model: ModelInfo, sharedPackageName: string, au
   const hasForeignKeys = foreignKeyFields.length > 0;
   
   // 外部キー用のstate定義を生成
-  const foreignKeyStates = foreignKeyFields.map(f => {
+  const foreignKeyStates = uniqueByReferencedModel(foreignKeyFields).map(f => {
     const refModel = f.referencedModel!;
     const refModelCamel = toCamelCase(refModel);
     return `  const [${refModelCamel}Map, set${refModel}Map] = useState<Record<string, string>>({});`;
   }).join('\n');
   
   // 外部キーデータのフェッチロジックを生成
-  const foreignKeyFetches = foreignKeyFields.map(f => {
+  const foreignKeyFetches = uniqueByReferencedModel(foreignKeyFields).map(f => {
     const refModel = f.referencedModel!;
     const refModelCamel = toCamelCase(refModel);
     return `    fetch('/api/${refModelCamel}')
@@ -234,6 +249,10 @@ ${displayFields.map(f => {
     return `                  <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-900 dark:text-gray-100">
                     {${refModelCamel}Map[item.${f.name}] || item.${f.name}}
                   </td>`;
+  } else if (isJsonField(f)) {
+    return `                  <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-900 dark:text-gray-100">
+                    {item.${f.name} === undefined ? '-' : JSON.stringify(item.${f.name})}
+                  </td>`;
   } else {
     return `                  <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-900 dark:text-gray-100">
                     {String(item.${f.name})}
@@ -305,14 +324,14 @@ export function generateDetailPage(model: ModelInfo, sharedPackageName: string,
   const hasForeignKeys = foreignKeyFields.length > 0;
   
   // 外部キー用のstate定義を生成
-  const foreignKeyStates = foreignKeyFields.map(f => {
+  const foreignKeyStates = uniqueByReferencedModel(foreignKeyFields).map(f => {
     const refModel = f.referencedModel!;
     const refModelCamel = toCamelCase(refModel);
     return `  const [${refModelCamel}Map, set${refModel}Map] = useState<Record<string, string>>({});`;
   }).join('\n');
   
   // 外部キーデータのフェッチロジックを生成
-  const foreignKeyFetches = foreignKeyFields.map(f => {
+  const foreignKeyFetches = uniqueByReferencedModel(foreignKeyFields).map(f => {
     const refModel = f.referencedModel!;
     const refModelCamel = toCamelCase(refModel);
     return `    fetch('/api/${refModelCamel}')
@@ -476,6 +495,11 @@ ${model.fields.map(f => {
               <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">${refModel}</dt>
               <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100">{${refModelCamel}Map[${modelCamel}.${f.name}] || ${modelCamel}.${f.name}}</dd>
             </div>`;
+  } else if (isJsonField(f)) {
+    return `            <div>
+              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">${f.name}</dt>
+              <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100"><pre className="whitespace-pre-wrap">{${modelCamel}.${f.name} === undefined ? '-' : JSON.stringify(${modelCamel}.${f.name}, null, 2)}</pre></dd>
+            </div>`;
   } else {
     return `            <div>
               <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">${f.name}</dt>
@@ -573,7 +597,7 @@ export default function ${modelName}Form({ initialData, isEdit = false }: ${mode
   const router = useRouter();
   const [loading, setLoading] = useState(false);
   const [errors, setErrors] = useState<Record<string, string>>({});
-${hasForignKeys ? foreignKeyFields.map(f => `  const [${toCamelCase(f.referencedModel!)}Options, set${f.referencedModel}Options] = useState<Array<{ id: string; name: string }>>([]);`).join('\n') : ''}
+${hasForignKeys ? uniqueByReferencedModel(foreignKeyFields).map(f => `  const [${toCamelCase(f.referencedModel!)}Options, set${f.referencedModel}Options] = useState<Array<{ id: string; name: string }>>([]);`).join('\n') : ''}
 ${hasNestedSchemas ? nestedSchemaStates : ''}
   
   const [formData, setFormData] = useState({
@@ -587,6 +611,11 @@ ${formFields.map(f => {
     }
   }
   
+  // インラインオブジェクトは JSON テキストとして編集する
+  if (isJsonField(f)) {
+    return `    ${f.name}: initialData?.${f.name} !== undefined ? JSON.stringify(initialData.${f.name}, null, 2) : '',`;
+  }
+
   let defaultValue = "''";
   if (f.isArray) {
     // Array の場合は空文字列（カンマ区切りで入力するため）
@@ -612,7 +641,7 @@ ${formFields.map(f => {
 ${needsUseEffect ? `
   // 参照データの選択肢を取得
   useEffect(() => {
-${hasForignKeys ? foreignKeyFields.map(f => `    // ${f.referencedModel} の一覧を取得
+${hasForignKeys ? uniqueByReferencedModel(foreignKeyFields).map(f => `    // ${f.referencedModel} の一覧を取得
     fetch('/api/${toKebabCase(f.referencedModel!)}')
       .then(res => res.json())
       .then(data => set${f.referencedModel}Options(data.map((item: Record<string, string>) => ({ id: item.id, name: item.name || item.title || item.id }))))
@@ -628,7 +657,19 @@ ${hasNestedSchemas ? nestedSchemaFetches : ''}
     try {
       // Array フィールドをカンマ区切りから配列に変換
       const submitData: Record<string, unknown> = { ...formData };
-${formFields.filter(f => f.isArray && !f.isNestedSchema).map(f => `      if (typeof submitData.${f.name} === 'string') {
+${formFields.filter(isJsonField).length > 0 ? `      // JSON フィールド（インラインオブジェクト）を解析
+${formFields.filter(isJsonField).map(f => `      if (submitData.${f.name} === '') {
+        submitData.${f.name} = undefined;
+      } else if (typeof submitData.${f.name} === 'string') {
+        try {
+          submitData.${f.name} = JSON.parse(submitData.${f.name});
+        } catch {
+          setErrors({ ${f.name}: 'Invalid JSON' });
+          setLoading(false);
+          return;
+        }
+      }`).join('\n')}
+` : ''}${formFields.filter(f => f.isArray && !f.isNestedSchema && !isJsonField(f)).map(f => `      if (typeof submitData.${f.name} === 'string') {
         submitData.${f.name} = submitData.${f.name}.split(',').map((s: string) => s.trim()).filter((s: string) => s.length > 0);
       }`).join('\n')}
 ${formFields.filter(f => f.enumValues && f.enumValues.length > 0).length > 0 ? `
@@ -833,6 +874,27 @@ ${f.enumValues.map(v => `          <option value="${v}">${v}</option>`).join('\n
       </div>`;
   }
   
+  // インラインオブジェクトは JSON テキストエリア
+  if (isJsonField(f)) {
+    return `      <div>
+        <label htmlFor="${f.name}" className="block text-sm font-medium text-gray-700 dark:text-gray-300">
+          ${f.name}${!f.isOptional ? ' *' : ''} <span className="text-xs text-gray-500">(JSON)</span>
+        </label>
+        <textarea
+          id="${f.name}"
+          name="${f.name}"
+          rows={4}
+          value={formData.${f.name}}
+          onChange={(e) => setFormData({ ...formData, ${f.name}: e.target.value })}
+          className="mt-1 block w-full rounded-md border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 shadow-sm px-3 py-2 font-mono focus:border-blue-500 focus:ring-blue-500 dark:focus:border-blue-400 dark:focus:ring-blue-400"
+          ${!f.isOptional ? 'required' : ''}
+        />
+        {errors.${f.name} && (
+          <p className="mt-1 text-sm text-red-600 dark:text-red-400">{errors.${f.name}}</p>
+        )}
+      </div>`;
+  }
+
   // Array の場合はカンマ区切りテキスト
   if (f.isArray) {
     return `      <div>

package/src/core/verify/index.ts

@@ -253,6 +253,8 @@ function runTypecheckCheck(projectRoot: string): VerifyCheckResult {
 
   const scripts = readPackageScripts(projectRoot);
   const pm = detectFromProject(projectRoot);
+  // Next.js App Router templates use generated route types (e.g. LayoutProps); create them before tsc.
+  const typegenNotes = runNextTypegenIfPresent(projectRoot, pm);
   let command: string;
   let args: string[];
   if (typeof scripts.typecheck === "string") {
@@ -263,13 +265,33 @@ function runTypecheckCheck(projectRoot: string): VerifyCheckResult {
     args = pm === "pnpm" ? ["exec", "tsc", "--noEmit"] : ["exec", "tsc", "--", "--noEmit"];
   }
 
-  return runCommandCheck(projectRoot, {
+  const result = runCommandCheck(projectRoot, {
     id: "typecheck",
     title: "TypeScript type check",
     command,
     args,
     failAction: "Fix the TypeScript errors listed in evidence.logTail, then re-run verify.",
   });
+  if (result.status !== "pass" && typegenNotes.length > 0) {
+    result.evidence.logTail = [...typegenNotes, ...(result.evidence.logTail ?? [])];
+  }
+  return result;
+}
+
+const NEXT_CONFIG_FILES = ["next.config.ts", "next.config.js", "next.config.mjs", "next.config.cjs"];
+
+function runNextTypegenIfPresent(projectRoot: string, pm: ReturnType<typeof detectFromProject>): string[] {
+  if (!NEXT_CONFIG_FILES.some((file) => fs.existsSync(path.join(projectRoot, file)))) return [];
+  if (!fs.existsSync(path.join(projectRoot, "node_modules", "next", "package.json"))) return [];
+  const args = pm === "pnpm" ? ["exec", "next", "typegen"] : ["exec", "--", "next", "typegen"];
+  const result = spawnSync(getCommands(pm).name, args, {
+    cwd: projectRoot,
+    shell: true,
+    encoding: "utf-8",
+    timeout: 2 * 60 * 1000,
+  });
+  if (!result.error && result.status === 0) return [];
+  return [`next typegen did not complete (${result.error?.message ?? `exit ${result.status}`}); route types such as LayoutProps may be missing.`];
 }
 
 const SCRIPT_CHECK_TITLES: Record<string, string> = {

package/src/machine/index.ts

@@ -274,7 +274,8 @@ function createMachineProgram(): Command {
     .option("--functions-dir <dir>", "Functions directory", "functions")
     .option("--api-dir <dir>", "BFF routes directory (Next.js: app/api; React: bff)")
     .option("--api-only", "Skip UI components; still update Functions, BFF routes, OpenAPI, and native schema assets", false)
-    .action(async (model: string, options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+    .option("--skip-infra", "Do not create or update anything under infra/ (container migration is reported as pending)", false)
+    .action(async (model: string, options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
       await handleMachineAction("generate-scaffold", async () => {
         ensureProjectForMachine();
         return runMachineScaffoldOperation({
@@ -282,6 +283,7 @@ function createMachineProgram(): Command {
         functionsDir: options.functionsDir,
         apiDir: options.apiDir,
         apiOnly: options.apiOnly,
+        skipInfra: options.skipInfra,
       });
       });
     });
@@ -294,7 +296,8 @@ function createMachineProgram(): Command {
     .option("--functions-dir <dir>", "Functions directory", "functions")
     .option("--api-dir <dir>", "BFF routes directory (Next.js: app/api; React: bff)")
     .option("--api-only", "Skip UI components in the plan", false)
-    .action(async (models: string[], options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+    .option("--skip-infra", "Exclude all infra/ changes (container migration) from the plan", false)
+    .action(async (models: string[], options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
       await handleMachineAction(
         "plan-scaffold",
         async () => {
@@ -307,6 +310,7 @@ function createMachineProgram(): Command {
                 functionsDir: options.functionsDir,
                 apiDir: options.apiDir,
                 apiOnly: options.apiOnly,
+                skipInfra: options.skipInfra,
               })
             );
           }
@@ -316,12 +320,20 @@ function createMachineProgram(): Command {
           const plans = "plans" in data ? data.plans : [data];
           return {
             status: plans.some((planData) => planData.requiresApproval) ? "requires-human" : "complete",
-            nextActions: plans.map((planData) => ({
-              command: `swallowkit machine apply scaffold --plan ${planData.planId}${planData.requiresApproval ? " --approve" : ""}`,
-              description: planData.requiresApproval
-                ? `Apply the plan for ${planData.model} after reviewing the listed conflicts (requires --approve).`
-                : `Apply the plan for ${planData.model}.`,
-            })),
+            nextActions: [
+              ...plans.map((planData) => ({
+                command: `swallowkit machine apply scaffold --plan ${planData.planId}${planData.requiresApproval ? " --approve" : ""}`,
+                description: planData.requiresApproval
+                  ? `Apply the plan for ${planData.model} after reviewing the listed conflicts (requires --approve).`
+                  : `Apply the plan for ${planData.model}.`,
+              })),
+              ...plans
+                .filter((planData) => planData.warnings.some((warning) => warning.startsWith("infra-skipped:")))
+                .map((planData) => ({
+                  command: `swallowkit migrations add-model ${planData.model}`,
+                  description: `Later, when infrastructure changes are allowed, generate only the Cosmos DB container migration for ${planData.model}.`,
+                })),
+            ],
           };
         }
       );
@@ -408,10 +420,11 @@ function createMachineProgram(): Command {
     .option("--functions-dir <dir>", "Functions directory")
     .option("--api-dir <dir>", "API routes directory")
     .option("--api-only", "Skip UI components; still update Functions, BFF routes, OpenAPI, and native schema assets")
+    .option("--skip-infra", "Do not create or update anything under infra/ (container migration is reported as pending)")
     .action(
       async (
         models: string[],
-        options: { plan?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean }
+        options: { plan?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }
       ) => {
         await handleMachineAction(
           "apply-scaffold",
@@ -433,6 +446,7 @@ function createMachineProgram(): Command {
                 functionsDir: options.functionsDir,
                 apiDir: options.apiDir,
                 apiOnly: options.apiOnly,
+                skipInfra: options.skipInfra,
               });
             }
             const results = [];
@@ -444,20 +458,30 @@ function createMachineProgram(): Command {
                   functionsDir: options.functionsDir,
                   apiDir: options.apiDir,
                   apiOnly: options.apiOnly,
+                  skipInfra: options.skipInfra,
                 })
               );
             }
             return { applyType: "scaffold-batch" as const, results };
           },
-          () => ({
-            status: "complete",
-            nextActions: [
-              {
-                command: "swallowkit machine verify project",
-                description: "Verify the project after applying scaffold changes.",
-              },
-            ],
-          })
+          (data) => {
+            const results = "results" in data ? data.results : [data];
+            return {
+              status: "complete",
+              nextActions: [
+                {
+                  command: "swallowkit machine verify project",
+                  description: "Verify the project after applying scaffold changes.",
+                },
+                ...results
+                  .filter((result) => result.warnings.some((warning) => warning.startsWith("infra-skipped:")))
+                  .map((result) => ({
+                    command: `swallowkit migrations add-model ${result.model}`,
+                    description: `The Cosmos DB container migration for ${result.model} is still pending; generate it when infrastructure changes are allowed.`,
+                  })),
+              ],
+            };
+          }
         );
       }
     );

package/src/mcp/index.ts

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
 
+import { spawn } from "child_process";
 import * as path from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod/v4";
 import type { MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
 import { getSwallowKitVersion } from "../version";
+import { detectFromProject, getCommands } from "../utils/package-manager";
+import {
+  MCP_DELEGATED_FROM_ENV,
+  McpVersionContext,
+  buildPinnedUpdateNotice,
+  decideMcpLaunch,
+  resolveProjectSwallowKit,
+} from "./version-selection";
 
 interface MachineSuccessPayload<TData> {
   ok: true;
@@ -70,6 +79,29 @@ async function executeMachineCommand<TData>(
   return parsed;
 }
 
+function defaultVersionContext(): McpVersionContext {
+  return {
+    mcpVersion: getSwallowKitVersion(),
+    requestedVersion: "latest",
+    projectVersion: null,
+    selection: "running-version",
+    delegated: false,
+    warnings: [],
+    nextActions: [],
+  };
+}
+
+function mergeNextActions(
+  first: MachineNextAction[] | undefined,
+  second: MachineNextAction[]
+): MachineNextAction[] {
+  const merged = [...(first ?? [])];
+  for (const action of second) {
+    if (!merged.some((existing) => existing.command === action.command)) merged.push(action);
+  }
+  return merged;
+}
+
 function withOperationStatus<TData>(response: MachineSuccessPayload<TData>): Record<string, unknown> {
   const data = response.data && typeof response.data === "object"
     ? (response.data as Record<string, unknown>)
@@ -92,25 +124,41 @@ function jsonTextContent(value: unknown): { content: Array<{ type: "text"; text:
   };
 }
 
-function withSwallowKitMetadata<TData>(data: TData): TData & { metadata: Record<string, unknown> } {
-  const value = data && typeof data === "object" ? data as Record<string, unknown> : { data };
+function withVersionMetadata(data: unknown, context: McpVersionContext): Record<string, unknown> {
+  const value = data && typeof data === "object" && !Array.isArray(data)
+    ? data as Record<string, unknown>
+    : { data };
   const metadata = value.metadata && typeof value.metadata === "object"
     ? value.metadata as Record<string, unknown>
     : {};
+  const existingNextActions = Array.isArray(value.nextActions) ? value.nextActions as MachineNextAction[] : undefined;
+  const nextActions = mergeNextActions(existingNextActions, context.nextActions);
 
   return {
     ...value,
+    ...(nextActions.length > 0 ? { nextActions } : {}),
     metadata: {
       ...metadata,
-      swallowkitVersion: getSwallowKitVersion(),
+      swallowkitVersion: context.mcpVersion,
+      mcp: {
+        version: context.mcpVersion,
+        requestedVersion: context.requestedVersion,
+        projectVersion: context.projectVersion,
+        selection: context.selection,
+        delegated: context.delegated,
+        ...(context.delegatedFrom ? { delegatedFrom: context.delegatedFrom } : {}),
+      },
+      ...(context.warnings.length > 0 ? { warnings: [...context.warnings] } : {}),
     },
-  } as TData & { metadata: Record<string, unknown> };
+  };
 }
 
 export function buildSwallowKitToolDefinitions(
-  runMachineCli: MachineCliRunner = defaultMachineCliRunner
+  runMachineCli: MachineCliRunner = defaultMachineCliRunner,
+  versionContext: McpVersionContext = defaultVersionContext()
 ): ToolDefinition[] {
-  return [
+  const withSwallowKitMetadata = (data: unknown) => withVersionMetadata(data, versionContext);
+  const definitions: ToolDefinition[] = [
     {
       name: "swallowkit_inspect_project",
       description: "Return framework-owned SwallowKit project metadata.",
@@ -169,8 +217,9 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Do not create or update anything under infra/; the container migration stays pending."),
       }),
-      handler: async ({ model, functionsDir, apiDir, apiOnly }: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, functionsDir, apiDir, apiOnly, skipInfra }: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
       const args = ["generate", "scaffold", model];
       if (functionsDir) {
         args.push("--functions-dir", functionsDir);
@@ -181,6 +230,9 @@ export function buildSwallowKitToolDefinitions(
       if (apiOnly) {
         args.push("--api-only");
       }
+      if (skipInfra) {
+        args.push("--skip-infra");
+      }
 
       const response = await executeMachineCommand(args, runMachineCli);
       return jsonTextContent(response.data);
@@ -195,14 +247,16 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Exclude all infra/ changes (container migration) from the plan."),
       }),
-      handler: async ({ model, models, functionsDir, apiDir, apiOnly }: { model?: string; models?: string[]; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, models, functionsDir, apiDir, apiOnly, skipInfra }: { model?: string; models?: string[]; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
         const targets = models && models.length > 0 ? models : model ? [model] : [];
         if (targets.length === 0) throw new Error("Provide model or models.");
         const args = ["plan", "scaffold", ...targets];
         if (functionsDir) args.push("--functions-dir", functionsDir);
         if (apiDir) args.push("--api-dir", apiDir);
         if (apiOnly) args.push("--api-only");
+        if (skipInfra) args.push("--skip-infra");
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));
@@ -218,8 +272,9 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Do not create or update anything under infra/ (defaults to the plan's setting)."),
       }),
-      handler: async ({ model, planId, approve, functionsDir, apiDir, apiOnly }: { model?: string; planId?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, planId, approve, functionsDir, apiDir, apiOnly, skipInfra }: { model?: string; planId?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
         const args = ["apply", "scaffold"];
         if (model) args.push(model);
         if (planId) args.push("--plan", planId);
@@ -227,6 +282,7 @@ export function buildSwallowKitToolDefinitions(
         if (functionsDir) args.push("--functions-dir", functionsDir);
         if (apiDir) args.push("--api-dir", apiDir);
         if (apiOnly) args.push("--api-only");
+        if (skipInfra) args.push("--skip-infra");
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));
@@ -391,16 +447,28 @@ export function buildSwallowKitToolDefinitions(
       },
     },
   ];
+
+  // Every response reports which SwallowKit version answered and why it was selected.
+  return definitions.map((definition) => ({
+    ...definition,
+    handler: async (input: unknown) => {
+      const result = await definition.handler(input);
+      return jsonTextContent(withSwallowKitMetadata(JSON.parse(result.content[0].text)));
+    },
+  }));
 }
 
-export function createSwallowKitMcpServer(runMachineCli: MachineCliRunner = defaultMachineCliRunner): McpServer {
-  const version = getSwallowKitVersion();
+export function createSwallowKitMcpServer(
+  runMachineCli: MachineCliRunner = defaultMachineCliRunner,
+  versionContext: McpVersionContext = defaultVersionContext()
+): McpServer {
+  const version = versionContext.mcpVersion;
   const server = new McpServer({
     name: "swallowkit-mcp",
     version,
   });
 
-  for (const tool of buildSwallowKitToolDefinitions(runMachineCli)) {
+  for (const tool of buildSwallowKitToolDefinitions(runMachineCli, versionContext)) {
     server.registerTool(
       tool.name,
       {
@@ -414,9 +482,83 @@ export function createSwallowKitMcpServer(runMachineCli: MachineCliRunner = defa
   return server;
 }
 
+function resolveExecCommand(cwd: string): string {
+  try {
+    return getCommands(detectFromProject(cwd)).exec;
+  } catch {
+    return "npx";
+  }
+}
+
+async function fetchPublishedLatest(): Promise<string | null> {
+  if (process.env.SWALLOWKIT_MCP_UPDATE_CHECK === "0") return null;
+  const registry = (process.env.npm_config_registry || "https://registry.npmjs.org").replace(/\/+$/, "");
+  try {
+    const response = await fetch(`${registry}/swallowkit/latest`, { signal: AbortSignal.timeout(3000) });
+    if (!response.ok) return null;
+    const body = await response.json() as { version?: unknown };
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function delegateToProjectMcp(entrypoint: string, fromVersion: string): void {
+  const child = spawn(process.execPath, [entrypoint], {
+    stdio: "inherit",
+    env: { ...process.env, [MCP_DELEGATED_FROM_ENV]: fromVersion },
+  });
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => child.kill(signal));
+  }
+  child.on("error", (error) => {
+    console.error(`[swallowkit-mcp] failed to start the project-installed MCP: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.on("exit", (code, signal) => {
+    process.exitCode = code ?? (signal ? 1 : 0);
+  });
+}
+
 export async function runMcpServer(): Promise<void> {
-  console.error(`[swallowkit-mcp] version: ${getSwallowKitVersion()}`);
-  const server = createSwallowKitMcpServer();
+  const selfVersion = getSwallowKitVersion();
+  const cwd = process.cwd();
+  const execCommand = resolveExecCommand(cwd);
+  const decision = decideMcpLaunch({
+    selfVersion,
+    selfPackageRoot: path.resolve(__dirname, "..", ".."),
+    env: process.env,
+    project: resolveProjectSwallowKit(cwd),
+    execCommand,
+  });
+
+  if (decision.action === "delegate") {
+    console.error(
+      `[swallowkit-mcp] version: ${selfVersion}; delegating to the project-installed swallowkit-mcp ${decision.toVersion} (newer than the launcher).`
+    );
+    delegateToProjectMcp(decision.entrypoint, decision.fromVersion);
+    return;
+  }
+
+  const context = decision.context;
+  // One write keeps the version line and its warnings together for log readers.
+  console.error([
+    `[swallowkit-mcp] version: ${selfVersion} (selection: ${context.selection}${context.delegatedFrom ? `, delegated from ${context.delegatedFrom}` : ""})`,
+    ...context.warnings.map((warning) => `[swallowkit-mcp] warning: ${warning}`),
+  ].join("\n"));
+
+  if (context.selection === "pinned") {
+    void fetchPublishedLatest().then((latest) => {
+      const notice = buildPinnedUpdateNotice(context, latest, execCommand);
+      if (notice) {
+        context.warnings.push(notice.warning);
+        context.nextActions.push(notice.nextAction);
+        console.error(`[swallowkit-mcp] warning: ${notice.warning}`);
+      }
+    });
+  }
+
+  const server = createSwallowKitMcpServer(defaultMachineCliRunner, context);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }