@contractkit/plugin-typescript 0.34.0 → 0.35.0

package/src/codegen-operation.ts

@@ -21,10 +21,19 @@ import {
 import { renderOutputTsType, quoteKey, headerNameToProperty, escapeJsDocLines, escapeSingleQuoted, sourceLink } from './ts-render.js';
 import { DECIMAL_IMPORT, DECIMAL_PRELUDE_LINES } from './decimal-runtime.js';
 import { basename, dirname, relative } from 'path';
+import type { ServerFramework } from './server-framework.js';
+import { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
+
+/** Which request-side object a validation block reads from. Names the variable the block declares. */
+export type ParamKind = 'params' | 'query' | 'headers';
 
 // ─── Content-type helpers ──────────────────────────────────────────────────
 
-/** Map a request MIME type to the koa-bodyparser parser token used in middleware. */
+/**
+ * Map a request MIME type to the ServerKit parser token used in middleware. The tokens are the keys
+ * of the parser map in `@maroonedsoftware/servercore`, so they are the same whichever HTTP framework
+ * the router targets.
+ */
 function bodyParserToken(contentType: string): string {
     switch (classifyContentType(contentType)) {
         case 'urlencoded':
@@ -34,9 +43,8 @@ function bodyParserToken(contentType: string): string {
         case 'text':
             return 'text';
         case 'binary':
-            // koa-bodyparser has no native binary token; fall back to text so the body is
-            // still readable as a string. Services handling binary uploads should switch to
-            // multipart/form-data.
+            // There is no native binary token; fall back to text so the body is still readable as a
+            // string. Services handling binary uploads should switch to multipart/form-data.
             return 'text';
         default:
             return 'json';
@@ -125,7 +133,7 @@ export function bodyTypesStructurallyEqual(a: ContractTypeNode, b: ContractTypeN
 
 // ─── Public entry point ────────────────────────────────────────────────────
 
-/** Options controlling how {@link generateOp} renders a Koa router module. */
+/** Options controlling how {@link generateOp} renders a server router module. */
 export interface OpCodegenOptions {
     servicePathTemplate?: string;
     typeImportPathTemplate?: string;
@@ -143,8 +151,8 @@ export interface OpCodegenOptions {
      */
     includeInternal?: boolean;
     /**
-     * Re-parse the service result through its declared response schema before writing `ctx.body`,
-     * and write the parsed value. Requires the type file to hold Zod schemas (`server.zod`) —
+     * Re-parse the service result through its declared response schema before writing the response
+     * body, and write the parsed value. Requires the type file to hold Zod schemas (`server.zod`) —
      * plain interfaces are types, with no runtime schema value to validate against. Default false.
      */
     validateResponses?: boolean;
@@ -154,10 +162,18 @@ export interface OpCodegenOptions {
      * post-transform shape, which the schema itself cannot re-parse.
      */
     modelsWithTransform?: Set<string>;
+    /**
+     * Which HTTP framework the emitted router targets. Every framework-specific string in the output
+     * comes from here. Defaults to Koa, the only framework shipped today.
+     */
+    framework?: ServerFramework;
 }
 
+/** {@link OpCodegenOptions} after {@link generateOp} has filled in the framework default. */
+type ResolvedOpCodegenOptions = OpCodegenOptions & { framework: ServerFramework };
+
 /**
- * Generate a Koa router module for every operation in `root`, including the imports, type
+ * Generate a server router module for every operation in `root`, including the imports, type
  * aliases, and handler list.
  *
  * Imports are derived from the generated body — each candidate symbol is emitted only if it
@@ -166,6 +182,10 @@ export interface OpCodegenOptions {
  * trips `noUnusedLocals` and lint downstream.
  */
 export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): string {
+    // Resolved once here rather than defaulted at each use, so every helper below reads a framework
+    // that is definitely present and no branch can quietly fall back to a different one.
+    const resolved: ResolvedOpCodegenOptions = { ...options, framework: options.framework ?? KOA_SERVER_FRAMEWORK };
+    const framework = resolved.framework;
     // Collect all referenced types across all routes
     const types = collectTypes(root, options.modelsWithInput, options.modelsWithOutput);
     const services = collectServices(root);
@@ -177,14 +197,14 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
     lines.push('/**');
     lines.push(` * generated from ${sourceLink(basename(root.file), options.outPath, root.file)}`);
     lines.push('*/');
-    lines.push(`export const ${routerName} = ServerKitRouter();`);
+    lines.push(framework.routerDeclaration(routerName));
     lines.push('');
 
     const includeInternal = options.includeInternal ?? true;
     for (const route of root.routes) {
         for (const op of route.operations) {
             if (!includeInternal && resolveModifiers(route, op).includes('internal')) continue;
-            lines.push(...generateHandler(route, op, root, options));
+            lines.push(...generateHandler(route, op, root, resolved));
             lines.push('');
         }
     }
@@ -231,10 +251,7 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
 
     const body: string[] = [];
 
-    const koaImports = ['ServerKitRouter', 'bodyParserMiddleware', 'requirePolicy', 'requireSignature'].filter(uses);
-    if (koaImports.length > 0) {
-        body.push(`import { ${koaImports.join(', ')} } from '@maroonedsoftware/koa';`);
-    }
+    body.push(...framework.imports(uses));
 
     // Services and model names come from the AST, which over-approximates two ways: a model with an
     // Input/Output variant contributes its base name even when only the variant is ever annotated,
@@ -280,11 +297,12 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
 
 // ─── Handler generation ────────────────────────────────────────────────────
 
-function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNode, options: OpCodegenOptions): string[] {
+function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNode, options: ResolvedOpCodegenOptions): string[] {
     const lines: string[] = [];
     const file = root.file;
     const outPath = options.outPath;
     const modelsWithInput = options.modelsWithInput;
+    const framework = options.framework;
 
     lines.push('/**');
 
@@ -310,10 +328,10 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     lines.push('*/');
 
     const method = op.method;
-    // `:name` from `{name}`, mapped to a valid identifier. Unlike a query parameter or a header,
-    // a path placeholder's name never reaches the wire — Koa matches by position — so renaming it
-    // is free, and it is what lets `ctx.params` be destructured at all.
-    const path = route.path.replace(PATH_PARAM_RE_G, (_m, name: string) => `:${toIdentifier(name)}`);
+    // The framework's placeholder syntax, from `{name}`, mapped to a valid identifier. Unlike a query
+    // parameter or a header, a path placeholder's name never reaches the wire — the framework matches
+    // by position — so renaming it is free, and it is what lets the params object be destructured.
+    const path = route.path.replace(PATH_PARAM_RE_G, (_m, name: string) => framework.pathParam(toIdentifier(name)));
     const bodies = op.request?.bodies ?? [];
     const hasBody = bodies.length > 0;
     const isSingleMultipart = bodies.length === 1 && bodies[0]!.contentType === 'multipart/form-data';
@@ -328,39 +346,37 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
                 : policy === false
                   ? '{ policy: false }'
                   : `{ policy: '${policy}' }`;
-        middlewares.push(`requirePolicy(${args})`);
+        middlewares.push(framework.middleware.policy(args));
     }
     if (hasBody) {
         const parserTokens = Array.from(new Set(bodies.map(b => bodyParserToken(b.contentType))));
         const tokensExpr = parserTokens.map(t => `'${t}'`).join(', ');
-        middlewares.push(`bodyParserMiddleware([${tokensExpr}])`);
+        middlewares.push(framework.middleware.bodyParser(tokensExpr));
     }
     if (op.signature) {
         const sigArgs = op.signaturePolicy
             ? `'${escapeSingleQuoted(op.signature)}', { policy: '${escapeSingleQuoted(op.signaturePolicy)}' }`
             : `'${escapeSingleQuoted(op.signature)}'`;
-        middlewares.push(`requireSignature(${sigArgs})`);
+        middlewares.push(framework.middleware.signature(sigArgs));
     }
-    const middlewareStr = middlewares.length > 0 ? `, ${middlewares.join(', ')},` : ',';
-
-    lines.push(`${deriveRouterName(file)}.${method}('${path}'${middlewareStr} async ctx => {`);
+    lines.push(framework.routeOpen(deriveRouterName(file), method, path, middlewares));
 
     // Params / query / headers validation (request-side — use Input variants)
-    lines.push(...generateParamValidation(route.params, 'ctx.params', 'params', route.paramsMode ?? 'strict', '', modelsWithInput));
-    lines.push(...generateParamValidation(op.query, 'ctx.query', 'query', op.queryMode ?? 'strict', '', modelsWithInput));
-    lines.push(...generateParamValidation(op.headers, 'ctx.headers', 'headers', op.headersMode ?? 'strip', '', modelsWithInput));
+    lines.push(...generateParamValidation(route.params, 'params', framework.request.params, route.paramsMode ?? 'strict', '', modelsWithInput));
+    lines.push(...generateParamValidation(op.query, 'query', framework.request.query, op.queryMode ?? 'strict', '', modelsWithInput));
+    lines.push(...generateParamValidation(op.headers, 'headers', framework.request.headers, op.headersMode ?? 'strip', '', modelsWithInput));
 
     // Body validation (request-side — use Input variants)
     if (hasBody && op.request) {
         if (isSingleMultipart) {
-            lines.push(`    const multipartBody = ctx.parsedBody as MultipartBody;`);
+            lines.push(`    const multipartBody = ${framework.request.parsedBody} as MultipartBody;`);
             lines.push('');
         } else if (bodies.length === 1) {
-            lines.push(`    const body = await parseAndValidate(ctx.parsedBody, ${renderInputType(bodies[0]!.bodyType, modelsWithInput)});`);
+            lines.push(`    const body = await parseAndValidate(${framework.request.parsedBody}, ${renderInputType(bodies[0]!.bodyType, modelsWithInput)});`);
             lines.push('');
         } else if (bodies.every(b => bodyTypesStructurallyEqual(b.bodyType, bodies[0]!.bodyType))) {
             // All declared MIMEs share the same body shape — single validation suffices
-            lines.push(`    const body = await parseAndValidate(ctx.parsedBody, ${renderInputType(bodies[0]!.bodyType, modelsWithInput)});`);
+            lines.push(`    const body = await parseAndValidate(${framework.request.parsedBody}, ${renderInputType(bodies[0]!.bodyType, modelsWithInput)});`);
             lines.push('');
         } else {
             // Different body types per MIME — dispatch on Content-Type
@@ -370,13 +386,13 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
                 )
                 .join(' | ');
             lines.push(`    let body!: ${annotation};`);
-            lines.push(`    switch (ctx.request.type) {`);
+            lines.push(`    switch (${framework.request.contentType}) {`);
             for (const b of bodies) {
                 lines.push(`        case '${b.contentType}':`);
                 if (b.contentType === 'multipart/form-data') {
-                    lines.push(`            body = ctx.parsedBody as MultipartBody;`);
+                    lines.push(`            body = ${framework.request.parsedBody} as MultipartBody;`);
                 } else {
-                    lines.push(`            body = await parseAndValidate(ctx.parsedBody, ${renderInputType(b.bodyType, modelsWithInput)});`);
+                    lines.push(`            body = await parseAndValidate(${framework.request.parsedBody}, ${renderInputType(b.bodyType, modelsWithInput)});`);
                 }
                 lines.push(`            break;`);
             }
@@ -397,25 +413,26 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
         lines.push(...generateSingleStatusResult(emitted[0], op, serviceParts.className, call, options));
     }
 
-    lines.push(`});`);
+    lines.push(...framework.routeClose());
 
     return lines;
 }
 
 /**
  * The service produces exactly one status (or none): the result is the body itself, or
- * `{ body, headers }` when the status declares headers, and `ctx.status` is a constant.
+ * `{ body, headers }` when the status declares headers, and the status code is a constant.
  *
  * A status declaring several mimes also gains a `contentType` the service picks, which is the
- * only thing here that can turn `ctx.type` from a literal into an expression.
+ * only thing here that can turn the response content type from a literal into an expression.
  */
 function generateSingleStatusResult(
     resp: OpResponseNode | undefined,
     op: OpOperationNode,
     className: string,
     call: string,
-    options: OpCodegenOptions,
+    options: ResolvedOpCodegenOptions,
 ): string[] {
+    const framework = options.framework;
     const lines: string[] = [];
     const bodies = resp ? resp.bodies : [];
     const respHeaders = resp?.headers ?? [];
@@ -428,7 +445,7 @@ function generateSingleStatusResult(
         const { annotation, prelude } = formatTypeAnnotation(bodies[0]!.bodyType, options.modelsWithOutput);
         if (prelude) lines.push(`    ${prelude}`);
         bodySchema = responseBodySchema(bodies[0]!.bodyType, options, prelude ? 'resultType' : undefined);
-        lines.push(`    const service = ctx.container.get(${className});`);
+        lines.push(`    const service = ${framework.resolveService(className)};`);
         if (hasRespHeaders) {
             lines.push(`    const result: { body: ${annotation}; headers: ${headersAnnotation} } = ${call};`);
         } else {
@@ -439,10 +456,10 @@ function generateSingleStatusResult(
         const { members, preludes } = rendered;
         bodySchema = rendered.bodySchema;
         for (const prelude of preludes) lines.push(`    ${prelude}`);
-        lines.push(`    const service = ctx.container.get(${className});`);
+        lines.push(`    const service = ${framework.resolveService(className)};`);
         lines.push(`    const result: ${members.join(' | ')} = ${call};`);
     } else {
-        lines.push(`    const service = ctx.container.get(${className});`);
+        lines.push(`    const service = ${framework.resolveService(className)};`);
         if (hasRespHeaders) {
             lines.push(`    const result: { headers: ${headersAnnotation} } = ${call};`);
         } else {
@@ -456,15 +473,18 @@ function generateSingleStatusResult(
     // also what aligns the three generators: `observableResponses` excludes a bare `400:` too, so
     // the SDK already types such a method `Promise<void>` and `thrownResponses` puts the 400 in
     // `@throws`. A bodyless 204 success is exactly what `Promise<void>` means.
-    lines.push(`    ctx.status = ${resp?.statusCode ?? 204};`);
-    lines.push(...headerSetLines(respHeaders, '    '));
+    lines.push(`    ${framework.response.status(String(resp?.statusCode ?? 204))}`);
+    lines.push(...headerSetLines(respHeaders, '    ', framework));
 
     if (bodies.length === 1) {
-        lines.push(`    ctx.type = '${bodies[0]!.contentType}';`);
-        lines.push(`    ctx.body = ${responseBodyExpr(hasRespHeaders ? 'result.body' : 'result', bodySchema)};`);
+        lines.push(`    ${framework.response.type(`'${bodies[0]!.contentType}'`)}`);
+        lines.push(...indent(framework.response.send(responseBodyExpr(hasRespHeaders ? 'result.body' : 'result', bodySchema)), '    '));
     } else if (bodies.length > 1) {
-        lines.push(`    ctx.type = result.contentType;`);
-        lines.push(`    ctx.body = ${responseBodyExpr('result.body', bodySchema)};`);
+        lines.push(`    ${framework.response.type('result.contentType')}`);
+        lines.push(...indent(framework.response.send(responseBodyExpr('result.body', bodySchema)), '    '));
+    } else {
+        // Nothing to write, but a framework that ends a response by returning still needs a statement.
+        lines.push(...indent(framework.response.send(undefined), '    '));
     }
 
     return lines;
@@ -475,7 +495,8 @@ function generateSingleStatusResult(
  * `status`, and the handler switches on it so each status writes only its own headers, mime
  * and body.
  */
-function generateMultiStatusResult(emitted: OpResponseNode[], className: string, call: string, options: OpCodegenOptions): string[] {
+function generateMultiStatusResult(emitted: OpResponseNode[], className: string, call: string, options: ResolvedOpCodegenOptions): string[] {
+    const framework = options.framework;
     const lines: string[] = [];
     const members: string[] = [];
     const preludes: string[] = [];
@@ -490,21 +511,23 @@ function generateMultiStatusResult(emitted: OpResponseNode[], className: string,
     }
 
     for (const prelude of preludes) lines.push(`    ${prelude}`);
-    lines.push(`    const service = ctx.container.get(${className});`);
+    lines.push(`    const service = ${framework.resolveService(className)};`);
     lines.push(`    const result:`);
     for (const member of members) lines.push(`        | ${member}`);
     lines.push(`        = ${call};`);
     lines.push('');
-    lines.push(`    ctx.status = result.status;`);
+    lines.push(`    ${framework.response.status('result.status')}`);
     lines.push(`    switch (result.status) {`);
     for (const resp of emitted) {
         lines.push(`        case ${resp.statusCode}:`);
-        lines.push(...headerSetLines(resp.headers ?? [], '            '));
+        lines.push(...headerSetLines(resp.headers ?? [], '            ', framework));
         if (resp.bodies.length > 0) {
-            lines.push(`            ctx.type = result.contentType;`);
-            lines.push(`            ctx.body = ${responseBodyExpr('result.body', bodySchemas.get(resp.statusCode))};`);
+            lines.push(`            ${framework.response.type('result.contentType')}`);
+            lines.push(...indent(framework.response.send(responseBodyExpr('result.body', bodySchemas.get(resp.statusCode))), '            '));
+        } else {
+            lines.push(...indent(framework.response.send(undefined), '            '));
         }
-        lines.push(`            break;`);
+        lines.push(...indent(framework.response.caseEnd(), '            '));
     }
     lines.push(`    }`);
 
@@ -565,16 +588,20 @@ function renderHeadersAnnotation(headers: OpResponseHeaderNode[], modelsWithOutp
     return `{ ${fields.join('; ')} }`;
 }
 
-/** `ctx.set(...)` calls for a status's declared response headers, guarding the optional ones. */
-function headerSetLines(headers: OpResponseHeaderNode[], indent: string): string[] {
+/** Response-header writes for a status's declared headers, guarding the optional ones. */
+function headerSetLines(headers: OpResponseHeaderNode[], pad: string, framework: ServerFramework): string[] {
     return headers.map(h => {
         const accessor = `result.headers[${JSON.stringify(headerNameToProperty(h.name))}]`;
-        return h.optional
-            ? `${indent}if (${accessor} !== undefined) ctx.set('${h.name}', String(${accessor}));`
-            : `${indent}ctx.set('${h.name}', String(${accessor}));`;
+        const write = framework.response.header(h.name, `String(${accessor})`);
+        return h.optional ? `${pad}if (${accessor} !== undefined) ${write}` : `${pad}${write}`;
     });
 }
 
+/** Prefix each of a framework's statements with the handler indentation the caller is writing at. */
+function indent(lines: string[], pad: string): string[] {
+    return lines.map(line => `${pad}${line}`);
+}
+
 // ─── Inference helpers ─────────────────────────────────────────────────────
 
 /**
@@ -778,7 +805,7 @@ function responseBodySchema(bodyType: ContractTypeNode, options: OpCodegenOption
 }
 
 /**
- * The `ctx.body = ...` right-hand side for a response body: the raw result expression, or a
+ * The right-hand side of a response body write: the raw result expression, or a
  * `parseAndValidate` of it. The `500` is deliberate — a service returning a shape its own contract
  * rejects is a server fault, not a client one, and `@maroonedsoftware/zod` routes the field-level
  * detail to `internalDetails` (log-only) rather than the response body at 5xx.
@@ -789,37 +816,35 @@ function responseBodyExpr(value: string, schema: string | undefined): string {
 
 function generateParamValidation(
     source: ParamSource | undefined,
-    ctxExpr: string,
-    varName: string,
+    kind: ParamKind,
+    sourceExpr: string,
     mode: ObjectMode,
     suffix = '',
     modelsWithInput?: Set<string>,
 ): string[] {
     if (!source) return [];
     const lines: string[] = [];
-    const isQuery = ctxExpr === 'ctx.query';
+    const isQuery = kind === 'query';
+    // Path params are destructured and spread into the service call; query and headers pass as
+    // whole objects. The variable the block declares is named after the kind either way.
+    const isPathParams = kind === 'params';
     if (source.kind === 'ref') {
         // Type reference — apply mode as a method call on the schema
         const typeName = modelsWithInput?.has(source.name) ? `${source.name}Input` : source.name;
-        lines.push(`    const ${varName} = await parseAndValidate(${ctxExpr}, ${typeName}.${mode}());`);
+        lines.push(`    const ${kind} = await parseAndValidate(${sourceExpr}, ${typeName}.${mode}());`);
         lines.push('');
     } else if (source.kind === 'params') {
         // Inline param declarations — wrap with the appropriate z.*Object constructor
         if (source.nodes.length > 0) {
-            // Destructure only for params (spread individually in service call);
-            // query/headers are passed as whole objects.
-            // Path params are destructured and spread into the service call; query and headers pass
-            // as whole objects.
-            const isPathParams = ctxExpr === 'ctx.params';
             const bind = (name: string) => (isPathParams ? toIdentifier(name) : name);
-            const lhs = varName === 'params' ? `{ ${source.nodes.map(p => bind(p.name)).join(', ')} }` : varName;
+            const lhs = isPathParams ? `{ ${source.nodes.map(p => bind(p.name)).join(', ')} }` : kind;
             lines.push(`    const ${lhs} = await parseAndValidate(`);
-            lines.push(`        ${ctxExpr},`);
+            lines.push(`        ${sourceExpr},`);
             lines.push(`        ${modeToWrapper(mode)}({`);
             for (const param of source.nodes) {
                 // For path params the key must match the name in the route pattern above, which
-                // is what `ctx.params` is keyed by. For query and headers it is the wire name,
-                // quoted when that is not an identifier — those the client actually sends.
+                // is what the framework keys its params object by. For query and headers it is the
+                // wire name, quoted when that is not an identifier — those the client actually sends.
                 const bound = bind(param.name);
                 const key = isValidIdentifier(bound) ? bound : `'${bound}'`;
                 // Delegating to renderQueryType rather than hand-rolling the array preprocess here:
@@ -837,7 +862,7 @@ function generateParamValidation(
         // ContractTypeNode — use query-aware rendering for query params (coerces single string → array),
         // otherwise use Input variant rendering; apply mode as a method call
         const schema = isQuery ? renderQueryType(source.node, modelsWithInput) : renderInputType(source.node, modelsWithInput);
-        lines.push(`    const ${varName} = await parseAndValidate(${ctxExpr}, (${schema}).${mode}());`);
+        lines.push(`    const ${kind} = await parseAndValidate(${sourceExpr}, (${schema}).${mode}());`);
         lines.push('');
     }
     return lines;

package/src/index.ts

@@ -45,6 +45,16 @@ import {
 } from './codegen-sdk.js';
 import { generatePlainTypes } from './codegen-plain-types.js';
 import { DEFAULT_REVIVABLE_SCALARS } from './codegen-revive.js';
+import { resolveServerFramework, SERVER_FRAMEWORK_NAMES, type ServerFrameworkName } from './server-framework.js';
+export {
+    SERVER_FRAMEWORK_NAMES,
+    DEFAULT_SERVER_FRAMEWORK_NAME,
+    resolveServerFramework,
+    SERVER_FRAMEWORKS,
+    type ServerFramework,
+    type ServerFrameworkName,
+} from './server-framework.js';
+export { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
 
 /** Taint set for the SDK's bigint response reviver. */
 const BIGINT_SCALARS: ReadonlySet<ScalarTypeNode['name']> = new Set(['bigint']);
@@ -65,14 +75,19 @@ import {
 
 // ─── Sub-config interfaces ─────────────────────────────────────────────────
 
-/** Koa server output: routers, and the type or Zod schema files they import. */
+/** Server output: routers, and the type or Zod schema files they import. */
 export interface ServerConfig {
     /** Directory (relative to rootDir) where server files are written. Default: rootDir. */
     baseDir?: string;
+    /**
+     * HTTP framework the generated routers target. Also selects the flavour of the optional
+     * `mcp.router.ts` the `mcp` sub-config emits. Supported: `'koa'`. Default `'koa'`.
+     */
+    framework?: ServerFrameworkName;
     /** When true, `output.types` emits Zod schema files (via `generateContract`). When false/omitted, emits plain TypeScript. */
     zod?: boolean;
     output?: {
-        /** Path template for Koa router files. Supports {filename}, {dir}, {area}. */
+        /** Path template for router files. Supports {filename}, {dir}, {area}. */
         routes?: string;
         /** Path template for type/schema files. Supports {filename}, {dir}, {area}. */
         types?: string;
@@ -151,7 +166,7 @@ export interface McpConfig {
          */
         types?: string;
     };
-    /** Emit the `mcp.router.ts` route boilerplate. Default true. */
+    /** Emit the `mcp.router.ts` route boilerplate. Its framework follows `server.framework`. Default true. */
     emitRouter?: boolean;
     /** Mount path used in the emitted router. Default `/mcp`. */
     path?: string;
@@ -207,6 +222,14 @@ export function createTypescriptPlugin(config: TypescriptPluginConfig, rootDir:
 
 /** Reject config combinations that would generate code that cannot compile or cannot run. */
 function assertValidConfig(config: TypescriptPluginConfig): void {
+    // Runtime check, not just a type: config arrives as JSON, so `ServerFrameworkName` constrains
+    // programmatic callers only. Checked before the rest so a typo'd framework is the error reported.
+    const framework = config.server?.framework;
+    if (framework !== undefined && !(SERVER_FRAMEWORK_NAMES as readonly string[]).includes(framework)) {
+        throw new Error(
+            `plugin-typescript: server.framework '${String(framework)}' is not supported — expected one of: ${SERVER_FRAMEWORK_NAMES.join(', ')}.`,
+        );
+    }
     if (config.server?.validateResponses && !config.server.zod) {
         throw new Error(
             'plugin-typescript: server.validateResponses requires server.zod: true — without it output.types emits plain TypeScript interfaces, which are types with no runtime schema value for the router to validate against.',
@@ -367,6 +390,7 @@ function collectServerOutput(
     units: IncrementalUnit[],
 ): void {
     const serverBase = resolve(rootDir, config.baseDir ?? '.');
+    const framework = resolveServerFramework(config.framework);
     const modelsWithInput = inputs.modelsWithInput as Set<string>;
     const modelsWithOutput = inputs.modelsWithOutput as Set<string>;
     // Not `modelsWithOutput`: that set seeds only from `format(output=...)`, because only that case
@@ -418,7 +442,7 @@ function collectServerOutput(
                     currentOutPath: typeOutPath,
                     modelsWithInput,
                     modelsWithOutput,
-                    // These types are consumed by Koa handlers, so `binary` is a Buffer, not a Blob.
+                    // These types are consumed by server handlers, so `binary` is a Buffer, not a Blob.
                     target: 'server' as const,
                 };
                 const content = config.zod ? generateContract(ast, renderCtx) : generatePlainTypes(ast, renderCtx);
@@ -446,6 +470,9 @@ function collectServerOutput(
             // this router's output with no change to `root` or the config.
             modelsWithTransform: sliceModelSet(refs, new Set(), modelsWithTransform),
             validateResponses: config.validateResponses ?? false,
+            // Covered by `sub` already, which is the whole sub-config; explicit for the same reason
+            // `validateResponses` is — the inputs that change a router's text read at a glance.
+            framework: framework.name,
             sub: subConfigKey,
         });
         units.push({
@@ -463,6 +490,7 @@ function collectServerOutput(
                         modelsWithTransform,
                         includeInternal: config.includeInternal,
                         validateResponses: config.validateResponses,
+                        framework,
                     }),
                 },
             ],
@@ -1107,7 +1135,10 @@ function collectMcpOutput(
     // ── Router (global, optional) ──
     if (config.emitRouter !== false) {
         const routerPath = join(mcpBase, config.output?.router ?? 'mcp.router.ts');
-        globalFiles.push({ relativePath: routerPath, content: generateMcpRouter({ path: config.path }) });
+        // The mount is server-side wiring, so it follows the server sub-config's framework. Koa when
+        // there is no `server` sub-config at all, which is the same default the router generator has.
+        const framework = resolveServerFramework(fullConfig.server?.framework);
+        globalFiles.push({ relativePath: routerPath, content: generateMcpRouter({ path: config.path, framework }) });
     }
 }
 

package/src/server-framework-koa.ts

@@ -0,0 +1,112 @@
+import type { ServerFramework } from './server-framework.js';
+
+/** Module the Koa flavour of ServerKit publishes its router and route middleware from. */
+const KOA_RUNTIME_MODULE = '@maroonedsoftware/koa';
+
+/**
+ * Symbols importable from {@link KOA_RUNTIME_MODULE}. Every one is a name the adapter itself emits,
+ * so none can collide with a service class or router name derived from a contract.
+ */
+const KOA_RUNTIME_SYMBOLS = ['ServerKitRouter', 'bodyParserMiddleware', 'requirePolicy', 'requireSignature'] as const;
+
+/**
+ * ServerKit on Koa: the router is a `@koa/router` instance, handlers take a single `ctx`, and a
+ * response is written by assigning to `ctx.status` / `ctx.type` / `ctx.body` rather than returned.
+ */
+export const KOA_SERVER_FRAMEWORK: ServerFramework = {
+    name: 'koa',
+
+    imports(uses) {
+        const symbols = KOA_RUNTIME_SYMBOLS.filter(uses);
+        return symbols.length > 0 ? [`import { ${symbols.join(', ')} } from '${KOA_RUNTIME_MODULE}';`] : [];
+    },
+
+    routerDeclaration(routerName) {
+        return `export const ${routerName} = ServerKitRouter();`;
+    },
+
+    pathParam(identifier) {
+        return `:${identifier}`;
+    },
+
+    routeOpen(routerName, method, path, middlewares) {
+        const middlewareStr = middlewares.length > 0 ? `, ${middlewares.join(', ')},` : ',';
+        return `${routerName}.${method}('${path}'${middlewareStr} async ctx => {`;
+    },
+
+    routeClose() {
+        return ['});'];
+    },
+
+    middleware: {
+        policy(args) {
+            return `requirePolicy(${args})`;
+        },
+        bodyParser(tokensExpr) {
+            return `bodyParserMiddleware([${tokensExpr}])`;
+        },
+        signature(args) {
+            return `requireSignature(${args})`;
+        },
+    },
+
+    request: {
+        params: 'ctx.params',
+        query: 'ctx.query',
+        headers: 'ctx.headers',
+        // Not `ctx.request.body`: the ServerKit body parser drains the stream and writes its result
+        // here, and in Koa `ctx.body` is the *response* body.
+        parsedBody: 'ctx.parsedBody',
+        // Koa strips the parameters off `Content-Type` for this accessor already.
+        contentType: 'ctx.request.type',
+    },
+
+    resolveService(className) {
+        return `ctx.container.get(${className})`;
+    },
+
+    response: {
+        status(expr) {
+            return `ctx.status = ${expr};`;
+        },
+        header(name, valueExpr) {
+            return `ctx.set('${name}', ${valueExpr});`;
+        },
+        type(expr) {
+            return `ctx.type = ${expr};`;
+        },
+        send(bodyExpr) {
+            // A bodyless response needs no statement at all: Koa sends whatever `ctx.status` and the
+            // headers say once the handler resolves.
+            return bodyExpr === undefined ? [] : [`ctx.body = ${bodyExpr};`];
+        },
+        caseEnd() {
+            return ['break;'];
+        },
+    },
+
+    mcpRouter({ path }) {
+        return `import { ServerKitRouter, bodyParserMiddleware, requireSignature } from '${KOA_RUNTIME_MODULE}';
+import { McpDispatcher, createMcpRequestContext, MCP_AUTH_POLICY } from '@maroonedsoftware/mcp';
+
+/** Mount the MCP endpoint onto a ServerKit router. Bind \`registerMcpTools\` to the \`McpToolHandlerMap\` token. */
+export function mountMcp(router: ReturnType<typeof ServerKitRouter>): void {
+    router.post('${path}', bodyParserMiddleware(['json']), requireSignature('mcp', { policy: MCP_AUTH_POLICY }), async (ctx) => {
+        const dispatcher = ctx.container.get(McpDispatcher);
+        const context = createMcpRequestContext({ requestId: ctx.requestId, logger: ctx.logger });
+        if (dispatcher.sessionMode === 'stateful') {
+            ctx.respond = false;
+            await dispatcher.dispatchStateful(
+                { req: ctx.req, res: ctx.res, body: ctx.parsedBody, sessionId: ctx.get('mcp-session-id') },
+                context,
+            );
+        } else {
+            const response = await dispatcher.dispatch(JSON.parse(String(ctx.rawBody)), context);
+            if (response) ctx.body = response;
+            else ctx.status = 202; // a notification — nothing to return
+        }
+    });
+}
+`;
+    },
+};