@tokenlabai/mcp-server 0.2.2 → 0.4.0

package/llms-install.md

@@ -0,0 +1,60 @@
+# Install TokenLab MCP Server
+
+Use the published npm package. Do not clone or build the repository unless the user explicitly asks for a source checkout.
+
+## Requirements
+
+- Node.js 18.17 or newer
+- An MCP client that supports stdio servers
+- `TOKENLAB_API_KEY` only when the user wants to call credentialed API tools
+
+## MCP Configuration
+
+Add this server entry to the client's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "tokenlab": {
+      "command": "npx",
+      "args": ["-y", "@tokenlabai/mcp-server"],
+      "env": {
+        "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
+      }
+    }
+  }
+}
+```
+
+Public model catalog and pricing tools work without credentials. When inference is requested, add the user's TokenLab key without printing or committing it. Do not put API keys in MCP tool arguments:
+
+```json
+{
+  "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>"
+}
+```
+
+## Verification
+
+Start or reload the MCP client, then confirm these public tools are available without an API key:
+
+- `list_models`
+- `get_model`
+- `get_model_pricing`
+- `compare_models`
+- `get_api_overview`
+
+The default `core` profile also exposes generated credentialed tools for:
+
+- OpenAI Chat Completions and Responses
+- Anthropic Messages and Gemini generateContent
+- image generation/editing through JSON or local multipart files
+- video, music, 3D, speech, transcription, and audio translation
+- task polling/cancellation and file operations
+- embeddings, multimodal embeddings, rerank, and text translation
+
+Set `TOKENLAB_MCP_TOOL_PROFILE=full` to expose every allowlisted developer operation generated from the public OpenAPI contract. Realtime and streaming-only operations remain excluded.
+
+Video, music, and 3D tools return async task summaries. Image tools may return a completed result or an async task summary. When `delivery.mode` is `async`, call `get_task_status` with `{ "id": delivery.task_id }` until `delivery.terminal` is `true`.
+
+If startup fails, run `node --version` and confirm it is at least `18.17`, then run `npx -y @tokenlabai/mcp-server` once in a terminal to surface npm or network errors.

package/package.json

@@ -1,15 +1,30 @@
 {
   "name": "@tokenlabai/mcp-server",
-  "version": "0.2.2",
-  "description": "MCP server for TokenLab model discovery, pricing, OpenAI-compatible Chat Completions, native endpoint guidance, and optional inference helpers.",
+  "version": "0.4.0",
+  "description": "MCP server for TokenLab model discovery, native LLM endpoints, multimodal generation, async tasks, embeddings, rerank, and translation.",
   "type": "module",
+  "engines": {
+    "node": ">=18.17"
+  },
   "mcpName": "io.github.hedging8563/tokenlab",
   "bin": {
     "tokenlab-mcp-server": "src/index.js"
   },
+  "files": [
+    "contract/mcp-overlay.json",
+    "contract/openapi.json",
+    "generated/tools.json",
+    "llms-install.md",
+    "scripts/generate-contract.mjs",
+    "scripts/sync-contract.mjs",
+    "src/index.js"
+  ],
   "scripts": {
     "start": "node ./src/index.js",
-    "test": "node --check ./src/index.js && node --test"
+    "contract:generate": "node ./scripts/generate-contract.mjs",
+    "contract:check": "node ./scripts/generate-contract.mjs --check",
+    "contract:sync": "node ./scripts/sync-contract.mjs",
+    "test": "node --check ./src/index.js && node --check ./scripts/generate-contract.mjs && npm run contract:check && node --test"
   },
   "keywords": [
     "mcp",

package/scripts/generate-contract.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const argv = process.argv.slice(2);
+const args = new Map();
+for (let index = 0; index < argv.length; index += 1) {
+  if (!argv[index].startsWith("--") || argv[index] === "--check") continue;
+  args.set(argv[index], argv[index + 1]);
+  index += 1;
+}
+
+const sourcePath = resolve(root, args.get("--source") || "contract/openapi.json");
+const overlayPath = resolve(root, args.get("--overlay") || "contract/mcp-overlay.json");
+const outputPath = resolve(root, args.get("--output") || "generated/tools.json");
+const check = argv.includes("--check");
+
+const [sourceText, overlayText] = await Promise.all([
+  readFile(sourcePath, "utf8"),
+  readFile(overlayPath, "utf8")
+]);
+const spec = JSON.parse(sourceText);
+const overlay = JSON.parse(overlayText);
+
+function snakeCase(value) {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Za-z])(\d+)/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase();
+}
+
+function getByPointer(pointer) {
+  return pointer
+    .replace(/^#\//, "")
+    .split("/")
+    .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"))
+    .reduce((value, key) => value?.[key], spec);
+}
+
+function normalizeSchema(value, stack = []) {
+  if (Array.isArray(value)) return value.map((entry) => normalizeSchema(entry, stack));
+  if (!value || typeof value !== "object") return value;
+
+  if (value.$ref) {
+    if (stack.includes(value.$ref)) {
+      return { type: "object", additionalProperties: true };
+    }
+    const target = getByPointer(value.$ref);
+    if (!target) throw new Error(`Unresolved OpenAPI reference: ${value.$ref}`);
+    const { $ref, ...rest } = value;
+    return {
+      ...normalizeSchema(target, [...stack, value.$ref]),
+      ...normalizeSchema(rest, stack)
+    };
+  }
+
+  const normalized = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (["example", "examples", "xml", "discriminator", "deprecated", "readOnly", "writeOnly"].includes(key)) continue;
+    normalized[key] = normalizeSchema(entry, stack);
+  }
+
+  if (normalized.nullable === true) {
+    delete normalized.nullable;
+    return { anyOf: [normalized, { type: "null" }] };
+  }
+
+  return normalized;
+}
+
+function operationIndex() {
+  const operations = new Map();
+  for (const [path, pathItem] of Object.entries(spec.paths || {})) {
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (!["get", "post", "put", "patch", "delete"].includes(method)) continue;
+      if (!operation.operationId) throw new Error(`${method.toUpperCase()} ${path} has no operationId`);
+      if (operations.has(operation.operationId)) throw new Error(`Duplicate operationId: ${operation.operationId}`);
+      operations.set(operation.operationId, { path, pathItem, method: method.toUpperCase(), operation });
+    }
+  }
+  return operations;
+}
+
+const operations = operationIndex();
+const coreOperations = new Set(overlay.profiles.core.operations);
+const fullTags = new Set(overlay.profiles.full.include_tags);
+const fullExclusions = new Set(overlay.profiles.full.exclude_operations || []);
+const publicAuth = new Set(overlay.public_auth_operations || []);
+
+for (const operationId of coreOperations) {
+  if (!operations.has(operationId)) throw new Error(`Core MCP operation is missing from OpenAPI: ${operationId}`);
+}
+
+function chooseContentTypes(operationId, operation, override) {
+  const available = Object.keys(operation.requestBody?.content || {});
+  if (available.length === 0) return [null];
+  if (override.all_content_types) return available;
+  if (override.content_type) {
+    if (!available.includes(override.content_type)) {
+      throw new Error(`${operationId} does not declare ${override.content_type}`);
+    }
+    return [override.content_type];
+  }
+  return [available.includes("application/json") ? "application/json" : available[0]];
+}
+
+function buildInputSchema(pathItem, operation, contentType) {
+  const properties = {};
+  const required = [];
+  const bindings = { path: [], query: [], header: [], body: [], files: [] };
+  const parameters = [...(pathItem.parameters || []), ...(operation.parameters || [])]
+    .map((parameter) => normalizeSchema(parameter));
+
+  for (const parameter of parameters) {
+    if (!["path", "query", "header"].includes(parameter.in)) continue;
+    if (properties[parameter.name]) throw new Error(`Duplicate MCP argument: ${parameter.name}`);
+    properties[parameter.name] = {
+      ...normalizeSchema(parameter.schema || { type: "string" }),
+      ...(parameter.description ? { description: parameter.description } : {})
+    };
+    bindings[parameter.in].push(parameter.name);
+    if (parameter.required) required.push(parameter.name);
+  }
+
+  if (contentType) {
+    const media = operation.requestBody.content[contentType];
+    const bodySchema = normalizeSchema(media.schema || { type: "object", additionalProperties: true });
+    if (bodySchema.type === "object" || bodySchema.properties) {
+      for (const [name, schema] of Object.entries(bodySchema.properties || {})) {
+        if (properties[name]) throw new Error(`MCP argument collision for ${operation.operationId}: ${name}`);
+        const property = structuredClone(schema);
+        const binaryNodes = [];
+        const visit = (value) => {
+          if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+          }
+          if (!value || typeof value !== "object") return;
+          if (value.format === "binary") {
+            delete value.format;
+            value.type = "string";
+            binaryNodes.push(value);
+          }
+          Object.values(value).forEach(visit);
+        };
+        visit(property);
+        if (binaryNodes.length > 0) {
+          property.description = `${property.description ? `${property.description} ` : ""}Pass local file path${binaryNodes.length > 1 || property.type === "array" ? "s" : ""}.`;
+          bindings.files.push(name);
+        }
+        properties[name] = property;
+        bindings.body.push(name);
+      }
+      for (const name of bodySchema.required || []) required.push(name);
+    } else {
+      properties.body = bodySchema;
+      bindings.body.push("body");
+      if (operation.requestBody.required) required.push("body");
+    }
+  }
+
+  return {
+    schema: {
+      type: "object",
+      properties,
+      ...(required.length > 0 ? { required: [...new Set(required)] } : {}),
+      additionalProperties: false
+    },
+    bindings
+  };
+}
+
+function applyInputOverrides(schema, bindings, override) {
+  for (const name of override.omit_arguments || []) {
+    if (!schema.properties[name]) throw new Error(`Cannot omit unknown MCP argument: ${name}`);
+    delete schema.properties[name];
+    if (schema.required) schema.required = schema.required.filter((entry) => entry !== name);
+    for (const binding of Object.values(bindings)) {
+      const index = binding.indexOf(name);
+      if (index >= 0) binding.splice(index, 1);
+    }
+  }
+  for (const [name, patch] of Object.entries(override.input_property_overrides || {})) {
+    if (!schema.properties[name]) throw new Error(`Cannot override unknown MCP argument: ${name}`);
+    schema.properties[name] = { ...schema.properties[name], ...patch };
+  }
+}
+
+function annotations(method) {
+  return {
+    readOnlyHint: method === "GET",
+    destructiveHint: method === "DELETE",
+    idempotentHint: ["GET", "PUT", "DELETE"].includes(method),
+    openWorldHint: true
+  };
+}
+
+const tools = [];
+for (const [operationId, indexed] of operations) {
+  const tags = indexed.operation.tags || [];
+  const inCore = coreOperations.has(operationId);
+  const inFull = !fullExclusions.has(operationId) && tags.some((tag) => fullTags.has(tag));
+  if (!inCore && !inFull) continue;
+
+  const override = overlay.operation_overrides[operationId] || {};
+  const contentTypes = chooseContentTypes(operationId, indexed.operation, override);
+  for (const contentType of contentTypes) {
+    const suffix = contentTypes.length > 1 && contentType !== "application/json"
+      ? `_${contentType.split("/").at(-1).replace(/[^A-Za-z0-9]+/g, "_")}`
+      : "";
+    const toolName = override.tool_names_by_content_type?.[contentType]
+      || `${override.tool_name || snakeCase(operationId)}${suffix}`;
+    const { schema, bindings } = buildInputSchema(indexed.pathItem, indexed.operation, contentType);
+    applyInputOverrides(schema, bindings, override);
+    const description = [indexed.operation.summary, indexed.operation.description]
+      .filter(Boolean)
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+
+    tools.push({
+      name: toolName,
+      operation_id: operationId,
+      method: indexed.method,
+      path: indexed.path,
+      content_type: contentType,
+      auth: publicAuth.has(operationId) ? "optional" : "required",
+      tags,
+      profiles: [...(inCore ? ["core"] : []), ...(inFull ? ["full"] : [])],
+      description,
+      input_schema: schema,
+      bindings,
+      annotations: annotations(indexed.method),
+      ...(override.task ? { task: override.task } : {})
+    });
+  }
+}
+
+tools.sort((left, right) => left.name.localeCompare(right.name));
+const duplicateNames = tools.filter((tool, index) => tools.findIndex((candidate) => candidate.name === tool.name) !== index);
+if (duplicateNames.length > 0) throw new Error(`Duplicate MCP tool names: ${duplicateNames.map((tool) => tool.name).join(", ")}`);
+
+const manifest = {
+  schema_version: 1,
+  generated_at: null,
+  source: {
+    url: overlay.openapi_url,
+    openapi: spec.openapi,
+    title: spec.info?.title,
+    version: spec.info?.version,
+    sha256: createHash("sha256").update(sourceText).digest("hex")
+  },
+  default_profile: overlay.default_profile,
+  profiles: Object.keys(overlay.profiles),
+  tool_count: tools.length,
+  tools
+};
+const output = `${JSON.stringify(manifest, null, 2)}\n`;
+
+if (check) {
+  const existing = await readFile(outputPath, "utf8");
+  if (existing !== output) {
+    console.error("Generated MCP contract is stale. Run npm run contract:generate.");
+    process.exit(1);
+  }
+  console.log(`[contract] PASS (${tools.length} generated tools)`);
+} else {
+  await writeFile(outputPath, output);
+  console.log(`[contract] generated ${tools.length} tools at ${outputPath}`);
+}

package/scripts/sync-contract.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const overlay = JSON.parse(await readFile(resolve(root, "contract/mcp-overlay.json"), "utf8"));
+const response = await fetch(overlay.openapi_url, {
+  headers: { Accept: "application/json", "User-Agent": "tokenlab-mcp-contract-sync" }
+});
+if (!response.ok) throw new Error(`OpenAPI fetch failed: ${response.status} ${response.statusText}`);
+
+const source = `${JSON.stringify(await response.json(), null, 2)}\n`;
+await writeFile(resolve(root, "contract/openapi.json"), source);
+
+await new Promise((resolvePromise, reject) => {
+  const child = spawn(process.execPath, ["scripts/generate-contract.mjs"], {
+    cwd: root,
+    stdio: "inherit"
+  });
+  child.once("error", reject);
+  child.once("exit", (code) => code === 0 ? resolvePromise() : reject(new Error(`Generator exited ${code}`)));
+});
+
+console.log(`[contract] synchronized ${overlay.openapi_url}`);