taurusdb-mcp 0.4.0 → 0.5.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TaurusDB MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,7 +10,7 @@ TaurusDB MCP server for MCP clients such as:
 ## Install
 
 ```bash
-npm install taurusdb-mcp
+npm install taurusdb-mcp@latest
 ```
 
 Run directly with:
@@ -28,17 +28,23 @@ Use this command in MCP client configs:
 }
 ```
 
+Configure Huawei Cloud identity through the operating-system credential store
+before adding the server. AK/SK values should not be copied into MCP client
+configuration:
+
+```bash
+npx -y taurusdb-mcp credentials configure
+TAURUSDB_CLOUD_KEYCHAIN_SERVICE=taurusdb-mcp/huaweicloud \
+  npx -y taurusdb-mcp credentials check
+```
+
 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='hw-kms-file:~/.taurusdb-mcp/password.ciphertext' \
+  -e TAURUSDB_CLOUD_KEYCHAIN_SERVICE=taurusdb-mcp/huaweicloud \
   -- npx -y taurusdb-mcp
 ```
 
@@ -47,14 +53,20 @@ 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='hw-kms-file:~/.taurusdb-mcp/password.ciphertext' \
+  --env TAURUSDB_CLOUD_KEYCHAIN_SERVICE=taurusdb-mcp/huaweicloud \
   -- npx -y taurusdb-mcp
 ```
 
+Interactive connection flow:
+
+1. Call `list_cloud_taurus_instances`.
+2. Call `select_cloud_taurus_instance`.
+3. Open the returned `login_url` in a browser and enter the database credentials.
+4. Continue with `list_databases`, `set_default_database`, and readonly tools.
+
+The browser submits credentials directly to the loopback MCP process. They are not
+sent through Agent-visible tool arguments or persisted by MCP.
+
 Initialize local MCP client config:
 
 ```bash
@@ -74,6 +86,25 @@ npx taurusdb-mcp credentials check
 
 - Requires Node.js `>= 20`
 - Depends on `taurusdb-core`
-- Database passwords support `env:`, `file:`, `hw-csms:`, `hw-kms:`, and `hw-kms-file:` references
-- Huawei DEW CSMS is recommended when the database password should be stored and retrieved from Huawei Cloud
+- Interactive clients do not need database usernames or passwords in MCP configuration
+- Unattended static deployments may use `env:`, `file:`, `hw-csms:`, `hw-kms:`, or `hw-kms-file:` password references
 - macOS Keychain, Linux Secret Service, or Windows Credential Manager cloud identity is enabled with `TAURUSDB_CLOUD_KEYCHAIN_SERVICE`
+- SQL TLS with certificate verification is required by default
+- General database mutation tools do not exist; the Agent-facing operating plane remains read-only regardless of database account privileges
+- `restore_recycle_bin_table` is visible by default and directly restores one exact recycle-bin object to one explicit non-existing destination after readonly preflight; it uses the active in-memory SQL session, post-verifies the destination, and writes audit evidence without a browser approval step
+- `analyze_mutation_sql` returns evidence-backed SQL Advice with `execution_status: not_executed`
+- Selecting a cloud instance returns a local SQL login link immediately; login validates the connection before binding credentials, allows at most three attempts per five-minute link, and never sends the password through Agent-visible tool arguments
+- Interactive instance selection binds the read/write public IP and fails immediately when the instance has no public IP; it never falls back to a VPC-private address that a local MCP client cannot route to
+- Before issuing a login link, instance selection performs a credential-free TCP endpoint preflight and returns actionable security-group/network guidance when the public database port is unreachable
+- Login validation distinguishes unreachable endpoint, refused port, TLS, authentication, and database validation timeout failures instead of returning a generic HTTP 504
+- Recoverable login errors render their structured code and remediation directly in the browser page with HTTP 200 so embedded webviews do not hide the message; cross-origin requests remain blocked with HTTP 403
+- Instance selection and local login tools are enabled by default; fixed static deployments may set `TAURUSDB_ENABLE_DYNAMIC_TARGETS=false`
+- Session SQL credentials expire after 30 idle minutes and eight absolute hours; administrators may shorten these limits with `TAURUSDB_SQL_CREDENTIAL_IDLE_TTL_MINUTES` and `TAURUSDB_SQL_CREDENTIAL_MAX_TTL_MINUTES`
+- MCP audit events are written to `~/.taurusdb-mcp/audit.jsonl` by default, with
+  configurable size rotation for collection into centralized immutable storage
+- Run one stdio process per customer/client trust boundary; this package is not
+  a shared multi-tenant HTTP service
+
+Customers execute reviewed general-purpose `advised_sql` through their own controlled
+change process. The only MCP database-state exception is the target-bound,
+same-browser-confirmed recycle-bin recovery described above.

package/dist/commands/approve.d.ts

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

package/dist/commands/approve.js

