@contractkit/plugin-typescript 0.34.1 → 0.35.0

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
+        }
+    });
+}
+`;
+    },
+};

package/src/server-framework.ts

@@ -0,0 +1,119 @@
+import { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
+
+/**
+ * HTTP frameworks the server sub-generator can target. Adding a name here without adding an adapter
+ * to {@link SERVER_FRAMEWORKS} fails to compile, which is the point of keeping the two in step.
+ */
+export const SERVER_FRAMEWORK_NAMES = ['koa'] as const;
+
+/** One of {@link SERVER_FRAMEWORK_NAMES}. */
+export type ServerFrameworkName = (typeof SERVER_FRAMEWORK_NAMES)[number];
+
+/** The framework assumed when a config names none. */
+export const DEFAULT_SERVER_FRAMEWORK_NAME: ServerFrameworkName = 'koa';
+
+/**
+ * Every framework-specific string the router and MCP router generators emit.
+ *
+ * Granularity is one statement (or one fragment) per method, so the shared codegen keeps ownership
+ * of control flow — which branches exist, what order they run in, and which values reach them — and
+ * an adapter only decides how a given step is spelled. Anything an adapter cannot express as a
+ * statement, such as ending a response, is returned as a list of lines so it can also be empty.
+ */
+export interface ServerFramework {
+    readonly name: ServerFrameworkName;
+
+    /**
+     * Import lines for the framework runtime, already filtered down to what the generated body uses.
+     *
+     * The adapter applies `uses` itself rather than declaring a symbol list, because a framework may
+     * need more than one import line, and because only names the adapter chooses ever go through the
+     * word-boundary probe — a handler-local identifier can never be mistaken for an import.
+     */
+    imports(uses: (symbol: string) => boolean): string[];
+
+    /** The module-level router value every handler attaches to. */
+    routerDeclaration(routerName: string): string;
+
+    /** Placeholder syntax for one path parameter, given a name already mapped to a valid identifier. */
+    pathParam(identifier: string): string;
+
+    /** Opening line of a handler, including its middleware and the handler function's parameters. */
+    routeOpen(routerName: string, method: string, path: string, middlewares: readonly string[]): string;
+
+    /** Lines that close a handler opened by {@link routeOpen}. */
+    routeClose(): string[];
+
+    /** Route middleware factory calls, rendered as expressions for {@link routeOpen}. */
+    readonly middleware: {
+        policy(args: string): string;
+        bodyParser(tokensExpr: string): string;
+        signature(args: string): string;
+    };
+
+    /** Expressions a handler reads the request through. */
+    readonly request: {
+        params: string;
+        query: string;
+        headers: string;
+        /** The body already parsed by the body-parser middleware. */
+        parsedBody: string;
+        /**
+         * The request's media type with any parameters stripped. It is matched against declared MIME
+         * literals, so an adapter whose framework exposes only the raw header must normalise it here
+         * — a `; charset=utf-8` left on the end matches nothing.
+         */
+        contentType: string;
+    };
+
+    /** Expression resolving a service class out of the request-scoped DI container. */
+    resolveService(className: string): string;
+
+    /** Statements a handler writes the response with. */
+    readonly response: {
+        status(expr: string): string;
+        /**
+         * One statement setting a response header. It is emitted bare or behind an `if` guard for an
+         * optional header, so it must stay a single statement.
+         */
+        header(name: string, valueExpr: string): string;
+        type(expr: string): string;
+        /**
+         * The terminal write for a response, or for one without a body when `bodyExpr` is undefined.
+         * A framework that ends a response by returning needs a statement in both cases; Koa, which
+         * ends it by assignment, emits nothing for a bodyless one.
+         */
+        send(bodyExpr: string | undefined): string[];
+        /** What closes one `case` of the multi-status switch, after that status has been written. */
+        caseEnd(): string[];
+    };
+
+    /** The whole `mcp.router.ts` file, which is boilerplate rather than a per-operation render. */
+    mcpRouter(options: { path: string }): string;
+}
+
+/**
+ * Every supported framework, keyed by name. The annotation is what ties this to
+ * {@link SERVER_FRAMEWORK_NAMES}: adding a name without an adapter is a compile error.
+ */
+export const SERVER_FRAMEWORKS: Readonly<Record<ServerFrameworkName, ServerFramework>> = {
+    koa: KOA_SERVER_FRAMEWORK,
+};
+
+/**
+ * Resolve a configured framework name to its adapter.
+ *
+ * @param name The `server.framework` value, or undefined for {@link DEFAULT_SERVER_FRAMEWORK_NAME}.
+ * @throws When `name` is not a supported framework. Config arrives as JSON, so this is a runtime
+ *   check and not something the `ServerFrameworkName` type can enforce on its own.
+ */
+export function resolveServerFramework(name: string | undefined): ServerFramework {
+    const resolved = name ?? DEFAULT_SERVER_FRAMEWORK_NAME;
+    const framework = (SERVER_FRAMEWORKS as Record<string, ServerFramework | undefined>)[resolved];
+    if (!framework) {
+        throw new Error(
+            `plugin-typescript: server.framework '${resolved}' is not supported — expected one of: ${SERVER_FRAMEWORK_NAMES.join(', ')}.`,
+        );
+    }
+    return framework;
+}

package/tests/codegen-mcp.test.ts

@@ -286,6 +286,18 @@ describe('generateMcpRouter', () => {
         expect(out).not.toContain('ctx.request.body');
     });
 
+        it('delegates the whole file to the framework adapter', () => {
+            const stub = { mcpRouter: ({ path }: { path: string }) => `// stub mount at ${path}` };
+            // Only `mcpRouter` is reachable from here, so the rest of the adapter is left off the stub.
+            const out = generateMcpRouter({ framework: stub as never });
+            expect(out).toBe('// stub mount at /mcp');
+        });
+
+        it('passes a configured path through to the adapter', () => {
+            const stub = { mcpRouter: ({ path }: { path: string }) => `// stub mount at ${path}` };
+            expect(generateMcpRouter({ path: '/tools', framework: stub as never })).toBe('// stub mount at /tools');
+        });
+
     it('defaults the mount path to /mcp', () => {
         expect(generateMcpRouter()).toContain("router.post('/mcp'");
     });

