taurusdb-mcp 0.3.0 → 0.5.0-rc.1

package/dist/tools/query.js

@@ -12,23 +12,24 @@ async function inspectSql(toolName, sql, ctx, deps) {
         context: ctx,
     });
 }
-async function ensureConfirmation(decision, ctx, deps, taskId, confirmationToken) {
+async function ensureConfirmation(decision, ctx, deps, invokeContext, approvalToken) {
     if (!decision.requiresConfirmation) {
         return undefined;
     }
-    const responseMetadata = metadata(taskId, {
+    const responseMetadata = metadata(invokeContext.taskId, {
         sql_hash: decision.sqlHash,
         statement_type: statementTypeFromSql(decision.normalizedSql),
     });
-    if (confirmationToken) {
-        const validation = await deps.engine.validateConfirmation(confirmationToken, decision.normalizedSql, ctx);
+    if (approvalToken) {
+        const validation = await deps.engine.validateConfirmation(approvalToken, decision.normalizedSql, ctx);
         if (validation.valid) {
+            invokeContext.approvalActor = validation.actor;
             return undefined;
         }
         return formatError({
             code: ErrorCode.CONFIRMATION_INVALID,
-            message: validation.reason ?? "Confirmation token validation failed.",
-            summary: "The provided confirmation token is invalid for this SQL statement.",
+            message: validation.reason ?? "Approval token validation failed.",
+            summary: "The provided external approval is invalid for this SQL statement.",
             metadata: responseMetadata,
             details: {
                 reason_codes: validation.reasonCodes,
@@ -37,9 +38,10 @@ async function ensureConfirmation(decision, ctx, deps, taskId, confirmationToken
         });
     }
     const outcome = await deps.engine.handleConfirmation(decision, ctx);
-    if (outcome.status === "token_issued") {
+    if (outcome.status === "approval_required") {
         return formatConfirmationRequired({
-            confirmationToken: outcome.token,
+            approvalRequest: outcome.request,
+            requestId: outcome.requestId,
             metadata: responseMetadata,
             riskLevel: decision.riskLevel,
             sqlHash: decision.sqlHash,
@@ -53,7 +55,7 @@ export const executeReadonlySqlTool = {
     inputSchema: {
         ...contextInputShape,
         sql: requiredSqlSchema("Readonly SQL to execute."),
-        confirmation_token: optionalTokenSchema(),
+        approval_token: optionalTokenSchema(),
     },
     async handler(input, deps, context) {
         const sql = asRequiredString(input.sql, "sql");
@@ -76,7 +78,7 @@ export const executeReadonlySqlTool = {
                     },
                 });
             }
-            const confirmationResponse = await ensureConfirmation(decision, ctx, deps, context.taskId, asOptionalString(input.confirmation_token, "confirmation_token"));
+            const confirmationResponse = await ensureConfirmation(decision, ctx, deps, context, asOptionalString(input.approval_token, "approval_token"));
             if (confirmationResponse) {
                 return confirmationResponse;
             }
@@ -85,6 +87,9 @@ export const executeReadonlySqlTool = {
                 maxRows: decision.runtimeLimits.maxRows,
                 maxColumns: decision.runtimeLimits.maxColumns,
                 maxFieldChars: decision.runtimeLimits.maxFieldChars,
+                maxResultBytes: decision.runtimeLimits.maxResultBytes,
+                maxBlobBytes: decision.runtimeLimits.maxBlobBytes,
+                maskAllColumns: decision.runtimeLimits.maskAllColumns,
             });
             return formatSuccess(toPublicQueryResult(result), {
                 summary: summarizeRows(result.rowCount, result.truncated),
@@ -161,7 +166,7 @@ export const executeSqlTool = {
     inputSchema: {
         ...contextInputShape,
         sql: requiredSqlSchema("Mutation SQL to execute."),
-        confirmation_token: optionalTokenSchema(),
+        approval_token: optionalTokenSchema(),
     },
     async handler(input, deps, context) {
         const sql = asRequiredString(input.sql, "sql");
@@ -184,7 +189,7 @@ export const executeSqlTool = {
                     },
                 });
             }
-            const confirmationResponse = await ensureConfirmation(decision, ctx, deps, context.taskId, asOptionalString(input.confirmation_token, "confirmation_token"));
+            const confirmationResponse = await ensureConfirmation(decision, ctx, deps, context, asOptionalString(input.approval_token, "approval_token"));
             if (confirmationResponse) {
                 return confirmationResponse;
             }
@@ -219,5 +224,5 @@ function optionalTokenSchema() {
         .trim()
         .min(1)
         .optional()
-        .describe("Confirmation token returned by a previous guarded call when required.");
+        .describe("Externally signed approval token produced by `taurusdb-mcp approve`.");
 }

package/dist/tools/registry.d.ts

@@ -1,18 +1,23 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { type Config } from "taurusdb-core";
 import type { ServerDeps } from "../server.js";
 import { type ToolResponse } from "../utils/formatter.js";
 export type ToolDeps = ServerDeps;
 export type ToolInvokeContext = {
     taskId: string;
+    approvalActor?: string;
 };
 export interface ToolDefinition<I extends Record<string, unknown> = Record<string, unknown>, O = unknown> {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    annotations?: ToolAnnotations;
     handler: (input: I, deps: ToolDeps, context: ToolInvokeContext) => Promise<ToolResponse<O>>;
 }
 export declare const commonToolDefinitions: ToolDefinition[];
 export declare const capabilityToolDefinitions: ToolDefinition[];
+export declare const dynamicTargetToolDefinitions: ToolDefinition[];
 export declare const taurusToolDefinitions: ToolDefinition[];
+export declare const mutationToolDefinitions: ToolDefinition[];
 export declare function registerTools(server: McpServer, deps: ToolDeps, config: Config, tools?: ToolDefinition[]): void;

package/dist/tools/registry.js

@@ -1,6 +1,7 @@
+import { z } from "zod";
 import { generateTaskId, logger, withTaskContext, } from "taurusdb-core";
 import { executeReadonlySqlTool, executeSqlTool, explainSqlTool, } from "./query.js";
-import { describeTableTool, listDatabasesTool, listTablesTool, } from "./discovery.js";
+import { describeTableTool, listDataSourcesTool, listDatabasesTool, listTablesTool, } from "./discovery.js";
 import { showProcesslistTool } from "./processlist.js";
 import { pingTool } from "./ping.js";
 import { getKernelInfoTool, listTaurusFeaturesTool } from "./taurus/capability.js";
@@ -29,22 +30,56 @@ function registerOneTool(server, tool, deps) {
         const taskId = generateTaskId();
         return withTaskContext(taskId, async () => {
             const startedAt = Date.now();
+            const invokeContext = { taskId };
             logger.info({ tool: tool.name }, "Tool invocation started");
             try {
-                const response = await tool.handler(rawInput, deps, { taskId });
+                const invoke = () => tool.handler(rawInput, deps, invokeContext);
+                const response = deps.sessionCoordinator
+                    ? SESSION_MUTATION_TOOLS.has(tool.name)
+                        ? await deps.sessionCoordinator.runExclusive(invoke)
+                        : await deps.sessionCoordinator.runShared(invoke)
+                    : await invoke();
+                try {
+                    await writeAuditEvent(deps, tool.name, rawInput, response, invokeContext, Date.now() - startedAt);
+                }
+                catch (auditError) {
+                    logger.fatal({ err: auditError, tool: tool.name }, "Tool completed but audit persistence failed");
+                    return toMcpToolResult(formatError({
+                        code: ErrorCode.AUDIT_FAILED,
+                        message: "The tool completed but its audit event could not be persisted. Verify database state before retrying.",
+                        summary: "Audit persistence failed after tool execution.",
+                        metadata: response.metadata,
+                        retryable: false,
+                    }));
+                }
                 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);
+                const fallback = formatUnhandledToolError(error, taskId);
+                try {
+                    await writeAuditEvent(deps, tool.name, rawInput, fallback.structuredContent, invokeContext, Date.now() - startedAt);
+                }
+                catch (auditError) {
+                    logger.fatal({ err: auditError, tool: tool.name }, "Unhandled tool failure could not be audited");
+                }
+                return fallback;
             }
         });
     };
     if (typeof registrar.registerTool === "function") {
+        const readOnly = !PRIVILEGED_TOOL_NAMES.has(tool.name);
         registrar.registerTool(tool.name, {
             description: tool.description,
             inputSchema: tool.inputSchema,
+            outputSchema: TOOL_OUTPUT_SHAPE,
+            annotations: tool.annotations ?? {
+                readOnlyHint: readOnly,
+                destructiveHint: DATABASE_MUTATION_TOOLS.has(tool.name),
+                idempotentHint: readOnly || IDEMPOTENT_SESSION_MUTATION_TOOLS.has(tool.name),
+                openWorldHint: true,
+            },
         }, wrappedHandler);
         return;
     }
@@ -54,39 +89,124 @@ function registerOneTool(server, tool, deps) {
     }
     throw new Error("Unsupported MCP SDK version: expected `tool` or `registerTool` on McpServer.");
 }
+const SESSION_MUTATION_TOOLS = new Set([
+    "set_cloud_region",
+    "begin_sql_login",
+    "clear_sql_credentials",
+    "set_default_database",
+    "select_cloud_taurus_instance",
+]);
+const PRIVILEGED_TOOL_NAMES = new Set([
+    ...SESSION_MUTATION_TOOLS,
+    "execute_sql",
+    "restore_recycle_bin_table",
+]);
+const DATABASE_MUTATION_TOOLS = new Set([
+    "execute_sql",
+    "restore_recycle_bin_table",
+]);
+const IDEMPOTENT_SESSION_MUTATION_TOOLS = new Set([
+    "set_cloud_region",
+    "clear_sql_credentials",
+    "set_default_database",
+    "select_cloud_taurus_instance",
+]);
+const TOOL_OUTPUT_SHAPE = {
+    ok: z.boolean(),
+    summary: z.string(),
+    data: z.unknown().optional(),
+    error: z.unknown().optional(),
+    metadata: z.record(z.unknown()),
+};
+async function writeAuditEvent(deps, tool, input, response, context, durationMs) {
+    if (!deps.auditWriter) {
+        return;
+    }
+    const datasource = typeof input.datasource === "string"
+        ? input.datasource
+        : deps.config.defaultDatasource ?? (await deps.profileLoader.getDefault());
+    const profile = datasource ? await deps.profileLoader.get(datasource) : undefined;
+    const target = datasource
+        ? deps.profileLoader.getRuntimeTarget(datasource)
+        : undefined;
+    const errorCode = response.error?.code;
+    const decision = response.ok
+        ? "allowed"
+        : errorCode === ErrorCode.BLOCKED_SQL
+            ? "blocked"
+            : errorCode === ErrorCode.CONFIRMATION_REQUIRED
+                ? "approval_required"
+                : errorCode === ErrorCode.CONFIRMATION_INVALID
+                    ? "approval_denied"
+                    : "failed";
+    await deps.auditWriter.write({
+        timestamp: new Date().toISOString(),
+        task_id: context.taskId,
+        tool,
+        actor: context.approvalActor ??
+            (() => {
+                const client = deps.clientIdentityProvider?.();
+                return client
+                    ? `mcp:${client.name}@${client.version}`
+                    : "unattributed-mcp-client";
+            })(),
+        datasource,
+        database: typeof input.database === "string" ? input.database : profile?.database,
+        host: profile?.host,
+        port: profile?.port,
+        project_id: deps.config.cloud.projectId,
+        instance_id: target?.instanceId ?? profile?.instanceId ?? deps.config.cloud.instanceId,
+        node_id: target?.nodeId ?? profile?.nodeId ?? deps.config.cloud.nodeId,
+        sql_hash: response.metadata.sql_hash,
+        raw_sql: deps.config.audit.includeRawSql && typeof input.sql === "string"
+            ? input.sql
+            : undefined,
+        decision,
+        outcome: response.ok ? "success" : "error",
+        error_code: errorCode,
+        duration_ms: durationMs,
+    });
+}
 export const commonToolDefinitions = [
     pingTool,
+    listDataSourcesTool,
     listDatabasesTool,
     listTablesTool,
     describeTableTool,
     showProcesslistTool,
     executeReadonlySqlTool,
     explainSqlTool,
-    executeSqlTool,
 ];
 export const capabilityToolDefinitions = [
     getKernelInfoTool,
     listTaurusFeaturesTool,
-    setCloudRegionTool,
     getSessionBindingTool,
+    listCloudTaurusInstancesTool,
+];
+export const dynamicTargetToolDefinitions = [
+    setCloudRegionTool,
     beginSqlLoginTool,
     clearSqlCredentialsTool,
     setDefaultDatabaseTool,
-    listCloudTaurusInstancesTool,
     selectCloudTaurusInstanceTool,
 ];
 export const taurusToolDefinitions = [
     explainSqlEnhancedTool,
     flashbackQueryTool,
     listRecycleBinTool,
+];
+export const mutationToolDefinitions = [
+    executeSqlTool,
     restoreRecycleBinTableTool,
 ];
-function buildDefaultToolDefinitions(_config) {
+function buildDefaultToolDefinitions(config) {
     return [
         ...commonToolDefinitions,
         ...capabilityToolDefinitions,
+        ...(config.security.dynamicTargetsEnabled ? dynamicTargetToolDefinitions : []),
         ...diagnosticToolDefinitions,
         ...taurusToolDefinitions,
+        ...(config.security.mutationsEnabled ? mutationToolDefinitions : []),
     ];
 }
 export function registerTools(server, deps, config, tools = buildDefaultToolDefinitions(config)) {

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

@@ -6,31 +6,57 @@ 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;
+function clearCloudSelection(config, deps) {
+    config.cloud.projectId = undefined;
+    config.cloud.instanceId = undefined;
+    config.cloud.nodeId = undefined;
+    config.slowSqlSource.taurusApi.projectId = undefined;
+    config.slowSqlSource.taurusApi.instanceId = undefined;
+    config.slowSqlSource.taurusApi.nodeId = undefined;
+    config.slowSqlSource.das.projectId = undefined;
+    config.slowSqlSource.das.instanceId = undefined;
+    config.metricsSource.ces.projectId = undefined;
+    config.metricsSource.ces.instanceId = undefined;
+    config.metricsSource.ces.nodeId = undefined;
     deps.profileLoader.clearAllRuntimeTargets();
 }
-async function reloadEngine(deps) {
+async function snapshotRuntimeTargets(deps) {
+    const profiles = await deps.profileLoader.load();
+    return new Map([...profiles.keys()].flatMap((name) => {
+        const target = deps.profileLoader.getRuntimeTarget(name);
+        return target ? [[name, target]] : [];
+    }));
+}
+function restoreRuntimeTargets(deps, targets) {
+    deps.profileLoader.clearAllRuntimeTargets();
+    for (const [name, target] of targets) {
+        deps.profileLoader.setRuntimeTarget(name, target);
+    }
+}
+async function reloadEngine(deps, nextConfig) {
     const nextEngine = await TaurusDBEngine.create({
-        config: deps.config,
+        config: nextConfig,
         profileLoader: deps.profileLoader,
     });
     const previousEngine = deps.engine;
+    deps.config = nextConfig;
     deps.engine = nextEngine;
     if (previousEngine?.close) {
         await previousEngine.close();
     }
 }
+async function updateSessionState(deps, mutate) {
+    const nextConfig = structuredClone(deps.config);
+    const previousTargets = await snapshotRuntimeTargets(deps);
+    try {
+        await mutate(nextConfig);
+        await reloadEngine(deps, nextConfig);
+    }
+    catch (error) {
+        restoreRuntimeTargets(deps, previousTargets);
+        throw error;
+    }
+}
 async function resolveBindingDatasource(deps, explicit) {
     const trimmed = typeof explicit === "string" ? explicit.trim() : "";
     if (trimmed) {
@@ -39,7 +65,7 @@ async function resolveBindingDatasource(deps, explicit) {
     return deps.engine.getDefaultDataSource();
 }
 function selectInstanceAddress(input) {
-    return input.publicIps[0] ?? input.privateIps[0] ?? input.hostnames[0];
+    return input.privateIps[0] ?? input.hostnames[0] ?? input.publicIps[0];
 }
 function normalizePort(port) {
     if (typeof port === "number" && Number.isFinite(port)) {
@@ -71,19 +97,22 @@ export const setCloudRegionTool = {
             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);
+            await updateSessionState(deps, (nextConfig) => {
+                const domainSuffix = nextConfig.cloud.domainSuffix ?? "myhuaweicloud.com";
+                nextConfig.cloud.region = region;
+                nextConfig.cloud.apiEndpoint = buildHuaweiCloudEndpoint("gaussdb", region, domainSuffix);
+                nextConfig.cloud.iamEndpoint = buildHuaweiCloudEndpoint("iam", region, domainSuffix);
+                nextConfig.cloud.kmsEndpoint = buildHuaweiCloudEndpoint("kms", region, domainSuffix);
+                nextConfig.slowSqlSource.taurusApi.endpoint = buildHuaweiCloudEndpoint("gaussdb", region, domainSuffix);
+                nextConfig.slowSqlSource.das.endpoint = buildHuaweiCloudEndpoint("das", region, domainSuffix);
+                nextConfig.metricsSource.ces.endpoint = buildHuaweiCloudEndpoint("ces", region, domainSuffix);
+                clearCloudSelection(nextConfig, deps);
+            });
             return formatSuccess({
                 region,
                 api_endpoint: deps.config.cloud.apiEndpoint,
                 iam_endpoint: deps.config.cloud.iamEndpoint,
+                kms_endpoint: deps.config.cloud.kmsEndpoint,
             }, {
                 summary: `Cloud region switched to ${region}.`,
                 metadata: metadata(context.taskId),
@@ -136,14 +165,15 @@ export const setDefaultDatabaseTool = {
                 throw new ToolInputError(`Datasource "${datasource}" was not found.`);
             }
             const currentTarget = deps.profileLoader.getRuntimeTarget(datasource);
-            deps.profileLoader.setRuntimeTarget(datasource, {
-                host: currentTarget?.host ?? profile.host,
-                port: currentTarget?.port ?? profile.port,
-                instanceId: currentTarget?.instanceId,
-                nodeId: currentTarget?.nodeId,
-                database,
+            await updateSessionState(deps, () => {
+                deps.profileLoader.setRuntimeTarget(datasource, {
+                    host: currentTarget?.host ?? profile.host,
+                    port: currentTarget?.port ?? profile.port,
+                    instanceId: currentTarget?.instanceId,
+                    nodeId: currentTarget?.nodeId,
+                    database,
+                });
             });
-            await reloadEngine(deps);
             return formatSuccess({
                 datasource,
                 database,
@@ -181,8 +211,9 @@ export const clearSqlCredentialsTool = {
             if (!profile) {
                 throw new ToolInputError(`Datasource "${datasource}" was not found.`);
             }
-            deps.profileLoader.clearRuntimeUser(datasource);
-            await reloadEngine(deps);
+            await updateSessionState(deps, () => {
+                deps.profileLoader.clearRuntimeUser(datasource);
+            });
             return formatSuccess({
                 datasource,
             }, {
@@ -278,29 +309,30 @@ export const selectCloudTaurusInstanceTool = {
             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);
+            await updateSessionState(deps, (nextConfig) => {
+                nextConfig.cloud.projectId = projectId;
+                nextConfig.cloud.instanceId = matched.id;
+                nextConfig.cloud.nodeId = matched.primaryNodeId;
+                nextConfig.slowSqlSource.taurusApi.projectId = projectId;
+                nextConfig.slowSqlSource.taurusApi.instanceId = matched.id;
+                nextConfig.slowSqlSource.taurusApi.nodeId = matched.primaryNodeId;
+                nextConfig.slowSqlSource.das.projectId = projectId;
+                nextConfig.slowSqlSource.das.instanceId = matched.id;
+                nextConfig.metricsSource.ces.projectId = projectId;
+                nextConfig.metricsSource.ces.instanceId = matched.id;
+                nextConfig.metricsSource.ces.nodeId = matched.primaryNodeId;
+                if (boundDatasource && selectedHost) {
+                    deps.profileLoader.setRuntimeTarget(boundDatasource, {
+                        host: selectedHost,
+                        port: selectedPort,
+                        instanceId: matched.id,
+                        nodeId: matched.primaryNodeId,
+                    });
+                }
+            });
             return formatSuccess({
                 project_id: projectId,
                 instance_id: matched.id,

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

@@ -6,4 +6,5 @@ export declare const diagnoseSlowQueryTool: ToolDefinition;
 export declare const diagnoseConnectionSpikeTool: ToolDefinition;
 export declare const diagnoseLockContentionTool: ToolDefinition;
 export declare const diagnoseStoragePressureTool: ToolDefinition;
+export declare const diagnoseReplicationLagTool: ToolDefinition;
 export declare const diagnosticToolDefinitions: ToolDefinition[];

package/dist/tools/taurus/diagnostics.js

@@ -303,6 +303,36 @@ export const diagnoseStoragePressureTool = {
         }
     },
 };
+export const diagnoseReplicationLagTool = {
+    name: "diagnose_replication_lag",
+    description: "Diagnose current replica delay and replication worker state using a bounded, readonly replication-status snapshot.",
+    inputSchema: {
+        ...diagnosticBaseInputShape,
+        replica_id: diagnosticString("Optional replica or source server id to focus on."),
+        channel: diagnosticString("Optional replication channel name to focus on."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const diagnosticInput = {
+                ...parseBaseInput(input),
+                replicaId: asOptionalString(input.replica_id, "replica_id"),
+                channel: asOptionalString(input.channel, "channel"),
+            };
+            const result = await deps.engine.diagnoseReplicationLag(diagnosticInput, ctx);
+            return formatSuccess(toPublicDiagnosticResult(result), {
+                summary: summarizeDiagnostic("Replication-lag diagnosis", result.status),
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "diagnose_replication_lag",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
 export const diagnosticToolDefinitions = [
     diagnoseServiceLatencyTool,
     diagnoseDbHotspotTool,
@@ -310,6 +340,7 @@ export const diagnosticToolDefinitions = [
     diagnoseSlowQueryTool,
     diagnoseConnectionSpikeTool,
     diagnoseLockContentionTool,
+    diagnoseReplicationLagTool,
     diagnoseStoragePressureTool,
 ];
 function diagnosticString(description) {

package/dist/tools/taurus/recycle-bin.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { buildRestoreRecycleBinTableSql, } from "taurusdb-core";
+import { buildRestoreRecycleBinTableSql, normalizeSql, sqlHash, } from "taurusdb-core";
 import { ErrorCode, formatConfirmationRequired, formatError, formatSuccess, } from "../../utils/formatter.js";
 import { formatToolError } from "../error-handling.js";
 import { asOptionalString, asRequiredString, contextInputShape, metadata, resolveContext, summarizeMutation, summarizeRows, toPublicMutationResult, toPublicQueryResult, } from "../common.js";
@@ -70,12 +70,12 @@ export const restoreRecycleBinTableTool = {
             .min(1)
             .optional()
             .describe("Destination table. Required for insert_select; optional with native_restore when renaming on restore."),
-        confirmation_token: z
+        approval_token: z
             .string()
             .trim()
             .min(1)
             .optional()
-            .describe("Confirmation token returned by the first guarded restore call."),
+            .describe("Externally signed approval token produced by `taurusdb-mcp approve`."),
     },
     async handler(input, deps, context) {
         const restoreInput = {
@@ -89,15 +89,16 @@ export const restoreRecycleBinTableTool = {
             const sql = buildRestoreRecycleBinTableSql(restoreInput);
             const responseMetadata = metadata(context.taskId, {
                 statement_type: restoreInput.method === "insert_select" ? "insert" : "unknown",
+                sql_hash: sqlHash(normalizeSql(sql)),
             });
-            const confirmationToken = asOptionalString(input.confirmation_token, "confirmation_token");
-            if (confirmationToken) {
-                const validation = await deps.engine.validateConfirmation(confirmationToken, sql, ctx);
+            const approvalToken = asOptionalString(input.approval_token, "approval_token");
+            if (approvalToken) {
+                const validation = await deps.engine.validateConfirmation(approvalToken, sql, ctx);
                 if (!validation.valid) {
                     return formatError({
                         code: ErrorCode.CONFIRMATION_INVALID,
-                        message: validation.reason ?? "Confirmation token validation failed.",
-                        summary: "The provided confirmation token is invalid for this recycle bin restore.",
+                        message: validation.reason ?? "Approval token validation failed.",
+                        summary: "The provided external approval is invalid for this recycle bin restore.",
                         metadata: responseMetadata,
                         details: {
                             reason_codes: validation.reasonCodes,
@@ -105,19 +106,21 @@ export const restoreRecycleBinTableTool = {
                         },
                     });
                 }
+                context.approvalActor = validation.actor;
             }
             else {
-                const token = await deps.engine.issueConfirmation({
+                const approval = await deps.engine.issueConfirmation({
                     sql,
                     context: ctx,
                     riskLevel: "high",
                 });
                 return formatConfirmationRequired({
-                    confirmationToken: token.token,
+                    approvalRequest: approval.request,
+                    requestId: approval.requestId,
                     metadata: responseMetadata,
                     riskLevel: "high",
                     summary: "Recycle bin restore requires explicit confirmation.",
-                    message: "Re-run restore_recycle_bin_table with the same input and confirmation_token to continue.",
+                    message: "An external operator must sign approval_request before retrying with approval_token.",
                 });
             }
             const result = await deps.engine.restoreRecycleBinTable(restoreInput, ctx);
@@ -132,6 +135,7 @@ export const restoreRecycleBinTableTool = {
                 summary: summarizeMutation(result.affectedRows),
                 metadata: metadata(context.taskId, {
                     statement_type: restoreInput.method === "insert_select" ? "insert" : "unknown",
+                    sql_hash: sqlHash(normalizeSql(sql)),
                     duration_ms: result.durationMs,
                 }),
             });