@tokenlabai/mcp-server 0.6.5 → 0.6.7

package/README.md

@@ -10,7 +10,7 @@ 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.5 generates 76 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.7 generates 76 endpoint tools; two composite discovery tools are registered at runtime.
 
 | Profile | Endpoint tools | Coverage |
 | --- | ---: | --- |
@@ -126,7 +126,7 @@ This repository includes `server.json` for the official MCP Registry.
 
 Release metadata:
 
-- npm package: `@tokenlabai/mcp-server@0.6.5`
+- npm package: `@tokenlabai/mcp-server@0.6.7`
 - MCP registry name: `io.github.hedging8563/tokenlab`
 - `package.json.mcpName`: `io.github.hedging8563/tokenlab`
 

package/contract/openapi.json

@@ -757,7 +757,7 @@
                     "code": "seedance_material_preparing",
                     "param": "material_asset_id",
                     "auto_material_asset_ids": [
-                      "seedance_asset_auto123"
+                      "asset-20260720123456-auto1"
                     ]
                   }
                 }
@@ -845,7 +845,7 @@
                     "asset_name": "Front view",
                     "asset_type": "Image",
                     "library_type": "aigc_avatar",
-                    "group_id": "seedance_group_virtual_123"
+                    "group_id": "group-20260720123456-vrt01"
                   }
                 },
                 "real_person_asset": {
@@ -855,7 +855,7 @@
                     "asset_name": "Creator A close-up",
                     "asset_type": "Image",
                     "library_type": "liveness_face",
-                    "group_id": "seedance_group_real_123"
+                    "group_id": "group-20260720123456-real1"
                   }
                 }
               }
