create-ailk 0.1.0

package/templates/apps/mcp/src/http-transport.ts

@@ -0,0 +1,303 @@
+/**
+ * MCP HTTP transport for @working-theory/mcp.
+ *
+ * Wraps the MCP SDK's StreamableHTTPServerTransport in a Fastify server with:
+ *   - @fastify/cors  — open for reads, allowlist-by-config for writes
+ *   - @fastify/rate-limit — 60/min reads, 10/min writes (env-overridable)
+ *   - abuse heuristics — UA deny list, honeypot, email validation, daily cap
+ *
+ * Decision references:
+ *   Decision 1 — same binary, env-var transport selection (apps/mcp/src/index.ts)
+ *   Decision 2 — configurable path, default /mcp, standalone root-mounted
+ *   Decision 3 — @fastify/rate-limit per-IP token bucket
+ *   Decision 4 — in-process abuse heuristics for write tools
+ *   Decision 5 — @fastify/cors open reads, allowlist writes
+ *
+ * The server is stateless: each initialize request creates a fresh
+ * StreamableHTTPServerTransport + McpServer pair. Session IDs are not
+ * persisted across restarts (acceptable for OSS; paid layer adds durability).
+ */
+
+import { randomUUID } from "node:crypto";
+
+import cors from "@fastify/cors";
+import rateLimit from "@fastify/rate-limit";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import Fastify, { type FastifyInstance, type FastifyRequest } from "fastify";
+
+import { AbuseGuard, type AbuseConfig } from "./abuse/index.js";
+import { createMcpServer } from "./server.js";
+
+/** MCP tool names that are write operations (subject to stricter CORS + rate limits). */
+const WRITE_TOOLS = new Set([
+  "capture_lead",
+  "subscribe_newsletter",
+  "request_callback",
+]);
+
+export interface HttpTransportCorsConfig {
+  /**
+   * Origins allowed to call write tools.
+   * Empty array = no cross-origin writes (most restrictive; default).
+   * ["*"] = allow all origins for writes (use only in dev/testing).
+   */
+  writeAllowedOrigins: string[];
+}
+
+export interface HttpTransportRateLimits {
+  /** Max requests per minute per IP for read tools. Default 60. */
+  readPerMin: number;
+  /** Max requests per minute per IP for write tools. Default 10. */
+  writePerMin: number;
+}
+
+export interface HttpTransportConfig {
+  /** URL path to mount the MCP endpoint on. Default "/mcp". */
+  path?: string;
+  /** Rate limit configuration. */
+  rateLimits: HttpTransportRateLimits;
+  /** CORS configuration. */
+  cors: HttpTransportCorsConfig;
+  /** Abuse protection configuration. */
+  abuse: AbuseConfig;
+  /**
+   * When true, use stateless transport mode: no session IDs, every request
+   * creates a fresh McpServer + transport. Useful for testing and simple
+   * deployments that don't need resumable sessions.
+   * Default: false (stateful).
+   */
+  stateless?: boolean;
+}
+
+/**
+ * Determine whether a tools/call payload targets a write tool.
+ * Returns false for any other method (tools/list, initialize, etc.).
+ */
+function isWriteToolCall(body: unknown): boolean {
+  if (!body || typeof body !== "object") return false;
+  const req = body as Record<string, unknown>;
+  if (req["method"] !== "tools/call") return false;
+  const params = req["params"] as Record<string, unknown> | undefined;
+  if (!params) return false;
+  return WRITE_TOOLS.has(params["name"] as string);
+}
+
+/**
+ * Determine whether an Origin header is in the write allowlist.
+ * ["*"] matches any origin. Empty list blocks all cross-origin writes.
+ */
+function isOriginAllowedForWrite(
+  origin: string | undefined,
+  allowedOrigins: string[],
+): boolean {
+  if (!origin) return true; // Same-origin or non-browser clients have no Origin header
+  if (allowedOrigins.includes("*")) return true;
+  return allowedOrigins.includes(origin);
+}
+
+/**
+ * Build and return a configured Fastify instance that exposes the MCP HTTP
+ * transport at `config.path`. The instance is not yet listening — callers
+ * call `.listen()` or `.inject()` (tests).
+ *
+ * @param config - HTTP transport configuration
+ * @returns Configured Fastify instance (ready to listen or inject)
+ */
+export async function buildHttpTransportApp(
+  config: HttpTransportConfig,
+): Promise<FastifyInstance> {
+  const mcpPath = config.path ?? "/mcp";
+  const abuseGuard = new AbuseGuard(config.abuse);
+
+  // Active transports keyed by session ID (stateful mode only).
+  const transports = new Map<string, StreamableHTTPServerTransport>();
+
+  const app = Fastify({ logger: false });
+
+  // ── CORS ──────────────────────────────────────────────────────────────────
+  // Read tools: open (origin: true — reflect the caller's Origin).
+  // Write tools: enforced per-request in the preHandler below.
+  // We register a permissive global CORS so browser preflight succeeds for
+  // reads; write-tool CORS is enforced by the preHandler, not this plugin.
+  await app.register(cors, {
+    origin: true,
+    methods: ["GET", "POST", "DELETE", "OPTIONS"],
+  });
+
+  // ── Rate limiting ─────────────────────────────────────────────────────────
+  // Global ceiling — the lower write limit is enforced per-request via the
+  // preHandler by checking the tool name after body parse.
+  await app.register(rateLimit, {
+    max: config.rateLimits.readPerMin,
+    timeWindow: "1 minute",
+    keyGenerator: (request: FastifyRequest) => request.ip,
+  });
+
+  // ── MCP route ─────────────────────────────────────────────────────────────
+
+  // GET — SSE stream for an existing session
+  app.get(mcpPath, async (request, reply) => {
+    const sessionId = request.headers["mcp-session-id"] as string | undefined;
+    if (!sessionId || !transports.has(sessionId)) {
+      reply.code(400).send("Invalid or missing session ID");
+      return;
+    }
+    const transport = transports.get(sessionId)!;
+    await transport.handleRequest(request.raw, reply.raw);
+  });
+
+  // POST — new session initialize or existing session message
+  app.post(mcpPath, {
+    preHandler: async (request, reply) => {
+      const body = request.body as unknown;
+      const origin = request.headers["origin"] as string | undefined;
+
+      // Write-tool CORS enforcement
+      if (isWriteToolCall(body)) {
+        if (!isOriginAllowedForWrite(origin, config.cors.writeAllowedOrigins)) {
+          reply
+            .code(403)
+            .send({ error: "CORS: cross-origin write not allowed" });
+          return;
+        }
+
+        // Write-tool rate limit (stricter than read ceiling)
+        // We re-use the same in-memory store but apply a tighter key.
+        // @fastify/rate-limit tracks by keyGenerator; we check manually here.
+        // Simple approach: use a second rate-limit store baked into the guard.
+        // For now, we rely on the global ceiling for writes (configurable).
+        // TODO: per-tool write rate limit when @fastify/rate-limit v11 lands
+        // a per-route override API compatible with our stateless route design.
+
+        // Abuse heuristics
+        const params = (body as Record<string, unknown>)["params"] as
+          | Record<string, unknown>
+          | undefined;
+        const toolName = (params?.["name"] as string) ?? "";
+        const args = params?.["arguments"] ?? {};
+
+        const abuseResult = abuseGuard.validate(toolName, args, request);
+        if (!abuseResult.allowed) {
+          const statusCode =
+            abuseResult.reason === "blocked user agent" ||
+            abuseResult.reason?.includes("daily cap")
+              ? 403
+              : 422;
+          reply.code(statusCode).send({ error: abuseResult.reason });
+          return;
+        }
+      } else {
+        // Read-tool or protocol message: check UA deny list only
+        const abuseGuardResult = abuseGuard.validate("__read__", {}, request);
+        if (!abuseGuardResult.allowed) {
+          reply.code(403).send({ error: abuseGuardResult.reason });
+          return;
+        }
+      }
+    },
+    handler: async (request, reply) => {
+      const body = request.body as unknown;
+      const sessionId = request.headers["mcp-session-id"] as string | undefined;
+
+      try {
+        let transport: StreamableHTTPServerTransport;
+
+        if (config.stateless) {
+          // Stateless mode: each request gets a fresh transport + server.
+          // enableJsonResponse: true ensures plain JSON responses (no SSE).
+          // sessionIdGenerator is intentionally omitted (stateless = no sessions).
+          transport = new StreamableHTTPServerTransport({
+            enableJsonResponse: true,
+          });
+          const server = createMcpServer();
+          // Cast needed: SDK's StreamableHTTPServerTransport.onclose is typed
+          // as `(() => void) | undefined`, which conflicts with Transport.onclose
+          // under exactOptionalPropertyTypes: true. The runtime behaviour is
+          // identical; the cast is safe.
+          await server.connect(transport as unknown as Transport);
+          try {
+            await transport.handleRequest(request.raw, reply.raw, body);
+          } finally {
+            // Close the per-request transport + server to release internal
+            // handles. Without this, the MCP SDK's transport leaves open
+            // sockets that surface as `socket.destroySoon is not a function`
+            // during Jest teardown on Node 20.x (@hono/node-server compat).
+            await transport.close().catch(() => undefined);
+            await server.close().catch(() => undefined);
+          }
+          return;
+        }
+
+        if (sessionId && transports.has(sessionId)) {
+          // Existing session — reuse transport
+          transport = transports.get(sessionId)!;
+        } else if (!sessionId && isInitializeRequest(body)) {
+          // New initialization — create a stateful transport + fresh server
+          transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sid) => {
+              transports.set(sid, transport);
+            },
+          });
+
+          transport.onclose = () => {
+            const sid = transport.sessionId;
+            if (sid) transports.delete(sid);
+          };
+
+          const server = createMcpServer();
+          // Cast needed: SDK's StreamableHTTPServerTransport.onclose is typed
+          // as `(() => void) | undefined`, which conflicts with Transport.onclose
+          // under exactOptionalPropertyTypes: true. The runtime behaviour is
+          // identical; the cast is safe.
+          await server.connect(transport as unknown as Transport);
+        } else {
+          reply.code(400).send({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Bad Request: no valid session" },
+            id: null,
+          });
+          return;
+        }
+
+        await transport.handleRequest(request.raw, reply.raw, body);
+      } catch (err) {
+        if (!reply.sent) {
+          reply.code(500).send({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: "Internal server error" },
+            id: null,
+          });
+        }
+        throw err;
+      }
+    },
+  });
+
+  // DELETE — session termination
+  app.delete(mcpPath, async (request, reply) => {
+    const sessionId = request.headers["mcp-session-id"] as string | undefined;
+    if (!sessionId || !transports.has(sessionId)) {
+      reply.code(400).send("Invalid or missing session ID");
+      return;
+    }
+    const transport = transports.get(sessionId)!;
+    await transport.handleRequest(request.raw, reply.raw);
+  });
+
+  return app;
+}
+
+/**
+ * Start the HTTP transport bound to the configured port.
+ * Returns the listening Fastify instance.
+ */
+export async function startHttpTransport(
+  config: HttpTransportConfig & { port: number },
+): Promise<FastifyInstance> {
+  const app = await buildHttpTransportApp(config);
+  await app.listen({ port: config.port, host: "0.0.0.0" });
+  return app;
+}

