Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Static materializer for MCP tool input schemas.
//
// Why this exists. scripts/build-mcp-catalog.mjs advertises the catalog as
// carrying "name, description, input schema, price, safety" in one request, but
// it shipped every tool without a schema: 272 tools an agent could discover and
// none it could actually call, because nothing said what arguments to pass.
// This module recovers the schema from source so the catalog delivers what it
// claims.
//
// Everything is read statically with acorn, for the same reason the rest of the
// MCP tooling is: importing a hosted catalog pulls in DB and RPC clients that
// block without live credentials, and a docs build must never depend on
// production.
//
// Two declaration styles exist in this repo and both are handled:
//
// 1. `inputSchema: { type: 'object', properties: { … } }` — a JSON Schema
// literal, which 262 of the 272 tools use. Read by `jsonValue`.
// 2. `inputSchema: inputJsonSchema` where `const inputJsonSchema =
// jsonSchemaFromZod(inputZodShape)` — built at import time from a zod
// shape (the IBM Granite and vanity-grinder tools). Read by `zodShape`,
// which re-derives what zod-to-json-schema would have produced.
//
// The hard rule for both readers: anything not recognized is reported as
// dynamic and omitted, never guessed. A catalog that is silently wrong about a
// tool's arguments is worse than one that says it does not know.
import { readFileSync } from 'node:fs';
import { dirname, join, normalize } from 'node:path';
import { parse } from 'acorn';
import { ROOT } from './mcp-tool-sources.mjs';
/* ── AST helpers ─────────────────────────────────────────────────────────── */
function walk(node, visit) {
if (!node || typeof node.type !== 'string') return;
visit(node);
for (const key of Object.keys(node)) {
if (key === 'type' || key === 'start' || key === 'end') continue;
const value = node[key];
if (Array.isArray(value)) for (const child of value) walk(child, visit);
else if (value && typeof value.type === 'string') walk(value, visit);
}
}
/** `Object.freeze(x)` and `x` alike resolve to x. */
function unwrapFreeze(node) {
if (
node?.type === 'CallExpression' &&
node.callee?.type === 'MemberExpression' &&
node.callee.property?.name === 'freeze' &&
node.arguments.length === 1
) {
return unwrapFreeze(node.arguments[0]);
}
return node;
}
/**
* The object literal an expression names: the literal itself, a const holding
* one, or a non-computed member of one (`def.inputSchema`). Null otherwise.
*/
function resolveObjectExpression(node, consts, seen = new Set()) {
const target = unwrapFreeze(node);
if (!target || seen.has(target)) return null;
seen.add(target);
if (target.type === 'ObjectExpression') return target;
if (target.type === 'Identifier') {
const bound = consts.get(target.name);
return bound ? resolveObjectExpression(bound, consts, seen) : null;
}
if (target.type === 'MemberExpression' && !target.computed) {
const owner = resolveObjectExpression(target.object, consts, seen);
const prop = owner?.properties.find(
(p) => p.type === 'Property' && !p.computed && propKey(p) === target.property?.name,
);
return prop ? resolveObjectExpression(prop.value, consts, seen) : null;
}
return null;
}
/**
* Every `const x = …` in the module, by name.
*
* A rest destructure (`const { confirm: _c, ...previewShape } = def.inputSchema`)
* is how a preview tool drops its executing tool's confirm flag, so the rest
* binding is recorded too, as the source literal minus the picked keys. Those
* resolve in a second pass, once every plain const they may name is known.
*/
function collectLocalConsts(ast) {
const out = new Map();
const rests = [];
walk(ast, (node) => {
if (node.type !== 'VariableDeclarator' || !node.init) return;
if (node.id?.type === 'Identifier') out.set(node.id.name, unwrapFreeze(node.init));
else if (node.id?.type === 'ObjectPattern') rests.push(node);
});
for (const { id, init } of rests) {
const rest = id.properties.find((p) => p.type === 'RestElement' && p.argument?.type === 'Identifier');
if (!rest || out.has(rest.argument.name)) continue;
const source = resolveObjectExpression(init, out);
if (!source) continue;
const picked = new Set(id.properties.filter((p) => p.type === 'Property' && !p.computed).map(propKey));
out.set(rest.argument.name, {
...source,
properties: source.properties.filter((p) => !(p.type === 'Property' && !p.computed && picked.has(propKey(p)))),
});
}
return out;
}
const moduleCache = new Map();
/** Parsed consts of a repo-relative module, or null when it cannot be read. */
function localConstsOf(relPath) {
if (moduleCache.has(relPath)) return moduleCache.get(relPath);
let consts = null;
try {
const ast = parse(readFileSync(join(ROOT, relPath), 'utf8'), {
ecmaVersion: 'latest',
sourceType: 'module',
});
consts = collectLocalConsts(ast);
} catch {
consts = null; // missing or unparseable: nothing to inherit
}
moduleCache.set(relPath, consts);
return consts;
}
/**
* Every const a tool file can see by name: its own, plus one level of
* relative imports.
*
* Schema bounds and enum member lists are routinely hoisted into a shared
* module (`maximum: TOKENIZE_3D_ROYALTY_CAP_BPS`, `z.enum(ACCEPTED_IMAGE_TYPES)`),
* and a reader that stopped at the file boundary dropped exactly those
* constraints. One level is enough for every case in this repo and keeps the
* read bounded; a bare package specifier is never followed.
*/
function collectConsts(ast, relPath) {
const out = collectLocalConsts(ast);
const dir = dirname(relPath);
for (const node of ast.body) {
if (node.type !== 'ImportDeclaration') continue;
const spec = node.source?.value;
if (typeof spec !== 'string' || !spec.startsWith('.')) continue;
const imported = localConstsOf(normalize(join(dir, spec)));
if (!imported) continue;
for (const s of node.specifiers) {
if (s.type !== 'ImportSpecifier') continue;
const local = s.local.name;
// A local declaration always wins over an import of the same name.
if (out.has(local)) continue;
const value = imported.get(s.imported.name ?? s.imported.value);
if (value) out.set(local, value);
}
}
return out;
}
const propKey = (prop) => prop.key?.name ?? prop.key?.value;
/* ── JSON Schema literals ────────────────────────────────────────────────── */
/**
* Materialize an expression as a plain JSON value.
*
* Records every expression it cannot resolve on `ctx.dynamic` (as a dotted path
* into the schema) and returns `undefined` for it, so the caller drops the key
* rather than emitting a placeholder.
*
* @param {object} node acorn expression node
* @param {{consts: Map<string, object>, dynamic: string[], seen: Set<object>}} ctx
* @param {string} path dotted path, for the dynamic report
* @returns {*} the value, or undefined when it is not statically knowable
*/
function jsonValue(node, ctx, path) {
if (!node) return undefined;
switch (node.type) {
case 'Literal':
// Regex literals carry no JSON value (`value` is a RegExp object).
if (node.regex) return node.raw;
return node.value;
case 'TemplateLiteral': {
// An interpolated description is still worth showing; `${…}` marks the
// hole, matching how the safety and golden readers render one.
const cooked = node.quasis.map((q) => q.value.cooked ?? '');
return node.expressions.length ? cooked.join('${…}') : cooked.join('');
}
case 'BinaryExpression': {
// Long descriptions are routinely written as `'part one ' + 'part two'`.
if (node.operator !== '+') break;
const left = jsonValue(node.left, ctx, path);
const right = jsonValue(node.right, ctx, path);
if (left === undefined && right === undefined) return undefined;
if (typeof left === 'number' && typeof right === 'number') return left + right;
// One side is an env-driven or computed value (`'cap: $' + CAPS.max`).
// Mark the hole the way a template literal's is marked rather than
// dropping a whole sentence of documentation over one number.
const text = (side) => (side === undefined ? '${…}' : String(side));
return `${text(left)}${text(right)}`;
}
case 'UnaryExpression': {
const inner = jsonValue(node.argument, ctx, path);
if (typeof inner !== 'number') break;
if (node.operator === '-') return -inner;
if (node.operator === '+') return inner;
break;
}
case 'ArrayExpression': {
// All or nothing. A truncated array is a lie in every position a schema
// puts one: a short `enum` rejects values the tool accepts, and a short
// `required` tells a caller an argument is optional when it is not.
const out = [];
for (let i = 0; i < node.elements.length; i++) {
const element = node.elements[i];
if (!element) continue; // a hole
if (element.type === 'SpreadElement') {
const spread = jsonValue(element.argument, ctx, `${path}[${i}]`);
if (!Array.isArray(spread)) return undefined;
out.push(...spread);
continue;
}
const value = jsonValue(element, ctx, `${path}[${i}]`);
if (value === undefined) return undefined;
out.push(value);
}
return out;
}
case 'ObjectExpression': {
const out = {};
for (const prop of node.properties) {
if (prop.type === 'SpreadElement') {
const spread = jsonValue(prop.argument, ctx, path);
if (spread && typeof spread === 'object' && !Array.isArray(spread)) {
Object.assign(out, spread);
} else {
ctx.dynamic.push(`${path}.…spread`);
}
continue;
}
if (prop.type !== 'Property' || prop.computed) {
ctx.dynamic.push(`${path}.…computed`);
continue;
}
const key = propKey(prop);
if (typeof key !== 'string') {
ctx.dynamic.push(`${path}.…computed`);
continue;
}
const child = `${path}.${key}`;
// A method or getter in a schema position is code, not data.
if (prop.value.type === 'FunctionExpression' || prop.value.type === 'ArrowFunctionExpression') {
ctx.dynamic.push(child);
continue;
}
const value = jsonValue(prop.value, ctx, child);
if (value === undefined) ctx.dynamic.push(child);
else out[key] = value;
}
return out;
}
case 'Identifier': {
const target = ctx.consts.get(node.name);
if (!target || ctx.seen.has(target)) return undefined;
ctx.seen.add(target);
try {
return jsonValue(target, ctx, path);
} finally {
ctx.seen.delete(target);
}
}
case 'MemberExpression': {
if (node.computed) break;
const object = jsonValue(node.object, ctx, path);
if (!object || typeof object !== 'object') break;
return object[node.property?.name];
}
case 'CallExpression': {
// `Object.keys(SOME_CONST)` is how several enums are declared, and the
// const it reads is right here in the module.
const callee = node.callee;
if (
callee?.type === 'MemberExpression' &&
callee.object?.name === 'Object' &&
callee.property?.name === 'keys' &&
node.arguments.length === 1
) {
const source = jsonValue(node.arguments[0], ctx, path);
if (source && typeof source === 'object' && !Array.isArray(source)) return Object.keys(source);
}
break;
}
default:
break;
}
return undefined;
}
/* ── zod shapes ──────────────────────────────────────────────────────────── */
// The zod vocabulary these tool files actually use, surveyed across every
// source in mcpToolSources(). Anything outside it makes the whole schema
// dynamic rather than a partially-invented one: an argument list that is subtly
// wrong costs an integrator more than one that is absent.
const ZOD_BASES = new Set([
'string',
'number',
'boolean',
'array',
'object',
'enum',
'literal',
'record',
'union',
'any',
]);
const ZOD_MODIFIERS = new Set([
'min',
'max',
'gt',
'int',
'positive',
'nonnegative',
'optional',
'nullable',
'describe',
'default',
'catch',
'trim',
'refine',
'partial',
'strict',
'url',
'uuid',
'email',
'regex',
'nonempty',
]);
/**
* Unwind a chained zod expression into its base call plus the modifiers applied
* to it, outermost last: `z.string().min(1).optional()` becomes
* `{ base: z.string() call, chain: [min, optional] }`.
* @returns {{base: object, chain: {name: string, args: object[]}[]}|null}
*/
function unwindZodChain(node, consts) {
const chain = [];
// A field is as often hoisted to a const as written inline
// (`inputSchema: { subscription }`), so follow the name before giving up.
let cursor = node?.type === 'Identifier' && consts?.has(node.name) ? consts.get(node.name) : node;
while (cursor?.type === 'CallExpression' && cursor.callee?.type === 'MemberExpression' && !cursor.callee.computed) {
const name = cursor.callee.property?.name;
const receiver = cursor.callee.object;
// `z.string()` is the base: its receiver is the zod namespace itself.
if (receiver?.type === 'Identifier' && receiver.name === 'z') {
if (!ZOD_BASES.has(name)) return null;
return { base: { name, args: cursor.arguments }, chain: chain.reverse() };
}
if (!ZOD_MODIFIERS.has(name)) return null;
chain.push({ name, args: cursor.arguments });
cursor = receiver;
}
return null;
}
/**
* A single zod field as JSON Schema, mirroring what zod-to-json-schema emits
* for the constructs in use.
* @returns {{schema: object, required: boolean}|null} null when unreadable
*/
function zodField(node, ctx, path) {
const unwound = unwindZodChain(node, ctx.consts);
if (!unwound) return null;
const { base, chain } = unwound;
let schema;
switch (base.name) {
case 'string':
schema = { type: 'string' };
break;
case 'number':
schema = { type: 'number' };
break;
case 'boolean':
schema = { type: 'boolean' };
break;
case 'array': {
const items = base.args[0] ? zodField(base.args[0], ctx, `${path}[]`) : null;
if (!items) return null;
schema = { type: 'array', items: items.schema };
break;
}
case 'object': {
const inner = base.args[0];
if (inner?.type !== 'ObjectExpression') return null;
const built = zodShapeObject(inner, ctx, path);
if (!built) return null;
schema = built;
break;
}
case 'enum': {
const values = jsonValue(base.args[0], ctx, `${path}.enum`);
if (Array.isArray(values) && values.every((v) => typeof v === 'string')) {
schema = { type: 'string', enum: values };
} else {
// The member list lives behind an import or a computed expression. The
// argument itself is still real and still a string; keeping it without
// the enum beats dropping a documented argument over a missing list.
ctx.dynamic.push(`${path}.enum`);
schema = { type: 'string' };
}
break;
}
case 'literal': {
const value = jsonValue(base.args[0], ctx, `${path}.const`);
if (value === undefined) return null;
schema = { type: typeof value === 'number' ? 'number' : typeof value, const: value };
break;
}
case 'record': {
// z.record(value) and z.record(key, value) both constrain the values.
const valueNode = base.args.length > 1 ? base.args[1] : base.args[0];
if (!valueNode) {
schema = { type: 'object' };
break;
}
const values = zodField(valueNode, ctx, `${path}.*`);
if (!values) return null;
schema = { type: 'object', additionalProperties: values.schema };
break;
}
case 'union': {
const members = base.args[0];
if (members?.type !== 'ArrayExpression') return null;
const built = [];
for (const member of members.elements) {
const field = member ? zodField(member, ctx, `${path}|`) : null;
if (!field) return null;
built.push(field.schema);
}
schema = { anyOf: built };
break;
}
case 'any':
// No constraint at all. An empty schema is what that means in JSON
// Schema, and it is the honest answer rather than inventing a type.
schema = {};
break;
default:
return null;
}
// zod-to-json-schema drops a field from `required` for both `.optional()` and
// `.default()`; a defaulted field is satisfiable without the caller sending it.
let required = true;
for (const step of chain) {
switch (step.name) {
case 'optional':
required = false;
break;
case 'nullable':
// A nullable field still has to be sent; it may just be null. Widening
// the type says exactly that, where treating it as optional would tell
// an integrator they can omit a required argument.
if (typeof schema.type === 'string') schema.type = [schema.type, 'null'];
else if (!schema.type) schema.anyOf = [{ ...schema }, { type: 'null' }];
break;
case 'int':
schema.type = 'integer';
break;
// Parse-time only: `.trim()` normalizes the value, `.catch()` swaps in a
// fallback on failure, `.refine()` runs a predicate. None of the three
// narrows the accepted shape, so none of them changes the schema.
case 'trim':
case 'catch':
case 'refine':
break;
case 'strict':
schema.additionalProperties = false;
break;
case 'partial':
delete schema.required;
break;
case 'positive':
schema.exclusiveMinimum = 0;
break;
case 'nonnegative':
schema.minimum = 0;
break;
case 'nonempty':
schema[base.name === 'array' ? 'minItems' : 'minLength'] = 1;
break;
case 'url':
schema.format = 'uri';
break;
case 'uuid':
schema.format = 'uuid';
break;
case 'email':
schema.format = 'email';
break;
case 'regex': {
// Inline literal, or a named const like `BASE58_RE` declared above.
let node = step.args[0];
if (node?.type === 'Identifier') node = ctx.consts.get(node.name) ?? node;
const source = node?.regex?.pattern;
if (typeof source !== 'string') {
ctx.dynamic.push(`${path}.pattern`);
break;
}
schema.pattern = source;
break;
}
case 'describe': {
const text = jsonValue(step.args[0], ctx, `${path}.description`);
if (typeof text !== 'string') return null;
schema.description = text;
break;
}
case 'default': {
const value = jsonValue(step.args[0], ctx, `${path}.default`);
if (value === undefined) return null;
schema.default = value;
required = false;
break;
}
case 'gt': {
const bound = jsonValue(step.args[0], ctx, `${path}.gt`);
if (typeof bound !== 'number') return null;
schema.exclusiveMinimum = bound;
break;
}
case 'min':
case 'max': {
const bound = jsonValue(step.args[0], ctx, `${path}.${step.name}`);
if (typeof bound !== 'number') return null;
const key =
{
string: step.name === 'min' ? 'minLength' : 'maxLength',
array: step.name === 'min' ? 'minItems' : 'maxItems',
}[base.name] ?? (step.name === 'min' ? 'minimum' : 'maximum');
schema[key] = bound;
break;
}
default:
return null;
}
}
return { schema, required };
}
/**
* A `{ field: z.… }` shape object as a JSON Schema object node.
* @returns {object|null} null when any field is unreadable
*/
function zodShapeObject(node, ctx, path) {
const properties = {};
const required = [];
let readable = 0;
for (const prop of node.properties) {
if (prop.type !== 'Property' || prop.computed) {
ctx.dynamic.push(`${path}.…computed`);
continue;
}
const key = propKey(prop);
if (typeof key !== 'string') {
ctx.dynamic.push(`${path}.…computed`);
continue;
}
const field = zodField(prop.value, ctx, `${path}.${key}`);
// One field built with a construct this reader does not model must not cost
// the caller the other six. Report it and keep going.
if (!field) {
ctx.dynamic.push(`${path}.${key}`);
continue;
}
readable++;
properties[key] = field.schema;
if (field.required) required.push(key);
}
if (node.properties.length && !readable) return null;
// `.strict()` on the outer object and zod's default strip on inner ones both
// render as `additionalProperties: false`.
const schema = { type: 'object', properties };
if (required.length) schema.required = required;
schema.additionalProperties = false;
return schema;
}
/* ── entry points ────────────────────────────────────────────────────────── */
/**
* Resolve one `inputSchema:` property value to a JSON Schema.
*
* @param {object} node the expression assigned to `inputSchema`
* @param {Map<string, object>} consts the module's const initializers
* @returns {{schema: object|null, dynamic: string[], reason: string|null}}
*/
export function materializeSchema(node, consts) {
const ctx = { consts, dynamic: [], seen: new Set() };
const unreadable = 'declared with a zod construct this reader does not model';
// `const inputJsonSchema = jsonSchemaFromZod(inputZodShape)` — follow the
// identifier to the call, then read the zod shape it was built from.
let target = node;
if (target?.type === 'Identifier') {
const resolved = consts.get(target.name);
if (resolved) target = resolved;
}
// `inputSchema: def.inputSchema`: a preview tool reusing the schema of the
// tool it previews. Read the literal that member names.
if (target?.type === 'MemberExpression') {
const resolved = resolveObjectExpression(target, consts);
if (resolved) target = resolved;
}
if (target?.type === 'CallExpression') {
const callee = target.callee?.name ?? target.callee?.property?.name;
if (callee === 'jsonSchemaFromZod' && target.arguments.length === 1) {
let shape = target.arguments[0];
if (shape.type === 'Identifier') shape = consts.get(shape.name) ?? shape;
if (shape?.type === 'ObjectExpression') {
const schema = zodShapeObject(shape, ctx, 'inputSchema');
if (schema) return { schema, dynamic: [], reason: null };
}
return { schema: null, dynamic: [], reason: unreadable };
}
// `parameters: z.object({ … })`: the tool-SDK style. Read the zod chain
// directly; a bare `z.object()` is already the whole argument schema.
const field = zodField(target, ctx, 'inputSchema');
if (field?.schema?.type === 'object') return { schema: field.schema, dynamic: [], reason: null };
return { schema: null, dynamic: [], reason: 'built by a call at import time' };
}
if (target?.type !== 'ObjectExpression') {
return { schema: null, dynamic: [], reason: 'not a statically-declared object' };
}
// Two object shapes are legal here and they are not interchangeable: a JSON
// Schema (`{ type: 'object', properties: { … } }`) and a raw zod shape
// (`{ field: z.string() }`, which the MCP SDK converts itself). Reading a raw
// shape with the JSON reader is what dropped the arguments of 33 tools: every
// value was a call expression it could not resolve, so every property was
// discarded and the tool shipped an empty `properties` object.
if (isRawZodShape(target, consts)) {
const schema = zodShapeObject(target, ctx, 'inputSchema');
if (schema) return { schema, dynamic: [], reason: null };
return { schema: null, dynamic: [], reason: unreadable };
}
const schema = jsonValue(target, ctx, 'inputSchema');
if (!schema || typeof schema !== 'object') {
return { schema: null, dynamic: ctx.dynamic, reason: 'did not resolve to an object' };
}
return { schema, dynamic: ctx.dynamic, reason: null };
}
/**
* True when an object literal is a zod raw shape rather than a JSON Schema.
* A JSON Schema always announces itself with `type` or `properties`; a raw
* shape's values are all zod chains.
*/
function isRawZodShape(node, consts) {
// Decided on the values, never the keys: a shape whose first field happens to
// be named `type` (`{ type: z.enum(['http','mcp']) }`) is still a zod shape,
// and a key-based test read six of those as JSON Schema and emitted them with
// no arguments at all. A JSON Schema literal can never hold a `z.…()` chain
// in a property position, so one is proof.
return node.properties.some(
(prop) => prop.type === 'Property' && !prop.computed && Boolean(unwindZodChain(prop.value, consts)),
);
}
/**
* Every statically-declared tool input schema in one tool-definition file,
* keyed by wire tool name.
*
* The tool predicate here is deliberately looser than the safety gate's (a
* string `name` plus an `inputSchema` is enough): callers correlate by name, so
* a superset costs nothing, while a stricter predicate that drifted from the
* gate's would silently drop a tool's arguments.
*
* @param {string} relPath repo-relative path to a tool-definition file
* @returns {Map<string, {schema: object|null, dynamic: string[], reason: string|null}>}
*/
export function extractInputSchemas(relPath) {
const src = readFileSync(join(ROOT, relPath), 'utf8');
let ast;
try {
ast = parse(src, { ecmaVersion: 'latest', sourceType: 'module' });
} catch {
return new Map();
}
const consts = collectConsts(ast, relPath);
const out = new Map();
walk(ast, (node) => {
if (node.type !== 'ObjectExpression') return;
let name = null;
let schemaNode = null;
let parametersNode = null;
for (const prop of node.properties) {
if (prop.type !== 'Property' || prop.computed) continue;
const key = propKey(prop);
if (key === 'name') {
// A wire name is as often `name: TOOL_NAME` as a literal; resolving it
// through the module's consts is what keeps @three-ws/tool-sdk tools
// (which always name themselves that way) from vanishing.
const value = jsonValue(prop.value, { consts, dynamic: [], seen: new Set() }, 'name');
if (typeof value === 'string') name = value;
} else if (key === 'inputSchema') {
schemaNode = prop.value;
} else if (key === 'parameters') {
// @three-ws/tool-sdk names the same field `parameters` and converts it
// to `inputSchema` when it emits MCP tools (defineTool → toMcpTools).
parametersNode = prop.value;
}
}
const source = schemaNode ?? parametersNode;
if (!name || !source || out.has(name)) return;
out.set(name, materializeSchema(source, consts));
});
return out;
}
/**
* Argument rows for one schema, in declaration order: what a reference table or
* a generated form needs, without either having to re-walk JSON Schema.
*
* @param {object|null} schema
* @returns {{name: string, type: string, required: boolean, description: string|null,
* enum: string[]|null, default: *, format: string|null}[]}
*/
export function schemaArguments(schema) {
const properties = schema?.properties;
if (!properties || typeof properties !== 'object') return [];
const required = new Set(Array.isArray(schema.required) ? schema.required : []);
return Object.entries(properties).map(([name, spec]) => ({
name,
type: Array.isArray(spec?.type) ? spec.type.join(' | ') : (spec?.type ?? 'any'),
required: required.has(name),
description: typeof spec?.description === 'string' ? spec.description : null,
enum: Array.isArray(spec?.enum) ? spec.enum.map(String) : null,
default: spec?.default,
format: typeof spec?.format === 'string' ? spec.format : null,
}));
}