@tokenlabai/mcp-server 0.6.13 → 0.6.15

package/README.md

@@ -10,24 +10,27 @@ It exposes public catalog tools for agents that need to choose models, inspect s
 
 ## Generated Tool Profiles
 
-The checked-in `generated/tools.json` manifest is generated from TokenLab's public OpenAPI document plus the small MCP-only overlay in `contract/mcp-overlay.json`. Version 0.6.13 generates 78 endpoint tools; two composite discovery tools are registered at runtime.
+The checked-in `generated/tools.json` manifest is generated from TokenLab's public OpenAPI document plus the small MCP-only overlay in `contract/mcp-overlay.json`. Version 0.6.15 generates 78 endpoint tools; two composite discovery tools are registered at runtime.
 
-| Profile | Endpoint tools | Coverage |
-| --- | ---: | --- |
-| `catalog` | 4 | Public model discovery and pricing only; no API key required |
-| `core` (default) | 29 | Catalog and pricing; Chat Completions, Responses, Anthropic Messages, Gemini generateContent; images, video, music, 3D, speech and transcription; async tasks; files; embeddings, rerank, and translation |
-| `full` | 78 | Every allowlisted developer API operation in the checked-in OpenAPI snapshot, including core plus response lifecycle, batches, worlds, and native model discovery |
+| Profile | Endpoint tools | Model-facing schema | Coverage |
+| --- | ---: | --- | --- |
+| `catalog` | 4 | Exact | Public model discovery and pricing only; no API key required |
+| `core` (default) | 29 | Portable | Catalog and pricing; Chat Completions, Responses, Anthropic Messages, Gemini generateContent; images, video, music, 3D, speech and transcription; async tasks; files; embeddings, rerank, and translation |
+| `full` | 78 | Portable | Every allowlisted developer API operation in the checked-in OpenAPI snapshot, including core plus response lifecycle, batches, worlds, and native model discovery |
 
-All profiles also include `compare_models` and `get_api_overview`, producing totals of 6, 31, and 80 tools. Realtime and streaming-only operations are excluded because stdio MCP tool calls return one final result. API operations that accept `stream` constrain it to `false` in the MCP overlay, and the Gemini query-string API key is intentionally hidden from tool arguments.
+All profiles also include `compare_models` and `get_api_overview`, producing totals of 6, 31, and 80 tools. Realtime and streaming-only operations are excluded because stdio MCP tool calls return one final result. API operations that accept `stream` fix it internally to `false` without exposing a boolean `const` to provider adapters, and the Gemini query-string API key is intentionally hidden from tool arguments.
 
-Set `TOKENLAB_MCP_TOOL_PROFILE=catalog` for the smallest public-only tool list or `TOKENLAB_MCP_TOOL_PROFILE=full` for the broad developer API. Tool names, descriptions, input JSON Schemas, HTTP bindings, content types, auth requirements, and task behavior can be inspected in [`generated/tools.json`](./generated/tools.json).
+The portable projection keeps every top-level argument but bounds deeply nested model-facing shapes. The server still validates calls against the complete generated OpenAPI schema before issuing an API request. Compatibility budgets keep `core` at no more than 60 KB and depth 8, and `full` at no more than 100 KB and depth 8 for the complete `tools/list` response. Tests also run the full profile through the Google AI SDK version used by the observed OpenCode/Gemini failure.
+
+Set `TOKENLAB_MCP_TOOL_PROFILE=catalog` for the smallest public-only tool list or `TOKENLAB_MCP_TOOL_PROFILE=full` for the broad developer API. Set `TOKENLAB_MCP_SCHEMA_MODE=exact` only when a client needs the complete nested JSON Schema and can accept its larger/deeper tool payload. Use `strict` for providers that require every property to be listed in `required` and every object to set `additionalProperties: false`; complex top-level arguments are represented as JSON-encoded strings and decoded before canonical validation. Canonical tool names, descriptions, input JSON Schemas, HTTP bindings, content types, auth requirements, and task behavior can be inspected in [`generated/tools.json`](./generated/tools.json).
 
 The smaller [`generated/public-contract.json`](./generated/public-contract.json) is the machine-readable projection used by TokenLab's website and other public consumers. It contains package identity, profile counts, core tool layers, resources, prompts, and source hashes without copying all endpoint schemas.
 
 ## Native MCP Features
 
 - JSON tool responses include `structuredContent` while retaining serialized text for older clients.