@@ -0,0 +1,66 @@
+import { readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { signApprovalRequest } from "taurusdb-core";
+function readOption(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1) {
+        return undefined;
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${name} requires a value.`);
+    }
+    return value;
+}
+function expandTilde(input) {
+    if (input === "~") {
+        return os.homedir();
+    }
+    return input.startsWith("~/") ? path.join(os.homedir(), input.slice(2)) : input;
+}
+function usage() {
+    return `Usage: taurusdb-mcp approve --request <approval-request> --actor <identity> [options]
+
+Options:
+  --secret-file <path>  Approval secret file; defaults to
+                        TAURUSDB_MUTATION_APPROVAL_SECRET_FILE
+  --request <value>     approval_request returned by a mutation tool
+  --actor <identity>    Human approver identity recorded in the signed token
+
+The command prints a one-time approval_token. Run it outside the MCP client
+after reviewing the SQL hash, datasource, database, risk, and expiry encoded
+in approval_request.`;
+}
+async function readProtectedSecret(filePath) {
+    const resolved = expandTilde(filePath);
+    const info = await stat(resolved);
+    if (!info.isFile()) {
+        throw new Error("Mutation approval secret path must reference a regular file.");
+    }
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+        throw new Error("Mutation approval secret file must not be accessible by group or other users.");
+    }
+    const secret = (await readFile(resolved, "utf8")).trim();
+    if (Buffer.byteLength(secret, "utf8") < 32) {
+        throw new Error("Mutation approval secret must contain at least 32 bytes.");
+    }
+    return secret;
+}
+export async function runApprove(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(`${usage()}\n`);
+        return 0;
+    }
+    const request = readOption(args, "--request");
+    const actor = readOption(args, "--actor");
+    const secretFile = readOption(args, "--secret-file") ??
+        process.env.TAURUSDB_MUTATION_APPROVAL_SECRET_FILE?.trim();
+    if (!request || !actor || !secretFile) {
+        process.stderr.write(`${usage()}\n`);
+        return 2;
+    }
+    const secret = await readProtectedSecret(secretFile);
+    process.stdout.write(`${signApprovalRequest(request, actor, secret)}\n`);
+    return 0;
+}

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { runInit } from "./commands/init.js";
 import { runCredentials } from "./commands/credentials.js";
+import { runApprove } from "./commands/approve.js";
 import { startMcpServer } from "./server.js";
 import { VERSION } from "./version.js";
 async function main() {
@@ -14,6 +15,10 @@ async function main() {
         process.exitCode = await runCredentials(args.slice(1));
         return;
     }
+    if (firstArg === "approve") {
+        process.exitCode = await runApprove(args.slice(1));
+        return;
+    }
     if (firstArg === "--version" || firstArg === "-v") {
         process.stdout.write(`${VERSION}\n`);
         return;

package/dist/security/database-endpoint-preflight.d.ts

@@ -0,0 +1,8 @@
+export type DatabaseEndpointFailure = "refused" | "unreachable";
+export declare class DatabaseEndpointPreflightError extends Error {
+    readonly kind: DatabaseEndpointFailure;
+    readonly host: string;
+    readonly port: number;
+    constructor(kind: DatabaseEndpointFailure, host: string, port: number);
+}
+export declare function preflightDatabaseEndpoint(host: string, port: number, timeoutMs?: number): Promise<void>;

package/dist/security/database-endpoint-preflight.js

@@ -0,0 +1,33 @@
+import { createConnection } from "node:net";
+export class DatabaseEndpointPreflightError extends Error {
+    kind;
+    host;
+    port;
+    constructor(kind, host, port) {
+        super(`Database endpoint preflight failed: ${kind}`);
+        this.name = "DatabaseEndpointPreflightError";
+        this.kind = kind;
+        this.host = host;
+        this.port = port;
+    }
+}
+export function preflightDatabaseEndpoint(host, port, timeoutMs = 3_000) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const socket = createConnection({ host, port });
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => finish());
+        socket.once("timeout", () => finish(new DatabaseEndpointPreflightError("unreachable", host, port)));
+        socket.once("error", (error) => finish(new DatabaseEndpointPreflightError(error.code === "ECONNREFUSED" ? "refused" : "unreachable", host, port)));
+    });
+}

package/dist/security/local-credential-login.d.ts

@@ -0,0 +1,50 @@
+export type SqlLoginCredentials = {
+    datasource: string;
+    username: string;
+    password: string;
+};
+export type SqlLoginTarget = {
+    datasource: string;
+    instanceId?: string;
+    region?: string;
+    credentialIdleTtlMinutes?: number;
+    credentialMaxTtlMinutes?: number;
+};
+export type SqlLoginRequest = {
+    datasource: string;
+    target?: SqlLoginTarget;
+    bind: (credentials: SqlLoginCredentials) => Promise<void>;
+};
+export type IssuedSqlLogin = {
+    loginUrl: string;
+    expiresAt: string;
+};
+export type CredentialValidationFailure = "credentials" | "unreachable" | "refused" | "connectivity" | "tls" | "timeout";
+export declare class SqlCredentialValidationError extends Error {
+    readonly kind: CredentialValidationFailure;
+    constructor(kind: CredentialValidationFailure);
+}
+export interface CredentialLoginService {
+    issueSqlLogin(request: SqlLoginRequest): Promise<IssuedSqlLogin>;
+    close(): Promise<void>;
+}
+export type LocalCredentialLoginServiceOptions = {
+    now?: () => number;
+    tokenTtlMs?: number;
+    maxAttempts?: number;
+    failureDelayMs?: number;
+};
+export declare class LocalCredentialLoginService implements CredentialLoginService {
+    private readonly now;
+    private readonly tokenTtlMs;
+    private readonly maxAttempts;
+    private readonly failureDelayMs;
+    private readonly pending;
+    private server;
+    private port;
+    constructor(options?: LocalCredentialLoginServiceOptions);
+    issueSqlLogin(request: SqlLoginRequest): Promise<IssuedSqlLogin>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private handle;
+}