package/templates/apps/mcp/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * @working-theory/mcp — MCP server entry point.
+ *
+ * Boots the server on the transport selected by MCP_TRANSPORT (default: stdio).
+ *
+ * MCP_TRANSPORT=stdio  — StdioServerTransport (default; local subprocess use)
+ * MCP_TRANSPORT=http   — StreamableHTTPServerTransport via Fastify
+ *
+ * HTTP transport configuration (all optional, shown with defaults):
+ *   MCP_HTTP_PORT=8080
+ *   MCP_HTTP_PATH=/mcp
+ *   MCP_RATE_LIMIT_READ_PER_MIN=60
+ *   MCP_RATE_LIMIT_WRITE_PER_MIN=10
+ *   MCP_CORS_WRITE_ALLOWED_ORIGINS=   (empty = no cross-origin writes)
+ *   MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP=50
+ *   MCP_ABUSE_BLOCKED_USER_AGENTS=    (comma-separated substrings)
+ */
+
+// Required to mark this file as an ES module (needed for top-level await).
+export {};
+
+const transport = process.env["MCP_TRANSPORT"] ?? "stdio";
+
+if (transport === "http") {
+  const { startHttpTransport } = await import("./http-transport.js");
+
+  const port = parseInt(process.env["MCP_HTTP_PORT"] ?? "8080", 10);
+  const path = process.env["MCP_HTTP_PATH"] ?? "/mcp";
+  const readPerMin = parseInt(
+    process.env["MCP_RATE_LIMIT_READ_PER_MIN"] ?? "60",
+    10,
+  );
+  const writePerMin = parseInt(
+    process.env["MCP_RATE_LIMIT_WRITE_PER_MIN"] ?? "10",
+    10,
+  );
+  const writeOriginsRaw = process.env["MCP_CORS_WRITE_ALLOWED_ORIGINS"] ?? "";
+  const writeAllowedOrigins = writeOriginsRaw
+    ? writeOriginsRaw.split(",").map((o) => o.trim())
+    : [];
+  const captureLeadDailyCapPerIp = parseInt(
+    process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] ?? "50",
+    10,
+  );
+  const blockedUserAgents =
+    process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] ?? "";
+
+  await startHttpTransport({
+    port,
+    path,
+    rateLimits: { readPerMin, writePerMin },
+    cors: { writeAllowedOrigins },
+    abuse: { captureLeadDailyCapPerIp, blockedUserAgents },
+  });
+
+  console.log(`MCP HTTP transport listening on port ${port} at ${path}`);
+} else {
+  // Default: stdio transport
+  const { StdioServerTransport } = await import(
+    "@modelcontextprotocol/sdk/server/stdio.js"
+  );
+  const { createMcpServer } = await import("./server.js");
+
+  const server = createMcpServer();
+  const stdioTransport = new StdioServerTransport();
+  await server.connect(stdioTransport);
+}

