flow-codeblock-rust-mcp 0.1.9 → 0.1.10

package/README.md

@@ -7,7 +7,7 @@ Local stdio MCP server for Flow Codeblock Rust+Bun. It calls the server-side Rus
 Bun 1.4.0 or newer is required:
 
 ```bash
-bunx --bun flow-codeblock-rust-mcp@0.1.9
+bunx --bun flow-codeblock-rust-mcp@0.1.10
 ```
 
 Configure the environment:
@@ -26,7 +26,7 @@ export FLOW_CODEBLOCK_TOKEN='<YOUR_INTERNAL_ACCESS_TOKEN>'
   "mcpServers": {
     "flow-codeblock-rust": {
       "command": "bunx",
-      "args": ["--bun", "flow-codeblock-rust-mcp@0.1.9"],
+      "args": ["--bun", "flow-codeblock-rust-mcp@0.1.10"],
       "env": {
         "FLOW_CODEBLOCK_BASE_URL": "https://flow.example.com",
         "FLOW_CODEBLOCK_TOKEN": "<YOUR_INTERNAL_ACCESS_TOKEN>"
@@ -56,6 +56,8 @@ At initialization the server sends complete tool selection, preview/confirmation
 
 Interface documents must include `schema_version`, `title`, `summary`, `endpoint`, `request`, `responses`, and `logic_description`. `endpoint` requires `methods` and `description`; `request.query` and `request.headers` must exist (use `[]` when empty). POST documents also require `request.body` with `content_type`, `schema`, and `example`. Every response requires `status`, `description`, `content_type`, `schema`, and `example`; every query/header parameter requires `name`, `type`, `required`, `description`, and `example`.
 
+Every nested schema property, array item, and object-form `additionalProperties` node requires `type`, `description`, and `example`, with examples covering declared fields. MCP accepts one legacy JSON-text parse, fills examples only from matching parent examples, and uses a neutral description when one is omitted.
+
 `endpoint.path` is relative: omit it when creating and use `/flow/codeblock/<actual-script-id>` when updating. Public request URLs combine the caller-provided service origin with `/flow/codeblock/{{script_id}}`. Never put real tokens, passwords, cookies, or Authorization values in code, documents, examples, or URLs.
 
 `interface_doc_patch` and `document_patch` require a positive integer `expected_version` and support at most 256 `add/remove/replace/move/copy/test` operations. Patch previews return operation counts, JSON Pointer paths, warnings, and version information, never the complete merged document.

package/dist/index.js

@@ -27896,6 +27896,7 @@ var interfaceDocNestedRules = [
 ];
 var interfaceDocInputDescription = [
   "A complete script-interface-doc.v1 document is required when creating a script, changing code, or saving documentation.",
+  "Submit interface_doc/document as a JSON object. Legacy JSON text is accepted and parsed once by MCP for compatibility. MCP fills nested examples only from matching parent examples, uses a neutral description when one is omitted, and never guesses a missing type.",
   `Required structure: ${Object.entries(interfaceDocRequiredFields).map(([key, fields]) => `${key}=[${fields.join(", ")}]`).join("; ")}.`,
   ...interfaceDocNestedRules,
   "endpoint.path is relative and must be /flow/codeblock/<actual-script-id> on update; the final public URL is the caller-provided domain followed by /flow/codeblock/<script-id>.",
@@ -27934,6 +27935,73 @@ var interfaceDocPatchJsonSchema = {
     ]
   }
 };
+var schemaNodeInputSchema;
+schemaNodeInputSchema = exports_external.lazy(() => exports_external.looseObject({
+  type: exports_external.string().min(1).describe("JSON Schema type such as object, array, string, integer, number, or boolean."),
+  description: exports_external.string().min(1).describe("Description of this nested field or data structure."),
+  example: exports_external.unknown().describe("A concrete value matching this nested schema node."),
+  properties: exports_external.record(exports_external.string(), schemaNodeInputSchema).optional().describe("Map fixed object field names to child schema nodes."),
+  items: schemaNodeInputSchema.optional().describe("Child schema node for each array item."),
+  additionalProperties: exports_external.union([exports_external.boolean(), schemaNodeInputSchema]).optional().describe("Boolean or child schema for dynamic object keys."),
+  required: exports_external.array(exports_external.string()).optional().describe("Runtime-required object field names.")
+}));
+var schemaRootInputSchema = exports_external.looseObject({
+  type: exports_external.string().min(1).describe("JSON Schema type such as object, array, string, integer, number, or boolean."),
+  description: exports_external.string().optional().describe("Description of the root data structure."),
+  example: exports_external.unknown().optional().describe("Complete example matching this root schema."),
+  properties: exports_external.record(exports_external.string(), schemaNodeInputSchema).optional().describe("Map fixed object field names to child schema nodes."),
+  items: schemaNodeInputSchema.optional().describe("Child schema node for each array item."),
+  additionalProperties: exports_external.union([exports_external.boolean(), schemaNodeInputSchema]).optional().describe("Boolean or child schema for dynamic object keys."),
+  required: exports_external.array(exports_external.string()).optional().describe("Runtime-required object field names.")
+});
+var parameterInputSchema = exports_external.looseObject({
+  name: exports_external.string().min(1).describe("Caller-facing query parameter or HTTP header name."),
+  type: exports_external.enum(["string", "integer", "number", "boolean", "array", "object"]).describe("Parameter JSON type."),
+  required: exports_external.boolean().describe("Whether the parameter is required at runtime."),
+  description: exports_external.string().min(1).describe("Purpose and constraints of the parameter."),
+  example: exports_external.unknown().describe("Concrete example value for the parameter."),
+  default: exports_external.unknown().optional().describe("Optional default value."),
+  format: exports_external.string().optional().describe("Optional format hint."),
+  enum_values: exports_external.array(exports_external.unknown()).optional().describe("Optional allowed values.")
+});
+var interfaceDocToolInputObjectSchema = exports_external.looseObject({
+  schema_version: exports_external.literal("script-interface-doc.v1").describe("Fixed document contract version."),
+  title: exports_external.string().min(1).describe("Interface document title."),
+  summary: exports_external.string().min(1).describe("One-sentence caller-facing summary."),
+  endpoint: exports_external.looseObject({
+    methods: exports_external.array(exports_external.enum(["GET", "POST"])).min(1).describe("HTTP methods supported by the endpoint."),
+    path: exports_external.string().optional().describe("Actual /flow/codeblock/{script_id} path on update."),
+    description: exports_external.string().min(1).describe("What the callable endpoint does.")
+  }).describe("HTTP endpoint contract."),
+  request: exports_external.looseObject({
+    query: exports_external.array(parameterInputSchema).describe("Caller-facing URL query parameters; use [] when empty."),
+    headers: exports_external.array(parameterInputSchema).describe("Caller-facing HTTP headers; use [] when empty."),
+    body: exports_external.looseObject({
+      content_type: exports_external.literal("application/json").describe("Must be application/json."),
+      schema: schemaRootInputSchema.describe("Request body JSON Schema."),
+      example: exports_external.unknown().describe("Complete request body example matching schema.")
+    }).optional().describe("POST request body.")
+  }).describe("Caller request contract."),
+  responses: exports_external.array(exports_external.looseObject({
+    status: exports_external.number().int().min(100).max(599).describe("HTTP status code from 100 through 599."),
+    description: exports_external.string().min(1).describe("Business meaning of this response branch."),
+    content_type: exports_external.literal("application/json").describe("Must be application/json."),
+    schema: schemaRootInputSchema.describe("Response body JSON Schema."),
+    example: exports_external.unknown().describe("Complete response example matching schema.")
+  })).min(1).describe("Complete response branches at the document root."),
+  logic_description: exports_external.string().min(20).describe("Endpoint processing logic; at least 20 characters."),
+  usage_refs: exports_external.array(exports_external.unknown()).optional().describe("Real application references only.")
+});
+function parseLegacyJsonDocument(value) {
+  if (typeof value !== "string")
+    return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+var interfaceDocToolInputSchema = exports_external.preprocess(parseLegacyJsonDocument, interfaceDocToolInputObjectSchema).describe(interfaceDocInputDescription);
 function assertInterfaceDocPatch(patch) {
   const parsed = interfaceDocPatchSchema.safeParse(patch);
   if (!parsed.success)
@@ -27945,18 +28013,82 @@ function isObject2(value) {
 function hasOwn(object4, key) {
   return Object.prototype.hasOwnProperty.call(object4, key);
 }
+function normalizeSchemaNode(schema, parentExample, fieldName, root = false) {
+  if (!root) {
+    if (typeof schema.description !== "string" || !schema.description.trim()) {
+      schema.description = `Value for field "${fieldName}".`;
+    }
+    if (!hasOwn(schema, "example") && parentExample !== undefined) {
+      schema.example = structuredClone(parentExample);
+    }
+  }
+  const example = hasOwn(schema, "example") ? schema.example : parentExample;
+  if (schema.type === "array") {
+    if (isObject2(schema.items)) {
+      const itemExample = Array.isArray(example) && example.length > 0 ? example[0] : undefined;
+      normalizeSchemaNode(schema.items, itemExample, `${fieldName} item`);
+    }
+    return;
+  }
+  if (schema.type !== "object")
+    return;
+  const properties = isObject2(schema.properties) ? schema.properties : undefined;
+  if (properties) {
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (!isObject2(propertySchema))
+        continue;
+      const childExample = isObject2(example) && hasOwn(example, key) ? example[key] : undefined;
+      normalizeSchemaNode(propertySchema, childExample, key);
+    }
+  }
+  if (isObject2(schema.additionalProperties)) {
+    const knownKeys = new Set(properties ? Object.keys(properties) : []);
+    const dynamicExample = isObject2(example) ? Object.entries(example).find(([key]) => !knownKeys.has(key))?.[1] : undefined;
+    normalizeSchemaNode(schema.additionalProperties, dynamicExample, `${fieldName} value`);
+  }
+}
+function normalizeInterfaceDocument(document) {
+  if (!isObject2(document))
+    return document;
+  const normalized = structuredClone(document);
+  const containers = [];
+  if (isObject2(normalized.request) && isObject2(normalized.request.body)) {
+    containers.push(normalized.request.body);
+  }
+  if (Array.isArray(normalized.responses)) {
+    containers.push(...normalized.responses.filter(isObject2));
+  }
+  for (const container of containers) {
+    const schema = isObject2(container.schema) ? container.schema : undefined;
+    if (!schema)
+      continue;
+    if (!hasOwn(container, "example") && hasOwn(schema, "example")) {
+      container.example = structuredClone(schema.example);
+    }
+    normalizeSchemaNode(schema, container.example, "root", true);
+  }
+  return normalized;
+}
 function requireText(object4, key, path, issues, minLength = 1) {
   const value = object4[key];
   if (typeof value !== "string" || value.trim().length < minLength) {
     issues.push(`${path}.${key} must be a non-empty string with at least ${minLength} characters`);
   }
 }
-function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath, issues) {
+function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath, issues, requireMetadata = false) {
   if (typeof schema.type !== "string") {
     issues.push(`${schemaPath}.type is required`);
-    return;
+  }
+  if (requireMetadata) {
+    requireText(schema, "description", schemaPath, issues);
+    if (!hasOwn(schema, "example")) {
+      issues.push(`${schemaPath}.example is required`);
+    }
   }
   if (schema.type === "array") {
+    if (!isObject2(schema.items)) {
+      issues.push(`${schemaPath}.items is required for array schemas`);
+    }
     if (!Array.isArray(example)) {
       issues.push(`${examplePath} must be an array`);
       return;
@@ -27965,14 +28097,15 @@ function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath,
       issues.push(`${schemaPath}.items must fully describe array elements`);
       return;
     }
-    example.forEach((item, index) => validateSchemaExampleCoverage(schema.items, item, `${schemaPath}.items`, `${examplePath}[${index}]`, issues));
+    example.forEach((item, index) => validateSchemaExampleCoverage(schema.items, item, `${schemaPath}.items`, `${examplePath}[${index}]`, issues, true));
     return;
   }
   if (schema.type !== "object")
     return;
   const properties = isObject2(schema.properties) ? schema.properties : undefined;
   const additionalProperties = isObject2(schema.additionalProperties) ? schema.additionalProperties : undefined;
-  if (!properties && !additionalProperties) {
+  const allowsAdditionalProperties = additionalProperties !== undefined || schema.additionalProperties === true;
+  if (!properties && !allowsAdditionalProperties) {
     issues.push(`${schemaPath} must define properties or an additionalProperties schema`);
     return;
   }
@@ -27985,7 +28118,7 @@ function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath,
       if (!hasOwn(example, key)) {
         issues.push(`${examplePath} is missing ${key}`);
       } else if (isObject2(propertySchema)) {
-        validateSchemaExampleCoverage(propertySchema, example[key], `${schemaPath}.properties.${key}`, `${examplePath}.${key}`, issues);
+        validateSchemaExampleCoverage(propertySchema, example[key], `${schemaPath}.properties.${key}`, `${examplePath}.${key}`, issues, true);
       } else {
         issues.push(`${schemaPath}.properties.${key} must be a JSON Schema object`);
       }
@@ -27995,8 +28128,8 @@ function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath,
     if (properties && hasOwn(properties, key))
       continue;
     if (additionalProperties) {
-      validateSchemaExampleCoverage(additionalProperties, value, `${schemaPath}.additionalProperties`, `${examplePath}.${key}`, issues);
-    } else {
+      validateSchemaExampleCoverage(additionalProperties, value, `${schemaPath}.additionalProperties`, `${examplePath}.${key}`, issues, true);
+    } else if (schema.additionalProperties !== true) {
       issues.push(`${schemaPath}.properties does not define example field ${key}`);
     }
   }
@@ -28128,7 +28261,7 @@ function interfaceDocCompletenessIssues(document, operation) {
       validateSchemaAndExample(response, path, issues);
     });
   }
-  return issues;
+  return [...new Set(issues)];
 }
 function assertCompleteInterfaceDoc(document, operation) {
   const issues = interfaceDocCompletenessIssues(document, operation);
@@ -28222,7 +28355,7 @@ var interfaceDocSchema = {
       additionalProperties: false,
       properties: {
         content_type: { const: "application/json" },
-        schema: {},
+        schema: { $ref: "#/$defs/schema_root" },
         example: {}
       }
     },
@@ -28234,30 +28367,68 @@ var interfaceDocSchema = {
         status: { type: "integer", minimum: 100, maximum: 599 },
         description: { type: "string", minLength: 1, maxLength: 4000 },
         content_type: { const: "application/json" },
-        schema: {},
+        schema: { $ref: "#/$defs/schema_root" },
         example: {}
       }
+    },
+    schema_root: {
+      type: "object",
+      required: ["type"],
+      additionalProperties: true,
+      properties: {
+        type: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        example: {},
+        properties: { type: "object", additionalProperties: { $ref: "#/$defs/schema_node" } },
+        items: { $ref: "#/$defs/schema_node" },
+        additionalProperties: { anyOf: [{ $ref: "#/$defs/schema_node" }, { type: "boolean" }] },
+        required: { type: "array", items: { type: "string" } }
+      }
+    },
+    schema_node: {
+      type: "object",
+      required: ["type", "description", "example"],
+      additionalProperties: true,
+      properties: {
+        type: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        example: {},
+        properties: { type: "object", additionalProperties: { $ref: "#/$defs/schema_node" } },
+        items: { $ref: "#/$defs/schema_node" },
+        additionalProperties: { anyOf: [{ $ref: "#/$defs/schema_node" }, { type: "boolean" }] },
+        required: { type: "array", items: { type: "string" } }
+      }
     }
   }
 };
