create-solvapay 0.8.0 → 0.8.1-preview-b07b713629dff72ea6d257f1f5145cb01ac62f2c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-solvapay",
-  "version": "0.8.0",
+  "version": "0.8.1-preview-b07b713629dff72ea6d257f1f5145cb01ac62f2c",
   "description": "Scaffold SolvaPay-monetized projects — MCP servers on Cloudflare Workers and more.",
   "type": "module",
   "bin": {

package/scripts/mcp/lib/openapi.mjs

@@ -198,7 +198,14 @@ export function listOperations(spec) {
       const op = pathItem[method]
       if (!op || typeof op !== 'object') continue
       const operationId = op.operationId ?? defaultOperationId(method, path)
-      const parameters = mergeParameters(pathLevelParams, op.parameters ?? [])
+      const merged = mergeParameters(pathLevelParams, op.parameters ?? [])
+      // Swagger 2.0 `type: file` form fields carry raw bytes the LLM can't
+      // supply, so they never become tool inputs; the operation is flagged
+      // instead (suggestTier skips it).
+      const hasFileUpload = merged.some(p => p.in === 'formData' && p.type === 'file')
+      const parameters = merged.filter(
+        p => p.in !== 'body' && !(p.in === 'formData' && p.type === 'file'),
+      )
       operations.push({
         operationId,
         method: method.toUpperCase(),
@@ -208,7 +215,11 @@ export function listOperations(spec) {
         deprecated: op.deprecated === true,
         tags: Array.isArray(op.tags) ? op.tags : [],
         parameters,
-        requestBody: extractRequestBody(op.requestBody),
+        requestBody:
+          extractRequestBody(op.requestBody) ??
+          extractSwagger2Body(spec, op, pathLevelParams),
+        formEncoding: formEncodingFor(spec, op, parameters, hasFileUpload),
+        hasFileUpload,
         security: op.security ?? spec.security ?? null,
         raw: op,
       })
@@ -313,6 +324,7 @@ function resolveOauth2ClientCredentialsFlow(scheme) {
 export function suggestTier(operation) {
   if (operation.deprecated) return 'skip'
   if (operation.raw?.['x-internal'] === true) return 'skip'
+  if (operation.hasFileUpload) return 'skip'
   if (operation.method === 'GET' || operation.method === 'HEAD') return 'free'
   if (MUTATING_METHODS.has(operation.method)) return 'paid'
   return 'free'
@@ -342,10 +354,10 @@ export function synthesizeExamples(operation) {
     if (operation.requestBody.example !== undefined) {
       // Media-type-level example takes precedence over schema synthesis.
       const value = operation.requestBody.example
-      Object.assign(inputs, isPlainObject(value) ? value : { body: value })
+      inputs.body = value
     } else if (operation.requestBody.schema) {
       const { value, source } = pickSchemaValue(operation.requestBody.schema)
-      Object.assign(inputs, isPlainObject(value) ? value : { body: value })
+      inputs.body = value
       if (source === 'placeholder') quality = 'placeholder'
     }
   }
@@ -562,7 +574,9 @@ function mergeParameters(pathLevel, opLevel) {
 }
 
 function normaliseParameter(param) {
-  const schema = param.schema ?? {}
+  // Swagger 2.0 non-body parameters declare type / format / enum /
+  // default on the parameter itself rather than under `schema`.
+  const schema = param.schema ?? param
   // Parameter-level `description` takes precedence over the inner
   // `schema.description` (OpenAPI 3 allows both; the parameter one is
   // the author's primary intent — schema-level usually describes the
@@ -589,6 +603,31 @@ function normaliseParameter(param) {
   }
 }
 
+// Swagger 2.0 carries the JSON body as an `in: body` parameter instead
+// of `requestBody`. Lift it into the same shape so codegen sends it.
+// Skipped when the operation only consumes non-JSON media types.
+function extractSwagger2Body(spec, op, pathLevelParams) {
+  const params = [...(op.parameters ?? []), ...pathLevelParams]
+  const body = params.find(p => p && typeof p === 'object' && p.in === 'body')
+  if (!body) return null
+  const consumes = op.consumes ?? spec.consumes
+  if (Array.isArray(consumes) && consumes.length > 0 && !consumes.some(c => /json/i.test(c))) {
+    return null
+  }
+  return { required: body.required === true, schema: body.schema ?? null, example: undefined }
+}
+
+// How Swagger 2.0 `in: formData` fields are sent: `multipart` when the
+// operation only accepts multipart (or uploads a file), otherwise
+// `urlencoded`. Null when there are no form fields.
+function formEncodingFor(spec, op, parameters, hasFileUpload) {
+  if (!parameters.some(p => p.in === 'formData')) return null
+  const consumes = op.consumes ?? spec.consumes ?? []
+  const urlencoded = consumes.some(c => /x-www-form-urlencoded/i.test(c))
+  const multipart = consumes.some(c => /multipart\/form-data/i.test(c))
+  return multipart && (hasFileUpload || !urlencoded) ? 'multipart' : 'urlencoded'
+}
+
 function extractRequestBody(requestBody) {
   if (!requestBody || typeof requestBody !== 'object') return null
   const json = requestBody.content?.['application/json']

package/scripts/mcp/scaffold.mjs

@@ -629,7 +629,8 @@ function renderToolFile({ operation, schemes, tier, auth, serverBaseUrl, freeLim
   const fnName = `register${toPascalIdentifier(operation.operationId)}`
   const urlTemplate = renderUrlTemplate(serverBaseUrl, operation)
   const headerLines = renderHeaderLines(auth, schemes, operation)
-  const includesEnv = headerLines.length > 0
+  // Matches the aggregator, which passes `env` whenever auth isn't `none`.
+  const includesEnv = auth.kind !== 'none'
   const needsAccessToken = auth.kind === 'oauth2-client-credentials'
   const signature = includesEnv
     ? `${fnName}(ctx: AdditionalToolsContext, env: Env)`
@@ -654,11 +655,15 @@ function renderToolFile({ operation, schemes, tier, auth, serverBaseUrl, freeLim
   // carries `{ status, contentType, bodySnippet }` on the thrown
   // error so the MCP `isError` envelope tells the LLM (and the
   // human) exactly why upstream rejected the call.
+  const fetchImports = fetchInit.usesStringifyLossless
+    ? 'upstreamFetchJson, stringifyLossless'
+    : 'upstreamFetchJson'
   const importLines = [
     "import { z } from 'zod'",
     "import type { AdditionalToolsContext } from '@solvapay/mcp'",
-    "import { upstreamFetchJson } from '../lib/upstreamFetch'",
+    `import { ${fetchImports} } from '../lib/upstreamFetch'`,
   ]
+  if (operation.parameters.some(isInt64Param)) importLines.push("import { int64 } from '../lib/int64'")
   if (needsAccessToken) importLines.push("import { getAccessToken } from '../lib/upstreamOAuth'")
   if (includesEnv) importLines.push("import type { Env } from '../worker'")
 
@@ -672,7 +677,10 @@ function renderSchemaFields(operation, indent) {
     lines.push(`${pad}${jsKey(param.name)}: ${zodForParam(param)},`)
   }
   if (operation.requestBody?.schema) {
-    lines.push(`${pad}body: z.record(z.string(), z.unknown()).optional(),`)
+    const bodySchema = isArrayBody(operation)
+      ? 'z.array(z.unknown())'
+      : 'z.record(z.string(), z.unknown())'
+    lines.push(`${pad}body: ${bodySchema}.optional(),`)
   }
   if (lines.length === 0) return ''
   return lines.join('\n')
@@ -694,7 +702,8 @@ function renderSchemaFields(operation, indent) {
 function zodForParam(param) {
   const { type, format, required, enum: enumValues, description } = param
   let z
-  if (type === 'integer') z = 'z.number().int()'
+  if (isInt64Param(param)) z = 'int64'
+  else if (type === 'integer') z = 'z.number().int()'
   else if (type === 'number') z = 'z.number()'
   else if (type === 'boolean') z = 'z.boolean()'
   else if (type === 'array') z = 'z.array(z.unknown())'
@@ -713,6 +722,35 @@ function zodForParam(param) {
   return required ? z : `${z}.optional()`
 }
 
+// 64-bit integers exceed JavaScript's exact range (2^53 - 1), so they use
+// the template's `int64` schema (safe number or digit string) instead of
+// `z.number().int()`.
+function isInt64Param(param) {
+  return param.type === 'integer' && (param.format === 'int64' || param.format === 'uint64')
+}
+
+// Names of every integer-typed property in a (dereferenced) request body
+// schema, walking nested objects, array items and composition keywords.
+// The generated tool passes them to `stringifyLossless` so int64 values
+// the LLM sends as digit strings go upstream as exact JSON numbers.
+// Collecting all integers (not only `int64`) is safe: the serializer only
+// rewrites values that are already digit strings.
+function collectIntegerPropertyNames(schema, names = new Set(), seen = new Set()) {
+  if (!schema || typeof schema !== 'object' || seen.has(schema)) return names
+  seen.add(schema)
+  for (const [name, prop] of Object.entries(schema.properties ?? {})) {
+    if (prop && typeof prop === 'object' && prop.type === 'integer') names.add(name)
+    collectIntegerPropertyNames(prop, names, seen)
+  }
+  collectIntegerPropertyNames(schema.items, names, seen)
+  for (const key of ['allOf', 'oneOf', 'anyOf']) {
+    for (const sub of Array.isArray(schema[key]) ? schema[key] : []) {
+      collectIntegerPropertyNames(sub, names, seen)
+    }
+  }
+  return names
+}
+
 function isScalarStringEnum(enumValues, type) {
   if (!Array.isArray(enumValues) || enumValues.length === 0) return false
   if (type !== undefined && type !== 'string') return false
@@ -732,6 +770,25 @@ function renderUrlTemplate(baseUrl, operation) {
   return `\`${joinUrl(baseUrl, path)}\``
 }
 
+function isArrayBody(operation) {
+  return operation.requestBody?.schema?.type === 'array'
+}
+
+// Swagger 2.0 `in: formData` fields, sent as URLSearchParams or FormData
+// per `operation.formEncoding`. fetch sets the matching content-type
+// (including the multipart boundary) from the body type.
+function renderFormAssign(operation) {
+  const fields = operation.parameters.filter(p => p.in === 'formData')
+  if (fields.length === 0 || !operation.formEncoding) return ''
+  const ctor = operation.formEncoding === 'multipart' ? 'FormData' : 'URLSearchParams'
+  const lines = [`      const form = new ${ctor}()`]
+  for (const field of fields) {
+    const access = `input.${jsAccessor(field.name)}`
+    lines.push(`      if (${access} !== undefined) form.set('${field.name}', String(${access}))`)
+  }
+  return lines.join('\n')
+}
+
 function renderFetchInit(operation, headerLines) {
   const method = operation.method
   const hasBody = !!operation.requestBody?.schema && method !== 'GET' && method !== 'HEAD'
@@ -741,19 +798,30 @@ function renderFetchInit(operation, headerLines) {
       const access = `input.${jsAccessor(p.name)}`
       return `      if (${access} !== undefined) url.searchParams.set('${p.name}', String(${access}))`
     })
+    .concat(renderFormAssign(operation) || [])
     .join('\n')
 
   const headersBlock = headerLines.length > 0
     ? `        headers: { ${headerLines.join(', ')} },\n`
     : ''
-  const bodyBlock = hasBody ? '        body: JSON.stringify(input.body ?? {}),\n' : ''
+  const integerKeys = hasBody
+    ? [...collectIntegerPropertyNames(operation.requestBody.schema)].sort()
+    : []
+  const usesStringifyLossless = integerKeys.length > 0
+  const emptyBody = isArrayBody(operation) ? '[]' : '{}'
+  const bodyBlock = !hasBody
+    ? operation.formEncoding
+      ? '        body: form,\n'
+      : ''
+    : usesStringifyLossless
+      ? `        body: stringifyLossless(input.body ?? ${emptyBody}, new Set(${JSON.stringify(integerKeys)})),\n`
+      : `        body: JSON.stringify(input.body ?? ${emptyBody}),\n`
   const methodBlock = `        method: '${method}',\n`
 
-  return { method, queryAssign, headersBlock, bodyBlock, methodBlock }
+  return { method, queryAssign, headersBlock, bodyBlock, methodBlock, usesStringifyLossless }
 }
 
 function renderHeaderLines(auth, schemes, operation) {
-  if (auth.kind === 'none') return []
   // Pick the first supported scheme this operation requires; fall back
   // to the top-level auth kind when the spec has no operation-level
   // security override.

package/templates/mcp/_base/scripts/lib/openapi.mjs

@@ -93,7 +93,14 @@ export function listOperations(spec) {
       const op = pathItem[method]
       if (!op || typeof op !== 'object') continue
       const operationId = op.operationId ?? defaultOperationId(method, path)
-      const parameters = mergeParameters(pathLevelParams, op.parameters ?? [])
+      const merged = mergeParameters(pathLevelParams, op.parameters ?? [])
+      // Swagger 2.0 `type: file` form fields carry raw bytes the LLM can't
+      // supply, so they never become tool inputs; the operation is flagged
+      // instead (suggestTier skips it).
+      const hasFileUpload = merged.some(p => p.in === 'formData' && p.type === 'file')
+      const parameters = merged.filter(
+        p => p.in !== 'body' && !(p.in === 'formData' && p.type === 'file'),
+      )
       operations.push({
         operationId,
         method: method.toUpperCase(),
@@ -103,7 +110,11 @@ export function listOperations(spec) {
         deprecated: op.deprecated === true,
         tags: Array.isArray(op.tags) ? op.tags : [],
         parameters,
-        requestBody: extractRequestBody(op.requestBody),
+        requestBody:
+          extractRequestBody(op.requestBody) ??
+          extractSwagger2Body(spec, op, pathLevelParams),
+        formEncoding: formEncodingFor(spec, op, parameters, hasFileUpload),
+        hasFileUpload,
         security: op.security ?? spec.security ?? null,
         raw: op,
       })
@@ -159,6 +170,7 @@ export function resolveSecuritySchemes(spec) {
 export function suggestTier(operation) {
   if (operation.deprecated) return 'skip'
   if (operation.raw?.['x-internal'] === true) return 'skip'
+  if (operation.hasFileUpload) return 'skip'
   if (operation.method === 'GET' || operation.method === 'HEAD') return 'free'
   if (MUTATING_METHODS.has(operation.method)) return 'paid'
   return 'free'
@@ -188,10 +200,10 @@ export function synthesizeExamples(operation) {
     if (operation.requestBody.example !== undefined) {
       // Media-type-level example takes precedence over schema synthesis.
       const value = operation.requestBody.example
-      Object.assign(inputs, isPlainObject(value) ? value : { body: value })
+      inputs.body = value
     } else if (operation.requestBody.schema) {
       const { value, source } = pickSchemaValue(operation.requestBody.schema)
-      Object.assign(inputs, isPlainObject(value) ? value : { body: value })
+      inputs.body = value
       if (source === 'placeholder') quality = 'placeholder'
     }
   }
@@ -252,7 +264,9 @@ function mergeParameters(pathLevel, opLevel) {
 }
 
 function normaliseParameter(param) {
-  const schema = param.schema ?? {}
+  // Swagger 2.0 non-body parameters declare type / format / enum /
+  // default on the parameter itself rather than under `schema`.
+  const schema = param.schema ?? param
   return {
     name: param.name,
     in: param.in,
@@ -267,6 +281,31 @@ function normaliseParameter(param) {
   }
 }
 
+// Swagger 2.0 carries the JSON body as an `in: body` parameter instead
+// of `requestBody`. Lift it into the same shape so codegen sends it.
+// Skipped when the operation only consumes non-JSON media types.
+function extractSwagger2Body(spec, op, pathLevelParams) {
+  const params = [...(op.parameters ?? []), ...pathLevelParams]
+  const body = params.find(p => p && typeof p === 'object' && p.in === 'body')
+  if (!body) return null
+  const consumes = op.consumes ?? spec.consumes
+  if (Array.isArray(consumes) && consumes.length > 0 && !consumes.some(c => /json/i.test(c))) {
+    return null
+  }
+  return { required: body.required === true, schema: body.schema ?? null, example: undefined }
+}
+
+// How Swagger 2.0 `in: formData` fields are sent: `multipart` when the
+// operation only accepts multipart (or uploads a file), otherwise
+// `urlencoded`. Null when there are no form fields.
+function formEncodingFor(spec, op, parameters, hasFileUpload) {
+  if (!parameters.some(p => p.in === 'formData')) return null
+  const consumes = op.consumes ?? spec.consumes ?? []
+  const urlencoded = consumes.some(c => /x-www-form-urlencoded/i.test(c))
+  const multipart = consumes.some(c => /multipart\/form-data/i.test(c))
+  return multipart && (hasFileUpload || !urlencoded) ? 'multipart' : 'urlencoded'
+}
+
 function extractRequestBody(requestBody) {
   if (!requestBody || typeof requestBody !== 'object') return null
   const json = requestBody.content?.['application/json']

package/templates/mcp/_base/src/lib/int64.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+
+/**
+ * Tool input schema for 64-bit integers (`format: int64`). JavaScript
+ * numbers are only exact up to 2^53 - 1, so larger values travel as a
+ * string of digits — the same form `upstreamFetchJson` returns them in.
+ * Unsafe numbers are rejected instead of being silently rounded.
+ */
+export const int64 = z.union([
+  z
+    .number()
+    .int()
+    .refine(Number.isSafeInteger, 'Integers this large must be passed as a string of digits'),
+  z.string().regex(/^-?\d+$/, 'Expected an integer as a string of digits'),
+])

package/templates/mcp/_base/src/lib/upstreamFetch.ts

@@ -12,6 +12,9 @@
  *  - Throws `UpstreamError` on non-2xx OR JSON parse failure. The
  *    error message names the method, URL, status, content-type, and
  *    a body snippet so the LLM has enough context to recover or stop.
+ *  - Keeps integers beyond `Number.MAX_SAFE_INTEGER` (int64 IDs,
+ *    snowflakes) as their exact decimal string instead of silently
+ *    rounding them. Send them back with `stringifyLossless`.
  *
  * The free-tool path (`ctx.server.registerTool`), the free-capped path
  * (`ctx.registerFree`), and the paid-tool path (`ctx.registerPayable`)
@@ -27,6 +30,41 @@
 
 const BODY_SNIPPET_MAX_CHARS = 500
 
+/**
+ * `JSON.parse` reviver that returns the exact source text for integers
+ * `JSON.parse` would round. Relies on JSON.parse source access (V8 11.4+:
+ * workerd, Node 21+); on older runtimes `context` is undefined and values
+ * pass through unchanged.
+ */
+function losslessIntReviver(_key: string, value: unknown, context?: { source?: string }): unknown {
+  if (
+    typeof value === 'number' &&
+    Number.isInteger(value) &&
+    !Number.isSafeInteger(value) &&
+    context?.source &&
+    /^-?\d+$/.test(context.source)
+  ) {
+    return context.source
+  }
+  return value
+}
+
+const rawJSON = (JSON as unknown as { rawJSON?: (text: string) => unknown }).rawJSON
+
+/**
+ * `JSON.stringify` that writes digit strings back as bare JSON numbers for
+ * the given keys (the spec's integer properties), so int64 values returned
+ * as strings by `upstreamFetchJson` round-trip exactly. Keys not listed are
+ * left alone, so digit-only strings such as phone numbers stay strings.
+ */
+export function stringifyLossless(body: unknown, integerKeys: ReadonlySet<string>): string {
+  return JSON.stringify(body, (key, value) =>
+    integerKeys.has(key) && typeof value === 'string' && /^-?\d+$/.test(value) && rawJSON
+      ? rawJSON(value)
+      : value,
+  )
+}
+
 export interface UpstreamErrorInit {
   method: string
   url: string
@@ -100,7 +138,7 @@ export async function upstreamFetchJson<T = unknown>(
   }
 
   try {
-    return JSON.parse(text) as T
+    return JSON.parse(text, losslessIntReviver as Parameters<typeof JSON.parse>[1]) as T
   } catch (err) {
     throw new UpstreamError({
       method,