package/templates/apps/mcp/src/lib/audit-single-page.ts

@@ -0,0 +1,194 @@
+/**
+ * audit-single-page — URL-or-slug → AuditInput adapter.
+ *
+ * Builds an `AuditInput` for a single page identified by slug or URL.
+ * The resulting value is ready to pass directly to `runAudit`.
+ *
+ * Security constraint — same-origin only:
+ *   URL inputs are checked against `AILK_BASE_URL` (or `NEXT_PUBLIC_BASE_URL`
+ *   as fallback). Cross-domain URLs are rejected synchronously before any I/O.
+ *   No `fetch()` is called anywhere in this file.
+ *
+ * Input:  { slug, type? } | { url }  (exactly one branch; not both, not neither)
+ * Output: AuditInput ready for runAudit
+ * Session/scope: none — read-only filesystem access via content adapter.
+ */
+
+import { join } from "node:path";
+
+import { type AuditInput } from "@working-theory/aeo";
+import { createMdxAdapter, type SchemaOrgType } from "@working-theory/content-adapters";
+import { buildJsonLd, pageTypeRegistry } from "@working-theory/schema";
+
+import { resolveLocale } from "./resolve-locale.js";
+
+export interface SlugInput {
+  slug: string;
+  type?: SchemaOrgType;
+  /**
+   * BCP-47 locale tag (Phase 3 S3). Optional; falls back to the project's
+   * default locale when omitted or invalid (AC-i18n-07).
+   */
+  locale?: string;
+}
+
+export interface UrlInput {
+  url: string;
+  /**
+   * BCP-47 locale tag (Phase 3 S3). Optional; falls back to the project's
+   * default locale when omitted or invalid (AC-i18n-07).
+   */
+  locale?: string;
+}
+
+export type SinglePageInput = SlugInput | UrlInput;
+
+const DEFAULT_IDENTITY_MODE = "organization" as const;
+
+function getBaseUrl(): string {
+  return process.env.AILK_BASE_URL ?? process.env.NEXT_PUBLIC_BASE_URL ?? "";
+}
+
+/**
+ * Validates that a URL is on the AILK installation's own domain.
+ *
+ * Uses `URL` to parse and extract `hostname` — this correctly handles
+ * credential-stuffed bypass attempts like `https://attacker@own-domain/`
+ * (hostname is `attacker`, not `own-domain`) and IPv6 addresses.
+ * Case-folding: URL spec normalises hostname to lowercase before comparison.
+ *
+ * Throws with an agent-readable error referencing `ailk audit` CLI when
+ * the URL is cross-domain. The rejection is purely string-based — no I/O.
+ */
+function assertSameOrigin(raw: string): void {
+  const baseUrl = getBaseUrl();
+
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`Invalid URL: "${raw}"`);
+  }
+
+  if (!baseUrl) {
+    // No base URL configured — we cannot validate; reject to be safe.
+    throw new Error(
+      "AILK_BASE_URL (or NEXT_PUBLIC_BASE_URL) is not set. " +
+        "Cannot validate same-origin for URL input. " +
+        "Use slug input, or set AILK_BASE_URL. " +
+        "For cross-domain audits use `ailk audit` CLI.",
+    );
+  }
+
+  let base: URL;
+  try {
+    base = new URL(baseUrl);
+  } catch {
+    throw new Error(`AILK_BASE_URL is not a valid URL: "${baseUrl}"`);
+  }
+
+  // URL spec lowercases hostname; compare after normalisation.
+  if (parsed.hostname !== base.hostname) {
+    throw new Error(
+      `URL "${raw}" is out of scope for audit — ` +
+        `hostname "${parsed.hostname}" does not match installation domain "${base.hostname}". ` +
+        "For cross-domain or multi-site audits use `ailk audit` CLI.",
+    );
+  }
+}
+
+/**
+ * Extracts `{ type, slug }` from a same-origin URL path.
+ *
+ * Expects the path to follow the convention `/<SchemaOrgType>/<slug>`.
+ * Strips query strings and fragments before parsing.
+ */
+function extractTypeSlugFromUrl(raw: string): {
+  type: SchemaOrgType;
+  slug: string;
+} {
+  const parsed = new URL(raw);
+  // pathname is already stripped of query/fragment by the URL object
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  if (segments.length < 2) {
+    throw new Error(
+      `Cannot extract type/slug from URL path "${parsed.pathname}". ` +
+        "Expected format: /<SchemaOrgType>/<slug>",
+    );
+  }
+  const type = segments[0] as SchemaOrgType;
+  const slug = segments[1] as string;
+  return { type, slug };
+}
+
+/**
+ * Builds an `AuditInput` for a single page.
+ *
+ * Accepts an optional `contentRoot` override for testing. When omitted,
+ * resolves the content root relative to cwd (supports ESM runtime).
+ */
+export async function buildSinglePageAuditInput(
+  input: SinglePageInput,
+  contentRoot?: string,
+): Promise<AuditInput> {
+  // Validate: exactly one of slug or url, not both, not neither.
+  const hasSlug = "slug" in input;
+  const hasUrl = "url" in input;
+
+  if (hasSlug && hasUrl) {
+    throw new Error(
+      "slug and url are mutually exclusive — provide one, not both.",
+    );
+  }
+  if (!hasSlug && !hasUrl) {
+    throw new Error("Either slug or url is required.");
+  }
+
+  const root = contentRoot ?? join(process.cwd(), "content");
+  const locale = resolveLocale(input.locale);
+  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+
+  let type: SchemaOrgType;
+  let slug: string;
+
+  if (hasUrl) {
+    assertSameOrigin((input as UrlInput).url);
+    const extracted = extractTypeSlugFromUrl((input as UrlInput).url);
+    type = extracted.type;
+    slug = extracted.slug;
+  } else {
+    const slugInput = input as SlugInput;
+    slug = slugInput.slug;
+    type = slugInput.type ?? "HomePage";
+  }
+
+  const page = await adapter.getPageBySlug(type, slug, locale);
+  if (!page) {
+    throw new Error(
+      `Page not found: type="${type}" slug="${slug}". ` +
+        "Check that the page exists in the content directory.",
+    );
+  }
+
+  const pageKey = `${type}/${slug}`;
+  const jsonLdByPage: Record<string, unknown> = {};
+  try {
+    // Cast to ContentPageInput — structurally compatible but exactOptionalPropertyTypes
+    // differs between @working-theory/content-adapters ContentPage and @working-theory/schema ContentPageInput.
+    // This is the same pattern used in packages/aeo/src/cli/build-input.ts.
+    jsonLdByPage[pageKey] = buildJsonLd(
+      page as Parameters<typeof buildJsonLd>[0],
+    );
+  } catch {
+    // Omit key on build failure — downstream rule reports "no JSON-LD".
+    // This mirrors packages/aeo/src/cli/build-input.ts behavior.
+  }
+
+  return {
+    pages: [{ slug, type, locale }],
+    locale,
+    identityMode: DEFAULT_IDENTITY_MODE,
+    registry: pageTypeRegistry,
+    jsonLdByPage,
+  };
+}

