@contractkit/plugin-typescript 0.28.1 → 0.28.2

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,
@@ -104,11 +105,39 @@ export interface TypesConfig {
     output?: string;
 }
 
+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;
+}
+
 export interface TypescriptPluginConfig {
     server?: ServerConfig;
     sdk?: SdkConfig;
     zod?: ZodConfig;
     types?: TypesConfig;
+    mcp?: McpConfig;
 }
 
 // ─── Caching constants ─────────────────────────────────────────────────────
@@ -165,6 +194,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,
@@ -838,6 +868,130 @@ function collectTypesOutput(
     }
 }
 
+// ─── 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 {

package/tests/codegen-mcp.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from 'vitest';
+import type { McpConfigNode } from '@contractkit/core';
+import {
+    generateMcpFile,
+    generateMcpAggregator,
+    generateMcpRouter,
+    hasMcpOperations,
+    deriveMcpRegisterFnName,
+} from '../src/codegen-mcp.js';
+import { opRoot, opRoute, opOperation, opParam, opRequest, opResponse, scalarType, loc } from './helpers.js';
+
+function mcpBlock(over: Partial<McpConfigNode>): McpConfigNode {
+    return { loc: loc(), ...over };
+}
+
+describe('hasMcpOperations', () => {
+    it('is false when no op is flagged', () => {
+        const root = opRoot([opRoute('/users', [opOperation('get', { responses: [opResponse(200, 'User', 'application/json')] })])]);
+        expect(hasMcpOperations(root)).toBe(false);
+    });
+
+    it('is true when an op is flagged', () => {
+        const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+        expect(hasMcpOperations(root)).toBe(true);
+    });
+
+    it('excludes internal ops unless includeInternal', () => {
+        const root = opRoot([
+            opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })], undefined, ['internal']),
+        ]);
+        expect(hasMcpOperations(root)).toBe(false);
+        expect(hasMcpOperations(root, true)).toBe(true);
+    });
+});
+
+describe('generateMcpFile', () => {
+    describe('op selection', () => {
+        it('emits a tool class only for flagged ops', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', { sdk: 'listUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] }),
+                    opOperation('post', { sdk: 'createUser', request: opRequest('User'), responses: [opResponse(201, 'User', 'application/json')] }),
+                ]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('export class ListUsersMcpTool');
+            expect(out).not.toContain('CreateUserMcpTool');
+        });
+
+        it('skips mcp: false', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { sdk: 'listUsers', mcp: false, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            const out = generateMcpFile(root);
+            expect(out).not.toContain('implements McpToolHandler');
+        });
+
+        it('skips internal ops unless includeInternal', () => {
+            const root = opRoot([
+                opRoute('/users', [opOperation('get', { sdk: 'listUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })], undefined, [
+                    'internal',
+                ]),
+            ]);
+            expect(generateMcpFile(root)).not.toContain('ListUsersMcpTool');
+            expect(generateMcpFile(root, { includeInternal: true })).toContain('ListUsersMcpTool');
+        });
+    });
+
+    describe('tool name + class name', () => {
+        it('uses explicit mcp.name verbatim', () => {
+            const root = opRoot([
+                opRoute('/routes', [opOperation('post', { mcp: mcpBlock({ name: 'searchRoutes' }), request: opRequest('Query'), responses: [opResponse(200, 'RouteList', 'application/json')] })]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("name: 'searchRoutes'");
+            expect(out).toContain('export class SearchRoutesMcpTool');
+        });
+
+        it('snake_cases the sdk field', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { sdk: 'listAllUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("name: 'list_all_users'");
+            expect(out).toContain('export class ListAllUsersMcpTool');
+        });
+
+        it('snake_cases the name field', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { name: 'Get User', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).toContain("name: 'get_user'");
+        });
+
+        it('infers snake_case name from method + path', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            expect(generateMcpFile(root)).toContain("name: 'get_payments_by_id'");
+        });
+    });
+
+    describe('definition metadata', () => {
+        it('emits title, description, and only the defined annotations', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [
+                    opOperation('get', {
+                        mcp: mcpBlock({ title: 'Get Payment', description: 'Fetch a payment by id.', readOnlyHint: true, idempotentHint: true, destructiveHint: false }),
+                        responses: [opResponse(200, 'Payment', 'application/json')],
+                    }),
+                ], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("title: 'Get Payment'");
+            expect(out).toContain("description: 'Fetch a payment by id.'");
+            expect(out).toContain('annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }');
+            expect(out).not.toContain('openWorldHint');
+        });
+
+        it('omits annotations when no hints set', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).not.toContain('annotations:');
+        });
+
+        it('falls back to op description', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, description: 'List users.', responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).toContain("description: 'List users.'");
+        });
+    });
+
+    describe('input schema + validation', () => {
+        it('folds path params into a shared args const used for schema and validation', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('const GetPaymentsByIdArgs = z.object({ id: z.uuid() });');
+            expect(out).toContain("inputSchema: z.toJSONSchema(GetPaymentsByIdArgs, { unrepresentable: 'any' }) as Tool['inputSchema']");
+            expect(out).toContain('const { id } = await parseAndValidate(args, GetPaymentsByIdArgs);');
+        });
+
+        it('nests the request body under a body field', () => {
+            const root = opRoot([
+                opRoute('/payments', [opOperation('post', { sdk: 'createPayment', mcp: true, request: opRequest('PaymentInput'), responses: [opResponse(201, 'Payment', 'application/json')] })]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('const CreatePaymentArgs = z.object({ body: PaymentInput });');
+            expect(out).toContain('const { body } = await parseAndValidate(args, CreatePaymentArgs);');
+        });
+    });
+
+    describe('service call + result', () => {
+        it('injects the declared service and calls it', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('constructor(private readonly service: PaymentsService) {}');
+            expect(out).toContain('const result = await this.service.getById(id);');
+            expect(out).toContain('structuredContent: result');
+        });
+
+        it('returns bare content (no structuredContent / outputSchema) for a void response', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('delete', { mcp: true, service: 'PaymentsService.remove', responses: [opResponse(204)] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('await this.service.remove(id);');
+            expect(out).toContain("return { content: [{ type: 'text', text: 'OK' }] };");
+            expect(out).not.toContain('structuredContent');
+            expect(out).not.toContain('outputSchema');
+        });
+
+        it('emits outputSchema for an object response', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            expect(generateMcpFile(root)).toContain("outputSchema: z.toJSONSchema(Payment, { unrepresentable: 'any' }) as Tool['outputSchema']");
+        });
+    });
+
+    describe('imports + registration', () => {
+        it('imports the MCP + injectkit primitives and emits a per-file register fn', () => {
+            const root = opRoot(
+                [opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))])],
+                'payments.op',
+            );
+            const out = generateMcpFile(root);
+            expect(out).toContain("import { Injectable, type Container } from 'injectkit';");
+            expect(out).toContain("import type { McpToolHandler, McpToolHandlerMap, McpToolContext } from '@maroonedsoftware/mcp';");
+            expect(out).toContain("import { parseAndValidate } from '@maroonedsoftware/zod';");
+            expect(out).toContain('export function registerPaymentsMcpTools(map: McpToolHandlerMap, container: Container): void {');
+            expect(out).toContain("map.set('get_payments_by_id', container.get(GetPaymentsByIdMcpTool));");
+        });
+
+        it('resolves service + schema imports via modelOutPaths', () => {
+            const root = opRoot(
+                [opRoute('/payments', [opOperation('post', { sdk: 'createPayment', mcp: true, service: 'PaymentsService.create', request: opRequest('PaymentInput'), responses: [opResponse(201, 'Payment', 'application/json')] })])],
+                'payments.op',
+            );
+            const modelOutPaths = new Map<string, string>([
+                ['Payment', '/api/src/types/payment.ts'],
+                ['PaymentInput', '/api/src/types/payment.ts'],
+            ]);
+            const out = generateMcpFile(root, {
+                outPath: '/api/src/mcp/payments.mcp.ts',
+                modelOutPaths,
+                modelsWithInput: new Set(['Payment']),
+                servicePathTemplate: '#modules/{kebab}/{kebab}.service.js',
+            });
+            expect(out).toContain("import { PaymentsService } from '#modules/payments/payments.service.js';");
+            expect(out).toContain("import { Payment, PaymentInput } from '../types/payment.js';");
+        });
+    });
+});
+
+describe('generateMcpAggregator', () => {
+    it('imports each register fn and assembles one map', () => {
+        const out = generateMcpAggregator([
+            { registerFn: 'registerPaymentsMcpTools', importPath: './payments.mcp.js' },
+            { registerFn: 'registerUsersMcpTools', importPath: './users.mcp.js' },
+        ]);
+        expect(out).toContain("import { McpToolHandlerMap } from '@maroonedsoftware/mcp';");
+        expect(out).toContain("import { registerPaymentsMcpTools } from './payments.mcp.js';");
+        expect(out).toContain('export function registerMcpTools(container: Container): McpToolHandlerMap {');
+        expect(out).toContain('const map = new McpToolHandlerMap();');
+        expect(out).toContain('registerPaymentsMcpTools(map, container);');
+        expect(out).toContain('registerUsersMcpTools(map, container);');
+        expect(out).toContain('container.register(McpToolHandlerMap, { useValue: map });');
+    });
+});
+
+describe('generateMcpRouter', () => {
+    it('emits a ServerKit route wired to the dispatcher at the configured path', () => {
+        const out = generateMcpRouter({ path: '/mcp' });
+        expect(out).toContain("import { McpDispatcher, createMcpRequestContext, MCP_AUTH_POLICY } from '@maroonedsoftware/mcp';");
+        expect(out).toContain("router.post('/mcp'");
+        expect(out).toContain('ctx.container.get(McpDispatcher)');
+        expect(out).toContain("dispatcher.sessionMode === 'stateful'");
+    });
+
+    it('defaults the mount path to /mcp', () => {
+        expect(generateMcpRouter()).toContain("router.post('/mcp'");
+    });
+});
+
+describe('deriveMcpRegisterFnName', () => {
+    it('derives from the op-root filename', () => {
+        expect(deriveMcpRegisterFnName('payments.op')).toBe('registerPaymentsMcpTools');
+        expect(deriveMcpRegisterFnName('ledger.categories.op')).toBe('registerLedgerCategoriesMcpTools');
+    });
+});

