create-m5kdev 0.36.0 → 0.37.2

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "create-m5kdev",
-  "version": "0.36.0",
+  "version": "0.37.2",
   "license": "GPL-3.0-only",
   "engines": {
     "node": ">=24"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/michalkow/m5kdev.git"
+    "url": "git+https://github.com/michalkow/m5kdev.git"
   },
   "homepage": "https://github.com/michalkow/m5kdev#readme",
   "bugs": "https://github.com/michalkow/m5kdev/issues",
@@ -25,7 +25,7 @@
     "semver": "7.8.5",
     "tslib": "2.8.1",
     "yaml": "2.9.0",
-    "zod": "4.2.1"
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/jscodeshift": "17.3.0",

package/templates/minimal-app/.dockerignore.tpl

@@ -11,6 +11,12 @@ node_modules
 # Local env files — never bake secrets into the image
 .env*
 
+# Databases
+*.db
+*.db-wal
+*.db-shm
+*.db-info
+
 # Testing
 coverage
 

package/templates/minimal-app/apps/e2e/playwright.config.ts.tpl

@@ -33,6 +33,9 @@ export default defineConfig({
         // m5k:workflows:start
         "workflow.spec.ts",
         // m5k:workflows:end
+        // m5k:mcp:start
+        "mcp.spec.ts",
+        // m5k:mcp:end
       ],
       use: {
         ...devices["Desktop Chrome"],

package/templates/minimal-app/apps/e2e/servers.ts.tpl

@@ -58,6 +58,7 @@ function serverEnv(profile: E2EProfile, expo: boolean): Record<string, string> {
     REDIS_URL: `redis://127.0.0.1:6379/${expo ? PORTS[profile].expoRedisDb : PORTS[profile].redisDb}`,
     VITE_ENABLE_WAITLIST: profile === "waitlist" ? "true" : "false",
     AUTH_E2E_PROFILE: profile,
+    M5K_MCP_E2E_CIMD: "1",
     BETTER_AUTH_SECRET: "auth-e2e-local-secret-auth-e2e-local-secret",
     SYSTEM_NOTIFICATION_EMAIL: "ops@auth-e2e.local",
     NODE_ENV: "development",

package/templates/minimal-app/apps/e2e/tests/mcp-helpers.ts.tpl

@@ -0,0 +1,406 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import {
+  E2E_MCP_CIMD_CLIENT_ID,
+  E2E_MCP_CIMD_REDIRECT_URI,
+} from "@m5kdev/backend/modules/auth/auth.mcp-e2e";
+import {
+  MCP_AUTH_ISSUER_PATH,
+  MCP_AUTHORIZATION_SERVER_METADATA_PATH,
+  MCP_HTTP_PATH,
+  MCP_PROTECTED_RESOURCE_METADATA_PATH,
+  mcpResourceUrl,
+} from "@m5kdev/backend/modules/mcp/mcp.types";
+import type { APIRequestContext, APIResponse, Page } from "@playwright/test";
+import { expect } from "@playwright/test";
+
+export const MCP_PROTOCOL_VERSION = "2026-07-28";
+
+export interface McpOAuthDiscovery {
+  resource: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  scopes: string[];
+}
+
+export interface McpOAuthSession {
+  accessToken: string;
+  redirectUri: string;
+  close(): Promise<void>;
+}
+
+interface AuthorizationServerMetadata {
+  authorization_endpoint: string;
+  token_endpoint: string;
+  scopes_supported: string[];
+}
+
+interface ProtectedResourceMetadata {
+  resource?: string;
+  scopes_supported: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function readStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
+}
+
+function pkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`${response.status} ${response.statusText}: ${text}`);
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new Error(`Expected JSON from ${response.url}, received: ${text.slice(0, 300)}`);
+  }
+}
+
+function parseAuthorizationServerMetadata(value: unknown): AuthorizationServerMetadata {
+  if (!isRecord(value)) {
+    throw new Error("Authorization server metadata was not an object");
+  }
+  const authorizationEndpoint = readString(value.authorization_endpoint);
+  const tokenEndpoint = readString(value.token_endpoint);
+  if (!authorizationEndpoint || !tokenEndpoint) {
+    throw new Error("Authorization server metadata is missing endpoints");
+  }
+  return {
+    authorization_endpoint: authorizationEndpoint,
+    token_endpoint: tokenEndpoint,
+    scopes_supported: readStringArray(value.scopes_supported),
+  };
+}
+
+function parseProtectedResourceMetadata(value: unknown): ProtectedResourceMetadata {
+  if (!isRecord(value)) {
+    return { scopes_supported: [] };
+  }
+  return {
+    resource: readString(value.resource),
+    scopes_supported: readStringArray(value.scopes_supported),
+  };
+}
+
+export async function discoverMcpOAuth(serverUrl: string): Promise<McpOAuthDiscovery> {
+  const protectedResourceResponse = await fetch(
+    `${serverUrl}${MCP_PROTECTED_RESOURCE_METADATA_PATH}/mcp`
+  );
+  const protectedResource = parseProtectedResourceMetadata(
+    await readJson(protectedResourceResponse)
+  );
+  const authorizationServer = parseAuthorizationServerMetadata(
+    await readJson(
+      await fetch(`${serverUrl}${MCP_AUTHORIZATION_SERVER_METADATA_PATH}${MCP_AUTH_ISSUER_PATH}`)
+    )
+  );
+  const resource = protectedResource.resource ?? mcpResourceUrl(serverUrl);
+  const scopes =
+    protectedResource.scopes_supported.length > 0
+      ? protectedResource.scopes_supported
+      : authorizationServer.scopes_supported.length > 0
+        ? authorizationServer.scopes_supported
+        : ["openid"];
+  return {
+    resource,
+    authorizationEndpoint: authorizationServer.authorization_endpoint,
+    tokenEndpoint: authorizationServer.token_endpoint,
+    scopes,
+  };
+}
+
+function startCallbackServer(): Promise<{
+  redirectUri: string;
+  waitForCode: Promise<string>;
+  close: () => Promise<void>;
+}> {
+  return new Promise((resolveStart, rejectStart) => {
+    let settleCode: ((code: string) => void) | undefined;
+    let failCode: ((error: Error) => void) | undefined;
+    const waitForCode = new Promise<string>((resolve, reject) => {
+      settleCode = resolve;
+      failCode = reject;
+    });
+
+    const server: Server = createServer((req, res) => {
+      const requestUrl = new URL(req.url ?? "/", E2E_MCP_CIMD_REDIRECT_URI);
+      if (requestUrl.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      const error = requestUrl.searchParams.get("error");
+      const code = requestUrl.searchParams.get("code");
+      res.writeHead(200, { "content-type": "text/plain" });
+      if (error) {
+        const description = requestUrl.searchParams.get("error_description") ?? error;
+        res.end(description);
+        failCode?.(new Error(description));
+        return;
+      }
+      if (!code) {
+        res.end("missing code");
+        failCode?.(new Error("OAuth callback did not include a code"));
+        return;
+      }
+      res.end("ok");
+      settleCode?.(code);
+    });
+
+    server.once("error", rejectStart);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        rejectStart(new Error("OAuth callback server did not bind a port"));
+        return;
+      }
+      resolveStart({
+        redirectUri: `http://127.0.0.1:${address.port}/callback`,
+        waitForCode,
+        close: () =>
+          new Promise<void>((resolve, reject) => {
+            server.close((error) => {
+              if (error) reject(error);
+              else resolve();
+            });
+          }),
+      });
+    });
+  });
+}
+
+async function loginIfNeeded(page: Page, email: string, password: string): Promise<void> {
+  const emailField = page.locator('[name="login-email"]');
+  if (!(await emailField.isVisible().catch(() => false))) return;
+  await emailField.fill(email);
+  await page.locator('[name="login-password"]').fill(password);
+  await page.getByRole("button", { name: /^login$/i }).click();
+}
+
+async function allowConsent(page: Page, organization: { id: string; name: string }): Promise<void> {
+  await expect(
+    page.getByText("Allow this MCP client"),
+    `expected MCP consent page, at ${page.url()}`
+  ).toBeVisible({ timeout: 20_000 });
+  const orgRow = page.getByTestId(`mcp-consent-org-${organization.id}`);
+  await expect(orgRow).toBeVisible({ timeout: 15_000 });
+  const checkbox = orgRow.getByRole("checkbox");
+  if (!(await checkbox.isChecked())) {
+    await orgRow.locator('[data-slot="checkbox-control"]').click();
+    await expect(checkbox).toBeChecked();
+  }
+  await page.getByTestId("mcp-consent-allow").click();
+  await expect(page, `expected OAuth redirect after consent, at ${page.url()}`).not.toHaveURL(
+    /\/consent(?:\?|$)/,
+    { timeout: 20_000 }
+  );
+}
+
+async function exchangeAuthorizationCode(input: {
+  tokenEndpoint: string;
+  code: string;
+  redirectUri: string;
+  verifier: string;
+  resource: string;
+}): Promise<string> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: input.code,
+    redirect_uri: input.redirectUri,
+    client_id: E2E_MCP_CIMD_CLIENT_ID,
+    code_verifier: input.verifier,
+    resource: input.resource,
+  });
+  const response = await fetch(input.tokenEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body,
+  });
+  const payload = await readJson(response);
+  if (!isRecord(payload)) {
+    throw new Error("Token response was not an object");
+  }
+  const accessToken = readString(payload.access_token);
+  if (!accessToken) {
+    throw new Error(`Token response did not include access_token: ${JSON.stringify(payload)}`);
+  }
+  return accessToken;
+}
+
+export async function authorizeMcpClient(input: {
+  page: Page;
+  serverUrl: string;
+  email: string;
+  password: string;
+  organization: { id: string; name: string };
+}): Promise<McpOAuthSession> {
+  const discovery = await discoverMcpOAuth(input.serverUrl);
+  const { verifier, challenge } = pkce();
+  const state = randomBytes(16).toString("hex");
+  const callback = await startCallbackServer();
+  const authorizeUrl = new URL(discovery.authorizationEndpoint);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("client_id", E2E_MCP_CIMD_CLIENT_ID);
+  authorizeUrl.searchParams.set("redirect_uri", callback.redirectUri);
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  authorizeUrl.searchParams.set("resource", discovery.resource);
+  authorizeUrl.searchParams.set("scope", "openid");
+
+  try {
+    await input.page.goto(authorizeUrl.toString());
+    await expect(
+      input.page.getByText("Allow this MCP client").or(input.page.locator('[name="login-email"]')),
+      `expected consent or login after authorize, at ${input.page.url()}`
+    ).toBeVisible({ timeout: 30_000 });
+    await loginIfNeeded(input.page, input.email, input.password);
+    await allowConsent(input.page, input.organization);
+    const code = await callback.waitForCode;
+    const accessToken = await exchangeAuthorizationCode({
+      tokenEndpoint: discovery.tokenEndpoint,
+      code,
+      redirectUri: callback.redirectUri,
+      verifier,
+      resource: discovery.resource,
+    });
+    return {
+      accessToken,
+      redirectUri: callback.redirectUri,
+      close: callback.close,
+    };
+  } catch (error) {
+    await callback.close().catch(() => undefined);
+    throw error;
+  }
+}
+
+function parseSseJson(body: string): unknown {
+  const dataLines = body
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice("data:".length).trim());
+  if (dataLines.length === 0) {
+    throw new Error(`SSE body did not include data: ${body.slice(0, 300)}`);
+  }
+  return JSON.parse(dataLines.join("\n")) as unknown;
+}
+
+function unwrapJsonRpc(payload: unknown): unknown {
+  if (!isRecord(payload)) {
+    throw new Error(`MCP JSON-RPC payload was not an object: ${JSON.stringify(payload)}`);
+  }
+  if ("error" in payload) {
+    throw new Error(`MCP JSON-RPC error: ${JSON.stringify(payload.error)}`);
+  }
+  if (!("result" in payload)) {
+    throw new Error(`MCP JSON-RPC response missing result: ${JSON.stringify(payload)}`);
+  }
+  return payload.result;
+}
+
+function readToolText(result: unknown): { isError: boolean; text: string | undefined } {
+  if (!isRecord(result)) {
+    throw new Error(`MCP tool result was not an object: ${JSON.stringify(result)}`);
+  }
+  const content = result.content;
+  const textEntry = Array.isArray(content)
+    ? content.find(
+        (entry) => isRecord(entry) && entry.type === "text" && typeof entry.text === "string"
+      )
+    : undefined;
+  return {
+    isError: result.isError === true,
+    text: isRecord(textEntry) && typeof textEntry.text === "string" ? textEntry.text : undefined,
+  };
+}
+
+async function readMcpJsonRpc(response: APIResponse): Promise<unknown> {
+  const text = await response.text();
+  if (!response.ok()) {
+    throw new Error(`${response.status()} ${response.statusText()}: ${text}`);
+  }
+  const contentType = response.headers()["content-type"] ?? "";
+  if (contentType.includes("text/event-stream")) {
+    return parseSseJson(text);
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new Error(`MCP response was not JSON: ${text.slice(0, 300)}`);
+  }
+}
+
+function mcpToolCallParams(input: {
+  name: string;
+  arguments?: Record<string, unknown>;
+}): Record<string, unknown> {
+  return {
+    name: input.name,
+    arguments: input.arguments ?? {},
+    _meta: {
+      "io.modelcontextprotocol/protocolVersion": MCP_PROTOCOL_VERSION,
+      "io.modelcontextprotocol/clientCapabilities": {},
+      "io.modelcontextprotocol/clientInfo": {
+        name: "starter-e2e",
+        version: "1.0.0",
+      },
+    },
+  };
+}
+
+export async function callMcpTool(input: {
+  request: APIRequestContext;
+  serverUrl: string;
+  accessToken: string;
+  name: string;
+  arguments?: Record<string, unknown>;
+}): Promise<unknown> {
+  const response = await input.request.post(`${input.serverUrl}${MCP_HTTP_PATH}`, {
+    headers: {
+      authorization: `Bearer ${input.accessToken}`,
+      accept: "application/json",
+      "content-type": "application/json",
+      "mcp-protocol-version": MCP_PROTOCOL_VERSION,
+      "mcp-method": "tools/call",
+      "mcp-name": input.name,
+    },
+    data: {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: mcpToolCallParams({ name: input.name, arguments: input.arguments }),
+    },
+  });
+  const result = unwrapJsonRpc(await readMcpJsonRpc(response));
+  const toolText = readToolText(result);
+  if (toolText.isError) {
+    throw new Error(toolText.text ?? `MCP call ${input.name} failed`);
+  }
+  if (toolText.text === undefined) {
+    return result;
+  }
+  try {
+    return JSON.parse(toolText.text) as unknown;
+  } catch {
+    return toolText.text;
+  }
+}
+
+export { E2E_MCP_CIMD_CLIENT_ID, MCP_HTTP_PATH };