package/tests/codegen-operation-framework.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from 'vitest';
+import { generateOp } from '../src/codegen-operation.js';
+import type { ServerFramework } from '../src/server-framework.js';
+import { scalarType, refType, opParam, opRequest, opMultiRequest, opResponse, opResponseMulti, opOperation, opRoute, opRoot } from './helpers.js';
+
+/**
+ * A framework whose every string is unmistakable. Rendering a router through it and finding no Koa
+ * left in the output is what proves the seam is complete: a `ctx.` the generator still emits inline
+ * would survive this substitution, and a `toContain` test against the Koa output never notices,
+ * because the default adapter puts the very same string there.
+ */
+const STUB: ServerFramework = {
+    // The registry's key type admits only shipped frameworks; the adapter under test is a fake.
+    name: 'koa',
+    imports: uses => (uses('StubRouter') ? ["import { StubRouter } from '@stub/http';"] : []),
+    routerDeclaration: routerName => `export const ${routerName} = StubRouter();`,
+    pathParam: identifier => `<${identifier}>`,
+    routeOpen: (routerName, method, path, middlewares) => `${routerName}.route('${method}', '${path}', [${middlewares.join(', ')}], async (rq, rs) => {`,
+    routeClose: () => ['}, END);'],
+    middleware: {
+        policy: args => `stubPolicy(${args})`,
+        bodyParser: tokens => `stubBody(${tokens})`,
+        signature: args => `stubSignature(${args})`,
+    },
+    request: {
+        params: 'rq.pathParams',
+        query: 'rq.searchParams',
+        headers: 'rq.headerBag',
+        parsedBody: 'rq.payload',
+        contentType: 'rq.mediaType',
+    },
+    resolveService: className => `rq.services.resolve(${className})`,
+    response: {
+        status: expr => `rs.setStatus(${expr});`,
+        header: (name, valueExpr) => `rs.putHeader('${name}', ${valueExpr});`,
+        type: expr => `rs.setMedia(${expr});`,
+        send: bodyExpr => (bodyExpr === undefined ? ['return rs.finish();'] : [`return rs.deliver(${bodyExpr});`]),
+        caseEnd: () => [],
+    },
+    mcpRouter: ({ path }) => `// stub mcp at ${path}\n`,
+};
+
+/** One op root touching every branch of the generator that can emit a framework string. */
+function everyBranchRoot() {
+    return opRoot([
+        opRoute(
+            '/payments/{paymentId}',
+            [
+            // Path params + query + headers + a single JSON body, with policy and signature middleware.
+            opOperation('post', {
+                request: opRequest('Payment'),
+                query: [opParam('limit', scalarType('int'))],
+                headers: [opParam('x-tenant', scalarType('string'))],
+                signature: 'stripe',
+                responses: [opResponse(201, 'Payment')],
+            }),
+            // Several request MIMEs with different shapes — the content-type switch.
+            opOperation('put', {
+                request: opMultiRequest([
+                    ['application/json', 'Payment'],
+                    ['multipart/form-data', 'Receipt'],
+                ]),
+                responses: [opResponse(200, 'Payment')],
+            }),
+            // No emitted body at all — the bodyless 204 path.
+            opOperation('delete', { responses: [] }),
+            // Several emitted statuses, one carrying response headers — the status switch.
+            opOperation('patch', {
+                responses: [
+                    opResponseMulti(200, [{ contentType: 'application/json', bodyType: 'Payment' }], {
+                        headers: [{ name: 'etag', optional: false, type: scalarType('string') }],
+                    }),
+                    opResponseMulti(202, [{ contentType: 'application/json', bodyType: refType('Payment') }], {
+                        headers: [{ name: 'retry-after', optional: true, type: scalarType('string') }],
+                    }),
+                ],
+            }),
+            ],
+            [opParam('paymentId', scalarType('uuid'))],
+        ),
+    ]);
+}
+
+describe('generateOp — framework seam', () => {
+    const output = generateOp(everyBranchRoot(), { framework: STUB });
+
+    it('leaves no Koa string anywhere in the output', () => {
+        expect(output).not.toMatch(/\bctx\b/);
+        expect(output).not.toContain('ServerKitRouter');
+        expect(output).not.toContain('@maroonedsoftware/koa');
+        expect(output).not.toContain('requirePolicy');
+        expect(output).not.toContain('bodyParserMiddleware');
+        expect(output).not.toContain('requireSignature');
+    });
+
+    it('renders the router shell through the adapter', () => {
+        expect(output).toContain('export const UsersRouter = StubRouter();');
+        expect(output).toContain("import { StubRouter } from '@stub/http';");
+        expect(output).toContain('}, END);');
+    });
+
+    it('renders the route line, its path params and its middleware through the adapter', () => {
+        expect(output).toContain("UsersRouter.route('post', '/payments/<paymentId>', [stubPolicy(), stubBody('json'), stubSignature('stripe')], async (rq, rs) => {");
+    });
+
+    it('reads params, query, headers and the body through the adapter', () => {
+        expect(output).toContain('rq.pathParams');
+        expect(output).toContain('rq.searchParams');
+        expect(output).toContain('rq.headerBag');
+        expect(output).toContain('rq.payload');
+        expect(output).toContain('switch (rq.mediaType) {');
+    });
+
+    it('resolves services through the adapter', () => {
+        expect(output).toContain('rq.services.resolve(UsersService)');
+    });
+
+    it('writes status, headers, content type and body through the adapter', () => {
+        expect(output).toContain('rs.setStatus(201);');
+        expect(output).toContain("rs.setMedia('application/json');");
+        expect(output).toContain('return rs.deliver(result);');
+        expect(output).toContain('rs.putHeader(\'etag\', String(result.headers["etag"]));');
+        expect(output).toContain('if (result.headers["retryAfter"] !== undefined) rs.putHeader(\'retry-after\', String(result.headers["retryAfter"]));');
+    });
+
+    it('gives a bodyless response the adapter\'s terminal statement', () => {
+        // Koa needs none, so the generator only emits one because the adapter asked for it.
+        expect(output).toContain('rs.setStatus(204);');
+        expect(output).toContain('return rs.finish();');
+    });
+
+    it('omits the status-case terminator when the adapter has none', () => {
+        expect(output).toContain('rs.setStatus(result.status);');
+        // Scoped to the status switch: the multi-MIME request dispatch is the generator's own control
+        // flow and keeps its `break;` whatever the framework is.
+        const statusSwitch = output.slice(output.indexOf('switch (result.status) {'));
+        expect(statusSwitch).toContain('case 202:');
+        expect(statusSwitch).not.toContain('break;');
+    });
+});

