@contractkit/plugin-typescript 0.28.1 → 0.29.0

package/src/codegen-operation.ts

@@ -1,4 +1,4 @@
-import type { OpRootNode, OpRouteNode, OpOperationNode, ContractTypeNode, ParamSource, ObjectMode } from '@contractkit/core';
+import type { OpRootNode, OpRouteNode, OpOperationNode, ContractTypeNode, ScalarTypeNode, ParamSource, ObjectMode } from '@contractkit/core';
 import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType } from '@contractkit/core';
 import {
     renderType,
@@ -107,6 +107,7 @@ export function bodyTypesStructurallyEqual(a: ContractTypeNode, b: ContractTypeN
 
 // ─── Public entry point ────────────────────────────────────────────────────
 
+/** Options controlling how {@link generateOp} renders a Koa router module. */
 export interface OpCodegenOptions {
     servicePathTemplate?: string;
     typeImportPathTemplate?: string;
@@ -152,8 +153,14 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
         body.push(...generateTypeImports(types, root.file, options));
     }
 
-    if (opNeedsDateTime(root)) {
-        body.push(`import { DateTime } from 'luxon';`);
+    // luxon is needed for date/time/datetime (DateTime), duration (Duration) and interval (Interval);
+    // the rendered Zod schemas and the service-result annotations both reference these classes.
+    const luxonImports: string[] = [];
+    if (opNeedsDateTime(root)) luxonImports.push('DateTime');
+    if (opNeedsScalar(root, 'duration')) luxonImports.push('Duration');
+    if (opNeedsScalar(root, 'interval')) luxonImports.push('Interval');
+    if (luxonImports.length > 0) {
+        body.push(`import { ${luxonImports.join(', ')} } from 'luxon';`);
     }
 
     if (needsParseAndValidate) {
@@ -173,6 +180,11 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
             `const _ZodDatetime = z.preprocess((val) => typeof val === 'string' ? DateTime.fromISO(val) : val, z.custom<DateTime>((val) => val instanceof DateTime && val.isValid, { message: 'Must be in ISO 8601 format' }));`,
         );
     }
+    if (opNeedsScalar(root, 'interval')) {
+        helpers.push(
+            `const _ZodInterval = z.preprocess((val) => typeof val === 'string' ? Interval.fromISO(val) : val, z.custom<Interval>((val) => val instanceof Interval && val.isValid, { message: 'Must be an ISO 8601 interval' })).transform(val => val.toISO()!);`,
+        );
+    }
     if (opNeedsScalar(root, 'json')) {
         helpers.push(`type _JsonValue = string | number | boolean | null | _JsonValue[] | { [key: string]: _JsonValue };`);
         helpers.push(
@@ -267,7 +279,7 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     }
     const middlewareStr = middlewares.length > 0 ? `, ${middlewares.join(', ')},` : ',';
 
-    lines.push(`${deriveRouterName(file)}.${method}('${path}'${middlewareStr} async (ctx, next) => {`);
+    lines.push(`${deriveRouterName(file)}.${method}('${path}'${middlewareStr} async ctx => {`);
 
     // Params / query / headers validation (request-side — use Input variants)
     lines.push(...generateParamValidation(route.params, 'ctx.params', 'params', route.paramsMode ?? 'strict', '', modelsWithInput));
@@ -316,7 +328,10 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     const hasRespHeaders = respHeaders.length > 0;
     const headersAnnotation = hasRespHeaders
         ? `{ ${respHeaders
-              .map(h => `${quoteKey(headerNameToProperty(h.name))}${h.optional ? '?' : ''}: ${renderOutputTsType(h.type, options.modelsWithOutput)}`)
+              .map(
+                  h =>
+                      `${quoteKey(headerNameToProperty(h.name))}${h.optional ? '?' : ''}: ${renderOutputTsType(h.type, options.modelsWithOutput, 'server')}`,
+              )
               .join('; ')} }`
         : '';
 
@@ -368,7 +383,16 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
 
 // ─── Inference helpers ─────────────────────────────────────────────────────
 
-function inferService(op: OpOperationNode, route: OpRouteNode, file: string): { className: string; methodName: string } {
+/**
+ * Resolve the service class and method a handler should delegate to.
+ *
+ * Uses the operation's explicit `service: Class.method` declaration when present; otherwise derives
+ * the class from the contract file name (`ledger.categories.ck` → `LedgerCategoriesService`) and the
+ * method from the HTTP verb and whether the path carries a parameter (`get` → `list` / `getById`).
+ *
+ * @param file Path of the `.ck` file the operation came from.
+ */
+export function inferService(op: OpOperationNode, route: OpRouteNode, file: string): { className: string; methodName: string } {
     // If explicitly declared: service: ServiceClass.methodName
     if (op.service) {
         const [cls = '', method] = op.service.split('.');
@@ -400,7 +424,16 @@ function inferMethodName(method: string, path: string): string {
     }
 }
 
-function buildArgs(route: OpRouteNode, op: OpOperationNode): string {
+/**
+ * Build the comma-separated argument list passed to the service method in a generated handler.
+ *
+ * Order is params, body, query, headers. Inline path params are spread as individual identifiers;
+ * a referenced/compound params type is passed as a single `params` object. A lone
+ * `multipart/form-data` request body is passed as `multipartBody` rather than `body`.
+ *
+ * @returns The rendered argument list, or an empty string when the method takes no arguments.
+ */
+export function buildArgs(route: OpRouteNode, op: OpOperationNode): string {
     const args: string[] = [];
     // Path params: spread individually (inline) or pass 'params' object (type-ref/ContractTypeNode)
     if (route.params) {
@@ -423,6 +456,52 @@ function buildArgs(route: OpRouteNode, op: OpOperationNode): string {
     return args.join(', ');
 }
 
+/**
+ * Map a `.ck` scalar to the TypeScript type a server handler sees, i.e. `z.infer` of the schema
+ * `renderType` emits for that scalar. This is deliberately NOT `renderTsScalar` from ts-render:
+ * that one describes the wire/SDK view (`binary` → `Blob`, dates → `string`), while the router
+ * runs on Node against the parsed Zod output (`binary` → `Buffer`, dates → luxon `DateTime`).
+ */
+function serverTsScalar(name: ScalarTypeNode['name']): string {
+    switch (name) {
+        case 'string':
+        case 'email':
+        case 'url':
+        case 'uuid':
+            return 'string';
+        case 'number':
+        case 'int':
+            return 'number';
+        case 'bigint':
+            return 'bigint';
+        case 'boolean':
+            return 'boolean';
+        case 'date':
+        case 'time':
+        case 'datetime':
+            return 'DateTime';
+        case 'duration':
+            return 'Duration';
+        case 'interval':
+            // _ZodInterval transforms to an ISO string, so the inferred output type is string.
+            return 'string';
+        case 'binary':
+            return 'Buffer';
+        case 'json':
+            return '_JsonValue';
+        case 'object':
+            return 'Record<string, unknown>';
+        case 'null':
+            return 'null';
+        case 'unknown':
+            return 'unknown';
+        default: {
+            const _exhaustive: never = name;
+            throw new Error(`plugin-typescript: unmapped scalar '${String(_exhaustive)}' — add a case`);
+        }
+    }
+}
+
 function formatTypeAnnotation(bodyType: ContractTypeNode, modelsWithOutput?: Set<string>): { annotation: string; prelude?: string } {
     if (bodyType.kind === 'array') {
         const inner = formatTypeAnnotation(bodyType.item, modelsWithOutput);
@@ -432,7 +511,7 @@ function formatTypeAnnotation(bodyType: ContractTypeNode, modelsWithOutput?: Set
         const name = modelsWithOutput?.has(bodyType.name) ? `${bodyType.name}Output` : bodyType.name;
         return { annotation: name };
     }
-    if (bodyType.kind === 'scalar') return { annotation: bodyType.name };
+    if (bodyType.kind === 'scalar') return { annotation: serverTsScalar(bodyType.name) };
     // For complex types, extract schema into a variable so the result line stays readable
     const schema = renderType(bodyType);
     return {
@@ -792,7 +871,13 @@ function isValidIdentifier(name: string): boolean {
 
 // ─── Naming conventions ────────────────────────────────────────────────────
 
-function deriveBaseName(file: string): string {
+/**
+ * Derive the PascalCase base name used for router, service, and type names from a contract file path.
+ *
+ * Strips directories and the `.op`/`.ck` extension, then PascalCases each dot-separated segment
+ * (`contracts/ledger.categories.ck` → `LedgerCategories`). Falls back to `Resource` for an empty path.
+ */
+export function deriveBaseName(file: string): string {
     const base =
         file
             .split('/')
@@ -809,7 +894,16 @@ function deriveRouterName(file: string): string {
     return `${deriveBaseName(file)}Router`;
 }
 
-function deriveModulePath(serviceName: string, template?: string): string {
+/**
+ * Resolve the import specifier for a service class.
+ *
+ * Drops the trailing `Service` suffix and kebab-cases the remainder, then applies `template` if given
+ * (`{name}` → `Ledger`, `{kebab}` → `ledger`). Without a template, defaults to
+ * `#modules/<kebab>/<kebab>.service.js`.
+ *
+ * @param template Optional `servicePathTemplate` from the plugin config.
+ */
+export function deriveModulePath(serviceName: string, template?: string): string {
     // LedgerService -> #modules/ledger/ledger.service.js
     const base = serviceName.replace(/Service$/, '');
     const kebab = base.replace(/([A-Z])/g, m => `-${m.toLowerCase()}`).replace(/^-/, '');

package/src/codegen-plain-types.ts

@@ -11,6 +11,7 @@ import {
     rootNeedsScalar,
 } from './codegen-contract.js';
 import { renderTsType, renderInputTsType, renderOutputTsType, quoteKey, escapeJsDocLines, JSON_VALUE_TYPE_DECL } from './ts-render.js';
+import type { TsRenderTarget } from './ts-render.js';
 
 // ─── Public entry point ────────────────────────────────────────────────────
 
@@ -19,8 +20,12 @@ import { renderTsType, renderInputTsType, renderOutputTsType, quoteKey, escapeJs
  * Unlike `generateContract()` which produces Zod schemas, this emits
  * vanilla TypeScript `interface` and `type` declarations suitable
  * for SDK consumers that don't need runtime validation.
+ *
+ * @param context Import resolution and Input/Output variant sets. `context.target` selects the
+ * runtime the types describe (`'server'` renders `binary` as `Buffer`, `'client'` as `Blob`).
  */
 export function generatePlainTypes(root: ContractRootNode, context?: ContractCodegenContext): string {
+    const target: TsRenderTarget = context?.target ?? 'client';
     const externalRefs = collectExternalRefs(root);
     const lines: string[] = [];
 
@@ -58,7 +63,7 @@ export function generatePlainTypes(root: ContractRootNode, context?: ContractCod
     const modelMap = new Map(root.models.map(m => [m.name, m]));
 
     for (const model of topoSortModels(root.models)) {
-        lines.push(...generateModel(model, context?.currentOutPath, allModelsWithInput, allModelsWithOutput, modelMap));
+        lines.push(...generateModel(model, target, context?.currentOutPath, allModelsWithInput, allModelsWithOutput, modelMap));
         lines.push('');
     }
 
@@ -69,6 +74,7 @@ export function generatePlainTypes(root: ContractRootNode, context?: ContractCod
 
 function generateModel(
     model: ModelNode,
+    target: TsRenderTarget,
     outPath?: string,
     modelsWithInput?: Set<string>,
     modelsWithOutput?: Set<string>,
@@ -76,18 +82,20 @@ function generateModel(
 ): string[] {
     // Type alias: Name : typeExpression
     if (model.type) {
-        return generateTypeAlias(model, outPath, modelsWithInput, modelsWithOutput);
+        return generateTypeAlias(model, target, outPath, modelsWithInput, modelsWithOutput);
     }
 
     // A model needs Input/read split if it has visibility-modified fields OR if it
     // transitively references models that have Input variants (captured in modelsWithInput).
     const needsInputSplit = model.fields.some(f => f.visibility !== 'normal') || (modelsWithInput?.has(model.name) ?? false);
 
-    const lines = needsInputSplit ? generateVisibilityModel(model, outPath, modelsWithInput, modelMap) : generateSimpleModel(model, outPath, modelMap);
+    const lines = needsInputSplit
+        ? generateVisibilityModel(model, target, outPath, modelsWithInput, modelMap)
+        : generateSimpleModel(model, target, outPath, modelMap);
 
     if (modelsWithOutput?.has(model.name)) {
         lines.push('');
-        lines.push(...generateOutputModel(model, modelsWithOutput));
+        lines.push(...generateOutputModel(model, target, modelsWithOutput));
     }
     return lines;
 }
@@ -132,15 +140,21 @@ function generateComments(model: ModelNode, outPath?: string): string[] {
     return lines;
 }
 
-function generateTypeAlias(model: ModelNode, outPath?: string, modelsWithInput?: Set<string>, modelsWithOutput?: Set<string>): string[] {
+function generateTypeAlias(
+    model: ModelNode,
+    target: TsRenderTarget,
+    outPath?: string,
+    modelsWithInput?: Set<string>,
+    modelsWithOutput?: Set<string>,
+): string[] {
     const lines: string[] = [];
     lines.push(...generateComments(model, outPath));
-    lines.push(`export type ${model.name} = ${renderTsType(model.type!)};`);
+    lines.push(`export type ${model.name} = ${renderTsType(model.type!, target)};`);
     if (modelsWithInput?.has(model.name)) {
-        lines.push(`export type ${model.name}Input = ${renderInputTsType(model.type!, modelsWithInput)};`);
+        lines.push(`export type ${model.name}Input = ${renderInputTsType(model.type!, modelsWithInput, target)};`);
     }
     if (modelsWithOutput?.has(model.name)) {
-        lines.push(`export type ${model.name}Output = ${renderOutputTsType(model.type!, modelsWithOutput)};`);
+        lines.push(`export type ${model.name}Output = ${renderOutputTsType(model.type!, modelsWithOutput, target)};`);
     }
     return lines;
 }
@@ -158,7 +172,7 @@ function buildExtendsClause(bases: string[], overrideNames: string[], baseNameRe
     return ` extends ${wrapped.join(', ')}`;
 }
 
-function generateSimpleModel(model: ModelNode, outPath?: string, modelMap?: Map<string, ModelNode>): string[] {
+function generateSimpleModel(model: ModelNode, target: TsRenderTarget, outPath?: string, modelMap?: Map<string, ModelNode>): string[] {
     const lines: string[] = [];
     lines.push(...generateComments(model, outPath));
 
@@ -167,14 +181,20 @@ function generateSimpleModel(model: ModelNode, outPath?: string, modelMap?: Map<
     lines.push(`export interface ${model.name}${buildExtendsClause(bases, overrideNames, b => b)} {`);
 
     for (const field of model.fields) {
-        lines.push(`    ${renderField(field)}`);
+        lines.push(`    ${renderField(field, target)}`);
     }
 
     lines.push('}');
     return lines;
 }
 
-function generateVisibilityModel(model: ModelNode, outPath?: string, modelsWithInput?: Set<string>, modelMap?: Map<string, ModelNode>): string[] {
+function generateVisibilityModel(
+    model: ModelNode,
+    target: TsRenderTarget,
+    outPath?: string,
+    modelsWithInput?: Set<string>,
+    modelMap?: Map<string, ModelNode>,
+): string[] {
     const lines: string[] = [];
     lines.push(...generateComments(model, outPath));
 
@@ -185,7 +205,7 @@ function generateVisibilityModel(model: ModelNode, outPath?: string, modelsWithI
     const readFields = model.fields.filter(f => f.visibility !== 'writeonly');
     lines.push(`export interface ${model.name}${buildExtendsClause(bases, overrideNames, b => b)} {`);
     for (const field of readFields) {
-        lines.push(`    ${renderField(field)}`);
+        lines.push(`    ${renderField(field, target)}`);
     }
     lines.push('}');
     lines.push('');
@@ -196,7 +216,7 @@ function generateVisibilityModel(model: ModelNode, outPath?: string, modelsWithI
     const inputResolver = (b: string) => (modelsWithInput?.has(b) ? `${b}Input` : b);
     lines.push(`export interface ${model.name}Input${buildExtendsClause(bases, overrideNames, inputResolver)} {`);
     for (const field of writeFields) {
-        lines.push(`    ${modelsWithInput ? renderInputField(field, modelsWithInput) : renderField(field)}`);
+        lines.push(`    ${modelsWithInput ? renderInputField(field, modelsWithInput, target) : renderField(field, target)}`);
     }
     lines.push('}');
 
@@ -217,9 +237,9 @@ function withFieldJsDoc(jsdocParts: string[], line: string): string {
     return `/**\n${body}\n     */\n    ${line}`;
 }
 
-function renderField(field: FieldNode): string {
+function renderField(field: FieldNode, target: TsRenderTarget): string {
     const opt = field.optional || field.default !== undefined ? '?' : '';
-    let typeStr = renderTsType(field.type);
+    let typeStr = renderTsType(field.type, target);
     if (field.nullable) typeStr += ' | null';
     const line = `${quoteKey(field.name)}${opt}: ${typeStr};`;
     const jsdocParts: string[] = [];
@@ -228,9 +248,9 @@ function renderField(field: FieldNode): string {
     return withFieldJsDoc(jsdocParts, line);
 }
 
-function renderInputField(field: FieldNode, modelsWithInput: Set<string>): string {
+function renderInputField(field: FieldNode, modelsWithInput: Set<string>, target: TsRenderTarget): string {
     const opt = field.optional || field.default !== undefined ? '?' : '';
-    let typeStr = renderInputTsType(field.type, modelsWithInput);
+    let typeStr = renderInputTsType(field.type, modelsWithInput, target);
     if (field.nullable) typeStr += ' | null';
     const line = `${quoteKey(field.name)}${opt}: ${typeStr};`;
     const jsdocParts: string[] = [];
@@ -264,7 +284,7 @@ function applyOutputCase(name: string, c: 'camel' | 'snake' | 'pascal' | undefin
  * ancestor has format(...) (see `flattenFormatChain` in codegen-contract); we mirror that here
  * so the plain interface matches the wire shape produced by the Zod transform.
  */
-function generateOutputModel(model: ModelNode, modelsWithOutput: Set<string>): string[] {
+function generateOutputModel(model: ModelNode, target: TsRenderTarget, modelsWithOutput: Set<string>): string[] {
     const lines: string[] = [];
     const outputCase = model.outputCase && model.outputCase !== 'camel' ? model.outputCase : undefined;
     const readFields = model.fields.filter(f => f.visibility !== 'writeonly');
@@ -279,7 +299,7 @@ function generateOutputModel(model: ModelNode, modelsWithOutput: Set<string>): s
                   : '';
         lines.push(`export interface ${model.name}Output${baseExt} {`);
         for (const field of readFields) {
-            lines.push(`    ${renderOutputField(field, model.outputCase, modelsWithOutput)}`);
+            lines.push(`    ${renderOutputField(field, model.outputCase, modelsWithOutput, target)}`);
         }
         lines.push('}');
         return lines;
@@ -288,16 +308,21 @@ function generateOutputModel(model: ModelNode, modelsWithOutput: Set<string>): s
     // Direct hit: emit a flat interface with renamed keys.
     lines.push(`export interface ${model.name}Output {`);
     for (const field of readFields) {
-        lines.push(`    ${renderOutputField(field, outputCase, modelsWithOutput)}`);
+        lines.push(`    ${renderOutputField(field, outputCase, modelsWithOutput, target)}`);
     }
     lines.push('}');
     return lines;
 }
 
-function renderOutputField(field: FieldNode, outputCase: 'camel' | 'snake' | 'pascal' | undefined, modelsWithOutput: Set<string>): string {
+function renderOutputField(
+    field: FieldNode,
+    outputCase: 'camel' | 'snake' | 'pascal' | undefined,
+    modelsWithOutput: Set<string>,
+    target: TsRenderTarget,
+): string {
     const opt = field.optional || field.default !== undefined ? '?' : '';
     const key = applyOutputCase(field.name, outputCase);
-    let typeStr = renderOutputTsType(field.type, modelsWithOutput);
+    let typeStr = renderOutputTsType(field.type, modelsWithOutput, target);
     if (field.nullable) typeStr += ' | null';
     const line = `${quoteKey(key)}${opt}: ${typeStr};`;
     const jsdocParts: string[] = [];

package/src/index.ts

@@ -41,6 +41,7 @@ import {
     type SdkScaffoldDeps,
 } from './codegen-sdk.js';
 import { generatePlainTypes } from './codegen-plain-types.js';
+import { generateMcpFile, generateMcpAggregator, generateMcpRouter, hasMcpOperations, deriveMcpRegisterFnName } from './codegen-mcp.js';
 import {
     TEMPLATE_VAR_RE,
     resolveTemplate,
@@ -56,6 +57,7 @@ import {
 
 // ─── Sub-config interfaces ─────────────────────────────────────────────────
 
+/** Koa 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;
@@ -73,6 +75,7 @@ export interface ServerConfig {
     includeInternal?: boolean;
 }
 
+/** TypeScript SDK client output: the client class, per-area operation clients, and their types. */
 export interface SdkConfig {
     baseDir?: string;
     name?: string;
@@ -94,21 +97,59 @@ export interface SdkConfig {
     scaffold?: boolean;
 }
 
+/** Standalone Zod schema output, independent of the server and SDK sub-generators. */
 export interface ZodConfig {
     baseDir?: string;
     output?: string;
 }
 
+/** Standalone plain TypeScript type output, independent of the server and SDK sub-generators. */
 export interface TypesConfig {
     baseDir?: string;
     output?: string;
+    /**
+     * Runtime the emitted types describe. Affects scalars whose TypeScript type is runtime-specific:
+     * `binary` renders as `Buffer` for `'server'` and `Blob` for `'client'`. Default `'client'`.
+     * The `server` and `sdk` sub-generators set this themselves.
+     */
+    target?: 'client' | 'server';
+}
+
+/** MCP tool output: per-op-file handlers, the aggregator, and the optional POST route. */
+export interface McpConfig {
+    /** Directory (relative to rootDir) where MCP files are written. Default: rootDir. */
+    baseDir?: string;
+    output?: {
+        /** Path template for per-op-file tool handlers. Supports {filename}, {dir}, {area}. Default `{filename}.mcp.ts`. */
+        tools?: string;
+        /** Path (or template) for the aggregator that assembles the McpToolHandlerMap. Default `mcp.tools.ts`. */
+        index?: string;
+        /** Path (or template) for the optional POST /mcp route file. Default `mcp.router.ts`. */
+        router?: string;
+        /**
+         * Path template for the model **Zod schema** files the tools import (for arg validation and
+         * `z.toJSONSchema`). When omitted, falls back to the `server` sub-config's `output.types`
+         * (if `server.zod`) or the `zod` sub-config's output. Tools require Zod schemas, not plain types.
+         */
+        types?: string;
+    };
+    /** Emit the `mcp.router.ts` route boilerplate. Default true. */
+    emitRouter?: boolean;
+    /** Mount path used in the emitted router. Default `/mcp`. */
+    path?: string;
+    /** Import path template for service implementations (same semantics as ServerConfig). */
+    servicePathTemplate?: string;
+    /** Whether to expose operations marked `internal` as MCP tools. Default false. */
+    includeInternal?: boolean;
 }
 
+/** Top-level plugin config. Each sub-config that is present enables its sub-generator. */
 export interface TypescriptPluginConfig {
     server?: ServerConfig;
     sdk?: SdkConfig;
     zod?: ZodConfig;
     types?: TypesConfig;
+    mcp?: McpConfig;
 }
 
 // ─── Caching constants ─────────────────────────────────────────────────────
@@ -165,6 +206,7 @@ async function runTypescriptCodegen(
     if (config.sdk) collectSdkOutput(config.sdk, rootDir, inputs, units, globalFiles);
     if (config.zod) collectZodOutput(config.zod, rootDir, inputs, units);
     if (config.types) collectTypesOutput(config.types, rootDir, inputs, units);
+    if (config.mcp) collectMcpOutput(config.mcp, config, rootDir, inputs, units, globalFiles);
 
     const result = runIncrementalCodegen({
         codegenVersion: TYPESCRIPT_CODEGEN_VERSION,
@@ -325,6 +367,8 @@ function collectServerOutput(
                     currentOutPath: typeOutPath,
                     modelsWithInput,
                     modelsWithOutput,
+                    // These types are consumed by Koa handlers, so `binary` is a Buffer, not a Blob.
+                    target: 'server' as const,
                 };
                 const content = config.zod ? generateContract(ast, renderCtx) : generatePlainTypes(ast, renderCtx);
                 return [{ relativePath: typeOutPath, content }];
@@ -831,13 +875,143 @@ function collectTypesOutput(
             render: () => [
                 {
                     relativePath: outPath,
-                    content: generatePlainTypes(ast, { modelOutPaths, currentOutPath: outPath, modelsWithInput, modelsWithOutput }),
+                    content: generatePlainTypes(ast, {
+                        modelOutPaths,
+                        currentOutPath: outPath,
+                        modelsWithInput,
+                        modelsWithOutput,
+                        target: config.target,
+                    }),
                 },
             ],
         });
     }
 }
 
+// ─── MCP sub-generator ─────────────────────────────────────────────────────
+
+/**
+ * Resolve where the model **Zod schema** files live so the MCP tools can import them (for arg
+ * validation + `z.toJSONSchema`). Precedence: explicit `mcp.output.types` → the `server` sub-config's
+ * `output.types` (only when `server.zod`) → the `zod` sub-config's output. Returns an empty map when
+ * none resolve (imports then fall back to a colocated `./<name>.js` guess).
+ */
+function resolveMcpModelOutPaths(
+    config: TypescriptPluginConfig,
+    rootDir: string,
+    contractRoots: readonly ContractRootNode[],
+    commonRoot: string,
+    modelsWithInput: Set<string>,
+    modelsWithOutput: Set<string>,
+): Map<string, string> {
+    const map = new Map<string, string>();
+    let base: string;
+    let template: string | undefined;
+    let suffix: string;
+    if (config.mcp?.output?.types) {
+        base = resolve(rootDir, config.mcp.baseDir ?? '.');
+        template = config.mcp.output.types;
+        suffix = '.ts';
+    } else if (config.server?.zod && config.server.output?.types) {
+        base = resolve(rootDir, config.server.baseDir ?? '.');
+        template = config.server.output.types;
+        suffix = '.ts';
+    } else if (config.zod) {
+        base = resolve(rootDir, config.zod.baseDir ?? '.');
+        template = config.zod.output;
+        suffix = '.schema.ts';
+    } else {
+        return map;
+    }
+
+    for (const ast of contractRoots) {
+        const outPath = computeContractOutPath(ast.file, base, template, suffix, commonRoot, ast.meta);
+        for (const model of ast.models) {
+            map.set(model.name, outPath);
+            if (modelsWithInput.has(model.name)) map.set(`${model.name}Input`, outPath);
+            if (modelsWithOutput.has(model.name)) map.set(`${model.name}Output`, outPath);
+        }
+    }
+    return map;
+}
+
+function collectMcpOutput(
+    config: McpConfig,
+    fullConfig: TypescriptPluginConfig,
+    rootDir: string,
+    inputs: Parameters<NonNullable<ContractKitPlugin['generateTargets']>>[0],
+    units: IncrementalUnit[],
+    globalFiles: IncrementalOutputFile[],
+): void {
+    const mcpBase = resolve(rootDir, config.baseDir ?? '.');
+    const modelsWithInput = inputs.modelsWithInput as Set<string>;
+    const modelsWithOutput = inputs.modelsWithOutput as Set<string>;
+    const modelMap = buildModelMap(inputs.contractRoots);
+    const allFiles = [...inputs.contractRoots.map(r => r.file), ...inputs.opRoots.map(r => r.file)];
+    const commonRoot = commonDir(allFiles, rootDir);
+    const subConfigKey = stableSubConfig(config);
+    const includeInternal = config.includeInternal ?? false;
+
+    const modelOutPaths = resolveMcpModelOutPaths(fullConfig, rootDir, inputs.contractRoots, commonRoot, modelsWithInput, modelsWithOutput);
+
+    // ── Per-op-root tool-handler units (only files with MCP-exposed ops) ──
+    const entries: { outPath: string; registerFn: string }[] = [];
+    for (const ast of inputs.opRoots) {
+        if (!hasMcpOperations(ast, includeInternal)) continue;
+        const outPath = computeOpOutPath(ast.file, mcpBase, config.output?.tools, '.mcp.ts', commonRoot, ast.meta);
+        const refs = collectOpRootRefs(ast, modelMap);
+        const fingerprint = hashFingerprint({
+            kind: 'mcp-tools',
+            v: TYPESCRIPT_CODEGEN_VERSION,
+            outPath,
+            root: ast,
+            outPathSlice: sliceOutPathMap(refs, modelOutPaths, modelsWithInput, modelsWithOutput),
+            modelsWithInput: sliceModelSet(refs, new Set(), modelsWithInput),
+            modelsWithOutput: sliceModelSet(refs, new Set(), modelsWithOutput),
+            servicePathTemplate: config.servicePathTemplate ?? null,
+            includeInternal,
+            sub: subConfigKey,
+        });
+        units.push({
+            key: `mcp-tools::${outPath}`,
+            fingerprint,
+            render: () => [
+                {
+                    relativePath: outPath,
+                    content: generateMcpFile(ast, {
+                        outPath,
+                        modelOutPaths,
+                        modelsWithInput,
+                        modelsWithOutput,
+                        servicePathTemplate: config.servicePathTemplate,
+                        includeInternal,
+                    }),
+                },
+            ],
+        });
+        entries.push({ outPath, registerFn: deriveMcpRegisterFnName(ast.file) });
+    }
+
+    if (entries.length === 0) return;
+
+    // ── Aggregator (global) ──
+    const indexPath = join(mcpBase, config.output?.index ?? 'mcp.tools.ts');
+    const aggregatorEntries = entries
+        .map(e => {
+            let rel = relative(dirname(indexPath), e.outPath).replace(/\.ts$/, '.js');
+            if (!rel.startsWith('.')) rel = './' + rel;
+            return { registerFn: e.registerFn, importPath: rel };
+        })
+        .sort((a, b) => a.registerFn.localeCompare(b.registerFn));
+    globalFiles.push({ relativePath: indexPath, content: generateMcpAggregator(aggregatorEntries) });
+
+    // ── 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 }) });
+    }
+}
+
 // ─── Manifest IO + cleanup ─────────────────────────────────────────────────
 
 function readManifest(manifestPath: string): IncrementalManifest {