package/templates/minimal-app/apps/e2e/tests/mcp.spec.ts.tpl

@@ -0,0 +1,108 @@
+import { expect, test } from "@playwright/test";
+import { clearEmails, getUserState, login, profiles, signUp, verifyLatestEmail } from "./helpers";
+import { authorizeMcpClient, callMcpTool, MCP_HTTP_PATH } from "./mcp-helpers";
+
+const profile = "standard" as const;
+
+test.beforeEach(async ({ request }) => {
+  await clearEmails(request, profile);
+});
+
+test("authenticate through MCP OAuth and call list-organizations, list-posts, and create-post", async ({
+  page,
+  request,
+}) => {
+  test.setTimeout(120_000);
+  const email = `mcp.${Date.now()}@auth-e2e.local`;
+  const password = "password1234";
+  const serverUrl = profiles[profile].serverUrl;
+  const title = `MCP e2e ${Date.now()}`;
+
+  await signUp(page, email, password);
+  await verifyLatestEmail(request, profile, email);
+  await login(page, email, password);
+
+  const unauthenticated = await request.post(`${serverUrl}${MCP_HTTP_PATH}`, {
+    data: {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/list",
+      params: {},
+    },
+  });
+  expect(unauthenticated.status()).toBe(401);
+  expect(unauthenticated.headers()["www-authenticate"] ?? "").toMatch(/Bearer/i);
+
+  const state = await getUserState(request, profile, email);
+  const organization = state.organizations[0];
+  if (!organization) {
+    throw new Error("Expected signup to create an Organization");
+  }
+
+  const session = await authorizeMcpClient({
+    page,
+    serverUrl,
+    email,
+    password,
+    organization,
+  });
+
+  try {
+    const listedOrganizations = await callMcpTool({
+      request,
+      serverUrl,
+      accessToken: session.accessToken,
+      name: "list-organizations",
+    });
+    expect(listedOrganizations).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: organization.id,
+          name: organization.name,
+        }),
+      ])
+    );
+
+    const listedBefore = await callMcpTool({
+      request,
+      serverUrl,
+      accessToken: session.accessToken,
+      name: "list-posts",
+      arguments: { organizationId: organization.id },
+    });
+    expect(listedBefore).toEqual(
+      expect.objectContaining({
+        rows: expect.any(Array),
+        total: expect.any(Number),
+      })
+    );
+
+    const created = await callMcpTool({
+      request,
+      serverUrl,
+      accessToken: session.accessToken,
+      name: "create-post",
+      arguments: {
+        organizationId: organization.id,
+        title,
+        content: "Written through the MCP client.",
+      },
+    });
+    expect(created).toEqual(expect.objectContaining({ title }));
+
+    const listedAfter = await callMcpTool({
+      request,
+      serverUrl,
+      accessToken: session.accessToken,
+      name: "list-posts",
+      arguments: { organizationId: organization.id },
+    });
+    expect(listedAfter).toEqual(
+      expect.objectContaining({
+        rows: expect.arrayContaining([expect.objectContaining({ title })]),
+      })
+    );
+  } finally {
+    await session.close();
+  }
+});