package/tests/codegen-operation.test.ts

@@ -103,6 +103,24 @@ describe('generateOperation', () => {
         });
     });
 
+    // ─── Handler signature ─────────────────────────────────────────
+
+    describe('handler signature', () => {
+        it('emits a single-parameter handler without the unused next argument', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { security: SECURITY_NONE })])]);
+            const output = generateOp(root);
+            expect(output).toContain(".get('/users', async ctx => {");
+            expect(output).not.toContain('ctx, next');
+        });
+
+        it('omits next on handlers that carry middleware', () => {
+            const root = opRoot([opRoute('/users', [opOperation('post', { request: opRequest('CreateUser') })])]);
+            const output = generateOp(root);
+            expect(output).toContain('async ctx => {');
+            expect(output).not.toContain('ctx, next');
+        });
+    });
+
     // ─── Handler generation — GET ──────────────────────────────────
 
     describe('GET handlers', () => {

package/tests/pipeline.test.ts

@@ -2,6 +2,7 @@ import { parseCk, decomposeCk, validateOp, validateRefs, applyOptionsDefaults, D
 import { generateContract } from '../src/codegen-contract.js';
 import { generateOp } from '../src/codegen-operation.js';
 import { generateSdk } from '../src/codegen-sdk.js';
+import { generateMcpFile } from '../src/codegen-mcp.js';
 import { SIMPLE_USER_CONTRACT, VISIBILITY_CONTRACT, INHERITANCE_CONTRACT, SIMPLE_USERS_OP, PARAMETERIZED_OP } from './helpers.js';
 
 function compileContractSource(source: string) {
@@ -118,6 +119,64 @@ describe('OP pipeline (source -> parse -> codegen)', () => {
     });
 });
 
+describe('MCP pipeline (source -> parse -> codegen)', () => {
+    function compileMcp(source: string, file = 'payments.ck') {
+        const diag = new DiagnosticCollector();
+        const ck = parseCk(source, file, diag);
+        const { op } = decomposeCk(ck);
+        return { output: generateMcpFile(op, { includeInternal: false }), diag };
+    }
+
+    it('generates a tool handler from a parsed mcp block', () => {
+        const source = `\
+operation /payments/{id}: {
+    params: { id: uuid }
+    get: {
+        mcp: {
+            title: "Get Payment"
+            description: "Fetch a payment by id."
+            hint: readOnly, idempotent, nonDestructive
+        }
+        service: PaymentsService.getById
+        response: { 200: { application/json: Payment } }
+    }
+}`;
+        const { output, diag } = compileMcp(source);
+        expect(diag.hasErrors()).toBe(false);
+        expect(output).toContain('export class GetPaymentsByIdMcpTool implements McpToolHandler');
+        expect(output).toContain("title: 'Get Payment'");
+        expect(output).toContain('annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }');
+        expect(output).toContain('const GetPaymentsByIdArgs = z.object({ id: z.uuid() });');
+        expect(output).toContain('constructor(private readonly service: PaymentsService) {}');
+        expect(output).toContain('const result = await this.service.getById(id);');
+        expect(output).toContain('export function registerPaymentsMcpTools(map: McpToolHandlerMap, container: Container): void {');
+        expect(output).toContain("map.set('get_payments_by_id', container.get(GetPaymentsByIdMcpTool));");
+    });
+
+    it('generates a tool from mcp: true with an inferred name', () => {
+        const source = `\
+operation /payments: {
+    post: {
+        mcp: true
+        service: PaymentsService.create
+        request: { application/json: PaymentInput }
+        response: { 201: { application/json: Payment } }
+    }
+}`;
+        const { output, diag } = compileMcp(source);
+        expect(diag.hasErrors()).toBe(false);
+        expect(output).toContain("name: 'post_payments'");
+        expect(output).toContain('const PostPaymentsArgs = z.object({ body: PaymentInput });');
+        expect(output).not.toContain('annotations:');
+    });
+
+    it('emits nothing tool-like for a file with no flagged ops', () => {
+        const source = `operation /payments: { get: { response: { 200: { application/json: Payment } } } }`;
+        const { output } = compileMcp(source);
+        expect(output).not.toContain('implements McpToolHandler');
+    });
+});
+
 describe('undeclared path param warnings', () => {
     it('warns when a route has path params but no params block', () => {
         const source = `operation /users/{id}: { get: {} }`;