taurusdb-mcp 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,8 @@
 
 TaurusDB MCP server for MCP clients such as:
 
-- Claude
+- Claude Code
+- Codex
 - Cursor
 - VS Code
 
@@ -15,7 +16,43 @@ npm install taurusdb-mcp
 Run directly with:
 
 ```bash
-npx taurusdb-mcp --version
+npx -y taurusdb-mcp --version
+```
+
+Use this command in MCP client configs:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "taurusdb-mcp"]
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add huaweicloud-taurusdb \
+  --transport stdio \
+  -e TAURUSDB_CLOUD_REGION=<your-region> \
+  -e TAURUSDB_CLOUD_ACCESS_KEY_ID=<your-ak> \
+  -e TAURUSDB_CLOUD_SECRET_ACCESS_KEY=<your-sk> \
+  -e TAURUSDB_SQL_DATABASE=<your-database> \
+  -e TAURUSDB_SQL_USER=<your-readonly-user> \
+  -e TAURUSDB_SQL_PASSWORD=<your-readonly-password> \
+  -- npx -y taurusdb-mcp
+```
+
+Codex:
+
+```bash
+codex mcp add huaweicloud-taurusdb \
+  --env TAURUSDB_CLOUD_REGION=<your-region> \
+  --env TAURUSDB_CLOUD_ACCESS_KEY_ID=<your-ak> \
+  --env TAURUSDB_CLOUD_SECRET_ACCESS_KEY=<your-sk> \
+  --env TAURUSDB_SQL_DATABASE=<your-database> \
+  --env TAURUSDB_SQL_USER=<your-readonly-user> \
+  --env TAURUSDB_SQL_PASSWORD=<your-readonly-password> \
+  -- npx -y taurusdb-mcp
 ```
 
 Initialize local MCP client config:

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

@@ -5,7 +5,6 @@ export declare function toPublicDataSourceInfo(info: DataSourceInfo): {
     host: string | undefined;
     port: number;
     database: string | undefined;
-    has_mutation_user: boolean;
     pool_size: number | undefined;
     is_default: boolean;
 };

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

@@ -5,7 +5,6 @@ export function toPublicDataSourceInfo(info) {
         host: info.host,
         port: info.port,
         database: info.database,
-        has_mutation_user: info.hasMutationUser,
         pool_size: info.poolSize,
         is_default: info.isDefault,
     };

package/dist/tools/error-handling.js

@@ -75,15 +75,19 @@ export function formatToolError(error, context) {
         });
     }
     if (error instanceof UnsupportedFeatureError) {
+        const parameterHint = error.parameterHint
+            ? ` Enable or verify ${error.parameterHint} on the target instance if this feature should be available.`
+            : "";
         return formatError({
             code: ErrorCode.UNSUPPORTED_FEATURE,
-            message: error.message,
+            message: `${error.message}${parameterHint}`,
             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,
+                parameter_hint: error.parameterHint,
             },
         });
     }

package/dist/tools/query.js

@@ -163,7 +163,6 @@ export const executeSqlTool = {
         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);

package/dist/tools/registry.d.ts

@@ -19,4 +19,5 @@ export interface ToolDefinition<I extends Record<string, unknown> = Record<strin
 }
 export declare const commonToolDefinitions: ToolDefinition[];
 export declare const capabilityToolDefinitions: ToolDefinition[];
+export declare const taurusToolDefinitions: ToolDefinition[];
 export declare function registerTools(server: McpServer, deps: ToolDeps, config: Config, probeOrTools?: ToolRegistrationProbe | ToolDefinition[], maybeTools?: ToolDefinition[]): void;

package/dist/tools/registry.js

@@ -4,7 +4,7 @@ import { describeTableTool, listDatabasesTool, listTablesTool, } from "./discove
 import { showProcesslistTool } from "./processlist.js";
 import { pingTool } from "./ping.js";
 import { getKernelInfoTool, listTaurusFeaturesTool } from "./taurus/capability.js";
-import { selectCloudTaurusInstanceTool, setCloudAccessKeysTool, setCloudRegionTool, } from "./taurus/cloud-context.js";
+import { clearSqlCredentialsTool, getSessionBindingTool, selectCloudTaurusInstanceTool, setCloudAccessKeysTool, setCloudRegionTool, setDefaultDatabaseTool, setSqlCredentialsTool, } from "./taurus/cloud-context.js";
 import { listCloudTaurusInstancesTool } from "./taurus/cloud-instances.js";
 import { diagnosticToolDefinitions } from "./taurus/diagnostics.js";
 import { explainSqlEnhancedTool } from "./taurus/explain.js";
@@ -68,27 +68,27 @@ export const capabilityToolDefinitions = [
     listTaurusFeaturesTool,
     setCloudRegionTool,
     setCloudAccessKeysTool,
+    getSessionBindingTool,
+    setSqlCredentialsTool,
+    clearSqlCredentialsTool,
+    setDefaultDatabaseTool,
     listCloudTaurusInstancesTool,
     selectCloudTaurusInstanceTool,
 ];
+export const taurusToolDefinitions = [
+    explainSqlEnhancedTool,
+    flashbackQueryTool,
+    listRecycleBinTool,
+    restoreRecycleBinTableTool,
+];
 function buildDefaultToolDefinitions(_config, probe) {
-    const tools = [
+    void probe;
+    return [
         ...commonToolDefinitions,
         ...capabilityToolDefinitions,
         ...diagnosticToolDefinitions,
+        ...taurusToolDefinitions,
     ];
-    if (probe?.features) {
-        if (probe.features.ndp_pushdown.available || probe.features.parallel_query.available) {
-            tools.push(explainSqlEnhancedTool);
-        }
-        if (probe.features.flashback_query.available) {
-            tools.push(flashbackQueryTool);
-        }
-        if (probe.features.recycle_bin.available) {
-            tools.push(listRecycleBinTool, restoreRecycleBinTableTool);
-        }
-    }
-    return tools;
 }
 function isToolDefinitionArray(value) {
     return Array.isArray(value);

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

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

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

@@ -50,6 +50,15 @@ function normalizePort(port) {
     }
     return undefined;
 }
+function maskUsername(username) {
+    if (!username) {
+        return undefined;
+    }
+    if (username.length <= 2) {
+        return `${username[0]}*`;
+    }
+    return `${username.slice(0, 1)}***${username.slice(-1)}`;
+}
 export const setCloudRegionTool = {
     name: "set_cloud_region",
     description: "Update the active Huawei Cloud region for the current MCP session and reset any stale cloud project or instance selections.",
@@ -129,6 +138,230 @@ export const setCloudAccessKeysTool = {
         }
     },
 };
+export const setDefaultDatabaseTool = {
+    name: "set_default_database",
+    description: "Set the default database for a datasource in the current MCP session so later tool calls can omit input.database.",
+    inputSchema: {
+        database: z
+            .string()
+            .trim()
+            .min(1)
+            .describe("Database name to bind as the session default for the selected datasource."),
+        datasource: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("Optional datasource template to bind. Defaults to the current default datasource."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const database = typeof input.database === "string" ? input.database.trim() : "";
+            if (!database) {
+                throw new ToolInputError("database is required.");
+            }
+            const datasource = await resolveBindingDatasource(deps, typeof input.datasource === "string" ? input.datasource : undefined);
+            if (!datasource) {
+                throw new ToolInputError("No datasource selected. Configure a default datasource or pass datasource explicitly.");
+            }
+            const ctx = await deps.engine.resolveContext({
+                datasource,
+                readonly: true,
+            }, context.taskId);
+            const databases = await deps.engine.listDatabases(ctx);
+            if (!databases.some((item) => item.name === database)) {
+                throw new ToolInputError(`Database "${database}" was not found on datasource "${datasource}". Run list_databases first and choose one of the returned names.`);
+            }
+            const profile = await deps.profileLoader.get(datasource);
+            if (!profile) {
+                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 reloadEngine(deps);
+            return formatSuccess({
+                datasource,
+                database,
+            }, {
+                summary: `Default database for ${datasource} set to ${database} in the current session.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "set_default_database",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const setSqlCredentialsTool = {
+    name: "set_sql_credentials",
+    description: "Set the SQL username and password for a datasource in the current MCP session without writing credentials to disk.",
+    inputSchema: {
+        username: z
+            .string()
+            .trim()
+            .min(1)
+            .describe("Database username to use for the selected datasource in this session."),
+        password: z
+            .string()
+            .trim()
+            .min(1)
+            .describe("Database password to use for the selected datasource in this session."),
+        datasource: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("Optional datasource template to bind. Defaults to the current default datasource."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const username = typeof input.username === "string" ? input.username.trim() : "";
+            const password = typeof input.password === "string" ? input.password.trim() : "";
+            if (!username || !password) {
+                throw new ToolInputError("username and password are required.");
+            }
+            const datasource = await resolveBindingDatasource(deps, typeof input.datasource === "string" ? input.datasource : undefined);
+            if (!datasource) {
+                throw new ToolInputError("No datasource selected. Configure a default datasource or pass datasource explicitly.");
+            }
+            const profile = await deps.profileLoader.get(datasource);
+            if (!profile) {
+                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,
+                database: currentTarget?.database ?? profile.database,
+                instanceId: currentTarget?.instanceId,
+                nodeId: currentTarget?.nodeId,
+                user: {
+                    username,
+                    password: { type: "plain", value: password },
+                },
+            });
+            await reloadEngine(deps);
+            return formatSuccess({
+                datasource,
+                username,
+            }, {
+                summary: `SQL credentials for ${datasource} updated in the current session.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "set_sql_credentials",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const clearSqlCredentialsTool = {
+    name: "clear_sql_credentials",
+    description: "Clear any session-scoped SQL credential override for a datasource and fall back to the configured profile credentials.",
+    inputSchema: {
+        datasource: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("Optional datasource template to clear. Defaults to the current default datasource."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const datasource = await resolveBindingDatasource(deps, typeof input.datasource === "string" ? input.datasource : undefined);
+            if (!datasource) {
+                throw new ToolInputError("No datasource selected. Configure a default datasource or pass datasource explicitly.");
+            }
+            const profile = await deps.profileLoader.get(datasource);
+            if (!profile) {
+                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,
+                database: currentTarget?.database ?? profile.database,
+                instanceId: currentTarget?.instanceId,
+                nodeId: currentTarget?.nodeId,
+                user: profile.user,
+            });
+            await reloadEngine(deps);
+            return formatSuccess({
+                datasource,
+            }, {
+                summary: `Session SQL credential override cleared for ${datasource}.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "clear_sql_credentials",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const getSessionBindingTool = {
+    name: "get_session_binding",
+    description: "Return the current session binding for a datasource, including selected instance, host, database, and whether SQL credentials are overridden in memory.",
+    inputSchema: {
+        datasource: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("Optional datasource template to inspect. Defaults to the current default datasource."),
+    },
+    async handler(input, deps, context) {
+        try {
+            const datasource = await resolveBindingDatasource(deps, typeof input.datasource === "string" ? input.datasource : undefined);
+            if (!datasource) {
+                throw new ToolInputError("No datasource selected. Configure a default datasource or pass datasource explicitly.");
+            }
+            const profile = await deps.profileLoader.get(datasource);
+            if (!profile) {
+                throw new ToolInputError(`Datasource "${datasource}" was not found.`);
+            }
+            const target = deps.profileLoader.getRuntimeTarget(datasource);
+            return formatSuccess({
+                datasource,
+                host: profile.host,
+                port: profile.port,
+                database: profile.database,
+                username_masked: maskUsername(profile.user.username),
+                runtime_override: {
+                    instance_id: target?.instanceId,
+                    node_id: target?.nodeId,
+                    host: target?.host,
+                    port: target?.port,
+                    database: target?.database,
+                    has_sql_credentials_override: Boolean(target?.user),
+                    username_masked: maskUsername(target?.user?.username),
+                },
+            }, {
+                summary: `Returned current session binding for ${datasource}.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "get_session_binding",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
 export const selectCloudTaurusInstanceTool = {
     name: "select_cloud_taurus_instance",
     description: "Select the default TaurusDB cloud instance for the current session so diagnostics can reuse its instance id and default node id.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taurusdb-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TaurusDB MCP server for Claude, Cursor, VS Code, and other MCP clients.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
     "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
-    "taurusdb-core": "0.1.0",
+    "taurusdb-core": "0.2.0",
     "@modelcontextprotocol/sdk": "^1.17.0",
     "mysql2": "^3.22.1",
     "zod": "^3.24.1"