TokenLab MCP Server

Servidor MCP para descubrimiento de modelos de TokenLab, precios, guía de endpoints nativos y asistentes de inferencia opcionales.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de TokenLab

CI npm npm downloads

Servidor de Protocolo de Contexto de Modelo (MCP) generado a partir de OpenAPI para el descubrimiento público de modelos de TokenLab, precios, endpoints nativos de LLM, decisiones tipadas, generación multimodal, tareas asíncronas, archivos, embeddings, rerank, traducción, recursos, prompts y la API de desarrollador más amplia.

Expone herramientas de catálogo público para agentes que necesitan elegir modelos, inspeccionar formatos de solicitud admitidos o comparar precios antes de llamar a las APIs de TokenLab. Las herramientas con credenciales cubren inferencia de texto, generación y edición de imágenes, video, música, 3D, sondeo de tareas asíncronas, embeddings, rerank, decisiones tipadas y traducción de texto.

Perfiles de herramientas generados

El manifiesto generated/tools.json incluido se genera a partir del documento OpenAPI público de TokenLab más la pequeña superposición solo-MCP en contract/mcp-overlay.json. La versión 0.6.24 genera 87 herramientas de endpoint; con las dos herramientas compuestas de descubrimiento solo-MCP, el perfil completo devuelve 89 herramientas de tools/list.

PerfilHerramientas de endpointTotal de herramientas registradasEsquema orientado al modeloCobertura
catalog46ExactoDescubrimiento público de modelos y precios únicamente; no se requiere clave de API
core (predeterminado)3032PortableCatálogo y precios; Chat Completions, Responses, Anthropic Messages, Gemini generateContent; decisiones tipadas de System One; imágenes, video, música, 3D, voz y transcripción; tareas asíncronas; archivos; embeddings, rerank y traducción
full8789PortableCada operación de API de desarrollador permitida en la instantánea OpenAPI incluida, incluyendo núcleo más ciclo de vida de respuestas, lotes, mundos y descubrimiento nativo de modelos

El total registrado es el número devuelto por tools/list. Todos los perfiles incluyen compare_models y get_api_overview, produciendo totales de 6, 32 y 89 herramientas. Las operaciones en tiempo real y solo de transmisión están excluidas porque las llamadas a herramientas MCP stdio devuelven un único resultado final. Las operaciones de API que aceptan stream lo fijan internamente a false sin exponer un booleano const a los adaptadores de proveedor, y la clave de API de cadena de consulta de Gemini se oculta intencionalmente de los argumentos de herramienta.

La proyección portable mantiene cada argumento de nivel superior pero limita las formas anidadas profundas orientadas al modelo. El servidor aún valida las llamadas contra el esquema OpenAPI generado completo antes de emitir una solicitud de API. Los presupuestos de compatibilidad mantienen core en no más de 60 KB y profundidad 8, y full en no más de 100 KB y profundidad 8 para la respuesta completa de tools/list. Las pruebas también ejecutan el perfil completo a través de la versión del SDK de Google AI utilizada por la falla observada de OpenCode/Gemini.

Establezca TOKENLAB_MCP_TOOL_PROFILE=catalog para la lista de herramientas más pequeña solo-pública o TOKENLAB_MCP_TOOL_PROFILE=full para la API de desarrollador amplia. Establezca TOKENLAB_MCP_SCHEMA_MODE=exact solo cuando un cliente necesite el JSON Schema anidado completo y pueda aceptar su carga útil de herramienta más grande/profunda. Use strict para proveedores que requieran que cada propiedad esté listada en required y que cada objeto establezca additionalProperties: false; los argumentos complejos de nivel superior se representan como cadenas codificadas en JSON y se decodifican antes de la validación canónica. Los nombres canónicos de herramientas, descripciones, JSON Schemas de entrada, enlaces HTTP, tipos de contenido, requisitos de autenticación y comportamiento de tareas se pueden inspeccionar en generated/tools.json.

El generated/public-contract.json más pequeño es la proyección legible por máquina utilizada por el sitio web de TokenLab y otros consumidores públicos. Contiene identidad del paquete, conteos de perfil, capas de herramientas principales, recursos, prompts y hashes de fuente sin copiar todos los esquemas de endpoint.