package/templates/apps/mcp/src/lib/errors.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical error shape for apps/mcp content-write tools (D14a Stage 0).
+ *
+ * Mirrors the apps/api shape (`apps/api/src/lib/errors.ts`) intentionally —
+ * REST and MCP surfaces must produce isomorphic error bodies (per brief
+ * Layer 1 AC). The only structural difference is that MCP returns the body as
+ * the tool result itself; HTTP carries it alongside a status code.
+ *
+ * Codes are the same closed set used by apps/api so an agent calling either
+ * surface gets the same machine-readable shape.
+ */
+
+export type ErrorCode =
+  | "validation_failed"
+  | "not_found"
+  | "conflict"
+  | "payment_required"
+  | "unauthorized";
+
+export interface ErrorBody {
+  error: ErrorCode;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+function makeBody(
+  code: ErrorCode,
+  message: string,
+  details?: Record<string, unknown>,
+): ErrorBody {
+  if (details === undefined) {
+    return { error: code, message };
+  }
+  return { error: code, message, details };
+}
+
+export function validationError(
+  message: string,
+  details?: Record<string, unknown>,
+): ErrorBody {
+  return makeBody("validation_failed", message, details);
+}
+
+export function unauthorizedError(message: string): ErrorBody {
+  return makeBody("unauthorized", message);
+}
+
+export function paymentRequiredError(message: string): ErrorBody {
+  return makeBody("payment_required", message);
+}
+
+export function notFoundError(message: string): ErrorBody {
+  return makeBody("not_found", message);
+}
+
+export function conflictError(
+  message: string,
+  details?: Record<string, unknown>,
+): ErrorBody {
+  return makeBody("conflict", message, details);
+}