@contractkit/plugin-typescript 0.34.0 → 0.34.1

package/llms.txt

@@ -82,6 +82,20 @@ Options worth knowing:
   schema for argument validation and `z.toJSONSchema`. It falls back to `server.output.types` (when
   `server.zod`) or the `zod` sub-config's output.
 
+## Wiring the MCP tools
+
+`mcp.tools.ts` exports `registerMcpTools(container)`, which **builds and returns** the
+`McpToolHandlerMap`. It registers nothing: `register` belongs to InjectKit's `Registry`
+(composition phase), while a `Container` (resolution phase) only resolves. Bind the aggregator from
+a factory, which is also what supplies the `Container` it needs:
+
+```typescript
+registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();
+```
+
+The emitted tool classes are not registered for you either, so register each one on the same
+`Registry` before the aggregator resolves it.
+
 ## Programmatic use
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.34.0",
+  "version": "0.34.1",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "license": "MIT",
   "author": {

package/src/codegen-mcp.ts

@@ -372,7 +372,10 @@ function renderToolClass(plan: ToolPlan, file: string, options: McpCodegenOption
     const isVoid = !primaryResponseBody(op);
     const structured = !!outExpr;
 
-    lines.push('    async handle(args: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {');
+    // No args to destructure means the parameter goes unread, which trips no-unused-vars in
+    // consumers that lint generated output; the leading underscore opts it out.
+    const argsParam = destructure.length > 0 ? 'args' : '_args';
+    lines.push(`    async handle(${argsParam}: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {`);
     if (destructure.length > 0) {
         lines.push(`        const { ${destructure.join(', ')} } = await parseAndValidate(args, ${argsConstName});`);
     }
@@ -477,11 +480,19 @@ export function generateMcpAggregator(entries: McpAggregatorEntry[]): string {
     lines.push(`import { McpToolHandlerMap } from '@maroonedsoftware/mcp';`);
     for (const e of sorted) lines.push(`import { ${e.registerFn} } from '${e.importPath}';`);
     lines.push('');
-    lines.push('/** Build + register the MCP tool catalog. Call once at startup. */');
+    lines.push('/**');
+    lines.push(' * Build the MCP tool catalog.');
+    lines.push(' *');
+    lines.push(' * Bind it to the `McpToolHandlerMap` token from a factory, which is what supplies the');
+    lines.push(' * `Container` needed to resolve each handler:');
+    lines.push(' *');
+    lines.push(' * ```ts');
+    lines.push(' * registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();');
+    lines.push(' * ```');
+    lines.push(' */');
     lines.push('export function registerMcpTools(container: Container): McpToolHandlerMap {');
     lines.push('    const map = new McpToolHandlerMap();');
     for (const e of sorted) lines.push(`    ${e.registerFn}(map, container);`);
-    lines.push('    container.register(McpToolHandlerMap, { useValue: map });');
     lines.push('    return map;');
     lines.push('}');
     return lines.join('\n') + '\n';
@@ -493,7 +504,7 @@ export function generateMcpRouter(options: { path?: string } = {}): string {
     return `import { ServerKitRouter, bodyParserMiddleware, requireSignature } from '@maroonedsoftware/koa';
 import { McpDispatcher, createMcpRequestContext, MCP_AUTH_POLICY } from '@maroonedsoftware/mcp';
 
-/** Mount the MCP endpoint onto a ServerKit router. Call \`registerMcpTools(container)\` at startup. */
+/** 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);

package/tests/codegen-mcp.test.ts

@@ -141,6 +141,16 @@ describe('generateMcpFile', () => {
             expect(out).toContain('const CreatePaymentArgs = z.object({ body: PaymentInput });');
             expect(out).toContain('const { body } = await parseAndValidate(args, CreatePaymentArgs);');
         });
+
+        it('underscores the args param when the op takes no arguments', () => {
+            const root = opRoot([opRoute('/health', [opOperation('get', { mcp: true, responses: [opResponse(200, 'Health', 'application/json')] })])]);
+            const out = generateMcpFile(root);
+            // Nothing destructures `args` here, so an un-prefixed name trips no-unused-vars in
+            // consumers that lint generated output.
+            expect(out).toContain('async handle(_args: Record<string, unknown>, _context: McpToolContext)');
+            expect(out).not.toContain('async handle(args:');
+            expect(out).not.toContain('parseAndValidate');
+        });
     });
 
     describe('service call + result', () => {
@@ -220,7 +230,13 @@ describe('generateMcpAggregator', () => {
         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 });');
+        expect(out).toContain('return map;');
+    });
+
+    it('only builds the map — Container has no register, that belongs to Registry', () => {
+        const out = generateMcpAggregator([{ registerFn: 'registerPaymentsMcpTools', importPath: './payments.mcp.js' }]);
+        expect(out).not.toContain('container.register');
+        expect(out).toContain('registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();');
     });
 });
 
@@ -233,6 +249,12 @@ describe('generateMcpRouter', () => {
         expect(out).toContain("dispatcher.sessionMode === 'stateful'");
     });
 
+    it('tells consumers to bind the aggregator rather than call it at startup', () => {
+        const out = generateMcpRouter();
+        expect(out).toContain('Bind `registerMcpTools` to the `McpToolHandlerMap` token.');
+        expect(out).not.toContain('Call `registerMcpTools(container)` at startup');
+    });
+
     it('parses the body before verifying the signature', () => {
         const out = generateMcpRouter({ path: '/mcp' });
         // `requireSignature` HMACs `ctx.rawBody`, which only `bodyParserMiddleware` populates,