Características nativas de MCP

  • Las respuestas JSON de herramientas incluyen structuredContent mientras conservan texto serializado para clientes más antiguos.
  • Los errores HTTP conservan el texto de respuesta original (hasta 4,000 caracteres), incluyendo sugerencias públicas de corrección, junto con estado estructurado, ID de solicitud y tiempo de reintento. Solo se exponen el ID de solicitud y los encabezados de reintento; las solicitudes de generación fallidas nunca se reenvían automáticamente.
  • Las herramientas generadas exponen títulos legibles por humanos, anotaciones estándar de solo-lectura/destructiva/idempotente/mundo-abierto e IDs de solicitud de respuesta cuando están disponibles.
  • Los esquemas de herramientas se publican y validan directamente como JSON Schema. El tiempo de ejecución no hace un viaje de ida y vuelta de los esquemas de herramientas generados a través de Zod; el modo exact es equivalente en forma de bytes al esquema canónico generado.
  • Tres recursos exponen la descripción general de la API en vivo, la instantánea OpenAPI del paquete y el contrato público MCP compacto.
  • Los prompts choose_tokenlab_model y build_tokenlab_request guían a los agentes para usar la verdad de modelos en vivo y preservar las formas nativas de endpoint.
  • Las instrucciones del servidor indican a los clientes confirmar operaciones facturables o destructivas y tratar la salida externa de modelos/API como contenido no confiable.

Ejecución

npm install
npm start

Instale desde npm:

npx -y @tokenlabai/mcp-server

Los instaladores asistidos por agentes pueden seguir llms-install.md para un flujo de configuración y verificación seguro con credenciales.

Ejecute en Docker:

docker build -t tokenlab-mcp-server .
docker run --rm -i tokenlab-mcp-server

Agregue -e TOKENLAB_API_KEY cuando use herramientas de API con credenciales. Las herramientas de catálogo público no requieren una clave.

Configuración estilo Claude Desktop:

{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
      }
    }
  }
}

No se requiere clave de API de TokenLab para operaciones públicas de catálogo y precios. Establezca TOKENLAB_API_KEY cuando las herramientas con credenciales deban llamar a las APIs de TokenLab. Las herramientas generadas preservan la forma de solicitud OpenAPI para endpoints compatibles con OpenAI y nativos en lugar de aplanarlos en un formato de prompt compartido.

Las operaciones multiparte aceptan rutas de archivo locales. Las respuestas pequeñas de imagen y audio se devuelven como contenido MCP nativo; las respuestas binarias más grandes u otras se escriben en TOKENLAB_ARTIFACT_DIR y se devuelven como una ruta con tipo MIME y conteo de bytes.

Resultados de medios síncronos y asíncronos

Las herramientas de creación de video, música y 3D siempre devuelven una tarea asíncrona. La generación y edición de imágenes pueden devolver un resultado completado o una tarea asíncrona dependiendo del modelo y la solicitud seleccionados.

Las herramientas de medios preservan la respuesta completa de la API de TokenLab bajo response y agregan un resumen normalizado delivery:

{
  "delivery": {
    "mode": "async",
    "task_id": "ldtask_...",
    "status": "pending",
    "poll_url": "/v1/tasks/ldtask_...",
    "terminal": false,
    "next_tool": "get_task_status"
  },
  "response": {}
}

Use delivery.mode en lugar de asumir que todas las solicitudes de imagen son síncronas. Para tareas asíncronas, llame a get_task_status con { "id": delivery.task_id } hasta que delivery.terminal sea true. La finalización se determina a partir de status, no de un campo de progreso opcional.

Entorno

  • TOKENLAB_API_BASE: opcional, predeterminado a https://api.tokenlab.sh
  • TOKENLAB_API_KEY: opcional; requerido para inferencia de texto, generación multimodal, tareas asíncronas, embedding, rerank, decisión y herramientas de traducción
  • TOKENLAB_MCP_TOOL_PROFILE: opcional, catalog, core (predeterminado) o full
  • TOKENLAB_MCP_SCHEMA_MODE: opcional, portable, exact o strict; predeterminado al modo probado del perfil seleccionado
  • TOKENLAB_REQUEST_TIMEOUT_MS: tiempo de espera de solicitud opcional en milisegundos, predeterminado a 120000
  • TOKENLAB_MCP_MAX_FILE_BYTES: tamaño máximo de carga local opcional por archivo, predeterminado a 104857600 (100 MiB)
  • TOKENLAB_MCP_INLINE_BYTES: tamaño máximo de respuesta binaria/JSON devuelta en línea, predeterminado a 2097152 (2 MiB)
  • TOKENLAB_ARTIFACT_DIR: directorio de salida opcional para artefactos de respuesta no en línea, predeterminado al directorio temporal del sistema operativo bajo tokenlab-mcp