-- Generated tools expose human-readable titles, standard read-only/destructive/idempotent/open-world annotations, auth/profile metadata, and response request IDs when available.
+- Generated tools expose human-readable titles, standard read-only/destructive/idempotent/open-world annotations, and response request IDs when available.
+- Tool schemas are published and validated directly as JSON Schema. The runtime does not round-trip generated tool schemas through Zod; `exact` mode is byte-shape equivalent to the generated canonical schema.
 - Three resources expose the live API overview, the package's OpenAPI snapshot, and the compact MCP public contract.
 - `choose_tokenlab_model` and `build_tokenlab_request` prompts guide agents to use live model truth and preserve native endpoint shapes.
 - Server instructions tell clients to confirm billable or destructive operations and treat external model/API output as untrusted content.
@@ -103,6 +106,7 @@ Use `delivery.mode` instead of assuming all image requests are synchronous. For
 - `TOKENLAB_API_BASE`: optional, defaults to `https://api.tokenlab.sh`
 - `TOKENLAB_API_KEY`: optional; required for text inference, multimodal generation, async task, embedding, rerank, and translation tools
 - `TOKENLAB_MCP_TOOL_PROFILE`: optional, `catalog`, `core` (default), or `full`
+- `TOKENLAB_MCP_SCHEMA_MODE`: optional, `portable`, `exact`, or `strict`; defaults to the selected profile's tested mode
 - `TOKENLAB_REQUEST_TIMEOUT_MS`: optional request timeout in milliseconds, defaults to `120000`
 - `TOKENLAB_MCP_MAX_FILE_BYTES`: optional maximum local upload size per file, defaults to `104857600` (100 MiB)
 - `TOKENLAB_MCP_INLINE_BYTES`: optional maximum binary/JSON response size returned inline, defaults to `2097152` (2 MiB)
@@ -118,7 +122,7 @@ The public OpenAPI document is the API contract source. The overlay contains onl
 npm run contract:source-check # compare the snapshot with the live canonical OpenAPI (read-only)
 npm run contract:check        # check generated output against the checked-in snapshot (offline)
 npm run contract:sync         # fetch OpenAPI and regenerate; refuses dirty outputs or a stale branch