package/tests/codegen-operation.test.ts

@@ -567,6 +567,35 @@ describe('generateOperation', () => {
             expect(output).toContain('z.object({');
         });
 
+        it('renders an inline array header through renderInputType, without the query coercion', () => {
+            // The comma-splitting preprocess belongs to query strings only. Headers and params share
+            // the same inline-param renderer, so the block has to be told which one it is rendering.
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        headers: [opParam('x-tags', arrayType(scalarType('string')))],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root);
+            expect(output).toContain('ctx.headers');
+            expect(output).not.toContain('z.preprocess');
+            expect(output).not.toContain("v.split(',')");
+        });
+
+        it('declares headers as a whole object rather than destructuring it', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        headers: [opParam('authorization', scalarType('string'))],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root);
+            expect(output).toContain('const headers = await parseAndValidate(');
+            expect(output).not.toContain('const { authorization }');
+        });
+
         it('generates parseAndValidate import when operation has headers', () => {
             const root = opRoot([
                 opRoute('/users', [

package/tests/codegen-server.test.ts

@@ -37,6 +37,13 @@ function inputs(opRoots = [opRoot([opRoute('/users', [opOperation('get')])], '/p
     };
 }
 
+/** Inputs carrying an MCP-exposed operation, which is what makes the mcp sub-generator emit a router. */
+function mcpInputs() {
+    return inputs([
+        opRoot([opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])], '/project/contracts/users.ck'),
+    ]);
+}
+
 // ─── Tests ─────────────────────────────────────────────────────────────────
 
 describe('createTypescriptPlugin (server)', () => {
@@ -224,6 +231,55 @@ describe('createTypescriptPlugin (server)', () => {
         });
     });
 
+    describe('framework', () => {
+        it('emits a Koa router when no framework is configured', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs(), ctx);
+            const [content] = [...ctx.emitted.values()];
+            expect(content).toContain("from '@maroonedsoftware/koa'");
+        });
+
+        it('emits byte-identical output when koa is named explicitly', async () => {
+            const runWith = async (server: Record<string, unknown>) => {
+                const ctx = makeCtx('/project');
+                await createTypescriptPlugin({ server }, '/project').generateTargets!(inputs(), ctx);
+                return [...ctx.emitted.values()].join('\n');
+            };
+            expect(await runWith({ framework: 'koa' })).toEqual(await runWith({}));
+        });
+
+        it('rejects a framework that has no adapter', async () => {
+            const plugin = createTypescriptPlugin({ server: { framework: 'express' as never } }, '/project');
+            await expect(plugin.generateTargets!(inputs(), makeCtx('/project'))).rejects.toThrow(
+                /server\.framework 'express' is not supported — expected one of: koa/,
+            );
+        });
+
+        it('rejects the unknown framework before any other config complaint', async () => {
+            // Both rules are broken here; the framework is the one reported, since a router for a
+            // framework that does not exist cannot be generated whatever the other settings say.
+            const plugin = createTypescriptPlugin({ server: { framework: 'express' as never, validateResponses: true } }, '/project');
+            await expect(plugin.generateTargets!(inputs(), makeCtx('/project'))).rejects.toThrow(/server\.framework/);
+        });
+
+        it('renders mcp.router.ts for the configured framework', async () => {
+            const plugin = createTypescriptPlugin({ server: { framework: 'koa' }, mcp: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(mcpInputs(), ctx);
+            const router = [...ctx.emitted.entries()].find(([p]) => p.endsWith('mcp.router.ts'))?.[1];
+            expect(router).toContain("from '@maroonedsoftware/koa'");
+        });
+
+        it('still emits a Koa mcp.router.ts when there is no server sub-config', async () => {
+            const plugin = createTypescriptPlugin({ mcp: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(mcpInputs(), ctx);
+            const router = [...ctx.emitted.entries()].find(([p]) => p.endsWith('mcp.router.ts'))?.[1];
+            expect(router).toContain("from '@maroonedsoftware/koa'");
+        });
+    });
+
     describe('validateResponses', () => {
         const userRoot = () =>
             opRoot(