@@ -874,9 +874,9 @@
                   "asset_created": {
                     "summary": "Material asset accepted for processing",
                     "value": {
-                      "id": "seedance_asset_123",
+                      "id": "asset-20260720123456-qn7wr",
                       "object": "seedance.material_asset",
-                      "group_id": "seedance_group_virtual_123",
+                      "group_id": "group-20260720123456-vrt01",
                       "library_type": "aigc_avatar",
                       "asset_name": "Front view",
                       "asset_type": "Image",
@@ -993,9 +993,9 @@
                     "value": {
                       "assets": [
                         {
-                          "id": "seedance_asset_123",
+                          "id": "asset-20260720123456-qn7wr",
                           "object": "seedance.material_asset",
-                          "group_id": "seedance_group_virtual_123",
+                          "group_id": "group-20260720123456-vrt01",
                           "library_type": "aigc_avatar",
                           "asset_name": "Front view",
                           "asset_type": "Image",
@@ -1141,7 +1141,7 @@
                           "status": "bound",
                           "verification_status": "succeeded",
                           "result_code": "10000",
-                          "group_id": "seedance_group_real_123",
+                          "group_id": "group-20260720123456-real1",
                           "group_name": "Creator A",
                           "error_message": null,
                           "created_at": 1782998400000,
@@ -1213,9 +1213,9 @@
                     "summary": "Real-person material group bound",
                     "value": {
                       "object": "seedance.visual_validation_result",
-                      "group_id": "seedance_group_real_123",
+                      "group_id": "group-20260720123456-real1",
                       "material_group": {
-                        "id": "seedance_group_real_123",
+                        "id": "group-20260720123456-real1",
                         "library_type": "liveness_face",
                         "status": "ACTIVE",
                         "group_name": "Creator A"
@@ -1267,7 +1267,7 @@
             "schema": {
               "type": "string"
             },
-            "example": "seedance_asset_123"
+            "example": "asset-20260720123456-qn7wr"
           }
         ],
         "responses": {
@@ -1282,9 +1282,9 @@
                   "asset": {
                     "summary": "Material asset",
                     "value": {
-                      "id": "seedance_asset_123",
+                      "id": "asset-20260720123456-qn7wr",
                       "object": "seedance.material_asset",
-                      "group_id": "seedance_group_virtual_123",
+                      "group_id": "group-20260720123456-vrt01",
                       "library_type": "aigc_avatar",
                       "asset_name": "Front view",
                       "asset_type": "Image",
@@ -1329,7 +1329,7 @@
             "schema": {
               "type": "string"
             },
-            "example": "seedance_asset_123"
+            "example": "asset-20260720123456-qn7wr"
           }
         ],
         "requestBody": {
@@ -1365,9 +1365,9 @@
                   "asset_updated": {
                     "summary": "Material asset updated",
                     "value": {
-                      "id": "seedance_asset_123",
+                      "id": "asset-20260720123456-qn7wr",
                       "object": "seedance.material_asset",
-                      "group_id": "seedance_group_virtual_123",
+                      "group_id": "group-20260720123456-vrt01",
                       "library_type": "aigc_avatar",
                       "asset_name": "Front view approved",
                       "asset_type": "Image",
@@ -1418,7 +1418,7 @@
             "schema": {
               "type": "string"
             },
-            "example": "seedance_asset_123"
+            "example": "asset-20260720123456-qn7wr"
           }
         ],
         "responses": {
@@ -1434,7 +1434,7 @@
                     "summary": "Material asset deleted",
                     "value": {
                       "deleted": true,
-                      "id": "seedance_asset_123"
+                      "id": "asset-20260720123456-qn7wr"
                     }
                   }
                 }
@@ -5584,7 +5584,7 @@
                   "group_created": {
                     "summary": "Material group created",
                     "value": {
-                      "id": "seedance_group_virtual_123",
+                      "id": "group-20260720123456-vrt01",
                       "object": "seedance.material_asset_group",
                       "library_type": "aigc_avatar",
                       "group_name": "Product references",
@@ -5689,7 +5689,7 @@
                     "value": {
                       "groups": [
                         {
-                          "id": "seedance_group_virtual_123",
+                          "id": "group-20260720123456-vrt01",
                           "object": "seedance.material_asset_group",
                           "library_type": "aigc_avatar",
                           "group_name": "Product references",
@@ -5699,7 +5699,7 @@
                           "created_at": 1782998400000
                         },
                         {
-                          "id": "seedance_group_real_123",
+                          "id": "group-20260720123456-real1",
                           "object": "seedance.material_asset_group",
                           "library_type": "liveness_face",
                           "group_name": "Creator A",
@@ -5744,7 +5744,7 @@
             "schema": {
               "type": "string"
             },
-            "example": "seedance_group_virtual_123"
+            "example": "group-20260720123456-vrt01"
           }
         ],
         "responses": {
@@ -5759,7 +5759,7 @@
                   "group": {
                     "summary": "Material group",
                     "value": {
-                      "id": "seedance_group_virtual_123",
+                      "id": "group-20260720123456-vrt01",
                       "object": "seedance.material_asset_group",
                       "library_type": "aigc_avatar",
                       "group_name": "Product references",
@@ -5802,7 +5802,7 @@
             "schema": {
               "type": "string"
             },
-            "example": "seedance_group_virtual_123"
+            "example": "group-20260720123456-vrt01"
           }
         ],
         "requestBody": {
@@ -5836,7 +5836,7 @@
                   "group_updated": {
                     "summary": "Material group updated",
                     "value": {
-                      "id": "seedance_group_virtual_123",
+                      "id": "group-20260720123456-vrt01",
                       "object": "seedance.material_asset_group",
                       "library_type": "aigc_avatar",
                       "group_name": "Updated references",
@@ -5882,7 +5882,7 @@
             "schema": {
               "type": "string"
             },
-            "example": "seedance_group_virtual_123"
+            "example": "group-20260720123456-vrt01"
           }
         ],
         "responses": {
@@ -5898,7 +5898,7 @@
                     "summary": "Material group deleted",
                     "value": {
                       "deleted": true,
-                      "id": "seedance_group_virtual_123"
+                      "id": "group-20260720123456-vrt01"
                     }
                   }
                 }
@@ -7289,7 +7289,7 @@
               "opaque",
               "auto"
             ],
-            "description": "Background handling for compatible image generation flows such as gpt-image-2 text-to-image. Not supported for gpt-image-2 image edits."
+            "description": "Background handling for compatible image flows. For gpt-image-2 generation and edits, accepted values are auto and opaque; transparent is not supported. Other models may support different values."
           },
           "output_format": {
             "type": "string",
@@ -7722,7 +7722,7 @@
           "image_url": {
             "type": "string",
             "format": "uri",
-            "description": "Publicly reachable image URL for image-to-video generation. Preferred over inline base64 in production. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
+            "description": "Publicly reachable image URL for image-to-video generation, or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab Seedance material used as the first frame. Preferred over inline base64 in production. TokenLab verifies material ownership. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
           },
           "video_url": {
             "type": "string",
@@ -7792,11 +7792,11 @@
           },
           "start_image": {
             "type": "string",
-            "description": "First frame image input for start-end-to-video flows. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
+            "description": "First frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
           },
           "end_image": {
             "type": "string",
-            "description": "Last frame image input for start-end-to-video flows. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
+            "description": "Last frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
           },
           "user": {
             "type": "string",
@@ -7852,7 +7852,7 @@
           },
           "reference_images": {
             "type": "array",
-            "description": "Canonical public reference-image field for reference-to-video conditioning. This endpoint currently allows up to 9 URLs or compatible data URLs; model-specific limits can be lower. xAI grok-imagine-video accepts up to 7 image references with duration capped at 10 seconds; grok-imagine-video-1.5 and grok-imagine-video-1.5-preview are image-to-video only and do not accept reference images. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.",
+            "description": "Canonical public reference-image field for reference-to-video conditioning. This endpoint currently allows up to 9 URLs, compatible data URLs, or for Seedance, asset://asset-YYYYMMDDHHMMSS-xxxxx URIs for ACTIVE TokenLab materials owned by the requesting organization; model-specific limits can be lower. xAI grok-imagine-video accepts up to 7 image references with duration capped at 10 seconds; grok-imagine-video-1.5 and grok-imagine-video-1.5-preview are image-to-video only and do not accept reference images. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.",
             "minItems": 1,
             "maxItems": 9,
             "items": {
@@ -7861,7 +7861,7 @@
           },
           "material_asset_id": {
             "type": "string",
-            "description": "TokenLab Seedance material asset ID returned by /v1/videos/assets, by automatic image preparation, or by a real-person verification bind flow. Use it after the asset is ACTIVE with Seedance models that can use the TokenLab material library. The asset must belong to the current account."
+            "description": "TokenLab Seedance material asset ID returned by /v1/videos/assets, by automatic image preparation, or by a real-person verification bind flow. Use it after the asset is ACTIVE with Seedance models that can use the TokenLab material library. The asset must belong to the current account. This field is a generic reference input; to assign first-frame, last-frame, or reference-image semantics explicitly, put asset://<material_asset_id> in start_image, end_image, or reference_images."
           },
           "material_asset_ids": {
             "type": "array",
@@ -12440,7 +12440,7 @@
                 "additionalProperties": true
               }
             ],
-            "description": "Image URL. The object form {\"url\":\"https://...\"} matches the official request shape; a plain string is accepted for convenience."
+            "description": "Image reference. The object form {\"url\":\"https://...\"} matches the official request shape; a plain string is accepted for convenience. TokenLab also accepts asset://asset-YYYYMMDDHHMMSS-xxxxx URIs for ACTIVE materials owned by the requesting organization, and preserves the item's first_frame, last_frame, or reference_image role."
           },
           "video_url": {
             "oneOf": [
@@ -12528,6 +12528,12 @@
               "$ref": "#/components/schemas/VolcSeedanceContentItem"
             }
           },
+          "material_asset_id": {
+            "type": "string",
+            "pattern": "^asset-\\d{14}-[a-z0-9]{5}$",
+            "maxLength": 128,
+            "description": "TokenLab compatibility shorthand for one ACTIVE Seedance material owned by the requesting organization. It is treated as the first frame and cannot be combined with other media inputs. For multiple materials, use content image_url items with explicit roles; top-level material_asset_ids is rejected as ambiguous."
+          },
           "ratio": {
             "type": "string",
             "enum": [

package/generated/public-contract.json

@@ -5,7 +5,7 @@
     "id": "tokenlab-mcp-server",
     "name": "@tokenlabai/mcp-server",
     "title": "TokenLab MCP Server",
-    "version": "0.6.5",
+    "version": "0.6.7",
     "registry_name": "io.github.hedging8563/tokenlab",
     "source_url": "https://github.com/hedging8563/tokenlab-mcp-server",
     "landing_url": "https://tokenlab.sh/mcp",
@@ -25,8 +25,8 @@
     "openapi": "3.0.3",
     "title": "TokenLab AI Gateway",
     "version": "1.0.0",
-    "sha256": "b74ba0927ad8a227fe200bca76441345adc5b36649f5a7f6a150c824626d99d6",
-    "tool_manifest_sha256": "62a3ca62dbe71ffa06e558f7b023f0a4ce6fbe0c2406dc31250cd320608ffb61"
+    "sha256": "b97e2566a0ee162a76bf3036e53e124cc7555d0efe51bd38e17894baf7124152",
+    "tool_manifest_sha256": "020115866467dcabae35643182b950b59ec533eb6346e887ec5046cf2d021423"
   },
   "profiles": {
     "catalog": {

package/generated/tools.json

@@ -6,7 +6,7 @@
     "openapi": "3.0.3",
     "title": "TokenLab AI Gateway",
     "version": "1.0.0",
-    "sha256": "b74ba0927ad8a227fe200bca76441345adc5b36649f5a7f6a150c824626d99d6"
+    "sha256": "b97e2566a0ee162a76bf3036e53e124cc7555d0efe51bd38e17894baf7124152"
   },
   "default_profile": "core",
   "profiles": [
@@ -2301,7 +2301,7 @@
               "opaque",
               "auto"
             ],
-            "description": "Background handling for compatible image generation flows such as gpt-image-2 text-to-image. Not supported for gpt-image-2 image edits."
+            "description": "Background handling for compatible image flows. For gpt-image-2 generation and edits, accepted values are auto and opaque; transparent is not supported. Other models may support different values."
           },
           "output_format": {
             "type": "string",
@@ -3484,7 +3484,7 @@
           "image_url": {
             "type": "string",
             "format": "uri",
-            "description": "Publicly reachable image URL for image-to-video generation. Preferred over inline base64 in production. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
+            "description": "Publicly reachable image URL for image-to-video generation, or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab Seedance material used as the first frame. Preferred over inline base64 in production. TokenLab verifies material ownership. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
           },
           "video_url": {
             "type": "string",
@@ -3554,11 +3554,11 @@
           },
           "start_image": {
             "type": "string",
-            "description": "First frame image input for start-end-to-video flows. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
+            "description": "First frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
           },
           "end_image": {
             "type": "string",
-            "description": "Last frame image input for start-end-to-video flows. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
+            "description": "Last frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path."
           },
           "user": {
             "type": "string",
@@ -3614,7 +3614,7 @@
           },
           "reference_images": {
             "type": "array",
-            "description": "Canonical public reference-image field for reference-to-video conditioning. This endpoint currently allows up to 9 URLs or compatible data URLs; model-specific limits can be lower. xAI grok-imagine-video accepts up to 7 image references with duration capped at 10 seconds; grok-imagine-video-1.5 and grok-imagine-video-1.5-preview are image-to-video only and do not accept reference images. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.",
+            "description": "Canonical public reference-image field for reference-to-video conditioning. This endpoint currently allows up to 9 URLs, compatible data URLs, or for Seedance, asset://asset-YYYYMMDDHHMMSS-xxxxx URIs for ACTIVE TokenLab materials owned by the requesting organization; model-specific limits can be lower. xAI grok-imagine-video accepts up to 7 image references with duration capped at 10 seconds; grok-imagine-video-1.5 and grok-imagine-video-1.5-preview are image-to-video only and do not accept reference images. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.",
             "minItems": 1,
             "maxItems": 9,
             "items": {
@@ -3623,7 +3623,7 @@
           },
           "material_asset_id": {
             "type": "string",
-            "description": "TokenLab Seedance material asset ID returned by /v1/videos/assets, by automatic image preparation, or by a real-person verification bind flow. Use it after the asset is ACTIVE with Seedance models that can use the TokenLab material library. The asset must belong to the current account."
+            "description": "TokenLab Seedance material asset ID returned by /v1/videos/assets, by automatic image preparation, or by a real-person verification bind flow. Use it after the asset is ACTIVE with Seedance models that can use the TokenLab material library. The asset must belong to the current account. This field is a generic reference input; to assign first-frame, last-frame, or reference-image semantics explicitly, put asset://<material_asset_id> in start_image, end_image, or reference_images."
           },
           "material_asset_ids": {
             "type": "array",
@@ -3927,7 +3927,7 @@
                       "additionalProperties": true
                     }
                   ],
-                  "description": "Image URL. The object form {\"url\":\"https://...\"} matches the official request shape; a plain string is accepted for convenience."
+                  "description": "Image reference. The object form {\"url\":\"https://...\"} matches the official request shape; a plain string is accepted for convenience. TokenLab also accepts asset://asset-YYYYMMDDHHMMSS-xxxxx URIs for ACTIVE materials owned by the requesting organization, and preserves the item's first_frame, last_frame, or reference_image role."
                 },
                 "video_url": {
                   "oneOf": [
@@ -3997,6 +3997,12 @@
               "additionalProperties": true
             }
           },
+          "material_asset_id": {
+            "type": "string",
+            "pattern": "^asset-\\d{14}-[a-z0-9]{5}$",
+            "maxLength": 128,
+            "description": "TokenLab compatibility shorthand for one ACTIVE Seedance material owned by the requesting organization. It is treated as the first frame and cannot be combined with other media inputs. For multiple materials, use content image_url items with explicit roles; top-level material_asset_ids is rejected as ambiguous."
+          },
           "ratio": {
             "type": "string",
             "enum": [
@@ -4112,6 +4118,7 @@
         "body": [
           "model",
           "content",
+          "material_asset_id",
           "ratio",
           "duration",
           "resolution",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenlabai/mcp-server",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "OpenAPI-generated TokenLab MCP server with catalog, native AI, multimodal, resource, prompt, and async task support.",
   "type": "module",
   "engines": {