-npm test                      # compile profiles and test routing, tasks, files, and binary output
+npm test                      # compile profiles and test exact/portable/strict schemas, provider conversion, routing, tasks, files, and binary output
 ```
 
 Always run `git pull --ff-only` before a manual contract sync. `contract:check` proves internal consistency only; `contract:source-check` proves freshness against the canonical source. The scheduled `Sync TokenLab OpenAPI contract` workflow runs the full write sequence and commits only the verified OpenAPI snapshot and generated manifest to `main`. A failed fetch, stale local branch, dirty generated output, generation error, schema compilation error, or test leaves the tracked contract unchanged.
@@ -129,7 +133,7 @@ This repository includes `server.json` for the official MCP Registry.
 
 Release metadata:
 
-- npm package: `@tokenlabai/mcp-server@0.6.13`
+- npm package: `@tokenlabai/mcp-server@0.6.15`
 - MCP registry name: `io.github.hedging8563/tokenlab`
 - `package.json.mcpName`: `io.github.hedging8563/tokenlab`
 

package/contract/mcp-overlay.json

@@ -4,6 +4,13 @@
   "default_profile": "core",
   "profiles": {
     "catalog": {
+      "schema_mode": "exact",
+      "compatibility_budget": {
+        "max_endpoint_tools": 4,
+        "max_input_schema_bytes": 2000,
+        "max_input_schema_depth": 4,
+        "max_tools_list_bytes": 6000
+      },
       "operations": [
         "listModels",
         "getModel",
@@ -12,6 +19,13 @@
       ]
     },
     "core": {
+      "schema_mode": "portable",
+      "compatibility_budget": {
+        "max_endpoint_tools": 29,
+        "max_input_schema_bytes": 48000,
+        "max_input_schema_depth": 8,
+        "max_tools_list_bytes": 60000
+      },
       "operations": [
         "listModels",
         "getModel",
@@ -43,6 +57,13 @@
       ]
     },
     "full": {
+      "schema_mode": "portable",
+      "compatibility_budget": {
+        "max_endpoint_tools": 78,
+        "max_input_schema_bytes": 72000,
+        "max_input_schema_depth": 8,
+        "max_tools_list_bytes": 100000
+      },
       "include_tags": [
         "Chat",
         "Embeddings",
@@ -229,13 +250,15 @@
         "openWorldHint": true
       }
     },
+    "compactResponse": {
+      "fixed_arguments": {
+        "stream": false
+      }
+    },
     "createAnthropicMessage": {
       "tool_name": "create_anthropic_message",
-      "input_property_overrides": {
-        "stream": {
-          "const": false,
-          "description": "MCP tool calls return one final result; omit stream or set it to false."
-        }
+      "fixed_arguments": {
+        "stream": false
       }
     },
     "geminiGenerateContent": {
@@ -244,19 +267,18 @@
     },
     "createChatCompletion": {
       "description": "Create an OpenAI-compatible chat completion. For inline image_url data URLs, declare the byte-accurate image MIME type. The MCP boundary corrects recognized PNG, JPEG, WebP, and GIF payloads declared as application/octet-stream and rejects unrecognized generic binary image payloads before sending a billable request.",
-      "input_property_overrides": {
-        "stream": {
-          "const": false,
-          "description": "MCP tool calls return one final result; omit stream or set it to false."
-        }
+      "fixed_arguments": {
+        "stream": false
       }
     },
     "createResponse": {
-      "input_property_overrides": {
-        "stream": {
-          "const": false,
-          "description": "MCP tool calls return one final result; omit stream or set it to false."
-        }
+      "fixed_arguments": {
+        "stream": false
+      }
+    },
+    "retrieveResponse": {
+      "fixed_arguments": {
+        "stream": false
       }
     },
     "getAsyncTask": {
@@ -294,11 +316,8 @@
         "application/json": "create_image",
         "multipart/form-data": "create_image_file"
       },
-      "input_property_overrides": {
-        "stream": {
-          "const": false,
-          "description": "Image streaming is not exposed through MCP tool calls; omit stream or set it to false."
-        }
+      "fixed_arguments": {
+        "stream": false
       },
       "task": {
         "mode": "hybrid",
@@ -314,11 +333,8 @@
         "application/json": "edit_image",
         "multipart/form-data": "edit_image_file"
       },
-      "input_property_overrides": {
-        "stream": {
-          "const": false,
-          "description": "Image streaming is not exposed through MCP tool calls; omit stream or set it to false."
-        }
+      "fixed_arguments": {
+        "stream": false
       },
       "task": {
         "mode": "hybrid",

package/contract/openapi.json

@@ -832,7 +832,7 @@
           "Video"
         ],
         "summary": "Create Seedance material asset",
-        "description": "Uploads one Seedance material asset URL into a TokenLab material group. Real-person assets require the group_id mapped from Result.GroupId returned by GetVisualValidateResult.",
+        "description": "Uploads one Seedance material asset URL into a TokenLab material group. Image materials must use supported dimensions; an invalid source is rejected with 400 seedance_material_source_invalid instead of remaining in PROCESSING. Real-person assets require the group_id mapped from Result.GroupId returned by GetVisualValidateResult.",
         "operationId": "createSeedanceMaterialAsset",
         "requestBody": {
           "required": true,
@@ -1195,8 +1195,39 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "409": {
+            "description": "Material asset is still processing or has failed without an active replica",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "The stored material source failed permanent validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                },
+                "example": {
+                  "error": {
+                    "message": "Image width must be between 300px and 6000px.",
+                    "type": "invalid_request_error",
+                    "code": "seedance_material_source_invalid",
+                    "param": "asset_url"
+                  }
+                }
+              }
+            }
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
+          },
+          "503": {
+            "$ref": "#/components/responses/MaterialLibraryUnavailable"
           }
         },
         "security": [
@@ -8801,7 +8832,8 @@
           },
           "error_message": {
             "type": "string",
-            "nullable": true
+            "nullable": true,
+            "description": "Public-safe terminal processing error. Permanent source validation failures include the rejected dimension constraint."
           },
           "metadata": {
             "type": "object",

package/generated/public-contract.json

@@ -5,7 +5,7 @@
     "id": "tokenlab-mcp-server",
     "name": "@tokenlabai/mcp-server",
     "title": "TokenLab MCP Server",
-    "version": "0.6.13",
+    "version": "0.6.15",
     "registry_name": "io.github.hedging8563/tokenlab",
     "source_url": "https://github.com/hedging8563/tokenlab-mcp-server",
     "landing_url": "https://tokenlab.sh/mcp",
@@ -18,22 +18,26 @@
       "@tokenlabai/mcp-server"
     ],
     "api_key_environment_variable": "TOKENLAB_API_KEY",
-    "tool_profile_environment_variable": "TOKENLAB_MCP_TOOL_PROFILE"
+    "tool_profile_environment_variable": "TOKENLAB_MCP_TOOL_PROFILE",
+    "tool_schema_mode_environment_variable": "TOKENLAB_MCP_SCHEMA_MODE"
   },
   "source": {
     "url": "https://docs.tokenlab.sh/openapi.json",
     "openapi": "3.0.3",
     "title": "TokenLab AI Gateway",
     "version": "1.0.0",
-    "sha256": "01b575d702e9fc955085f089e850de7caca46708fd6e482bf5749224ff6e7d21",
-    "tool_manifest_sha256": "63c82f9e26c9694bed568e6f73c53ae90e5d166f36575d05004eb1d0594486bb"
+    "sha256": "85963db54cafb169aaf6e9c28bf200cc217f59a9d457ed61fe80ba7047d1d511",
+    "tool_manifest_sha256": "77536f77ea5ec73b1dba72758be2374f2d7ad1943b5cf066c246269aeeeb54b5"
   },
   "profiles": {
     "catalog": {
       "is_default": false,
+      "schema_mode": "exact",
       "endpoint_tools": 4,
       "composite_tools": 2,
       "total_tools": 6,
+      "input_schema_bytes": 1553,
+      "max_input_schema_depth": 4,
       "tool_names": [
         "compare_models",
         "get_api_overview",
@@ -45,9 +49,12 @@
     },
     "core": {
       "is_default": true,
+      "schema_mode": "portable",
       "endpoint_tools": 29,
       "composite_tools": 2,
       "total_tools": 31,
+      "input_schema_bytes": 44738,
+      "max_input_schema_depth": 8,
       "tool_names": [
         "cancel_task",
         "compare_models",
@@ -84,9 +91,12 @@
     },
     "full": {
       "is_default": false,
+      "schema_mode": "portable",
       "endpoint_tools": 78,
       "composite_tools": 2,
       "total_tools": 80,
+      "input_schema_bytes": 69847,
+      "max_input_schema_depth": 8,
       "tool_names": [
         "cancel_anthropic_message_batch",
         "cancel_batch",