taurusdb-mcp 0.1.0

package/dist/tools/registry.js

@@ -0,0 +1,106 @@
+import { generateTaskId, logger, withTaskContext, } from "taurusdb-core";
+import { executeReadonlySqlTool, executeSqlTool, explainSqlTool, } from "./query.js";
+import { describeTableTool, listDatabasesTool, listTablesTool, } from "./discovery.js";
+import { showProcesslistTool } from "./processlist.js";
+import { pingTool } from "./ping.js";
+import { getKernelInfoTool, listTaurusFeaturesTool } from "./taurus/capability.js";
+import { selectCloudTaurusInstanceTool, setCloudAccessKeysTool, setCloudRegionTool, } from "./taurus/cloud-context.js";
+import { listCloudTaurusInstancesTool } from "./taurus/cloud-instances.js";
+import { diagnosticToolDefinitions } from "./taurus/diagnostics.js";
+import { explainSqlEnhancedTool } from "./taurus/explain.js";
+import { flashbackQueryTool } from "./taurus/flashback.js";
+import { listRecycleBinTool, restoreRecycleBinTableTool } from "./taurus/recycle-bin.js";
+import { ErrorCode, formatError, toMcpToolResult, } from "../utils/formatter.js";
+function formatUnhandledToolError(error, taskId) {
+    const message = error instanceof Error ? error.message : String(error);
+    const response = formatError({
+        code: ErrorCode.CONNECTION_FAILED,
+        message,
+        summary: "Tool execution failed unexpectedly.",
+        metadata: { task_id: taskId },
+        retryable: false,
+    });
+    return toMcpToolResult(response);
+}
+function registerOneTool(server, tool, deps) {
+    const registrar = server;
+    const wrappedHandler = async (rawInput) => {
+        const taskId = generateTaskId();
+        return withTaskContext(taskId, async () => {
+            const startedAt = Date.now();
+            logger.info({ tool: tool.name }, "Tool invocation started");
+            try {
+                const response = await tool.handler(rawInput, deps, { taskId });
+                logger.info({ tool: tool.name, ok: response.ok, durationMs: Date.now() - startedAt }, "Tool invocation finished");
+                return toMcpToolResult(response);
+            }
+            catch (error) {
+                logger.error({ err: error, tool: tool.name }, "Tool invocation failed with unhandled error");
+                return formatUnhandledToolError(error, taskId);
+            }
+        });
+    };
+    if (typeof registrar.registerTool === "function") {
+        registrar.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, wrappedHandler);
+        return;
+    }
+    if (typeof registrar.tool === "function") {
+        registrar.tool(tool.name, tool.description, tool.inputSchema, wrappedHandler);
+        return;
+    }
+    throw new Error("Unsupported MCP SDK version: expected `tool` or `registerTool` on McpServer.");
+}
+export const commonToolDefinitions = [
+    pingTool,
+    listDatabasesTool,
+    listTablesTool,
+    describeTableTool,
+    showProcesslistTool,
+    executeReadonlySqlTool,
+    explainSqlTool,
+    executeSqlTool,
+];
+export const capabilityToolDefinitions = [
+    getKernelInfoTool,
+    listTaurusFeaturesTool,
+    setCloudRegionTool,
+    setCloudAccessKeysTool,
+    listCloudTaurusInstancesTool,
+    selectCloudTaurusInstanceTool,
+];
+function buildDefaultToolDefinitions(_config, probe) {
+    const tools = [
+        ...commonToolDefinitions,
+        ...capabilityToolDefinitions,
+        ...diagnosticToolDefinitions,
+    ];
+    if (probe?.features) {
+        if (probe.features.ndp_pushdown.available || probe.features.parallel_query.available) {
+            tools.push(explainSqlEnhancedTool);
+        }
+        if (probe.features.flashback_query.available) {
+            tools.push(flashbackQueryTool);
+        }
+        if (probe.features.recycle_bin.available) {
+            tools.push(listRecycleBinTool, restoreRecycleBinTableTool);
+        }
+    }
+    return tools;
+}
+function isToolDefinitionArray(value) {
+    return Array.isArray(value);
+}
+export function registerTools(server, deps, config, probeOrTools, maybeTools) {
+    const probe = isToolDefinitionArray(probeOrTools) ? undefined : probeOrTools;
+    const tools = maybeTools
+        ?? (isToolDefinitionArray(probeOrTools) ? probeOrTools : buildDefaultToolDefinitions(config, probe));
+    for (const tool of tools) {
+        if (tool.exposeWhen && !tool.exposeWhen(config)) {
+            continue;
+        }
+        registerOneTool(server, tool, deps);
+    }
+}

