taurusdb-mcp 0.1.0

package/dist/tools/discovery.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { formatSuccess } from "../utils/formatter.js";
+import { formatToolError } from "./error-handling.js";
+import { contextInputShape, metadata, requireDatabase, resolveContext, toPublicDataSourceInfo, toPublicDatabaseInfo, toPublicTableInfo, toPublicTableSchema, asRequiredString, } from "./common.js";
+export const listDataSourcesTool = {
+    name: "list_data_sources",
+    description: "List all configured datasource profiles and indicate the current default datasource.",
+    inputSchema: {},
+    async handler(_input, deps, context) {
+        try {
+            const [items, defaultDatasource] = await Promise.all([
+                deps.engine.listDataSources(),
+                deps.engine.getDefaultDataSource(),
+            ]);
+            return formatSuccess({
+                items: items.map(toPublicDataSourceInfo),
+                default_datasource: defaultDatasource,
+            }, {
+                summary: `Resolved ${items.length} datasource profiles.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "list_data_sources",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const listDatabasesTool = {
+    name: "list_databases",
+    description: "List databases available on the selected datasource.",
+    inputSchema: contextInputShape,
+    async handler(input, deps, context) {
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const items = await deps.engine.listDatabases(ctx);
+            return formatSuccess({
+                datasource: ctx.datasource,
+                database: ctx.database,
+                items: items.map(toPublicDatabaseInfo),
+            }, {
+                summary: `Resolved ${items.length} databases from datasource ${ctx.datasource}.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "list_databases",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const listTablesTool = {
+    name: "list_tables",
+    description: "List tables or views in the selected database.",
+    inputSchema: contextInputShape,
+    async handler(input, deps, context) {
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const database = requireDatabase(input.database, ctx);
+            const items = await deps.engine.listTables(ctx, database);
+            return formatSuccess({
+                datasource: ctx.datasource,
+                database,
+                items: items.map(toPublicTableInfo),
+            }, {
+                summary: `Resolved ${items.length} tables from ${database}.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "list_tables",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const describeTableTool = {
+    name: "describe_table",
+    description: "Describe a table, including columns, indexes, primary key, and engine hints.",
+    inputSchema: {
+        ...contextInputShape,
+        table: asRequiredStringSchema("Table name to describe."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const database = requireDatabase(input.database, ctx);
+            const table = asRequiredString(input.table, "table");
+            const schema = await deps.engine.describeTable(ctx, database, table);
+            return formatSuccess({
+                datasource: ctx.datasource,
+                ...toPublicTableSchema(schema),
+            }, {
+                summary: `Described ${database}.${table}.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "describe_table",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+function asRequiredStringSchema(description) {
+    return z.string().trim().min(1).describe(description);
+}

package/dist/tools/error-handling.d.ts

@@ -0,0 +1,10 @@
+import { type ResponseMetadata, type ToolResponse } from "../utils/formatter.js";
+export declare class ToolInputError extends Error {
+    constructor(message: string);
+}
+type ToolErrorContext = {
+    action: string;
+    metadata: ResponseMetadata;
+};
+export declare function formatToolError(error: unknown, context: ToolErrorContext): ToolResponse;
+export {};

package/dist/tools/error-handling.js

@@ -0,0 +1,122 @@
+import { ConnectionPoolError, DatasourceResolutionError, FlashbackNoViewError, SchemaIntrospectionError, UnsupportedFeatureError, } from "taurusdb-core";
+import { ErrorCode, formatError, } from "../utils/formatter.js";
+export class ToolInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ToolInputError";
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function timeoutLikely(error) {
+    return /timeout|timed out/i.test(messageOf(error));
+}
+function cancelledLikely(error) {
+    return /cancelled|canceled/i.test(messageOf(error));
+}
+function detailsOf(error) {
+    if (!error || typeof error !== "object" || !("details" in error)) {
+        return undefined;
+    }
+    const details = error.details;
+    return details && typeof details === "object" && !Array.isArray(details)
+        ? details
+        : undefined;
+}
+export function formatToolError(error, context) {
+    if (error instanceof ToolInputError) {
+        return formatError({
+            code: ErrorCode.INVALID_INPUT,
+            message: error.message,
+            summary: `${context.action} failed due to invalid input.`,
+            metadata: context.metadata,
+        });
+    }
+    if (error instanceof DatasourceResolutionError) {
+        if (error.code === "DATASOURCE_NOT_FOUND") {
+            return formatError({
+                code: ErrorCode.DATASOURCE_NOT_FOUND,
+                message: `${error.message} Verify the active datasource template or pass an explicit datasource name.`,
+                summary: `${context.action} failed because datasource could not be resolved.`,
+                metadata: context.metadata,
+            });
+        }
+        return formatError({
+            code: ErrorCode.INVALID_INPUT,
+            message: error.message,
+            summary: `${context.action} failed due to invalid input.`,
+            metadata: context.metadata,
+        });
+    }
+    if (error instanceof SchemaIntrospectionError) {
+        if (error.code === "INVALID_INTROSPECTION_INPUT") {
+            return formatError({
+                code: ErrorCode.INVALID_INPUT,
+                message: error.message,
+                summary: `${context.action} failed due to invalid schema input.`,
+                metadata: context.metadata,
+            });
+        }
+        return formatError({
+            code: ErrorCode.CONNECTION_FAILED,
+            message: error.message,
+            summary: `${context.action} failed because schema adapter is unavailable.`,
+            metadata: context.metadata,
+        });
+    }
+    if (error instanceof ConnectionPoolError) {
+        return formatError({
+            code: ErrorCode.CONNECTION_FAILED,
+            message: error.message,
+            summary: `${context.action} failed due to database connection issue.`,
+            metadata: context.metadata,
+            details: detailsOf(error),
+        });
+    }
+    if (error instanceof UnsupportedFeatureError) {
+        return formatError({
+            code: ErrorCode.UNSUPPORTED_FEATURE,
+            message: error.message,
+            summary: "The requested TaurusDB feature is not available on this instance.",
+            metadata: context.metadata,
+            details: {
+                feature: error.feature,
+                required_version: error.requiredVersion,
+                current_version: error.currentVersion,
+            },
+        });
+    }
+    if (error instanceof FlashbackNoViewError) {
+        return formatError({
+            code: ErrorCode.CONNECTION_FAILED,
+            message: error.message,
+            summary: "No historical flashback view was available for the requested timestamp.",
+            metadata: context.metadata,
+            details: detailsOf(error),
+        });
+    }
+    if (cancelledLikely(error)) {
+        return formatError({
+            code: ErrorCode.QUERY_CANCELLED,
+            message: messageOf(error),
+            summary: `${context.action} was cancelled.`,
+            metadata: context.metadata,
+        });
+    }
+    if (timeoutLikely(error)) {
+        return formatError({
+            code: ErrorCode.QUERY_TIMEOUT,
+            message: messageOf(error),
+            summary: `${context.action} timed out.`,
+            metadata: context.metadata,
+        });
+    }
+    return formatError({
+        code: ErrorCode.CONNECTION_FAILED,
+        message: messageOf(error),
+        summary: `${context.action} failed unexpectedly.`,
+        metadata: context.metadata,
+        details: detailsOf(error),
+    });
+}

package/dist/tools/ping.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "./registry.js";
+export declare const pingTool: ToolDefinition<Record<string, unknown>, {
+    value: string;
+}>;

package/dist/tools/ping.js

@@ -0,0 +1,13 @@
+import { formatSuccess } from "../utils/formatter.js";
+const PING_DESCRIPTION = "Connectivity smoke test. Returns `pong` when the server is alive.";
+export const pingTool = {
+    name: "ping",
+    description: PING_DESCRIPTION,
+    inputSchema: {},
+    async handler(_input, deps, context) {
+        return formatSuccess({ value: deps.pingResponse }, {
+            summary: deps.pingResponse,
+            metadata: { task_id: context.taskId },
+        });
+    },
+};

package/dist/tools/processlist.d.ts

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

package/dist/tools/processlist.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { formatSuccess } from "../utils/formatter.js";
+import { formatToolError, ToolInputError } from "./error-handling.js";
+import { asOptionalBoolean, asOptionalPositiveInteger, asOptionalString, contextInputShape, metadata, resolveContext, toPublicQueryResult, } from "./common.js";
+function summarizeProcesslistRows(rowCount, truncated) {
+    if (rowCount === 1) {
+        return truncated
+            ? "Returned 1 processlist row (truncated)."
+            : "Returned 1 processlist row.";
+    }
+    return truncated
+        ? `Returned ${rowCount} processlist rows (truncated).`
+        : `Returned ${rowCount} processlist rows.`;
+}
+export const showProcesslistTool = {
+    name: "show_processlist",
+    description: "Show current MySQL processlist rows with safe defaults for connection and lock troubleshooting.",
+    inputSchema: {
+        ...contextInputShape,
+        user: optionalStringSchema("Optional user to focus on."),
+        host: optionalStringSchema("Optional host or client IP prefix to focus on."),
+        session_database: optionalStringSchema("Optional processlist DB value to focus on."),
+        command: optionalStringSchema("Optional command to focus on, such as Query or Sleep."),
+        min_time_seconds: nonNegativeIntegerSchema("Only include rows whose TIME value is at least this many seconds.").optional(),
+        max_rows: positiveIntegerSchema("Maximum number of processlist rows to return.")
+            .max(100)
+            .optional()
+            .default(20),
+        include_idle: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Whether to include Sleep sessions."),
+        include_system: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Whether to include system user sessions."),
+        include_info: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Whether to include truncated SQL text from the INFO column."),
+        info_max_chars: positiveIntegerSchema("Maximum length of INFO text to return when include_info is true.")
+            .max(2048)
+            .optional()
+            .default(256),
+    },
+    async handler(input, deps, context) {
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const user = asOptionalString(input.user, "user");
+            const host = asOptionalString(input.host, "host");
+            const sessionDatabase = asOptionalString(input.session_database, "session_database");
+            const command = asOptionalString(input.command, "command");
+            const minTimeSeconds = asOptionalNonNegativeInteger(input.min_time_seconds, "min_time_seconds") ?? 0;
+            const maxRows = asOptionalPositiveInteger(input.max_rows, "max_rows") ?? 20;
+            const includeIdle = asOptionalBoolean(input.include_idle, "include_idle") ?? false;
+            const includeSystem = asOptionalBoolean(input.include_system, "include_system") ?? false;
+            const includeInfo = asOptionalBoolean(input.include_info, "include_info") ?? false;
+            const infoMaxChars = asOptionalPositiveInteger(input.info_max_chars, "info_max_chars") ??
+                256;
+            const result = await deps.engine.showProcesslist({
+                user,
+                host,
+                sessionDatabase,
+                command,
+                minTimeSeconds,
+                maxRows,
+                includeIdle,
+                includeSystem,
+                includeInfo,
+                infoMaxChars,
+            }, ctx);
+            return formatSuccess({
+                datasource: ctx.datasource,
+                filters: {
+                    user,
+                    host,
+                    session_database: sessionDatabase,
+                    command,
+                    min_time_seconds: minTimeSeconds || undefined,
+                    include_idle: includeIdle,
+                    include_system: includeSystem,
+                    include_info: includeInfo,
+                    max_rows: maxRows,
+                },
+                ...toPublicQueryResult(result),
+            }, {
+                summary: summarizeProcesslistRows(result.rowCount, result.truncated),
+                metadata: metadata(context.taskId, {
+                    duration_ms: result.durationMs,
+                }),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "show_processlist",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+function optionalStringSchema(description) {
+    return z.string().trim().min(1).optional().describe(description);
+}
+function positiveIntegerSchema(description) {
+    return z.number().int().positive().describe(description);
+}
+function nonNegativeIntegerSchema(description) {
+    return z.number().int().nonnegative().describe(description);
+}
+function asOptionalNonNegativeInteger(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new ToolInputError(`Invalid ${fieldName}: expected a non-negative integer.`);
+    }
+    return value;
+}

package/dist/tools/query.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "./registry.js";
+export declare const executeReadonlySqlTool: ToolDefinition;
+export declare const explainSqlTool: ToolDefinition;
+export declare const executeSqlTool: ToolDefinition;

package/dist/tools/query.js

@@ -0,0 +1,224 @@
+import { z } from "zod";
+import { ErrorCode, formatBlocked, formatConfirmationRequired, formatError, formatSuccess } from "../utils/formatter.js";
+import { formatToolError } from "./error-handling.js";
+import { asOptionalString, asRequiredString, contextInputShape, metadata, resolveContext, statementTypeFromSql, summarizeMutation, summarizeRows, toPublicExplainResult, toPublicMutationResult, toPublicQueryResult, } from "./common.js";
+function blockedReason(decision) {
+    return decision.riskHints[0] ?? "The SQL statement is blocked by safety policy.";
+}
+async function inspectSql(toolName, sql, ctx, deps) {
+    return deps.engine.inspectSql({
+        toolName,
+        sql,
+        context: ctx,
+    });
+}
+async function ensureConfirmation(sql, decision, ctx, deps, taskId, confirmationToken) {
+    if (!decision.requiresConfirmation) {
+        return undefined;
+    }
+    const responseMetadata = metadata(taskId, {
+        sql_hash: decision.sqlHash,
+        statement_type: statementTypeFromSql(sql),
+    });
+    if (confirmationToken) {
+        const validation = await deps.engine.validateConfirmation(confirmationToken, sql, ctx);
+        if (validation.valid) {
+            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.",
+            metadata: responseMetadata,
+            details: {
+                reason_codes: validation.reasonCodes,
+                risk_hints: validation.riskHints,
+            },
+        });
+    }
+    const outcome = await deps.engine.handleConfirmation(decision, ctx);
+    if (outcome.status === "token_issued") {
+        return formatConfirmationRequired({
+            confirmationToken: outcome.token,
+            metadata: responseMetadata,
+            riskLevel: decision.riskLevel,
+            sqlHash: decision.sqlHash,
+        });
+    }
+    return undefined;
+}
+export const executeReadonlySqlTool = {
+    name: "execute_readonly_sql",
+    description: "Execute readonly SQL such as SELECT, SHOW, EXPLAIN, or DESCRIBE with guardrail enforcement.",
+    inputSchema: {
+        ...contextInputShape,
+        sql: requiredSqlSchema("Readonly SQL to execute."),
+        confirmation_token: optionalTokenSchema(),
+    },
+    async handler(input, deps, context) {
+        const sql = asRequiredString(input.sql, "sql");
+        const statementType = statementTypeFromSql(sql);
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const decision = await inspectSql("execute_readonly_sql", sql, ctx, deps);
+            const baseMetadata = metadata(context.taskId, {
+                sql_hash: decision.sqlHash,
+                statement_type: statementType,
+            });
+            if (decision.action === "block") {
+                return formatBlocked({
+                    reason: blockedReason(decision),
+                    metadata: baseMetadata,
+                    details: {
+                        risk_level: decision.riskLevel,
+                        reason_codes: decision.reasonCodes,
+                        risk_hints: decision.riskHints,
+                    },
+                });
+            }
+            const confirmationResponse = await ensureConfirmation(sql, decision, ctx, deps, context.taskId, asOptionalString(input.confirmation_token, "confirmation_token"));
+            if (confirmationResponse) {
+                return confirmationResponse;
+            }
+            const result = await deps.engine.executeReadonly(sql, ctx, {
+                timeoutMs: decision.runtimeLimits.timeoutMs,
+                maxRows: decision.runtimeLimits.maxRows,
+                maxColumns: decision.runtimeLimits.maxColumns,
+                maxFieldChars: decision.runtimeLimits.maxFieldChars,
+            });
+            return formatSuccess(toPublicQueryResult(result), {
+                summary: summarizeRows(result.rowCount, result.truncated),
+                metadata: metadata(context.taskId, {
+                    sql_hash: decision.sqlHash,
+                    statement_type: statementType,
+                    duration_ms: result.durationMs,
+                }),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "execute_readonly_sql",
+                metadata: metadata(context.taskId, {
+                    statement_type: statementType,
+                }),
+            });
+        }
+    },
+};
+export const explainSqlTool = {
+    name: "explain_sql",
+    description: "Run EXPLAIN for a SQL statement and return plan analysis together with guardrail hints.",
+    inputSchema: {
+        ...contextInputShape,
+        sql: requiredSqlSchema("SQL statement to analyze with EXPLAIN."),
+    },
+    async handler(input, deps, context) {
+        const sql = asRequiredString(input.sql, "sql");
+        const statementType = statementTypeFromSql(sql);
+        try {
+            const ctx = await resolveContext(input, deps, context, true);
+            const decision = await inspectSql("explain_sql", sql, ctx, deps);
+            const baseMetadata = metadata(context.taskId, {
+                sql_hash: decision.sqlHash,
+                statement_type: statementType,
+            });
+            if (decision.action === "block") {
+                return formatBlocked({
+                    reason: blockedReason(decision),
+                    metadata: baseMetadata,
+                    details: {
+                        risk_level: decision.riskLevel,
+                        reason_codes: decision.reasonCodes,
+                        risk_hints: decision.riskHints,
+                    },
+                });
+            }
+            const result = await deps.engine.explain(sql, ctx);
+            return formatSuccess(toPublicExplainResult(result, decision), {
+                summary: decision.requiresConfirmation
+                    ? "Explain generated. Executing this SQL would require explicit confirmation."
+                    : "Explain generated.",
+                metadata: metadata(context.taskId, {
+                    sql_hash: decision.sqlHash,
+                    statement_type: statementType,
+                    duration_ms: result.durationMs,
+                }),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "explain_sql",
+                metadata: metadata(context.taskId, {
+                    statement_type: statementType,
+                }),
+            });
+        }
+    },
+};
+export const executeSqlTool = {
+    name: "execute_sql",
+    description: "Execute mutation SQL such as INSERT, UPDATE, or DELETE when mutations are explicitly enabled.",
+    inputSchema: {
+        ...contextInputShape,
+        sql: requiredSqlSchema("Mutation SQL to execute."),
+        confirmation_token: optionalTokenSchema(),
+    },
+    exposeWhen: (config) => config.enableMutations,
+    async handler(input, deps, context) {
+        const sql = asRequiredString(input.sql, "sql");
+        const statementType = statementTypeFromSql(sql);
+        try {
+            const ctx = await resolveContext(input, deps, context, false);
+            const decision = await inspectSql("execute_sql", sql, ctx, deps);
+            const baseMetadata = metadata(context.taskId, {
+                sql_hash: decision.sqlHash,
+                statement_type: statementType,
+            });
+            if (decision.action === "block") {
+                return formatBlocked({
+                    reason: blockedReason(decision),
+                    metadata: baseMetadata,
+                    details: {
+                        risk_level: decision.riskLevel,
+                        reason_codes: decision.reasonCodes,
+                        risk_hints: decision.riskHints,
+                    },
+                });
+            }
+            const confirmationResponse = await ensureConfirmation(sql, decision, ctx, deps, context.taskId, asOptionalString(input.confirmation_token, "confirmation_token"));
+            if (confirmationResponse) {
+                return confirmationResponse;
+            }
+            const result = await deps.engine.executeMutation(sql, ctx, {
+                timeoutMs: decision.runtimeLimits.timeoutMs,
+            });
+            return formatSuccess(toPublicMutationResult(result), {
+                summary: summarizeMutation(result.affectedRows),
+                metadata: metadata(context.taskId, {
+                    sql_hash: decision.sqlHash,
+                    statement_type: statementType,
+                    duration_ms: result.durationMs,
+                }),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "execute_sql",
+                metadata: metadata(context.taskId, {
+                    statement_type: statementType,
+                }),
+            });
+        }
+    },
+};
+function requiredSqlSchema(description) {
+    return z.string().trim().min(1).describe(description);
+}
+function optionalTokenSchema() {
+    return z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Confirmation token returned by a previous guarded call when required.");
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,22 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type FeatureMatrix, type KernelInfo, type Config } from "taurusdb-core";
+import type { ServerDeps } from "../server.js";
+import { type ToolResponse } from "../utils/formatter.js";
+export type ToolDeps = ServerDeps;
+export interface ToolRegistrationProbe {
+    kernelInfo?: KernelInfo;
+    features?: FeatureMatrix;
+}
+export type ToolInvokeContext = {
+    taskId: string;
+};
+export interface ToolDefinition<I extends Record<string, unknown> = Record<string, unknown>, O = unknown> {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (input: I, deps: ToolDeps, context: ToolInvokeContext) => Promise<ToolResponse<O>>;
+    exposeWhen?: (config: Config) => boolean;
+}
+export declare const commonToolDefinitions: ToolDefinition[];
+export declare const capabilityToolDefinitions: ToolDefinition[];
+export declare function registerTools(server: McpServer, deps: ToolDeps, config: Config, probeOrTools?: ToolRegistrationProbe | ToolDefinition[], maybeTools?: ToolDefinition[]): void;