swallowkit 1.0.0-beta.9 → 1.0.1

package/src/mcp/index.ts

@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+
+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";
+
+interface MachineSuccessPayload<TData> {
+  ok: true;
+  command: string;
+  status?: MachineOperationStatus;
+  nextActions?: MachineNextAction[];
+  data: TData;
+}
+
+type MachineCliRunner = (args: string[]) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+type ToolContentResult = { content: Array<{ type: "text"; text: string }> };
+type ToolDefinition = {
+  name: string;
+  description: string;
+  inputSchema: z.ZodTypeAny;
+  handler: (input: any) => Promise<ToolContentResult>;
+};
+type ExecaModule = typeof import("execa");
+
+// Keep this as a runtime dynamic import so CommonJS builds do not rewrite it to require().
+const importModule = new Function("specifier", "return import(specifier);") as (
+  specifier: string
+) => Promise<ExecaModule>;
+
+function resolveMachineCliEntrypoint(): string {
+  return path.resolve(__dirname, "..", "cli", "index.js");
+}
+
+async function defaultMachineCliRunner(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const { execa } = await importModule("execa");
+  const result = await execa(process.execPath, [resolveMachineCliEntrypoint(), "machine", ...args], {
+    reject: false,
+  });
+
+  return {
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode ?? 0,
+  };
+}
+
+async function executeMachineCommand<TData>(
+  args: string[],
+  runMachineCli: MachineCliRunner
+): Promise<MachineSuccessPayload<TData>> {
+  const result = await runMachineCli(args);
+
+  let parsed: MachineResponse<TData>;
+  try {
+    parsed = JSON.parse(result.stdout) as MachineResponse<TData>;
+  } catch {
+    throw new Error(result.stderr || result.stdout || "Machine CLI returned invalid JSON.");
+  }
+
+  if (!parsed.ok) {
+    const detailsSuffix =
+      parsed.error.details !== undefined ? `\ndetails: ${JSON.stringify(parsed.error.details)}` : "";
+    const statusSuffix = parsed.status ? ` (status: ${parsed.status})` : "";
+    throw new Error(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`);
+  }
+
+  return parsed;
+}
+
+function withOperationStatus<TData>(response: MachineSuccessPayload<TData>): Record<string, unknown> {
+  const data = response.data && typeof response.data === "object"
+    ? (response.data as Record<string, unknown>)
+    : { data: response.data };
+  return {
+    status: response.status ?? "complete",
+    ...(response.nextActions && response.nextActions.length > 0 ? { nextActions: response.nextActions } : {}),
+    ...data,
+  };
+}
+
+function jsonTextContent(value: unknown): { content: Array<{ type: "text"; text: string }> } {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}
+
+function withSwallowKitMetadata<TData>(data: TData): TData & { metadata: Record<string, unknown> } {
+  const value = data && typeof data === "object" ? data as Record<string, unknown> : { data };
+  const metadata = value.metadata && typeof value.metadata === "object"
+    ? value.metadata as Record<string, unknown>
+    : {};
+
+  return {
+    ...value,
+    metadata: {
+      ...metadata,
+      swallowkitVersion: getSwallowKitVersion(),
+    },
+  } as TData & { metadata: Record<string, unknown> };
+}
+
+export function buildSwallowKitToolDefinitions(
+  runMachineCli: MachineCliRunner = defaultMachineCliRunner
+): ToolDefinition[] {
+  return [
+    {
+      name: "swallowkit_inspect_project",
+      description: "Return framework-owned SwallowKit project metadata.",
+      inputSchema: z.object({}),
+      handler: async () => {
+      const response = await executeMachineCommand(["inspect", "project"], runMachineCli);
+      return jsonTextContent(withSwallowKitMetadata(response.data));
+      },
+    },
+    {
+      name: "swallowkit_inspect_entities",
+      description: "Return SwallowKit entities, schema metadata, and connector/auth annotations.",
+      inputSchema: z.object({}),
+      handler: async () => {
+      const response = await executeMachineCommand(["inspect", "entities"], runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_inspect_routes",
+      description: "Return BFF and Functions route metadata understood by SwallowKit.",
+      inputSchema: z.object({}),
+      handler: async () => {
+      const response = await executeMachineCommand(["inspect", "routes"], runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_validate_project",
+      description: "Validate project metadata, generated artifacts, and framework conventions.",
+      inputSchema: z.object({}),
+      handler: async () => {
+      const response = await executeMachineCommand(["validate", "project"], runMachineCli);
+      return jsonTextContent(withSwallowKitMetadata(response.data));
+      },
+    },
+    {
+      name: "swallowkit_generate_model",
+      description: "Generate SwallowKit model templates through the official generator.",
+      inputSchema: z.object({
+        names: z.array(z.string()).min(1),
+        modelsDir: z.string().optional(),
+        connector: z.string().optional(),
+        overwrite: z.enum(["always", "never"]).optional(),
+      }),
+      handler: async ({ names, modelsDir, connector, overwrite }: { names: string[]; modelsDir?: string; connector?: string; overwrite?: "always" | "never" }) => {
+      const response = await executeMachineCommand(["generate", "model", ...names, ...(modelsDir ? ["--models-dir", modelsDir] : []), ...(connector ? ["--connector", connector] : []), "--overwrite", overwrite || "never"], runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_scaffold_model",
+      description: "Generate SwallowKit scaffold artifacts through the official generator.",
+      inputSchema: z.object({
+        model: z.string(),
+        functionsDir: z.string().optional(),
+        apiDir: z.string().optional(),
+        apiOnly: z.boolean().optional(),
+      }),
+      handler: async ({ model, functionsDir, apiDir, apiOnly }: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      const args = ["generate", "scaffold", model];
+      if (functionsDir) {
+        args.push("--functions-dir", functionsDir);
+      }
+      if (apiDir) {
+        args.push("--api-dir", apiDir);
+      }
+      if (apiOnly) {
+        args.push("--api-only");
+      }
+
+      const response = await executeMachineCommand(args, runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_plan_scaffold",
+      description: "Compute the scaffold change plan (files to create/update/overwrite, conflicts, warnings) without writing any files. Accepts one or more models; returns a planId per model usable with swallowkit_apply_scaffold.",
+      inputSchema: z.object({
+        model: z.string().optional(),
+        models: z.array(z.string()).optional(),
+        functionsDir: z.string().optional(),
+        apiDir: z.string().optional(),
+        apiOnly: z.boolean().optional(),
+      }),
+      handler: async ({ model, models, functionsDir, apiDir, apiOnly }: { model?: string; models?: string[]; functionsDir?: string; apiDir?: string; apiOnly?: 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");
+
+        const response = await executeMachineCommand(args, runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_apply_scaffold",
+      description: "Apply scaffold changes. Rejects stale plans (files changed after planning) and requires approve=true when user-modified files would be overwritten.",
+      inputSchema: z.object({
+        model: z.string().optional(),
+        planId: z.string().optional(),
+        approve: z.boolean().optional(),
+        functionsDir: z.string().optional(),
+        apiDir: z.string().optional(),
+        apiOnly: z.boolean().optional(),
+      }),
+      handler: async ({ model, planId, approve, functionsDir, apiDir, apiOnly }: { model?: string; planId?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+        const args = ["apply", "scaffold"];
+        if (model) args.push(model);
+        if (planId) args.push("--plan", planId);
+        if (approve) args.push("--approve");
+        if (functionsDir) args.push("--functions-dir", functionsDir);
+        if (apiDir) args.push("--api-dir", apiDir);
+        if (apiOnly) args.push("--api-only");
+
+        const response = await executeMachineCommand(args, runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_inspect_artifacts",
+      description: "Return the generated-artifact ledger with ownership, source model, and modified/missing flags.",
+      inputSchema: z.object({}),
+      handler: async () => {
+        const response = await executeMachineCommand(["inspect", "artifacts"], runMachineCli);
+        return jsonTextContent(withSwallowKitMetadata(response.data));
+      },
+    },
+    {
+      name: "swallowkit_inspect_drift",
+      description: "Detect drift between generated artifacts and the current project state (schema changes, manual edits, missing files, manifest mismatch). Each finding includes a repairAction.",
+      inputSchema: z.object({}),
+      handler: async () => {
+        const response = await executeMachineCommand(["inspect", "drift"], runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_verify_project",
+      description: "Run verification checks (structure, drift, typecheck by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. summary.done=true means the project passed all checks. Set compact=true to suppress info-severity findings and keep the output small.",
+      inputSchema: z.object({
+        checks: z.array(z.string()).optional(),
+        compact: z.boolean().optional(),
+      }),
+      handler: async ({ checks, compact }: { checks?: string[]; compact?: boolean }) => {
+        const args = ["verify", "project"];
+        if (checks && checks.length > 0) {
+          args.push("--checks", checks.join(","));
+        }
+        if (compact) args.push("--compact");
+
+        const response = await executeMachineCommand(args, runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_explain_failure",
+      description: "Explain failures from the most recent swallowkit_verify_project run, including evidence and suggested actions.",
+      inputSchema: z.object({
+        check: z.string().optional(),
+      }),
+      handler: async ({ check }: { check?: string }) => {
+        const args = ["explain", "failure"];
+        if (check) {
+          args.push("--check", check);
+        }
+
+        const response = await executeMachineCommand(args, runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_inspect_boundaries",
+      description: "Return the responsibility boundary contract: which paths are deterministic (regenerate via plan/apply), which are AI/human-authored (free edit), and which are shared extension points.",
+      inputSchema: z.object({}),
+      handler: async () => {
+        const response = await executeMachineCommand(["inspect", "boundaries"], runMachineCli);
+        return jsonTextContent(withSwallowKitMetadata(response.data));
+      },
+    },
+    {
+      name: "swallowkit_inspect_capabilities",
+      description: "Return SwallowKit's capability contract: which declarations models support (partitionKey, authPolicy, displayName, connectorConfig, with format examples), the correct auth-introduction workflow, what generated CRUD does and does NOT guarantee (no owner scoping), how dev seeds are applied, and every machine command. Consult this before assuming SwallowKit can or cannot do something.",
+      inputSchema: z.object({}),
+      handler: async () => {
+        const response = await executeMachineCommand(["inspect", "capabilities"], runMachineCli);
+        return jsonTextContent(withSwallowKitMetadata(response.data));
+      },
+    },
+    {
+      name: "swallowkit_plan_auth",
+      description: "Compute the add-auth change plan (files to create/update/overwrite, conflicts, warnings) without writing any files. Returns a planId usable with swallowkit_apply_auth. Never hand-write auth.schemes in swallowkit.config; this operation owns them.",
+      inputSchema: z.object({
+        provider: z.enum(["custom-jwt", "swa", "external-token", "none"]),
+        scheme: z.string().optional(),
+        allowedProviders: z.array(z.string()).optional(),
+      }),
+      handler: async ({ provider, scheme, allowedProviders }: { provider: string; scheme?: string; allowedProviders?: string[] }) => {
+        const args = ["plan", "auth", "--provider", provider];
+        if (scheme) args.push("--scheme", scheme);
+        if (allowedProviders && allowedProviders.length > 0) args.push("--allowed-providers", allowedProviders.join(","));
+
+        const response = await executeMachineCommand(args, runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_apply_auth",
+      description: "Apply add-auth changes. Rejects stale plans and requires approve=true when user-modified files would be overwritten. Follow the returned nextActions: policies and swa.allowedProviders are hand-edited afterwards, and external-token verifier stubs must be implemented.",
+      inputSchema: z.object({
+        provider: z.enum(["custom-jwt", "swa", "external-token", "none"]).optional(),
+        scheme: z.string().optional(),
+        allowedProviders: z.array(z.string()).optional(),
+        planId: z.string().optional(),
+        approve: z.boolean().optional(),
+      }),
+      handler: async ({ provider, scheme, allowedProviders, planId, approve }: { provider?: string; scheme?: string; allowedProviders?: string[]; planId?: string; approve?: boolean }) => {
+        const args = ["apply", "auth"];
+        if (planId) args.push("--plan", planId);
+        if (provider) args.push("--provider", provider);
+        if (scheme) args.push("--scheme", scheme);
+        if (allowedProviders && allowedProviders.length > 0) args.push("--allowed-providers", allowedProviders.join(","));
+        if (approve) args.push("--approve");
+
+        const response = await executeMachineCommand(args, runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_inspect_infra",
+      description: "Inspect Bicep infrastructure assets deterministically (params, modules, outputs, container wiring). Does not call Azure.",
+      inputSchema: z.object({}),
+      handler: async () => {
+        const response = await executeMachineCommand(["inspect", "infra"], runMachineCli);
+        return jsonTextContent(withSwallowKitMetadata(response.data));
+      },
+    },
+    {
+      name: "swallowkit_plan_provision",
+      description: "Preflight Azure provisioning locally (Bicep analysis, az CLI availability, command preview). Never deploys. Set whatIf=true to run az what-if (requires az login). The returned plan always requires human approval.",
+      inputSchema: z.object({
+        resourceGroup: z.string(),
+        location: z.string(),
+        swaLocation: z.string(),
+        subscription: z.string().optional(),
+        whatIf: z.boolean().optional(),
+      }),
+      handler: async ({ resourceGroup, location, swaLocation, subscription, whatIf }: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean }) => {
+        const args = ["plan", "provision", "--resource-group", resourceGroup, "--location", location, "--swa-location", swaLocation];
+        if (subscription) args.push("--subscription", subscription);
+        if (whatIf) args.push("--what-if");
+
+        const response = await executeMachineCommand(args, runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_apply_provision",
+      description: "Apply an approved provisioning plan. Creates billable Azure resources; approve=true is always required and must reflect explicit human consent.",
+      inputSchema: z.object({
+        planId: z.string(),
+        approve: z.boolean().optional(),
+      }),
+      handler: async ({ planId, approve }: { planId: string; approve?: boolean }) => {
+        const args = ["apply", "provision", "--plan", planId];
+        if (approve) args.push("--approve");
+
+        const response = await executeMachineCommand(args, runMachineCli);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+  ];
+}
+
+export function createSwallowKitMcpServer(runMachineCli: MachineCliRunner = defaultMachineCliRunner): McpServer {
+  const version = getSwallowKitVersion();
+  const server = new McpServer({
+    name: "swallowkit-mcp",
+    version,
+  });
+
+  for (const tool of buildSwallowKitToolDefinitions(runMachineCli)) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      },
+      tool.handler
+    );
+  }
+
+  return server;
+}
+
+export async function runMcpServer(): Promise<void> {
+  console.error(`[swallowkit-mcp] version: ${getSwallowKitVersion()}`);
+  const server = createSwallowKitMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+if (require.main === module) {
+  void runMcpServer().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}

package/src/types/index.ts

@@ -26,6 +26,124 @@ export interface UseServerFnResult<TResult> {
   refetch: () => void;
 }
 
+// コネクタの操作種別
+export type ConnectorOperation = "getAll" | "getById" | "create" | "update" | "delete";
+
+// RDB コネクタ設定
+export interface RdbConnectorConfig {
+  type: "rdb";
+  provider: "mysql" | "postgres" | "sqlserver";
+  connectionEnvVar: string;
+}
+
+// API コネクタの認証設定
+export interface ApiConnectorAuth {
+  type: "apiKey" | "bearer" | "oauth2";
+  envVar: string;
+  placement?: "query" | "header";
+  paramName?: string;
+}
+
+// API コネクタ設定
+export interface ApiConnectorConfig {
+  type: "api";
+  baseUrlEnvVar: string;
+  auth?: ApiConnectorAuth;
+}
+
+// コネクタ設定の共用型
+export type ConnectorDefinition = RdbConnectorConfig | ApiConnectorConfig;
+
+// モデルに付与するコネクタメタデータ（RDB用）
+export interface RdbModelConnectorConfig {
+  connector: string;
+  operations: readonly ConnectorOperation[];
+  table: string;
+  idColumn?: string;
+}
+
+// モデルに付与するコネクタメタデータ（API用）
+export interface ApiModelConnectorConfig {
+  connector: string;
+  operations: readonly ConnectorOperation[];
+  endpoints?: Partial<Record<ConnectorOperation, string>>;
+}
+
+// モデルに付与するコネクタメタデータの共用型
+export type ModelConnectorConfig = RdbModelConnectorConfig | ApiModelConnectorConfig;
+
+// 認証プロバイダー種別
+export type AuthProvider = "custom-jwt" | "swa" | "external-token" | "swa-custom" | "none";
+
+// custom-jwt プロバイダー設定
+export interface CustomJwtConfig {
+  userConnector: string;
+  userTable: string;
+  loginIdColumn: string;
+  passwordHashColumn: string;
+  rolesColumn: string;
+  jwtSecretEnv?: string;
+  tokenExpiry?: string;
+}
+
+// SWA 認証設定（将来用）
+export interface SwaAuthConfig {
+  allowedProviders?: string[];
+  roleSource?: "swa-roles" | "connector";
+  roleConnector?: string;
+}
+
+// 認可設定
+export interface AuthorizationConfig {
+  defaultPolicy?: "authenticated" | "anonymous" | "public" | string;
+  policies?: Record<string, AuthorizationPolicy>;
+}
+
+export interface AuthorizationPolicy {
+  schemes: string[];
+  roles?: string[];
+}
+
+export interface AuthSchemeConfig {
+  provider: AuthProvider;
+  customJwt?: CustomJwtConfig;
+  swa?: SwaAuthConfig;
+}
+
+// 認証設定
+export interface AuthConfig {
+  provider?: AuthProvider;
+  schemes?: Record<string, AuthSchemeConfig>;
+  customJwt?: CustomJwtConfig;
+  swa?: SwaAuthConfig;
+  authorization?: AuthorizationConfig;
+}
+
+// モデルに付与する認可ポリシー
+export interface ModelAuthPolicy {
+  roles?: string[];
+  read?: string[] | string;
+  write?: string[] | string;
+  policy?: string;
+}
+
+export interface NormalizedAuthConfig extends Omit<AuthConfig, "schemes" | "authorization"> {
+  schemes: Record<string, AuthSchemeConfig>;
+  authorization: AuthorizationConfig & { defaultPolicy: string; policies: Record<string, AuthorizationPolicy> };
+}
+
+export interface AuthPrincipal {
+  subject: string;
+  scheme: string;
+  issuer: string;
+  roles: string[];
+  claims: Record<string, unknown>;
+  /** @deprecated Use subject. */
+  userId?: string;
+  /** @deprecated Read provider data from claims. */
+  userDetails?: string;
+}
+
 // CLI設定の型
 export interface SwallowKitConfig {
   database?: {
@@ -42,4 +160,23 @@ export interface SwallowKitConfig {
       credentials?: boolean;
     };
   };
+  connectors?: Record<string, ConnectorDefinition>;
+  auth?: AuthConfig;
+  verify?: VerifySettings;
+}
+
+// verify コマンドのプロジェクト固有設定
+export interface CustomVerifyCheck {
+  /** チェック ID (built-in と重複不可)。 */
+  id: string;
+  title?: string;
+  /** プロジェクトルートで実行するシェルコマンド。exit 0 = pass。 */
+  command: string;
+  /** タイムアウト (ms)。既定 5 分。 */
+  timeoutMs?: number;
+}
+
+export interface VerifySettings {
+  /** プロジェクト固有の追加チェック。デフォルト実行セットに含まれる。 */
+  checks?: CustomVerifyCheck[];
 }