Skip to main content

MCP SDK Usage

SDK Return Values

SDK code generated by MCP follows these return value conventions. Understanding these conventions will help you handle data correctly.

On Success​

SDK methods directly return the contents of the data field:

// Complete API response: { success: true, data: { id: 123, name: "..." }, msg: "" }
// SDK returns: { id: 123, name: "..." }
const result = await client.models.customer.create({ name: "Zhang San" });
console.log(result.id); // Direct data access

On Failure​

The SDK throws a LovrabetError exception:

try {
  const result = await client.models.customer.create({ name: "" });
} catch (error) {
  if (error instanceof LovrabetError) {
    console.error("Error message:", error.message);
    console.error("HTTP status code:", error.status);
    console.error("Business error code:", error.code);
    console.error("Full response:", error.data);
  }
}

SQL Queries​

SQL query return values have a different structure and require checking the execution status:

const data = await client.api.executeSql("sql-code", { param1: "value" });

// Must check execution status
if (!data.execSuccess) {
  throw new Error(data.execError || "SQL execution failed");
}

// Get results
const results = data.execResult || [];

v1.2.0 New Features

Modern Architecture​

v1.2.0 completed a major upgrade of the MCP SDK architecture:

  • McpServer API: Migrated from the deprecated Server API to the officially recommended McpServer API
  • Tool Metadata: All 8 tools support title and annotations (readOnlyHint, destructiveHint, idempotentHint)
  • Complete Test Coverage: 17 end-to-end automated test cases

Enhanced SDK Code Generation​

Added aliasHint field for smarter model access suggestions:

aliasHint: {
  defaultAlias: "customer",           // Default alias (camelCase table name)
  datasetSDKKey: "dataset_customer",  // SDK key (requires SDK >= 1.2.0)
  note: "Check custom alias in createClient or registerModels",
  versionNote: "Using alias access requires @lovrabet/sdk >= 1.2.0"
}

Two Access Modes​

ModeFormatDescription
Standard Modeclient.models.dataset_[code].operation()Stable, no configuration needed
Alias Modeclient.models.[alias].operation()Human-friendly, requires SDK >= 1.2.0

Enhanced Field Metadata​

Field information now includes database type fields:

{
  name: "customer_id",
  type: "NUMBER",
  dbType: "BIGINT",        // Database type
  dbTypeLen: 20,           // Type length
  autoIncrement: true,     // Auto-increment flag
}