package/templates/minimal-app/apps/server/AGENTS.md.tpl

@@ -20,6 +20,9 @@ apps/server/src/modules/<module>/
 ├── <module>.repository.ts
 ├── <module>.service.ts
 ├── <module>.trpc.ts
+// m5k:mcp:start
+├── <module>.mcp.ts
+// m5k:mcp:end
 └── <module>.module.ts
 ```
 
@@ -28,6 +31,9 @@ apps/server/src/modules/<module>/
 - Repositories own persistence and query construction.
 - Services own business rules, orchestration, and context-aware defaults.
 - tRPC files own transport only and must delegate to services.
+// m5k:mcp:start
+- MCP call maps live in `<module>.mcp.ts` and are contributed from `mcp()` / `mcpUser()`. Delegate to Procedures or unguarded service methods; do not scrape Service properties.
+// m5k:mcp:end
 - Register Core Modules and app modules in `apps/server/src/app.ts` via `createBackendApp(config, [modules])`. Do not use `backendApp.use`. Optional Backend Modules (`@m5kdev/module-*`) are not scaffolded; add them only when the product needs Clay, Docx, Pdf, Social, or Video.
 // m5k:ai:start
 - `AIModule` is registered in `app.ts` with an app-owned Mastra Agent (`assistant`). Conversation HTTP lives on `/ai`. Set `OPENROUTER_API_KEY` for live replies. Do not add a Starter service wrapper around `AIService` chat.
@@ -50,6 +56,10 @@ apps/server/src/modules/<module>/
 - `index.ts` calls `builtBackendApp.start()`, which listens and handles SIGINT/SIGTERM. Extra shutdown work (telemetry) is `onShutdown` on `createBackendApp`.
 - After changing Drizzle tables, run `pnpm --filter ./apps/server drizzle:generate` then `drizzle:migrate` — do not hand-edit SQL migrations in this repo.
 
+// m5k:mcp:start
+- `McpModule` is registered in `app.ts`. MCP clients authenticate with Better Auth MCP OAuth (not API keys). Compose `auth.oauth.db` plus `mcpAllowlistEntries`. Contribute Organization-scoped calls from `posts.mcp.ts`. Omit the module to disable MCP.
+// m5k:mcp:end
+
 // m5k:notifications:start
 - `NotificationModule` is registered in `app.ts` when this feature is selected. Push-related server env vars are documented in `apps/shared/.env.example`.
 // m5k:notifications:end

package/templates/minimal-app/apps/server/db.e2e.ts.tpl

@@ -82,6 +82,7 @@ async function ensureUser(input: {
     await orm.insert(schema.accounts).values({
       id: uuidv4(),
       accountId: user.id,
+      issuer: "local:credential",
       providerId: "credential",
       userId: user.id,
       password: await hashPassword(password),

package/templates/minimal-app/apps/server/db.ts.tpl

@@ -52,6 +52,7 @@ async function ensureDemoUser(orm: SeedOrm): Promise<typeof schema.users.$inferS
   await orm.insert(schema.accounts).values({
     id: uuidv4(),
     accountId: user.id,
+    issuer: "local:credential",
     providerId: "credential",
     userId: user.id,
     password: await hashPassword(DEMO_PASSWORD),