@tokenlabai/mcp-server 0.4.2 → 0.5.0

package/README.md

@@ -4,22 +4,33 @@
 [![npm](https://img.shields.io/npm/v/%40tokenlabai%2Fmcp-server)](https://www.npmjs.com/package/@tokenlabai/mcp-server)
 [![npm downloads](https://img.shields.io/npm/dm/%40tokenlabai%2Fmcp-server)](https://www.npmjs.com/package/@tokenlabai/mcp-server)
 
-OpenAPI-generated Model Context Protocol server for TokenLab public model discovery, pricing, native LLM endpoints, multimodal generation, async tasks, files, embeddings, rerank, translation, and the broader developer API.
+OpenAPI-generated Model Context Protocol server for TokenLab public model discovery, pricing, native LLM endpoints, multimodal generation, async tasks, files, embeddings, rerank, translation, resources, prompts, and the broader developer API.
 
 It exposes public catalog tools for agents that need to choose models, inspect supported request formats, or compare pricing before calling TokenLab APIs. Credentialed tools cover text inference, image generation and editing, video, music, 3D, async task polling, embeddings, rerank, and text translation.
 
 ## 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.4.2 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.5.0 generates 76 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` | 76 | Every allowlisted developer API operation in the checked-in OpenAPI snapshot, including core plus response lifecycle, batches, worlds, and native model discovery |
 
-Both profiles also include `compare_models` and `get_api_overview`. 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 78 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.
 
-Set `TOKENLAB_MCP_TOOL_PROFILE=full` to expose the full profile. 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).
+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 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.
+- 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.
 
 ## Run
 
@@ -91,7 +102,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, `core` (default) or `full`
+- `TOKENLAB_MCP_TOOL_PROFILE`: optional, `catalog`, `core` (default), or `full`
 - `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)
@@ -99,7 +110,7 @@ Use `delivery.mode` instead of assuming all image requests are synchronous. For
 
 ## Contract Sync
 
-The public OpenAPI document is the API contract source. The overlay contains only MCP-specific choices: profile exposure, stable tool aliases, secret omission, non-streaming constraints, content-type variants, and async task semantics.
+The public OpenAPI document is the API contract source. The overlay contains only MCP-specific choices: profile exposure, stable tool aliases, secret omission, non-streaming constraints, content-type variants, async task semantics, and the compact public projection consumed by the website and docs gates.
 
 ```bash
 npm run contract:sync      # fetch OpenAPI and regenerate the manifest
@@ -115,21 +126,25 @@ This repository includes `server.json` for the official MCP Registry.
 
 Release metadata:
 
-- npm package: `@tokenlabai/mcp-server@0.4.2`
+- npm package: `@tokenlabai/mcp-server@0.5.0`
 - MCP registry name: `io.github.hedging8563/tokenlab`
 - `package.json.mcpName`: `io.github.hedging8563/tokenlab`
 
 For a new release:
 
 1. Bump the matching versions in `package.json`, `package-lock.json`, and `server.json`.
-2. Push a matching tag such as `v0.4.2`.
+2. Push a matching tag such as `v0.5.0`.
 3. The publish workflow tests and publishes npm through trusted publishing, then publishes the MCP Registry entry through GitHub Actions OIDC.
 
 The same workflow can be run manually from `main` to republish only the current MCP Registry metadata. No npm or MCP Registry token is stored in GitHub.
 
+## Security
+
+Use the `catalog` profile when no credentialed tools are needed. Keep `TOKENLAB_API_KEY` in the local MCP client's secret environment, enable human confirmation for billable and destructive calls, and review tool annotations before granting persistent approval. Do not send a TokenLab API key to an untrusted hosted MCP server.
+
 ## Links
 
-- Website: https://tokenlab.sh
+- Website: https://tokenlab.sh/mcp
 - Docs: https://docs.tokenlab.sh
 - OpenAPI: https://docs.tokenlab.sh/openapi.json
 - Model catalog: https://api.tokenlab.sh/v1/models

package/contract/mcp-overlay.json

@@ -3,6 +3,14 @@
   "openapi_url": "https://docs.tokenlab.sh/openapi.json",
   "default_profile": "core",
   "profiles": {
+    "catalog": {
+      "operations": [
+        "listModels",
+        "getModel",
+        "getModelPricing",
+        "getPricing"
+      ]
+    },
     "core": {
       "operations": [
         "listModels",
@@ -57,6 +65,96 @@
       ]
     }
   },
+  "public_contract": {
+    "landing_url": "https://tokenlab.sh/mcp",
+    "docs_url": "https://docs.tokenlab.sh/integrations/tokenlab-mcp-server",
+    "recommended_client_name": "tokenlab",
+    "composite_tools": [
+      {
+        "name": "compare_models",
+        "profiles": ["catalog", "core", "full"],
+        "auth": "optional",
+        "annotations": {
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true
+        }
+      },
+      {
+        "name": "get_api_overview",
+        "profiles": ["catalog", "core", "full"],
+        "auth": "optional",
+        "annotations": {
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true
+        }
+      }
+    ],
+    "core_tool_layers": [
+      {
+        "id": "discover",
+        "authentication": "none",
+        "tool_rows": [
+          ["list_models", "get_model", "get_pricing"],
+          ["get_model_pricing", "compare_models", "get_api_overview"]
+        ]
+      },
+      {
+        "id": "create",
+        "authentication": "api_key",
+        "tool_rows": [
+          ["create_chat_completion", "create_response", "create_anthropic_message", "create_gemini_content"],
+          ["create_image", "create_image_file", "edit_image", "edit_image_file"],
+          ["create_video", "create_music", "create_3d_model", "create_speech", "transcribe_audio", "translate_audio"]
+        ]
+      },
+      {
+        "id": "operate",
+        "authentication": "api_key",
+        "tool_rows": [
+          ["upload_file", "list_files", "retrieve_file"],
+          ["retrieve_file_content", "delete_file", "get_task_status", "cancel_task"],
+          ["create_embedding", "create_multimodal_embedding", "rerank_documents", "translate_text"]
+        ]
+      }
+    ],
+    "resources": [
+      {
+        "name": "tokenlab-api-overview",
+        "title": "TokenLab API Overview",
+        "uri": "tokenlab://api/overview",
+        "mime_type": "text/plain",
+        "freshness": "live"
+      },
+      {
+        "name": "tokenlab-openapi-contract",
+        "title": "TokenLab OpenAPI Contract",
+        "uri": "tokenlab://contract/openapi",
+        "mime_type": "application/json",
+        "freshness": "package_snapshot"
+      },
+      {
+        "name": "tokenlab-mcp-public-contract",
+        "title": "TokenLab MCP Public Contract",
+        "uri": "tokenlab://contract/mcp",
+        "mime_type": "application/json",
+        "freshness": "package_snapshot"
+      }
+    ],
+    "prompts": [
+      {
+        "name": "choose_tokenlab_model",
+        "title": "Choose a TokenLab Model"
+      },
+      {
+        "name": "build_tokenlab_request",
+        "title": "Build a TokenLab Request"
+      }
+    ]
+  },
   "public_auth_operations": [
     "listModels",
     "getModel",
@@ -64,6 +162,22 @@
     "getPricing"
   ],
   "operation_overrides": {
+    "cancelAnthropicMessageBatch": {
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": true,
+        "idempotentHint": true,
+        "openWorldHint": true
+      }
+    },
+    "cancelBatch": {
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": true,
+        "idempotentHint": true,
+        "openWorldHint": true
+      }
+    },
     "createAnthropicMessage": {
       "tool_name": "create_anthropic_message",
       "input_property_overrides": {

package/contract/openapi.json

@@ -117,6 +117,34 @@
                     "stream": true
                   }
                 },
+                "live_translation": {
+                  "summary": "Stream audio translation",
+                  "value": {
+                    "model": "qwen3-livetranslate-flash",
+                    "messages": [
+                      {
+                        "role": "user",
+                        "content": [
+                          {
+                            "type": "input_audio",
+                            "input_audio": {
+                              "data": "https://example.com/sample.wav",
+                              "format": "wav"
+                            }
+                          }
+                        ]
+                      }
+                    ],
+                    "translation_options": {
+                      "source_lang": "zh",
+                      "target_lang": "en"
+                    },
+                    "modalities": [
+                      "text"
+                    ],
+                    "stream": true
+                  }
+                },
                 "function_calling": {
                   "summary": "Function calling",
                   "value": {
@@ -6520,7 +6548,7 @@
           },
           "top_k": {
             "type": "integer",
-            "minimum": 1,
+            "minimum": 0,
             "description": "Top-k sampling cutoff for compatible providers."
           },
           "logit_bias": {
@@ -6542,6 +6570,35 @@
             "additionalProperties": true,
             "description": "Audio output configuration when requesting audio modality."
           },
+          "translation_options": {
+            "type": "object",
+            "required": [
+              "target_lang"
+            ],
+            "properties": {
+              "source_lang": {
+                "type": "string",
+                "description": "Source language code. Omit when the model supports automatic detection."
+              },
+              "target_lang": {
+                "type": "string",
+                "description": "Target language code."
+              }
+            },
+            "description": "Language settings for models that translate audio or video through Chat Completions."
+          },
+          "speech_rate": {
+            "type": "number",
+            "minimum": 0.5,
+            "maximum": 2,
+            "description": "Speech rate for compatible translated audio output."
+          },
+          "repetition_penalty": {
+            "type": "number",
+            "minimum": 0,
+            "exclusiveMinimum": true,
+            "description": "Repetition penalty for compatible models."
+          },
           "prediction": {
             "type": "object",
             "additionalProperties": true,
@@ -6634,6 +6691,62 @@
                         "type",
                         "image_url"
                       ]
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "video_url"
+                          ]
+                        },
+                        "video_url": {
+                          "type": "object",
+                          "properties": {
+                            "url": {
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "url"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "type",
+                        "video_url"
+                      ]
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "input_audio"
+                          ]
+                        },
+                        "input_audio": {
+                          "type": "object",
+                          "properties": {
+                            "data": {
+                              "type": "string",
+                              "description": "Public audio URL or Base64 data URL."
+                            },
+                            "format": {
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "data"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "type",
+                        "input_audio"
+                      ]
                     }
                   ]
                 }