Para entradas de imagen de Chat Completions, prefiera URLs de datos precisas en bytes como data:image/png;base64,.... Si un llamador MCP etiqueta una carga útil reconocida de PNG, JPEG, WebP o GIF como application/octet-stream, el servidor corrige ese MIME genérico antes de reenviar. Una carga útil binaria genérica no reconocida se rechaza localmente con un error de entrada preciso.

Sincronización de contrato

El documento OpenAPI público es la fuente del contrato de API. La superposición contiene solo opciones específicas de MCP: exposición de perfil, alias de herramientas estables, omisión de secretos, restricciones de no transmisión, variantes de tipo de contenido, semántica de tareas asíncronas y la proyección pública compacta consumida por el sitio web y las puertas de documentación.

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 exact/portable/strict schemas, provider conversion, routing, tasks, files, and binary output

Siempre ejecute git pull --ff-only antes de una sincronización manual de contrato. contract:check prueba la consistencia interna únicamente; contract:source-check prueba la frescura contra la fuente canónica. El flujo de trabajo programado Sync TokenLab OpenAPI contract ejecuta la secuencia de escritura completa y confirma solo la instantánea OpenAPI verificada y el manifiesto generado a main. Una obtención fallida, rama local desactualizada, salida generada sucia, error de generación, error de compilación de esquema o prueba deja el contrato rastreado sin cambios.

Metadatos del registro MCP

Este repositorio incluye server.json para el registro MCP oficial.

Metadatos de lanzamiento:

  • Paquete npm: @tokenlabai/mcp-server@0.6.24
  • Nombre del registro MCP: io.github.hedging8563/tokenlab
  • package.json.mcpName: io.github.hedging8563/tokenlab

Para un nuevo lanzamiento:

  1. Aumente las versiones coincidentes en package.json, package-lock.json y server.json.
  2. Empuje una etiqueta coincidente como v0.6.0.
  3. El flujo de trabajo de publicación prueba y publica npm a través de publicación confiable, luego publica la entrada del registro MCP a través de GitHub Actions OIDC.

El mismo flujo de trabajo se puede ejecutar manualmente desde main para republicar solo los metadatos actuales del registro MCP. No se almacena ningún token de npm o registro MCP en GitHub.

Seguridad

Use el perfil catalog cuando no se necesiten herramientas con credenciales. Mantenga TOKENLAB_API_KEY en el entorno secreto del cliente MCP local, habilite la confirmación humana para llamadas facturables y destructivas, y revise las anotaciones de herramientas antes de otorgar aprobación persistente. No envíe una clave de API de TokenLab a un servidor MCP alojado no confiable.

Enlaces

Gestión de webhooks

Use el perfil full para configurar webhooks de espacio de trabajo con list_webhooks, create_webhook, get_webhook, update_webhook, delete_webhook, rotate_webhook_secret, test_webhook y list_webhook_deliveries.

Establezca TOKENLAB_MANAGEMENT_TOKEN=mt-... por separado de TOKENLAB_API_KEY=sk-.... Cree el token de gestión en Panel → API → Tokens de gestión. Autoriza operaciones de gestión solo dentro de su espacio de trabajo y no se limita a webhooks. La clave de inferencia no puede sustituirlo; el whsec_... devuelto por creación/rotación es solo para verificación de firma del receptor. Mantenga todas las credenciales fuera de los argumentos de herramientas y prompts.

Las notificaciones de webhook evitan el sondeo continuo de tareas. En un respaldo de sondeo, deténgase en estado terminal, 401/403/404 o retryable: false; retroceda en fallas transitorias. Consulte la guía completa de webhooks para cargas útiles, firma, deduplicación e historial de entrega.