taurusdb-mcp 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# taurusdb-mcp
+
+TaurusDB MCP server for MCP clients such as:
+
+- Claude
+- Cursor
+- VS Code
+
+## Install
+
+```bash
+npm install taurusdb-mcp
+```
+
+Run directly with:
+
+```bash
+npx taurusdb-mcp --version
+```
+
+Initialize local MCP client config:
+
+```bash
+npx taurusdb-mcp init --client claude
+npx taurusdb-mcp init --client cursor
+npx taurusdb-mcp init --client vscode
+```
+
+## Notes
+
+- Requires Node.js `>= 20`
+- Depends on `taurusdb-core`

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function runInit(args: string[]): Promise<number>;

package/dist/commands/init.js

@@ -0,0 +1,195 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const SERVER_NAME = "huaweicloud-taurusdb";
+function printInitUsage() {
+    console.error("Usage: taurusdb-mcp init --client <claude|cursor|vscode>");
+}
+function parseClientArg(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--client" || arg === "-c") {
+            return toClientName(args[index + 1]);
+        }
+        if (arg.startsWith("--client=")) {
+            return toClientName(arg.slice("--client=".length));
+        }
+    }
+    return undefined;
+}
+function toClientName(value) {
+    if (value === "claude" || value === "cursor" || value === "vscode") {
+        return value;
+    }
+    return undefined;
+}
+function getAppDataDir() {
+    const appData = process.env.APPDATA;
+    if (appData && appData.trim().length > 0) {
+        return appData;
+    }
+    return path.join(os.homedir(), "AppData", "Roaming");
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function pickExistingOrDefault(candidates) {
+    for (const candidate of candidates) {
+        if (await fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates[0];
+}
+async function readJsonObject(filePath) {
+    if (!(await fileExists(filePath))) {
+        return {};
+    }
+    const raw = await readFile(filePath, "utf-8");
+    if (raw.trim().length === 0) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in config file: ${filePath}`, { cause: error });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Config file root must be a JSON object: ${filePath}`);
+    }
+    return parsed;
+}
+async function writeJsonObject(filePath, config) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+function mergeWithKey(config, rootKey, serverName, entry) {
+    const current = config[rootKey];
+    const nextConfig = { ...config };
+    let servers;
+    if (current === undefined) {
+        servers = {};
+    }
+    else if (current !== null && typeof current === "object" && !Array.isArray(current)) {
+        servers = { ...current };
+    }
+    else {
+        throw new Error(`Config field \`${rootKey}\` must be an object.`);
+    }
+    if (Object.hasOwn(servers, serverName)) {
+        return {
+            config,
+            changed: false,
+            conflict: true,
+        };
+    }
+    servers[serverName] = entry;
+    nextConfig[rootKey] = servers;
+    return {
+        config: nextConfig,
+        changed: true,
+        conflict: false,
+    };
+}
+const SHARED_ENTRY = {
+    command: "npx",
+    args: ["-y", "taurusdb-mcp"],
+};
+function createClaudeAdapter() {
+    return {
+        name: "claude",
+        async getConfigPath() {
+            const home = os.homedir();
+            if (process.platform === "darwin") {
+                return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+            }
+            if (process.platform === "win32") {
+                return pickExistingOrDefault([
+                    path.join(getAppDataDir(), "Claude", "claude_desktop_config.json"),
+                    path.join(getAppDataDir(), "Claude", "config.json"),
+                ]);
+            }
+            return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+        },
+        readConfig: readJsonObject,
+        mergeServerEntry(config, serverName, entry) {
+            return mergeWithKey(config, "mcpServers", serverName, entry);
+        },
+        writeConfig: writeJsonObject,
+    };
+}
+function createCursorAdapter() {
+    return {
+        name: "cursor",
+        async getConfigPath() {
+            return path.join(os.homedir(), ".cursor", "mcp.json");
+        },
+        readConfig: readJsonObject,
+        mergeServerEntry(config, serverName, entry) {
+            return mergeWithKey(config, "mcpServers", serverName, entry);
+        },
+        writeConfig: writeJsonObject,
+    };
+}
+function createVsCodeAdapter() {
+    return {
+        name: "vscode",
+        async getConfigPath() {
+            const home = os.homedir();
+            if (process.platform === "darwin") {
+                return path.join(home, "Library", "Application Support", "Code", "User", "mcp.json");
+            }
+            if (process.platform === "win32") {
+                return path.join(getAppDataDir(), "Code", "User", "mcp.json");
+            }
+            return path.join(home, ".config", "Code", "User", "mcp.json");
+        },
+        readConfig: readJsonObject,
+        mergeServerEntry(config, serverName, entry) {
+            return mergeWithKey(config, "servers", serverName, entry);
+        },
+        writeConfig: writeJsonObject,
+    };
+}
+function getClientAdapter(client) {
+    switch (client) {
+        case "claude":
+            return createClaudeAdapter();
+        case "cursor":
+            return createCursorAdapter();
+        case "vscode":
+            return createVsCodeAdapter();
+        default: {
+            const exhaustive = client;
+            throw new Error(`Unsupported client: ${String(exhaustive)}`);
+        }
+    }
+}
+export async function runInit(args) {
+    const client = parseClientArg(args);
+    if (!client) {
+        printInitUsage();
+        return 1;
+    }
+    const adapter = getClientAdapter(client);
+    const configPath = await adapter.getConfigPath();
+    const config = await adapter.readConfig(configPath);
+    const merged = adapter.mergeServerEntry(config, SERVER_NAME, SHARED_ENTRY);
+    if (merged.conflict) {
+        console.error(`[init] ${adapter.name} config already contains '${SERVER_NAME}', skipped update.`);
+        console.error(`[init] config: ${configPath}`);
+        return 0;
+    }
+    await adapter.writeConfig(configPath, merged.config);
+    console.error(`[init] wrote ${adapter.name} config: ${configPath}`);
+    console.error(`[init] added MCP server '${SERVER_NAME}'. Restart ${adapter.name} to apply.`);
+    return 0;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { runInit } from "./commands/init.js";
+import { startMcpServer } from "./server.js";
+import { VERSION } from "./version.js";
+async function main() {
+    const args = process.argv.slice(2);
+    const firstArg = args[0];
+    if (firstArg === "init") {
+        process.exitCode = await runInit(args.slice(1));
+        return;
+    }
+    if (firstArg === "--version" || firstArg === "-v") {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    await startMcpServer();
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TaurusDBEngine, type CapabilitySnapshot, type Config, type RuntimeTargetProfileLoader } from "taurusdb-core";
+export interface ServerDeps {
+    config: Config;
+    profileLoader: RuntimeTargetProfileLoader;
+    engine: TaurusDBEngine;
+    pingResponse: string;
+    startupProbe?: CapabilitySnapshot;
+}
+export declare function bootstrapDependencies(): Promise<ServerDeps>;
+export declare function createServer(deps: ServerDeps): McpServer;
+export declare function startMcpServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,60 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createSqlProfileLoader, getConfig, RuntimeOverrideProfileLoader, redactConfigForLog, TaurusDBEngine, } from "taurusdb-core";
+import { registerTools } from "./tools/registry.js";
+import { logger } from "taurusdb-core";
+import { VERSION } from "./version.js";
+export async function bootstrapDependencies() {
+    const config = getConfig();
+    const profileLoader = new RuntimeOverrideProfileLoader(createSqlProfileLoader({ config }));
+    const engine = await TaurusDBEngine.create({ config, profileLoader });
+    const defaultDatasource = await engine.getDefaultDataSource();
+    let startupProbe;
+    if (defaultDatasource) {
+        try {
+            const bootstrapContext = await engine.resolveContext({
+                datasource: defaultDatasource,
+                readonly: true,
+            }, "task_bootstrap_probe");
+            startupProbe = await engine.probeCapabilities(bootstrapContext);
+        }
+        catch (error) {
+            logger.warn({
+                err: error,
+                defaultDatasource,
+            }, "Capability probe failed during bootstrap; TaurusDB-specific tools will stay disabled");
+        }
+    }
+    return {
+        config,
+        profileLoader,
+        engine,
+        pingResponse: "pong",
+        startupProbe,
+    };
+}
+export function createServer(deps) {
+    const server = new McpServer({
+        name: "huaweicloud-taurusdb",
+        version: VERSION,
+    });
+    registerTools(server, deps, deps.config, deps.startupProbe);
+    return server;
+}
+export async function startMcpServer() {
+    const deps = await bootstrapDependencies();
+    const [datasources, defaultDatasource] = await Promise.all([
+        deps.engine.listDataSources(),
+        deps.engine.getDefaultDataSource(),
+    ]);
+    const server = createServer(deps);
+    logger.info({ config: redactConfigForLog(deps.config) }, "Loaded effective config");
+    logger.info({
+        profileCount: datasources.length,
+        defaultDatasource: defaultDatasource ?? null,
+        taurusdbProbe: deps.startupProbe?.kernelInfo?.isTaurusDB ?? null,
+    }, "SQL profiles resolved");
+    logger.info({ server: "huaweicloud-taurusdb", version: VERSION }, "Starting MCP server");
+    await server.connect(new StdioServerTransport());
+    logger.info({ server: "huaweicloud-taurusdb" }, "MCP server connected to stdio transport");
+}

package/dist/tools/common/input.d.ts

@@ -0,0 +1,50 @@
+import type { ResponseMetadata, SessionContext, StatementType } from "taurusdb-core";
+import { z } from "zod";
+import { type ToolResponse } from "../../utils/formatter.js";
+import type { ToolDeps, ToolInvokeContext } from "../registry.js";
+type RawContextInput = {
+    datasource?: unknown;
+    database?: unknown;
+    schema?: unknown;
+    timeout_ms?: unknown;
+};
+export declare const contextInputShape: {
+    readonly datasource: z.ZodOptional<z.ZodString>;
+    readonly database: z.ZodOptional<z.ZodString>;
+    readonly schema: z.ZodOptional<z.ZodString>;
+    readonly timeout_ms: z.ZodOptional<z.ZodNumber>;
+};
+export declare const diagnosticBaseInputShape: {
+    readonly time_range: z.ZodOptional<z.ZodObject<{
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        relative: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        from?: string | undefined;
+        to?: string | undefined;
+        relative?: string | undefined;
+    }, {
+        from?: string | undefined;
+        to?: string | undefined;
+        relative?: string | undefined;
+    }>>;
+    readonly evidence_level: z.ZodOptional<z.ZodEnum<["basic", "standard", "full"]>>;
+    readonly include_raw_evidence: z.ZodOptional<z.ZodBoolean>;
+    readonly max_candidates: z.ZodOptional<z.ZodNumber>;
+    readonly datasource: z.ZodOptional<z.ZodString>;
+    readonly database: z.ZodOptional<z.ZodString>;
+    readonly schema: z.ZodOptional<z.ZodString>;
+    readonly timeout_ms: z.ZodOptional<z.ZodNumber>;
+};
+export declare function metadata(taskId: string, extra?: Omit<ResponseMetadata, "task_id">): ResponseMetadata;
+export declare function resolveContext(input: RawContextInput, deps: ToolDeps, context: ToolInvokeContext, readonly: boolean): Promise<SessionContext>;
+export declare function requireDatabase(value: unknown, ctx: SessionContext): string;
+export declare function asRequiredString(value: unknown, fieldName: string): string;
+export declare function asOptionalString(value: unknown, fieldName: string): string | undefined;
+export declare function asOptionalPositiveInteger(value: unknown, fieldName: string): number | undefined;
+export declare function asOptionalBoolean(value: unknown, fieldName: string): boolean | undefined;
+export declare function summarizeRows(rowCount: number, truncated: boolean): string;
+export declare function summarizeMutation(affectedRows: number): string;
+export declare function statementTypeFromSql(sql: string): StatementType | undefined;
+export declare function invalidInputResponse(message: string, taskId: string, summary?: string): ToolResponse;
+export {};

package/dist/tools/common/input.js

@@ -0,0 +1,168 @@
+import { z } from "zod";
+import { formatError, ErrorCode, } from "../../utils/formatter.js";
+import { ToolInputError } from "../error-handling.js";
+const STATEMENT_TYPES = new Set([
+    "select",
+    "show",
+    "explain",
+    "describe",
+    "insert",
+    "update",
+    "delete",
+    "alter",
+    "drop",
+    "create",
+    "grant",
+    "revoke",
+    "unknown",
+]);
+export const contextInputShape = {
+    datasource: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Datasource profile name. If omitted, the configured default datasource is used."),
+    database: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Database name. Overrides the datasource default database for this tool call."),
+    schema: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Optional schema name for engines that support schema scoping."),
+    timeout_ms: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Statement timeout in milliseconds. Clamped by the server-side maximum."),
+};
+export const diagnosticBaseInputShape = {
+    ...contextInputShape,
+    time_range: z
+        .object({
+        from: z.string().trim().min(1).optional(),
+        to: z.string().trim().min(1).optional(),
+        relative: z.string().trim().min(1).optional(),
+    })
+        .optional()
+        .describe("Optional diagnosis window. Use from/to or a relative window such as 15m or 1h."),
+    evidence_level: z
+        .enum(["basic", "standard", "full"])
+        .optional()
+        .describe("How much evidence the diagnostic should attempt to gather."),
+    include_raw_evidence: z
+        .boolean()
+        .optional()
+        .describe("Whether to include raw evidence references in the response."),
+    max_candidates: z
+        .number()
+        .int()
+        .positive()
+        .max(10)
+        .optional()
+        .describe("Maximum number of root-cause candidates to return."),
+};
+export function metadata(taskId, extra = {}) {
+    return {
+        task_id: taskId,
+        ...extra,
+    };
+}
+export async function resolveContext(input, deps, context, readonly) {
+    return deps.engine.resolveContext({
+        datasource: asOptionalString(input.datasource, "datasource"),
+        database: asOptionalString(input.database, "database"),
+        schema: asOptionalString(input.schema, "schema"),
+        timeout_ms: asOptionalPositiveInteger(input.timeout_ms, "timeout_ms"),
+        readonly,
+    }, context.taskId);
+}
+export function requireDatabase(value, ctx) {
+    const explicit = asOptionalString(value, "database");
+    const resolved = explicit ?? ctx.database;
+    if (!resolved) {
+        throw new ToolInputError("Missing database. Provide input.database or configure a default database on the datasource profile.");
+    }
+    return resolved;
+}
+export function asRequiredString(value, fieldName) {
+    if (typeof value !== "string") {
+        throw new ToolInputError(`Invalid ${fieldName}: expected a string.`);
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new ToolInputError(`Invalid ${fieldName}: value cannot be empty.`);
+    }
+    return trimmed;
+}
+export function asOptionalString(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return asRequiredString(value, fieldName);
+}
+export function asOptionalPositiveInteger(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new ToolInputError(`Invalid ${fieldName}: expected a positive integer.`);
+    }
+    return value;
+}
+export function asOptionalBoolean(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "boolean") {
+        throw new ToolInputError(`Invalid ${fieldName}: expected a boolean.`);
+    }
+    return value;
+}
+export function summarizeRows(rowCount, truncated) {
+    if (rowCount === 1) {
+        return truncated ? "Returned 1 row (truncated)." : "Returned 1 row.";
+    }
+    return truncated
+        ? `Returned ${rowCount} rows (truncated).`
+        : `Returned ${rowCount} rows.`;
+}
+export function summarizeMutation(affectedRows) {
+    if (affectedRows === 1) {
+        return "Mutation completed. 1 row affected.";
+    }
+    return `Mutation completed. ${affectedRows} rows affected.`;
+}
+export function statementTypeFromSql(sql) {
+    const trimmed = sql.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const firstToken = trimmed.match(/^([a-z]+)/i)?.[1]?.toLowerCase();
+    if (!firstToken) {
+        return undefined;
+    }
+    if (firstToken === "desc") {
+        return "describe";
+    }
+    if (firstToken === "with") {
+        return "select";
+    }
+    return STATEMENT_TYPES.has(firstToken)
+        ? firstToken
+        : undefined;
+}
+export function invalidInputResponse(message, taskId, summary = "Tool call failed due to invalid input.") {
+    return formatError({
+        code: ErrorCode.INVALID_INPUT,
+        message,
+        summary,
+        metadata: metadata(taskId),
+    });
+}