package/dist/tools/taurus/capability.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../registry.js";
+export declare const getKernelInfoTool: ToolDefinition;
+export declare const listTaurusFeaturesTool: ToolDefinition;

package/dist/tools/taurus/capability.js

@@ -0,0 +1,66 @@
+import { formatSuccess } from "../../utils/formatter.js";
+import { formatToolError } from "../error-handling.js";
+import { contextInputShape, metadata, resolveContext, toPublicFeatureMatrix, toPublicKernelInfo, } from "../common.js";
+export const getKernelInfoTool = {
+    name: "get_kernel_info",
+    description: "Detect whether the selected datasource is TaurusDB and return kernel metadata.",
+    inputSchema: {
+        datasource: contextInputShape.datasource,
+    },
+    async handler(input, deps, context) {
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const kernel = await deps.engine.getKernelInfo(ctx);
+            return formatSuccess({
+                datasource: ctx.datasource,
+                kernel: toPublicKernelInfo(kernel),
+            }, {
+                summary: kernel.isTaurusDB
+                    ? `TaurusDB instance detected on datasource ${ctx.datasource}.`
+                    : `Datasource ${ctx.datasource} does not appear to be TaurusDB.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "get_kernel_info",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const listTaurusFeaturesTool = {
+    name: "list_taurus_features",
+    description: "Return the TaurusDB kernel info and feature matrix for the selected datasource. Works on non-TaurusDB instances by returning unavailable features.",
+    inputSchema: {
+        datasource: contextInputShape.datasource,
+    },
+    async handler(input, deps, context) {
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const [kernel, features] = await Promise.all([
+                deps.engine.getKernelInfo(ctx),
+                deps.engine.listFeatures(ctx),
+            ]);
+            const publicFeatures = toPublicFeatureMatrix(features);
+            const availableCount = Object.values(publicFeatures).filter((feature) => feature.available).length;
+            const totalCount = Object.keys(publicFeatures).length;
+            return formatSuccess({
+                datasource: ctx.datasource,
+                kernel: toPublicKernelInfo(kernel),
+                features: publicFeatures,
+            }, {
+                summary: kernel.isTaurusDB
+                    ? `TaurusDB instance detected. Kernel version ${kernel.kernelVersion ?? "unknown"}, ${availableCount} of ${totalCount} features available.`
+                    : `Datasource ${ctx.datasource} is not TaurusDB. Returning an unavailable feature matrix for compatibility discovery.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "list_taurus_features",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};

package/dist/tools/taurus/cloud-context.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../registry.js";
+export declare const setCloudRegionTool: ToolDefinition;
+export declare const setCloudAccessKeysTool: ToolDefinition;
+export declare const selectCloudTaurusInstanceTool: ToolDefinition;

package/dist/tools/taurus/cloud-context.js

@@ -0,0 +1,209 @@
+import { createCloudTaurusInstanceClient, TaurusDBEngine, } from "taurusdb-core";
+import { z } from "zod";
+import { formatSuccess } from "../../utils/formatter.js";
+import { formatToolError, ToolInputError } from "../error-handling.js";
+import { metadata } from "../common.js";
+function buildHuaweiCloudEndpoint(service, region, domainSuffix) {
+    return `https://${service}.${region}.${domainSuffix}`;
+}
+function clearCloudSelection(deps) {
+    deps.config.cloud.projectId = undefined;
+    deps.config.cloud.instanceId = undefined;
+    deps.config.cloud.nodeId = undefined;
+    deps.config.slowSqlSource.taurusApi.projectId = undefined;
+    deps.config.slowSqlSource.taurusApi.instanceId = undefined;
+    deps.config.slowSqlSource.taurusApi.nodeId = undefined;
+    deps.config.slowSqlSource.das.projectId = undefined;
+    deps.config.slowSqlSource.das.instanceId = undefined;
+    deps.config.metricsSource.ces.projectId = undefined;
+    deps.config.metricsSource.ces.instanceId = undefined;
+    deps.config.metricsSource.ces.nodeId = undefined;
+    deps.profileLoader.clearAllRuntimeTargets();
+}
+async function reloadEngine(deps) {
+    const nextEngine = await TaurusDBEngine.create({
+        config: deps.config,
+        profileLoader: deps.profileLoader,
+    });
+    const previousEngine = deps.engine;
+    deps.engine = nextEngine;
+    if (previousEngine?.close) {
+        await previousEngine.close();
+    }
+}
+async function resolveBindingDatasource(deps, explicit) {
+    const trimmed = typeof explicit === "string" ? explicit.trim() : "";
+    if (trimmed) {
+        return trimmed;
+    }
+    return deps.engine.getDefaultDataSource();
+}
+function selectInstanceAddress(input) {
+    return input.publicIps[0] ?? input.privateIps[0] ?? input.hostnames[0];
+}
+function normalizePort(port) {
+    if (typeof port === "number" && Number.isFinite(port)) {
+        return port;
+    }
+    if (typeof port === "string" && /^\d+$/.test(port.trim())) {
+        return Number.parseInt(port, 10);
+    }
+    return undefined;
+}
+export const setCloudRegionTool = {
+    name: "set_cloud_region",
+    description: "Update the active Huawei Cloud region for the current MCP session and reset any stale cloud project or instance selections.",
+    inputSchema: {
+        region: z.string().trim().min(1).describe("Huawei Cloud region id, for example cn-north-4."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const region = typeof input.region === "string" ? input.region.trim() : "";
+            if (!region) {
+                throw new ToolInputError("region is required.");
+            }
+            const domainSuffix = deps.config.cloud.domainSuffix ?? "myhuaweicloud.com";
+            deps.config.cloud.region = region;
+            deps.config.cloud.apiEndpoint = buildHuaweiCloudEndpoint("gaussdb", region, domainSuffix);
+            deps.config.cloud.iamEndpoint = buildHuaweiCloudEndpoint("iam", region, domainSuffix);
+            deps.config.slowSqlSource.taurusApi.endpoint = buildHuaweiCloudEndpoint("gaussdb", region, domainSuffix);
+            deps.config.slowSqlSource.das.endpoint = buildHuaweiCloudEndpoint("das", region, domainSuffix);
+            deps.config.metricsSource.ces.endpoint = buildHuaweiCloudEndpoint("ces", region, domainSuffix);
+            clearCloudSelection(deps);
+            await reloadEngine(deps);
+            return formatSuccess({
+                region,
+                api_endpoint: deps.config.cloud.apiEndpoint,
+                iam_endpoint: deps.config.cloud.iamEndpoint,
+            }, {
+                summary: `Cloud region switched to ${region}.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "set_cloud_region",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const setCloudAccessKeysTool = {
+    name: "set_cloud_access_keys",
+    description: "Update the active Huawei Cloud AK/SK for the current MCP session and clear stale token or instance bindings.",
+    inputSchema: {
+        access_key_id: z.string().trim().min(1).describe("Huawei Cloud access key id."),
+        secret_access_key: z.string().trim().min(1).describe("Huawei Cloud secret access key."),
+        security_token: z.string().trim().min(1).optional().describe("Optional temporary security token when using temporary AK/SK."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const accessKeyId = typeof input.access_key_id === "string" ? input.access_key_id.trim() : "";
+            const secretAccessKey = typeof input.secret_access_key === "string" ? input.secret_access_key.trim() : "";
+            const securityToken = typeof input.security_token === "string" ? input.security_token.trim() : undefined;
+            if (!accessKeyId || !secretAccessKey) {
+                throw new ToolInputError("access_key_id and secret_access_key are required.");
+            }
+            deps.config.cloud.accessKeyId = accessKeyId;
+            deps.config.cloud.secretAccessKey = secretAccessKey;
+            deps.config.cloud.securityToken = securityToken;
+            deps.config.cloud.authToken = undefined;
+            deps.config.slowSqlSource.taurusApi.authToken = undefined;
+            deps.config.slowSqlSource.das.authToken = undefined;
+            deps.config.metricsSource.ces.authToken = undefined;
+            clearCloudSelection(deps);
+            await reloadEngine(deps);
+            return formatSuccess({
+                access_key_id_suffix: accessKeyId.slice(-4),
+                uses_security_token: Boolean(securityToken),
+            }, {
+                summary: "Cloud access keys updated for the current session.",
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "set_cloud_access_keys",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const selectCloudTaurusInstanceTool = {
+    name: "select_cloud_taurus_instance",
+    description: "Select the default TaurusDB cloud instance for the current session so diagnostics can reuse its instance id and default node id.",
+    inputSchema: {
+        instance_id: z.string().trim().min(1).describe("Exact TaurusDB instance id to bind into the current session."),
+        datasource: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("Optional datasource template to bind to this cloud instance. Defaults to the current default datasource."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const instanceId = typeof input.instance_id === "string" ? input.instance_id.trim() : "";
+            if (!instanceId) {
+                throw new ToolInputError("instance_id is required.");
+            }
+            const client = createCloudTaurusInstanceClient(deps.config);
+            if (!client) {
+                throw new ToolInputError("Cloud instance selection is not configured. Set cloud region and either auth token or AK/SK first.");
+            }
+            const [items, projectId] = await Promise.all([
+                client.list({ id: instanceId, limit: 10 }),
+                client.getProjectId(),
+            ]);
+            const matched = items.find((item) => item.id === instanceId);
+            if (!matched) {
+                throw new ToolInputError(`No TaurusDB cloud instance matched id ${instanceId}.`);
+            }
+            deps.config.cloud.projectId = projectId;
+            deps.config.cloud.instanceId = matched.id;
+            deps.config.cloud.nodeId = matched.primaryNodeId;
+            deps.config.slowSqlSource.taurusApi.projectId = projectId;
+            deps.config.slowSqlSource.taurusApi.instanceId = matched.id;
+            deps.config.slowSqlSource.taurusApi.nodeId = matched.primaryNodeId;
+            deps.config.slowSqlSource.das.projectId = projectId;
+            deps.config.slowSqlSource.das.instanceId = matched.id;
+            deps.config.metricsSource.ces.projectId = projectId;
+            deps.config.metricsSource.ces.instanceId = matched.id;
+            deps.config.metricsSource.ces.nodeId = matched.primaryNodeId;
+            const boundDatasource = await resolveBindingDatasource(deps, typeof input.datasource === "string" ? input.datasource : undefined);
+            const selectedHost = selectInstanceAddress(matched);
+            const selectedPort = normalizePort(matched.port);
+            if (boundDatasource && selectedHost) {
+                deps.profileLoader.setRuntimeTarget(boundDatasource, {
+                    host: selectedHost,
+                    port: selectedPort,
+                    instanceId: matched.id,
+                    nodeId: matched.primaryNodeId,
+                });
+            }
+            await reloadEngine(deps);
+            return formatSuccess({
+                project_id: projectId,
+                instance_id: matched.id,
+                instance_name: matched.name,
+                default_node_id: matched.primaryNodeId,
+                private_ips: matched.privateIps,
+                public_ips: matched.publicIps,
+                hostnames: matched.hostnames,
+                port: matched.port,
+                bound_datasource: boundDatasource,
+                bound_host: selectedHost,
+                bound_port: selectedPort,
+            }, {
+                summary: `Selected cloud instance ${matched.name} (${matched.id}).`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "select_cloud_taurus_instance",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};

package/dist/tools/taurus/cloud-instances.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../registry.js";
+export declare const listCloudTaurusInstancesTool: ToolDefinition;

package/dist/tools/taurus/cloud-instances.js

@@ -0,0 +1,73 @@
+import { createCloudTaurusInstanceClient, } from "taurusdb-core";
+import { z } from "zod";
+import { formatSuccess } from "../../utils/formatter.js";
+import { formatToolError, ToolInputError } from "../error-handling.js";
+import { metadata } from "../common.js";
+function toPublicInstance(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        status: item.status,
+        mode: item.mode,
+        region: item.region,
+        datastore_version: item.datastoreVersion,
+        vpc_id: item.vpcId,
+        subnet_id: item.subnetId,
+        private_ips: item.privateIps,
+        public_ips: item.publicIps,
+        hostnames: item.hostnames,
+        port: item.port,
+        node_ids: item.nodeIds,
+        default_node_id: item.primaryNodeId,
+        created: item.created,
+        updated: item.updated,
+    };
+}
+export const listCloudTaurusInstancesTool = {
+    name: "list_cloud_taurus_instances",
+    description: "List TaurusDB/GaussDB(for MySQL) instances visible to the configured Huawei Cloud project so the user can choose an instance id.",
+    inputSchema: {
+        name: z.string().trim().min(1).optional().describe("Optional fuzzy instance name filter."),
+        id: z.string().trim().min(1).optional().describe("Optional exact instance id filter."),
+        ip: z.string().trim().min(1).optional().describe("Optional private/public IP filter."),
+        offset: z.number().int().min(0).optional().describe("Pagination offset. Defaults to 0."),
+        limit: z.number().int().positive().max(100).optional().describe("Maximum number of instances to return. Defaults to 50."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const client = createCloudTaurusInstanceClient(deps.config);
+            if (!client) {
+                throw new ToolInputError("Cloud instance discovery is not configured. Provide TAURUSDB_CLOUD_REGION plus either TAURUSDB_CLOUD_AUTH_TOKEN or TAURUSDB_CLOUD_ACCESS_KEY_ID and TAURUSDB_CLOUD_SECRET_ACCESS_KEY.");
+            }
+            const items = await client.list({
+                name: typeof input.name === "string" ? input.name : undefined,
+                id: typeof input.id === "string" ? input.id : undefined,
+                ip: typeof input.ip === "string" ? input.ip : undefined,
+                offset: typeof input.offset === "number" ? input.offset : undefined,
+                limit: typeof input.limit === "number" ? input.limit : undefined,
+            });
+            const projectId = await client.getProjectId();
+            deps.config.cloud.projectId = deps.config.cloud.projectId ?? projectId;
+            return formatSuccess({
+                items: items.map(toPublicInstance),
+                total: items.length,
+                cloud: {
+                    provider: deps.config.cloud.provider,
+                    region: deps.config.cloud.region,
+                    project_id: projectId,
+                },
+            }, {
+                summary: items.length === 1
+                    ? "Resolved 1 cloud TaurusDB instance."
+                    : `Resolved ${items.length} cloud TaurusDB instances.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "list_cloud_taurus_instances",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};

package/dist/tools/taurus/diagnostics.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition } from "../registry.js";
+export declare const findTopSlowSqlTool: ToolDefinition;
+export declare const diagnoseServiceLatencyTool: ToolDefinition;
+export declare const diagnoseDbHotspotTool: ToolDefinition;
+export declare const diagnoseSlowQueryTool: ToolDefinition;
+export declare const diagnoseConnectionSpikeTool: ToolDefinition;
+export declare const diagnoseLockContentionTool: ToolDefinition;
+export declare const diagnoseStoragePressureTool: ToolDefinition;
+export declare const diagnosticToolDefinitions: ToolDefinition[];