@pikku/openapi-parser 0.12.11 → 0.12.12

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pikku/openapi-parser
 
+## 0.12.12
+
+### Patch Changes
+
+- d97f2a1: Always emit a description for generated addon functions (and their MCP tools). When an OpenAPI operation omits both `description` and `summary` (common), the generator now synthesizes one — a humanized `operationId` (with the `Controller` segment stripped), else `METHOD /path` — instead of emitting none. This removes the "MCP tool is missing a description" warnings and makes `--mcp`-exposed tools usable.
+
 ## 0.12.11
 
 ### Patch Changes

package/dist/codegen.js

@@ -27,12 +27,41 @@ const STATUS_TO_ERROR = {
 function capitalize(str) {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
+/**
+ * Turn an operationId like `contactsControllerGetContacts` (or snake/kebab
+ * variants) into a readable phrase — split camel/snake/kebab into words, drop
+ * noise segments ("controller"), and capitalize. Returns undefined if nothing
+ * usable remains.
+ */
+function humanizeOperationId(operationId) {
+    if (!operationId)
+        return undefined;
+    const words = operationId
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .split(/\s+/)
+        .map((w) => w.trim())
+        .filter((w) => w && w.toLowerCase() !== 'controller');
+    if (words.length === 0)
+        return undefined;
+    return capitalize(words.join(' ').toLowerCase());
+}
+/**
+ * A description for the generated function (and its MCP tool). Prefers the
+ * spec's `description`, then `summary`; when a spec omits both (common), a
+ * synthesized description is still emitted so no function — and no MCP tool —
+ * ships description-less: a humanized operationId, else "METHOD /path".
+ */
 function humanDescription(parsed) {
     const description = parsed.description?.trim();
     if (description && !GENERIC_SUMMARIES.has(description.toLowerCase())) {
         return capitalize(description);
     }
-    return undefined;
+    const summary = parsed.summary?.trim();
+    if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
+        return capitalize(summary);
+    }
+    return humanizeOperationId(parsed.operationId) ?? `${parsed.method.toUpperCase()} ${parsed.path}`;
 }
 function getErrorClassesForResponses(errorResponses) {
     const classes = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/openapi-parser",
-  "version": "0.12.11",
+  "version": "0.12.12",
   "description": "OpenAPI spec parser and code generator for Pikku",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/codegen.test.ts

@@ -780,3 +780,68 @@ describe('camelCase flag', () => {
     )
   })
 })
+
+// ---------------------------------------------------------------------------
+// Function/MCP-tool description synthesis (specs that omit descriptions)
+// ---------------------------------------------------------------------------
+describe('function description synthesis', () => {
+  test('synthesizes a description from operationId when the spec omits one', () => {
+    const spec = makeSpec({
+      operations: [
+        makeOp({
+          operationId: 'contactsControllerGetContacts',
+          method: 'get',
+          path: '/contacts',
+        }),
+      ],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+      mcp: true,
+    })
+    const funcFile = files['src/functions/contactsControllerGetContacts.function.ts']
+    assert.ok(funcFile, 'function file should exist')
+    assert.ok(
+      funcFile.includes('description: "Contacts get contacts"'),
+      'humanized operationId (Controller stripped) should be emitted as the description'
+    )
+    assert.ok(funcFile.includes('mcp: true'), 'mcp tool flag should be present')
+  })
+
+  test('falls back to "METHOD /path" when operationId is absent', () => {
+    const spec = makeSpec({
+      operations: [makeOp({ operationId: undefined, method: 'get', path: '/health' })],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+    })
+    const key = Object.keys(files).find((k) => k.startsWith('src/functions/'))
+    assert.ok(key, 'a function file should be generated')
+    assert.ok(
+      files[key].includes('description: "GET /health"'),
+      'should fall back to METHOD path when nothing else is available'
+    )
+  })
+
+  test('prefers the spec description over synthesis', () => {
+    const spec = makeSpec({
+      operations: [
+        makeOp({ operationId: 'getPet', description: 'Fetch a single pet by id' }),
+      ],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+    })
+    const funcFile = files['src/functions/getPet.function.ts']
+    assert.ok(
+      funcFile.includes('description: "Fetch a single pet by id"'),
+      'the real spec description should win over the synthesized one'
+    )
+  })
+})

package/src/codegen.ts

@@ -69,12 +69,40 @@ function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1)
 }
 
-function humanDescription(parsed: ParsedOperation): string | undefined {
+/**
+ * Turn an operationId like `contactsControllerGetContacts` (or snake/kebab
+ * variants) into a readable phrase — split camel/snake/kebab into words, drop
+ * noise segments ("controller"), and capitalize. Returns undefined if nothing
+ * usable remains.
+ */
+function humanizeOperationId(operationId?: string): string | undefined {
+  if (!operationId) return undefined
+  const words = operationId
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .split(/\s+/)
+    .map((w) => w.trim())
+    .filter((w) => w && w.toLowerCase() !== 'controller')
+  if (words.length === 0) return undefined
+  return capitalize(words.join(' ').toLowerCase())
+}
+
+/**
+ * A description for the generated function (and its MCP tool). Prefers the
+ * spec's `description`, then `summary`; when a spec omits both (common), a
+ * synthesized description is still emitted so no function — and no MCP tool —
+ * ships description-less: a humanized operationId, else "METHOD /path".
+ */
+function humanDescription(parsed: ParsedOperation): string {
   const description = parsed.description?.trim()
   if (description && !GENERIC_SUMMARIES.has(description.toLowerCase())) {
     return capitalize(description)
   }
-  return undefined
+  const summary = parsed.summary?.trim()
+  if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
+    return capitalize(summary)
+  }
+  return humanizeOperationId(parsed.operationId) ?? `${parsed.method.toUpperCase()} ${parsed.path}`
 }
 
 function getErrorClassesForResponses(