package/generated/public-contract.json

@@ -0,0 +1,324 @@
+{
+  "schema_version": 1,
+  "generated_at": null,
+  "asset": {
+    "id": "tokenlab-mcp-server",
+    "name": "@tokenlabai/mcp-server",
+    "title": "TokenLab MCP Server",
+    "version": "0.5.0",
+    "registry_name": "io.github.hedging8563/tokenlab",
+    "source_url": "https://github.com/hedging8563/tokenlab-mcp-server",
+    "landing_url": "https://tokenlab.sh/mcp",
+    "docs_url": "https://docs.tokenlab.sh/integrations/tokenlab-mcp-server",
+    "recommended_client_name": "tokenlab",
+    "transport": "stdio",
+    "command": "npx",
+    "args": [
+      "-y",
+      "@tokenlabai/mcp-server"
+    ],
+    "api_key_environment_variable": "TOKENLAB_API_KEY",
+    "tool_profile_environment_variable": "TOKENLAB_MCP_TOOL_PROFILE"
+  },
+  "source": {
+    "url": "https://docs.tokenlab.sh/openapi.json",
+    "openapi": "3.0.3",
+    "title": "TokenLab AI Gateway",
+    "version": "1.0.0",
+    "sha256": "f494fcfb2b4d67aaddc88a2ec164739c807bb59331a7e5270fd9d9fa282745e0",
+    "tool_manifest_sha256": "a2690dd92f5e7dbc47ce4fe25b327eaafd4848224f0e329bee0f1c2797c4521d"
+  },
+  "profiles": {
+    "catalog": {
+      "is_default": false,
+      "endpoint_tools": 4,
+      "composite_tools": 2,
+      "total_tools": 6,
+      "tool_names": [
+        "compare_models",
+        "get_api_overview",
+        "get_model",
+        "get_model_pricing",
+        "get_pricing",
+        "list_models"
+      ]
+    },
+    "core": {
+      "is_default": true,
+      "endpoint_tools": 29,
+      "composite_tools": 2,
+      "total_tools": 31,
+      "tool_names": [
+        "cancel_task",
+        "compare_models",
+        "create_3d_model",
+        "create_anthropic_message",
+        "create_chat_completion",
+        "create_embedding",
+        "create_gemini_content",
+        "create_image",
+        "create_image_file",
+        "create_multimodal_embedding",
+        "create_music",
+        "create_response",
+        "create_speech",
+        "create_video",
+        "delete_file",
+        "edit_image",
+        "edit_image_file",
+        "get_api_overview",
+        "get_model",
+        "get_model_pricing",
+        "get_pricing",
+        "get_task_status",
+        "list_files",
+        "list_models",
+        "rerank_documents",
+        "retrieve_file",
+        "retrieve_file_content",
+        "transcribe_audio",
+        "translate_audio",
+        "translate_text",
+        "upload_file"
+      ]
+    },
+    "full": {
+      "is_default": false,
+      "endpoint_tools": 76,
+      "composite_tools": 2,
+      "total_tools": 78,
+      "tool_names": [
+        "bind_seedance_visual_validation_result",
+        "cancel_anthropic_message_batch",
+        "cancel_batch",
+        "cancel_task",
+        "compact_response",
+        "compare_models",
+        "count_anthropic_message_tokens",
+        "create_3d_model",
+        "create_anthropic_message",
+        "create_anthropic_message_batch",
+        "create_batch",
+        "create_chat_completion",
+        "create_embedding",
+        "create_gemini_content",
+        "create_image",
+        "create_image_file",
+        "create_image_variation",
+        "create_multimodal_embedding",
+        "create_music",
+        "create_response",
+        "create_seedance_material_asset",
+        "create_seedance_material_asset_group",
+        "create_seedance_visual_validation_session",
+        "create_speech",
+        "create_video",
+        "create_volc_compatible_seedance_task",
+        "create_world",
+        "delete_anthropic_message_batch",
+        "delete_file",
+        "delete_response",
+        "delete_seedance_material_asset",
+        "delete_seedance_material_asset_group",
+        "delete_volc_compatible_seedance_task",
+        "delete_world",
+        "dispatch_volc_compatible_seedance_action_get",
+        "dispatch_volc_compatible_seedance_action_post",
+        "edit_image",
+        "edit_image_file",
+        "get_3_dtask",
+        "get_api_overview",
+        "get_gemini_model",
+        "get_image_task_status_alias",
+        "get_model",
+        "get_model_pricing",
+        "get_music_task",
+        "get_pricing",
+        "get_seedance_material_asset",
+        "get_seedance_material_asset_group",
+        "get_task_status",
+        "get_video_task",
+        "get_volc_compatible_seedance_task",
+        "get_world",
+        "get_world_media_asset",
+        "get_world_status",
+        "list_anthropic_message_batches",
+        "list_batches",
+        "list_files",
+        "list_gemini_models",
+        "list_models",
+        "list_seedance_material_asset_groups",
+        "list_seedance_material_assets",
+        "list_seedance_visual_validation_history",
+        "list_volc_compatible_seedance_tasks",
+        "list_worlds",
+        "prepare_world_media_asset_upload",
+        "rerank_documents",
+        "retrieve_anthropic_message_batch",
+        "retrieve_anthropic_message_batch_results",
+        "retrieve_batch",
+        "retrieve_file",
+        "retrieve_file_content",
+        "retrieve_response",
+        "transcribe_audio",
+        "translate_audio",
+        "translate_text",
+        "update_seedance_material_asset",
+        "update_seedance_material_asset_group",
+        "upload_file"
+      ]
+    }
+  },
+  "core_tool_layers": [
+    {
+      "id": "discover",
+      "authentication": "none",
+      "tool_rows": [
+        [
+          "list_models",
+          "get_model",
+          "get_pricing"
+        ],
+        [
+          "get_model_pricing",
+          "compare_models",
+          "get_api_overview"
+        ]
+      ],
+      "tool_count": 6
+    },
+    {
+      "id": "create",
+      "authentication": "api_key",
+      "tool_rows": [
+        [
+          "create_chat_completion",
+          "create_response",
+          "create_anthropic_message",
+          "create_gemini_content"
+        ],
+        [
+          "create_image",
+          "create_image_file",
+          "edit_image",
+          "edit_image_file"
+        ],
+        [
+          "create_video",
+          "create_music",
+          "create_3d_model",
+          "create_speech",
+          "transcribe_audio",
+          "translate_audio"
+        ]
+      ],
+      "tool_count": 14
+    },
+    {
+      "id": "operate",
+      "authentication": "api_key",
+      "tool_rows": [
+        [
+          "upload_file",
+          "list_files",
+          "retrieve_file"
+        ],
+        [
+          "retrieve_file_content",
+          "delete_file",
+          "get_task_status",
+          "cancel_task"
+        ],
+        [
+          "create_embedding",
+          "create_multimodal_embedding",
+          "rerank_documents",
+          "translate_text"
+        ]
+      ],
+      "tool_count": 11
+    }
+  ],
+  "features": {
+    "structured_content": true,
+    "tool_annotations": true,
+    "composite_tools": [
+      {
+        "name": "compare_models",
+        "profiles": [
+          "catalog",
+          "core",
+          "full"
+        ],
+        "auth": "optional",
+        "annotations": {
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true
+        }
+      },
+      {
+        "name": "get_api_overview",
+        "profiles": [
+          "catalog",
+          "core",
+          "full"
+        ],
+        "auth": "optional",
+        "annotations": {
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": true
+        }
+      }
+    ],
+    "async_delivery_tools": [
+      "cancel_task",
+      "create_3d_model",
+      "create_image",
+      "create_image_file",
+      "create_music",
+      "create_video",
+      "create_world",
+      "edit_image",
+      "edit_image_file",
+      "get_task_status",
+      "get_world_status"
+    ],
+    "resources": [
+      {
+        "name": "tokenlab-api-overview",
+        "title": "TokenLab API Overview",
+        "uri": "tokenlab://api/overview",
+        "mime_type": "text/plain",
+        "freshness": "live"
+      },
+      {
+        "name": "tokenlab-openapi-contract",
+        "title": "TokenLab OpenAPI Contract",
+        "uri": "tokenlab://contract/openapi",
+        "mime_type": "application/json",
+        "freshness": "package_snapshot"
+      },
+      {
+        "name": "tokenlab-mcp-public-contract",
+        "title": "TokenLab MCP Public Contract",
+        "uri": "tokenlab://contract/mcp",
+        "mime_type": "application/json",
+        "freshness": "package_snapshot"
+      }
+    ],
+    "prompts": [
+      {
+        "name": "choose_tokenlab_model",
+        "title": "Choose a TokenLab Model"
+      },
+      {
+        "name": "build_tokenlab_request",
+        "title": "Build a TokenLab Request"
+      }
+    ]
+  }
+}