-function schemaFromExample(value) {
+function schemaFromExample(value, fieldName = "value") {
+  const metadata = { description: `Value for ${fieldName}.`, example: structuredClone(value) };
   if (Array.isArray(value)) {
-    return { type: "array", items: value.length > 0 ? schemaFromExample(value[0]) : { type: "string" } };
+    return {
+      type: "array",
+      ...metadata,
+      items: value.length > 0 ? schemaFromExample(value[0], `${fieldName} item`) : {
+        type: "string",
+        description: `Value for ${fieldName} item.`,
+        example: ""
+      }
+    };
   }
   if (value !== null && typeof value === "object") {
     const entries = Object.entries(value);
     return {
       type: "object",
-      properties: Object.fromEntries(entries.map(([key, item]) => [key, schemaFromExample(item)])),
+      ...metadata,
+      properties: Object.fromEntries(entries.map(([key, item]) => [key, schemaFromExample(item, key)])),
       required: entries.map(([key]) => key),
       additionalProperties: false
     };
   }
   if (value === null)
-    return { type: "null" };
+    return { type: "null", ...metadata };
   if (typeof value === "number")
-    return { type: Number.isInteger(value) ? "integer" : "number" };
-  return { type: typeof value };
+    return { type: Number.isInteger(value) ? "integer" : "number", ...metadata };
+  return { type: typeof value, ...metadata };
 }
 function codeWriterContext(mode, requirement, inputExample, includeFullSchema, baseUrl) {
   const common = {
@@ -28535,8 +28706,9 @@ var serverInstructions = [
   "Tool routing: flow_write_code only generates code and its contract; flow_execute_code tests unpublished generated code; flow_execute_script runs published scripts. When the generated code and available safe input are sufficient for a meaningful runtime test, execute it immediately without waiting for user confirmation. If required input or credentials are missing, report that runtime verification was not performed instead of inventing them.",
   "Script workflow: read the current version with flow_get_script before updates; creates require a complete interface_doc, while code or document updates may use a complete interface_doc or an RFC 6902 interface_doc_patch (never both, and patches require expected_version). Preview with flow_preview_script_change, then call flow_apply_script_change(confirm=true) only after explicit user confirmation. Documentation-only changes use flow_preview_script_documentation -> flow_apply_script_documentation.",
   "Preview IDs are single-use and time-limited. On a version conflict, expired preview, or validation failure, stop, read again, and preview again; never retry an old preview_id. Every flow_apply_* call requires confirm=true.",
+  "Interface-document validation reports every discovered nested schema issue in one response; fix the complete list before making another preview call.",
   "script-interface-doc.v1 requires schema_version, title, summary, endpoint, request, responses, and logic_description. endpoint requires methods and description; request.query and request.headers are required arrays (use [] when empty); POST requires request.body and GET-only documents must omit it. JSON Patch supports at most 256 add/remove/replace/move/copy/test operations; preview responses show operation counts and paths, not merged documents.",
-  "Every query parameter and request header requires name, type, required, description, and example. Request bodies and responses require content_type=application/json, schema, and example; every response also requires status and description. Every JSON Schema node declares type, and object schemas and examples must cover each other.",
+  "Every query parameter and request header requires name, type, required, description, and example. Request bodies and responses require content_type=application/json, schema, and example; every response also requires status and description. Every root JSON Schema node declares type; every nested property, array item, and object-form additionalProperties node declares type, description, and example. Arrays must define items, fixed object properties must be covered by the complete example, and additionalProperties=true is reserved for opaque upstream JSON.",
   "Keep endpoint.path relative: omit it on create and use /flow/codeblock/<actual-script-id> on update. Public call URLs use the caller-provided domain plus /flow/codeblock/{{script_id}}; never put real tokens, passwords, cookies, or Authorization values in code, documents, examples, or URLs.",
   "Script input comes from input.query, input.header, input.body, and input.cookies; for immediate non-script POST /flow/codeblock, body.input becomes global input unchanged. Treat input as a reserved, read-only runtime binding: never declare, redeclare, rebind, or destructure a local binding named input in any scope, including function parameters and nested callbacks. Use an alias such as const payload = input when a local name is needed. Use top-level return by default; use a bare qf_output assignment only for event-style/asynchronous flows or when explicitly requested, never both.",
   "For every initial generation and every later revision in non-script mode, final delivery always includes the complete latest generated JavaScript, even after runtime verification; never return only a patch, diff, or partial snippet. Also include caller-facing invocation instructions, parameters/examples, logic, success/error examples, and execution_url. Script delivery omits JavaScript and raw interface_doc by default and includes invocation instructions, parameters/examples, logic, success/error examples, and the published script_url unless the user asks for source or raw documentation. Code and interface_doc remain internal preview/validation/publication inputs.",
@@ -28642,7 +28814,7 @@ function withApiErrors(handler) {
   };
 }
 var documentationFields = {
-  document: exports_external.unknown().optional().describe(`Normalized script-interface-doc.v1 JSON. Choose exactly one of document, raw_document, or document_patch; complete documents are required for saves and code updates. ${interfaceDocInputDescription}`),
+  document: interfaceDocToolInputSchema.optional().describe(`Normalized script-interface-doc.v1 JSON object. Choose exactly one of document, raw_document, or document_patch; complete documents are required for saves and code updates. ${interfaceDocInputDescription}`),
   raw_document: exports_external.string().optional().describe("JSON/OpenAPI document text for server parsing. Choose exactly one of document, raw_document, or document_patch; format=json parses JSON."),
   format: exports_external.literal("json").optional().describe("Format of raw_document; only json is supported."),
   document_patch: interfaceDocPatchSchema.optional().describe("RFC 6902 patch for an existing script only. Choose exactly one of document, raw_document, or document_patch."),
@@ -28655,7 +28827,7 @@ var changeSchema = exports_external.object({
   code_base64: exports_external.string().optional().describe("Non-empty Base64-encoded JavaScript, mutually exclusive with code."),
   description: exports_external.string().optional().describe("Script description. Can be updated without changing code."),
   ip_whitelist: exports_external.array(exports_external.string()).nullable().optional().describe("Source IP/CIDR allowlist. Omit on update to keep the current value; null or [] clears the restriction."),
-  interface_doc: exports_external.unknown().optional().describe(interfaceDocInputDescription),
+  interface_doc: interfaceDocToolInputSchema.optional().describe(interfaceDocInputDescription),
   interface_doc_patch: interfaceDocPatchSchema.optional().describe("RFC 6902 patch for update only; mutually exclusive with interface_doc and forbidden for create."),
   rollback_to_version: exports_external.number().int().positive().optional().describe("Historical version to restore. Use only as a standalone update and never with code, interface_doc, or interface_doc_patch."),
   expected_version: exports_external.number().int().positive().optional().describe("Required for update and must be the current_version from flow_get_script for concurrency protection; forbidden for create.")
@@ -28722,6 +28894,7 @@ function assertScriptChangeInput(input) {
     throw new Error("rollback_to_version cannot be combined with code, interface_doc, or interface_doc_patch");
   }
   if (input.interface_doc !== undefined) {
+    input.interface_doc = normalizeInterfaceDocument(input.interface_doc);
     assertCompleteInterfaceDoc(input.interface_doc, input.operation);
   }
   if (input.interface_doc_patch !== undefined)
@@ -28775,7 +28948,7 @@ function assertPreview(record3, operation) {
   return record3;
 }
 function createMcpServer({ api: api2, previews = new PreviewStore }) {
-  const server = new McpServer({ name: "flow-codeblock-rust", version: "0.1.9" }, { instructions: serverInstructions });
+  const server = new McpServer({ name: "flow-codeblock-rust", version: "0.1.10" }, { instructions: serverInstructions });
   server.registerTool("flow_write_code", {
     title: "Get the Flow JavaScript authoring contract",
     description: "Call this before writing or revising Flow Codeblock JavaScript. It returns the mode-specific authoring contract, including forbidden-identifier and reserved-input replacement rules, and never writes the database, publishes a script, or executes code. For every non_script generation or revision, always deliver the complete latest generated JavaScript plus execution_url, never only a patch or partial snippet; use script for persistent GET/POST /flow/codeblock/{{script_id}} code with a complete script-interface-doc.v1 for preview, validation, and publication. Script delivery includes invocation instructions, parameters/examples, logic, success/error examples, and script_url rather than source or raw interface_doc unless requested. Set base_url only when a caller-facing URL template is needed.",
@@ -28783,7 +28956,7 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
       mode: exports_external.enum(["non_script", "script"]).describe("Generation mode. Use non_script for immediate, non-persistent execution; use script for a persistent GET/POST endpoint or HTTP redirects."),
       requirement: exports_external.string().min(1).max(20000).describe("Complete business requirements, input fields, expected output, external APIs, synchronization/async needs, and error behavior. Include only requirements relevant to this code."),
       input_example: exports_external.unknown().optional().describe("Business input example. In script mode it helps generate request.body/schema/example; in non_script mode it supplies flow_execute_code test input. Never include real credentials."),
-      include_full_schema: exports_external.boolean().optional().describe("Whether to include the complete JSON Schema in the response; defaults to false. The generated interface document still contains all required fields."),
+      include_full_schema: exports_external.boolean().optional().describe("Whether to include the complete recursive JSON Schema in the response; defaults to true for script mode to avoid a follow-up schema call. Set false only when the caller already has the schema."),
       base_url: exports_external.string().url().refine((value) => {
         try {
           const parsed = new URL(value);
@@ -28794,7 +28967,7 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
       }, "base_url must be an http(s) URL without credentials or control characters").optional().describe("Optional caller service origin such as https://flow.example.com. Used only to render /flow/codeblock/{{script_id}}; credentials and control characters are forbidden.")
     }
   }, async ({ mode, requirement, input_example, include_full_schema, base_url }) => {
-    const context = codeWriterContext(mode, requirement, input_example, include_full_schema ?? false, base_url);
+    const context = codeWriterContext(mode, requirement, input_example, include_full_schema ?? mode === "script", base_url);
     return result(mode === "non_script" ? { ...context, execution_url: executionUrl(api2) } : context);
   });
   server.registerTool("flow_list_scripts", {
@@ -28856,6 +29029,7 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
   }, withApiErrors(async (input) => {
     const parsed = documentationSchema.parse(input);
     if (parsed.document !== undefined) {
+      parsed.document = normalizeInterfaceDocument(parsed.document);
       assertCompleteInterfaceDoc(parsed.document, "update");
     }
     if (parsed.document_patch !== undefined)
@@ -28956,6 +29130,8 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
     inputSchema: documentationSchema.shape
   }, withApiErrors(async (input) => {
     const parsed = documentationSchema.parse(input);
+    if (parsed.document !== undefined)
+      parsed.document = normalizeInterfaceDocument(parsed.document);
     const expectedVersion = await fetchCurrentVersion(api2, parsed.script_id);
     if (parsed.document_patch !== undefined && parsed.expected_version !== expectedVersion) {
       throw new Error(`Script version changed from ${parsed.expected_version} to ${expectedVersion}; read and preview again`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-codeblock-rust-mcp",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Flow Codeblock Rust+Bun stdio MCP Server for script management and execution.",
   "license": "MIT",
   "repository": {