taurusdb-mcp 0.1.0

package/dist/tools/common/public-formatters.d.ts

@@ -0,0 +1,344 @@
+import type { DbHotspotResult, DataSourceInfo, DatabaseInfo, DiagnosticResult, EnhancedExplainResult, ExplainResult, FeatureMatrix, FindTopSlowSqlResult, GuardrailDecision, KernelInfo, MutationResult, QueryResult, ServiceLatencyResult, TableInfo, TableSchema } from "taurusdb-core";
+export declare function toPublicDataSourceInfo(info: DataSourceInfo): {
+    name: string;
+    engine: import("taurusdb-core").DatabaseEngine;
+    host: string | undefined;
+    port: number;
+    database: string | undefined;
+    has_mutation_user: boolean;
+    pool_size: number | undefined;
+    is_default: boolean;
+};
+export declare function toPublicDatabaseInfo(info: DatabaseInfo): {
+    name: string;
+    owner: string | undefined;
+    comment: string | undefined;
+};
+export declare function toPublicTableInfo(info: TableInfo): {
+    database: string;
+    name: string;
+    type: "table" | "view" | "materialized_view" | undefined;
+    comment: string | undefined;
+    row_count_estimate: number | undefined;
+};
+export declare function toPublicTableSchema(schema: TableSchema): {
+    database: string;
+    table: string;
+    columns: {
+        name: string;
+        data_type: string;
+        nullable: boolean;
+        default_value: unknown;
+        max_length: number | undefined;
+        is_primary_key: boolean | undefined;
+        is_indexed: boolean | undefined;
+        comment: string | undefined;
+    }[];
+    indexes: {
+        name: string;
+        columns: string[];
+        unique: boolean;
+        type: string | undefined;
+    }[];
+    primary_key: string[] | undefined;
+    engine_hints: {
+        likely_time_columns: string[];
+        likely_filter_columns: string[];
+        sensitive_columns: string[];
+    } | undefined;
+    comment: string | undefined;
+    row_count_estimate: number | undefined;
+};
+export declare function toPublicQueryResult(result: QueryResult): {
+    columns: import("taurusdb-core/executor/types").ColumnMeta[];
+    rows: unknown[][];
+    row_count: number;
+    original_row_count: number;
+    truncated: boolean;
+    row_truncated: boolean;
+    column_truncated: boolean;
+    field_truncated: boolean;
+    redacted_columns: string[];
+    dropped_columns: string[];
+    truncated_columns: string[];
+};
+export declare function toPublicMutationResult(result: MutationResult): {
+    affected_rows: number;
+};
+export declare function toPublicGuardrailDecision(decision: GuardrailDecision): {
+    action: "allow" | "confirm" | "block";
+    risk_level: import("taurusdb-core").RiskLevel;
+    reason_codes: string[];
+    risk_hints: string[];
+    requires_explain: boolean;
+    requires_confirmation: boolean;
+    sql_hash: string;
+    runtime_limits: {
+        readonly: boolean;
+        timeout_ms: number;
+        max_rows: number;
+        max_columns: number;
+        max_field_chars: number;
+    };
+};
+export declare function toPublicExplainResult(result: ExplainResult, decision: GuardrailDecision): {
+    plan: Record<string, unknown>[];
+    risk_summary: {
+        full_table_scan_likely: boolean;
+        index_hit_likely: boolean;
+        estimated_rows: number | null;
+        uses_temp_structure: boolean;
+        uses_filesort: boolean;
+        risk_hints: string[];
+    };
+    recommendations: string[];
+    guardrail: {
+        action: "allow" | "confirm" | "block";
+        risk_level: import("taurusdb-core").RiskLevel;
+        reason_codes: string[];
+        risk_hints: string[];
+        requires_explain: boolean;
+        requires_confirmation: boolean;
+        sql_hash: string;
+        runtime_limits: {
+            readonly: boolean;
+            timeout_ms: number;
+            max_rows: number;
+            max_columns: number;
+            max_field_chars: number;
+        };
+    };
+};
+export declare function toPublicKernelInfo(info: KernelInfo): {
+    is_taurusdb: boolean;
+    kernel_version: string | undefined;
+    mysql_compat: "unknown" | "5.7" | "8.0";
+    instance_spec_hint: "small" | "medium" | "large" | undefined;
+    raw_version: string;
+};
+export declare function toPublicFeatureMatrix(features: FeatureMatrix): {
+    [k: string]: {
+        [k: string]: unknown;
+    };
+};
+export declare function toPublicEnhancedExplainResult(result: EnhancedExplainResult, decision: GuardrailDecision): {
+    standard_plan: {
+        plan: Record<string, unknown>[];
+        risk_summary: {
+            full_table_scan_likely: boolean;
+            index_hit_likely: boolean;
+            estimated_rows: number | null;
+            uses_temp_structure: boolean;
+            uses_filesort: boolean;
+            risk_hints: string[];
+        };
+        recommendations: string[];
+        guardrail: {
+            action: "allow" | "confirm" | "block";
+            risk_level: import("taurusdb-core").RiskLevel;
+            reason_codes: string[];
+            risk_hints: string[];
+            requires_explain: boolean;
+            requires_confirmation: boolean;
+            sql_hash: string;
+            runtime_limits: {
+                readonly: boolean;
+                timeout_ms: number;
+                max_rows: number;
+                max_columns: number;
+                max_field_chars: number;
+            };
+        };
+    };
+    tree_plan: string | undefined;
+    taurus_hints: {
+        ndp_pushdown: {
+            condition: boolean;
+            columns: boolean;
+            aggregate: boolean;
+            blocked_reason: string | undefined;
+        };
+        parallel_query: {
+            would_enable: boolean;
+            estimated_degree: number | undefined;
+            blocked_reason: string | undefined;
+        };
+        offset_pushdown: boolean;
+    };
+    feature_explanations: {
+        ndp_pushdown: {
+            matched: boolean;
+            meaning: string;
+            why_triggered: string;
+            expected_benefit: string;
+        };
+        parallel_query: {
+            matched: boolean;
+            meaning: string;
+            why_triggered: string;
+            expected_benefit: string;
+        };
+        offset_pushdown: {
+            matched: boolean;
+            meaning: string;
+            why_triggered: string;
+            expected_benefit: string;
+        };
+    };
+    optimization_suggestions: string[];
+};
+export declare function toPublicDiagnosticResult(result: DiagnosticResult): {
+    tool: import("taurusdb-core").DiagnosticToolName;
+    status: import("taurusdb-core").DiagnosticStatus;
+    severity: import("taurusdb-core").DiagnosticSeverity;
+    summary: string;
+    diagnosis_window: {
+        from: string | undefined;
+        to: string | undefined;
+        relative: string | undefined;
+    };
+    root_cause_candidates: {
+        code: string;
+        title: string;
+        confidence: import("taurusdb-core").DiagnosticConfidence;
+        rationale: string;
+    }[];
+    key_findings: string[];
+    suspicious_entities: {
+        sqls: {
+            sql_hash: string | undefined;
+            digest_text: string | undefined;
+            reason: string;
+        }[] | undefined;
+        sessions: {
+            session_id: string | undefined;
+            user: string | undefined;
+            state: string | undefined;
+            reason: string;
+        }[] | undefined;
+        tables: {
+            table: string;
+            reason: string;
+        }[] | undefined;
+        users: {
+            user: string;
+            client_host: string | undefined;
+            reason: string;
+        }[] | undefined;
+    } | undefined;
+    evidence: {
+        source: string;
+        title: string;
+        summary: string;
+        raw_ref: string | undefined;
+    }[];
+    recommended_actions: string[];
+    recommended_next_tools: string[] | undefined;
+    next_tool_inputs: {
+        tool: import("taurusdb-core").DiagnosticToolName | "show_processlist";
+        input: Record<string, unknown>;
+        rationale: string;
+    }[] | undefined;
+    limitations: string[] | undefined;
+};
+export declare function toPublicTopSlowSqlResult(result: FindTopSlowSqlResult): {
+    tool: "find_top_slow_sql";
+    status: import("taurusdb-core").DiagnosticStatus;
+    summary: string;
+    diagnosis_window: {
+        from: string | undefined;
+        to: string | undefined;
+        relative: string | undefined;
+    };
+    top_sqls: {
+        sql_hash: string | undefined;
+        digest_text: string | undefined;
+        sample_sql: string | undefined;
+        avg_latency_ms: number | undefined;
+        total_latency_ms: number | undefined;
+        exec_count: number | undefined;
+        avg_lock_time_ms: number | undefined;
+        avg_rows_examined: number | undefined;
+        evidence_sources: string[];
+        recommendation: string | undefined;
+    }[];
+    evidence: {
+        source: string;
+        title: string;
+        summary: string;
+        raw_ref: string | undefined;
+    }[];
+    limitations: string[] | undefined;
+};
+export declare function toPublicServiceLatencyResult(result: ServiceLatencyResult): {
+    tool: "diagnose_service_latency";
+    status: import("taurusdb-core").DiagnosticStatus;
+    summary: string;
+    diagnosis_window: {
+        from: string | undefined;
+        to: string | undefined;
+        relative: string | undefined;
+    };
+    suspected_category: import("taurusdb-core").ServiceLatencySuspectedCategory;
+    top_candidates: {
+        type: "table" | "sql" | "session";
+        title: string;
+        confidence: import("taurusdb-core").DiagnosticConfidence;
+        sql_hash: string | undefined;
+        digest_text: string | undefined;
+        sample_sql: string | undefined;
+        session_id: string | undefined;
+        table: string | undefined;
+        rationale: string;
+    }[];
+    evidence: {
+        source: string;
+        title: string;
+        summary: string;
+        raw_ref: string | undefined;
+    }[];
+    recommended_next_tools: string[];
+    next_tool_inputs: {
+        tool: import("taurusdb-core").DiagnosticToolName | "show_processlist";
+        input: Record<string, unknown>;
+        rationale: string;
+    }[];
+    limitations: string[] | undefined;
+};
+export declare function toPublicDbHotspotResult(result: DbHotspotResult): {
+    tool: "diagnose_db_hotspot";
+    status: import("taurusdb-core").DiagnosticStatus;
+    summary: string;
+    diagnosis_window: {
+        from: string | undefined;
+        to: string | undefined;
+        relative: string | undefined;
+    };
+    scope: "table" | "sql" | "session" | "all";
+    hotspots: {
+        type: "table" | "sql" | "session";
+        title: string;
+        confidence: import("taurusdb-core").DiagnosticConfidence;
+        sql_hash: string | undefined;
+        digest_text: string | undefined;
+        sample_sql: string | undefined;
+        session_id: string | undefined;
+        table: string | undefined;
+        rationale: string;
+        evidence_sources: string[];
+        recommendation: string | undefined;
+    }[];
+    evidence: {
+        source: string;
+        title: string;
+        summary: string;
+        raw_ref: string | undefined;
+    }[];
+    recommended_next_tools: string[];
+    next_tool_inputs: {
+        tool: import("taurusdb-core").DiagnosticToolName | "show_processlist";
+        input: Record<string, unknown>;
+        rationale: string;
+    }[];
+    limitations: string[] | undefined;
+};

package/dist/tools/common/public-formatters.js

@@ -0,0 +1,348 @@
+export function toPublicDataSourceInfo(info) {
+    return {
+        name: info.name,
+        engine: info.engine,
+        host: info.host,
+        port: info.port,
+        database: info.database,
+        has_mutation_user: info.hasMutationUser,
+        pool_size: info.poolSize,
+        is_default: info.isDefault,
+    };
+}
+export function toPublicDatabaseInfo(info) {
+    return {
+        name: info.name,
+        owner: info.owner,
+        comment: info.comment,
+    };
+}
+export function toPublicTableInfo(info) {
+    return {
+        database: info.database,
+        name: info.name,
+        type: info.type,
+        comment: info.comment,
+        row_count_estimate: info.rowCountEstimate,
+    };
+}
+export function toPublicTableSchema(schema) {
+    return {
+        database: schema.database,
+        table: schema.table,
+        columns: schema.columns.map((column) => ({
+            name: column.name,
+            data_type: column.dataType,
+            nullable: column.nullable,
+            default_value: column.defaultValue,
+            max_length: column.maxLength,
+            is_primary_key: column.isPrimaryKey,
+            is_indexed: column.isIndexed,
+            comment: column.comment,
+        })),
+        indexes: schema.indexes.map((index) => ({
+            name: index.name,
+            columns: index.columns,
+            unique: index.unique,
+            type: index.type,
+        })),
+        primary_key: schema.primaryKey,
+        engine_hints: schema.engineHints
+            ? {
+                likely_time_columns: schema.engineHints.likelyTimeColumns,
+                likely_filter_columns: schema.engineHints.likelyFilterColumns,
+                sensitive_columns: schema.engineHints.sensitiveColumns,
+            }
+            : undefined,
+        comment: schema.comment,
+        row_count_estimate: schema.rowCountEstimate,
+    };
+}
+export function toPublicQueryResult(result) {
+    return {
+        columns: result.columns,
+        rows: result.rows,
+        row_count: result.rowCount,
+        original_row_count: result.originalRowCount,
+        truncated: result.truncated,
+        row_truncated: result.rowTruncated,
+        column_truncated: result.columnTruncated,
+        field_truncated: result.fieldTruncated,
+        redacted_columns: result.redactedColumns,
+        dropped_columns: result.droppedColumns,
+        truncated_columns: result.truncatedColumns,
+    };
+}
+export function toPublicMutationResult(result) {
+    return {
+        affected_rows: result.affectedRows,
+    };
+}
+export function toPublicGuardrailDecision(decision) {
+    return {
+        action: decision.action,
+        risk_level: decision.riskLevel,
+        reason_codes: decision.reasonCodes,
+        risk_hints: decision.riskHints,
+        requires_explain: decision.requiresExplain,
+        requires_confirmation: decision.requiresConfirmation,
+        sql_hash: decision.sqlHash,
+        runtime_limits: {
+            readonly: decision.runtimeLimits.readonly,
+            timeout_ms: decision.runtimeLimits.timeoutMs,
+            max_rows: decision.runtimeLimits.maxRows,
+            max_columns: decision.runtimeLimits.maxColumns,
+            max_field_chars: decision.runtimeLimits.maxFieldChars,
+        },
+    };
+}
+export function toPublicExplainResult(result, decision) {
+    return {
+        plan: result.plan,
+        risk_summary: {
+            full_table_scan_likely: result.riskSummary.fullTableScanLikely,
+            index_hit_likely: result.riskSummary.indexHitLikely,
+            estimated_rows: result.riskSummary.estimatedRows,
+            uses_temp_structure: result.riskSummary.usesTempStructure,
+            uses_filesort: result.riskSummary.usesFilesort,
+            risk_hints: result.riskSummary.riskHints,
+        },
+        recommendations: result.recommendations,
+        guardrail: toPublicGuardrailDecision(decision),
+    };
+}
+export function toPublicKernelInfo(info) {
+    return {
+        is_taurusdb: info.isTaurusDB,
+        kernel_version: info.kernelVersion,
+        mysql_compat: info.mysqlCompat,
+        instance_spec_hint: info.instanceSpecHint,
+        raw_version: info.rawVersion,
+    };
+}
+function toPublicFeatureStatus(status) {
+    return Object.fromEntries(Object.entries(status).map(([key, value]) => {
+        if (key === "minVersion") {
+            return ["min_version", value];
+        }
+        return [key, value];
+    }));
+}
+const HIDDEN_PUBLIC_FEATURES = new Set([
+    "statement_outline",
+    "column_compression",
+    "multi_tenant",
+    "partition_mdl",
+    "hot_row_update",
+]);
+export function toPublicFeatureMatrix(features) {
+    return Object.fromEntries(Object.entries(features)
+        .filter(([name]) => !HIDDEN_PUBLIC_FEATURES.has(name))
+        .map(([name, status]) => [name, toPublicFeatureStatus(status)]));
+}
+export function toPublicEnhancedExplainResult(result, decision) {
+    return {
+        standard_plan: toPublicExplainResult(result.standardPlan, decision),
+        tree_plan: result.treePlan,
+        taurus_hints: {
+            ndp_pushdown: {
+                condition: result.taurusHints.ndpPushdown.condition,
+                columns: result.taurusHints.ndpPushdown.columns,
+                aggregate: result.taurusHints.ndpPushdown.aggregate,
+                blocked_reason: result.taurusHints.ndpPushdown.blockedReason,
+            },
+            parallel_query: {
+                would_enable: result.taurusHints.parallelQuery.wouldEnable,
+                estimated_degree: result.taurusHints.parallelQuery.estimatedDegree,
+                blocked_reason: result.taurusHints.parallelQuery.blockedReason,
+            },
+            offset_pushdown: result.taurusHints.offsetPushdown,
+        },
+        feature_explanations: {
+            ndp_pushdown: {
+                matched: result.featureExplanations.ndpPushdown.matched,
+                meaning: result.featureExplanations.ndpPushdown.meaning,
+                why_triggered: result.featureExplanations.ndpPushdown.whyTriggered,
+                expected_benefit: result.featureExplanations.ndpPushdown.expectedBenefit,
+            },
+            parallel_query: {
+                matched: result.featureExplanations.parallelQuery.matched,
+                meaning: result.featureExplanations.parallelQuery.meaning,
+                why_triggered: result.featureExplanations.parallelQuery.whyTriggered,
+                expected_benefit: result.featureExplanations.parallelQuery.expectedBenefit,
+            },
+            offset_pushdown: {
+                matched: result.featureExplanations.offsetPushdown.matched,
+                meaning: result.featureExplanations.offsetPushdown.meaning,
+                why_triggered: result.featureExplanations.offsetPushdown.whyTriggered,
+                expected_benefit: result.featureExplanations.offsetPushdown.expectedBenefit,
+            },
+        },
+        optimization_suggestions: result.optimizationSuggestions,
+    };
+}
+export function toPublicDiagnosticResult(result) {
+    return {
+        tool: result.tool,
+        status: result.status,
+        severity: result.severity,
+        summary: result.summary,
+        diagnosis_window: {
+            from: result.diagnosisWindow.from,
+            to: result.diagnosisWindow.to,
+            relative: result.diagnosisWindow.relative,
+        },
+        root_cause_candidates: result.rootCauseCandidates.map((candidate) => ({
+            code: candidate.code,
+            title: candidate.title,
+            confidence: candidate.confidence,
+            rationale: candidate.rationale,
+        })),
+        key_findings: result.keyFindings,
+        suspicious_entities: result.suspiciousEntities
+            ? {
+                sqls: result.suspiciousEntities.sqls?.map((item) => ({
+                    sql_hash: item.sqlHash,
+                    digest_text: item.digestText,
+                    reason: item.reason,
+                })),
+                sessions: result.suspiciousEntities.sessions?.map((item) => ({
+                    session_id: item.sessionId,
+                    user: item.user,
+                    state: item.state,
+                    reason: item.reason,
+                })),
+                tables: result.suspiciousEntities.tables?.map((item) => ({
+                    table: item.table,
+                    reason: item.reason,
+                })),
+                users: result.suspiciousEntities.users?.map((item) => ({
+                    user: item.user,
+                    client_host: item.clientHost,
+                    reason: item.reason,
+                })),
+            }
+            : undefined,
+        evidence: result.evidence.map((item) => ({
+            source: item.source,
+            title: item.title,
+            summary: item.summary,
+            raw_ref: item.rawRef,
+        })),
+        recommended_actions: result.recommendedActions,
+        recommended_next_tools: result.recommendedNextTools,
+        next_tool_inputs: result.nextToolInputs?.map((item) => ({
+            tool: item.tool,
+            input: item.input,
+            rationale: item.rationale,
+        })),
+        limitations: result.limitations,
+    };
+}
+export function toPublicTopSlowSqlResult(result) {
+    return {
+        tool: result.tool,
+        status: result.status,
+        summary: result.summary,
+        diagnosis_window: {
+            from: result.diagnosisWindow.from,
+            to: result.diagnosisWindow.to,
+            relative: result.diagnosisWindow.relative,
+        },
+        top_sqls: result.topSqls.map((item) => ({
+            sql_hash: item.sqlHash,
+            digest_text: item.digestText,
+            sample_sql: item.sampleSql,
+            avg_latency_ms: item.avgLatencyMs,
+            total_latency_ms: item.totalLatencyMs,
+            exec_count: item.execCount,
+            avg_lock_time_ms: item.avgLockTimeMs,
+            avg_rows_examined: item.avgRowsExamined,
+            evidence_sources: item.evidenceSources,
+            recommendation: item.recommendation,
+        })),
+        evidence: result.evidence.map((item) => ({
+            source: item.source,
+            title: item.title,
+            summary: item.summary,
+            raw_ref: item.rawRef,
+        })),
+        limitations: result.limitations,
+    };
+}
+export function toPublicServiceLatencyResult(result) {
+    return {
+        tool: result.tool,
+        status: result.status,
+        summary: result.summary,
+        diagnosis_window: {
+            from: result.diagnosisWindow.from,
+            to: result.diagnosisWindow.to,
+            relative: result.diagnosisWindow.relative,
+        },
+        suspected_category: result.suspectedCategory,
+        top_candidates: result.topCandidates.map((item) => ({
+            type: item.type,
+            title: item.title,
+            confidence: item.confidence,
+            sql_hash: item.sqlHash,
+            digest_text: item.digestText,
+            sample_sql: item.sampleSql,
+            session_id: item.sessionId,
+            table: item.table,
+            rationale: item.rationale,
+        })),
+        evidence: result.evidence.map((item) => ({
+            source: item.source,
+            title: item.title,
+            summary: item.summary,
+            raw_ref: item.rawRef,
+        })),
+        recommended_next_tools: result.recommendedNextTools,
+        next_tool_inputs: result.nextToolInputs.map((item) => ({
+            tool: item.tool,
+            input: item.input,
+            rationale: item.rationale,
+        })),
+        limitations: result.limitations,
+    };
+}
+export function toPublicDbHotspotResult(result) {
+    return {
+        tool: result.tool,
+        status: result.status,
+        summary: result.summary,
+        diagnosis_window: {
+            from: result.diagnosisWindow.from,
+            to: result.diagnosisWindow.to,
+            relative: result.diagnosisWindow.relative,
+        },
+        scope: result.scope,
+        hotspots: result.hotspots.map((item) => ({
+            type: item.type,
+            title: item.title,
+            confidence: item.confidence,
+            sql_hash: item.sqlHash,
+            digest_text: item.digestText,
+            sample_sql: item.sampleSql,
+            session_id: item.sessionId,
+            table: item.table,
+            rationale: item.rationale,
+            evidence_sources: item.evidenceSources,
+            recommendation: item.recommendation,
+        })),
+        evidence: result.evidence.map((item) => ({
+            source: item.source,
+            title: item.title,
+            summary: item.summary,
+            raw_ref: item.rawRef,
+        })),
+        recommended_next_tools: result.recommendedNextTools,
+        next_tool_inputs: result.nextToolInputs.map((item) => ({
+            tool: item.tool,
+            input: item.input,
+            rationale: item.rationale,
+        })),
+        limitations: result.limitations,
+    };
+}

package/dist/tools/common.d.ts

@@ -0,0 +1,2 @@
+export * from "./common/input.js";
+export * from "./common/public-formatters.js";

package/dist/tools/common.js

@@ -0,0 +1,2 @@
+export * from "./common/input.js";
+export * from "./common/public-formatters.js";

package/dist/tools/discovery.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition } from "./registry.js";
+export declare const listDataSourcesTool: ToolDefinition;
+export declare const listDatabasesTool: ToolDefinition;
+export declare const listTablesTool: ToolDefinition;
+export declare const describeTableTool: ToolDefinition;