@ffschrattenecker/tm1-mcp-server 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [8.1.0] - 2026-09-28
+
+### Added
+
+- Connection secrets can live in the OS keychain instead of the `.env`: set `TM1_SECRETS=keychain`
+  in a connection folder and store the secrets with `npx tm1-mcp-server secrets set|list|delete`,
+  or move an existing `.env` over with `secrets migrate <connection>`. The keychain is read the
+  first time a connection is used, never when connections are listed. At startup the server warns
+  about connections that still keep plaintext secrets. See
+  [docs/CONFIGURATION.md](docs/CONFIGURATION.md#secrets-in-the-os-keychain--tm1_secretskeychain).
+
+### Changed
+
+- **`tm1_clear_cube` no longer declares `dimensions`/`tuples`.** They are dropped like any
+  unknown input, so an old call that still sends them empties the whole cube once `confirm`
+  matches. *Action:* remove them from stored calls; a partial clear is a TI process.
+
 ## [8.0.0] - 2026-09-28
 
 Merged upstream tm1-mcp-server 5.0.0 (flameY3T1, 2026-09-27). Where both lines had
@@ -86,7 +103,7 @@ response-size guard, the per-connection caches) are unchanged.
 - **Corrected descriptions** of `tm1_unload_cube`, `tm1_clear_cube`, `tm1_delete_hierarchy`,
   `tm1_get_cube_stats` and `tm1_get_transaction_log`.
 - **The wire contracts were re-recorded against 11.8** upstream and merged with the fork's
-  plapp-franz recordings; the recorder now merges by default (`--replace` starts over).
+  own recordings; the recorder now merges by default (`--replace` starts over).
 
 ## [7.0.2] - 2026-09-27
 
@@ -1405,7 +1422,8 @@ Initial public release.
 - Quality gates: strict typecheck, ESLint, `lint:no-flat-api`,
   annotation-coverage, and tool-registration wiring.
 
-[Unreleased]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v8.0.0...HEAD
+[Unreleased]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v8.1.0...HEAD
+[8.1.0]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v8.0.0...v8.1.0
 [8.0.0]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v7.0.2...v8.0.0
 [7.0.2]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v7.0.1...v7.0.2
 [7.0.1]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v7.0.0...v7.0.1

package/README.md

@@ -171,7 +171,10 @@ its report, just redacted.
 Copy `mcp.json.example` to `.mcp.json` (project-local) or merge it into
 `~/.claude/settings.json`. **Do not put `TM1_PASSWORD` in either file** — those
 are routinely shared or committed; keep it in a gitignored `.env`
-([where the server looks for one](docs/CONFIGURATION.md#where-credentials-are-read-from)).
+([where the server looks for one](docs/CONFIGURATION.md#where-credentials-are-read-from)),
+or out of files altogether in the OS keychain with
+`npx tm1-mcp-server secrets migrate <connection>`
+([details](docs/CONFIGURATION.md#secrets-in-the-os-keychain--tm1_secretskeychain)).
 
 For the `npx` install:
 

package/dist/config.d.ts

@@ -35,7 +35,16 @@ export interface TM1Config {
 export declare const DEFAULT_MAX_RESPONSE_CHARS = 80000;
 export type ServerSettings = Pick<TM1Config, "logLevel" | "logFile" | "transport" | "httpHost" | "httpPort" | "httpAllowedOrigins" | "httpToken" | "responseMode" | "maxResponseChars">;
 export declare function loadServerSettings(env?: NodeJS.ProcessEnv): ServerSettings;
-export declare function loadConfig(env?: NodeJS.ProcessEnv): TM1Config;
+export interface LoadConfigOptions {
+    /**
+     * The secrets are not in `env` yet: they are read from the OS keychain when
+     * the connection is first used (see ./secrets.ts), and loadConfig runs again
+     * then, with them. Until then a missing secret is not an error, and neither
+     * is a missing TM1_USER — the keychain may hold a TM1_CAM_PASSPORT.
+     */
+    deferSecrets?: boolean;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv, options?: LoadConfigOptions): TM1Config;
 /**
  * Stable label for a connection: host and port, plus the v12
  * instance/database. Keys per-connection state (process backups, the callgraph

package/dist/config.js

@@ -106,7 +106,8 @@ export function loadServerSettings(env = process.env) {
 }
 // `env` defaults to the process environment. The multi-connection registry
 // passes one record per connection folder instead (see ./connections.ts).
-export function loadConfig(env = process.env) {
+export function loadConfig(env = process.env, options = {}) {
+    const deferred = options.deferSecrets === true;
     const baseUrl = env.TM1_BASE_URL;
     const user = env.TM1_USER;
     const password = env.TM1_PASSWORD;
@@ -143,7 +144,7 @@ export function loadConfig(env = process.env) {
     const missing = [];
     if (!baseUrl)
         missing.push("TM1_BASE_URL");
-    if (!camPassport) {
+    if (!camPassport && !deferred) {
         if (!user)
             missing.push("TM1_USER");
         if (password === undefined && !passwordlessV12) {
@@ -154,7 +155,7 @@ export function loadConfig(env = process.env) {
         throw new Error(`Missing or empty required environment variables: ${missing.join(", ")}. ` +
             `Set them in your shell or .env file before starting the server.`);
     }
-    if (!camPassport && !passwordlessV12 && password === "") {
+    if (!camPassport && !passwordlessV12 && !deferred && password === "") {
         process.stderr.write("[tm1-mcp-server] WARNING: TM1_PASSWORD is empty. " +
             "If TM1 rejects with 401, check whether the account actually allows blank passwords.\n");
     }
@@ -229,15 +230,15 @@ export function loadConfig(env = process.env) {
         if (authMode === "s2s") {
             if (!clientId)
                 missingV12.push("TM1_CLIENT_ID");
-            if (!clientSecret)
+            if (!clientSecret && !deferred)
                 missingV12.push("TM1_CLIENT_SECRET");
         }
         else if (authMode === "access_token" || authMode === "oidc") {
-            if (!accessToken)
+            if (!accessToken && !deferred)
                 missingV12.push("TM1_ACCESS_TOKEN");
         }
         else if (authMode === "iam") {
-            if (!apiKey)
+            if (!apiKey && !deferred)
                 missingV12.push("TM1_API_KEY");
             if (!iamUrl)
                 missingV12.push("TM1_IAM_URL");

package/dist/connections.d.ts

@@ -1,5 +1,6 @@
 import pino from "pino";
 import { type TM1Config } from "./config.js";
+import { type SecretStore } from "./secrets.js";
 import { TM1Client } from "./tm1-client.js";
 /** Folder holding one `<name>/.env` per connection. */
 export declare function connectionsDir(env: NodeJS.ProcessEnv): string;
@@ -30,6 +31,8 @@ export interface ConnectionInfo {
     connectionId?: string | undefined;
     /** Set when the folder's `.env` could not be turned into a config. */
     configError?: string | undefined;
+    /** "keychain" when the secrets are read from the OS keychain on first use. */
+    secrets?: "keychain" | undefined;
 }
 export interface ConnectionStatus extends ConnectionInfo {
     connected: boolean;
@@ -37,10 +40,14 @@ export interface ConnectionStatus extends ConnectionInfo {
 }
 export declare class ConnectionRegistry {
     private readonly logger;
+    /** Defaults to the OS keychain; tests inject a fake. */
+    private readonly secretStore?;
     private readonly entries;
     private constructor();
     /** Discover connections from the environment (see the header comment). */
-    static fromEnvironment(env: NodeJS.ProcessEnv, logger: pino.Logger): ConnectionRegistry;
+    static fromEnvironment(env: NodeJS.ProcessEnv, logger: pino.Logger, options?: {
+        secretStore?: SecretStore;
+    }): ConnectionRegistry;
     /** Wrap one prebuilt client (tests, embedders). */
     static single(client: TM1Client, logger?: pino.Logger): ConnectionRegistry;
     /**
@@ -54,6 +61,8 @@ export declare class ConnectionRegistry {
         client: TM1Client;
         mode?: TM1Config["mode"];
     }>, logger?: pino.Logger): ConnectionRegistry;
+    /** Validate one connection's env; keychain secrets are read later. */
+    private addEnv;
     private addConfig;
     private discover;
     /** Every connection name, including ones whose config failed to load. */
@@ -79,6 +88,8 @@ export declare class ConnectionRegistry {
      * until the server restarts.
      */
     get(name: string | undefined): Promise<TM1Client>;
+    /** The full config of a keychain connection, secrets included. */
+    private resolveSecrets;
     /** Connection metadata for a resolved call (mode/version gates). */
     resolveInfo(name: string | undefined): ConnectionInfo;
     disconnectAll(): Promise<void>;

package/dist/connections.js

@@ -18,12 +18,17 @@
 // defaults to readonly: a connection-level key (TM1_MODE, TM1_BASE_URL, …) in
 // the server's own environment is NOT inherited, so a TM1_MODE=readwrite in
 // the launching shell cannot silently arm every connection.
+//
+// A folder with TM1_SECRETS=keychain keeps its secrets in the OS keychain
+// (see ./secrets.ts). Discovery validates it without them; get() reads them
+// and builds the real config on first use.
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { parse as parseDotenv } from "dotenv";
 import pino from "pino";
 import { connectionIdOf, loadConfig } from "./config.js";
+import { keychainHint, plaintextSecretKeys, usesKeychain, withKeychainSecrets, } from "./secrets.js";
 import { SessionManager } from "./session-manager.js";
 import { TM1Client } from "./tm1-client.js";
 import { TM1Error, TM1ErrorCode } from "./types.js";
@@ -69,16 +74,20 @@ export function connectionEnv(folder, env) {
 }
 export class ConnectionRegistry {
     logger;
+    secretStore;
     entries = new Map();
-    constructor(logger) {
+    constructor(logger, 
+    /** Defaults to the OS keychain; tests inject a fake. */
+    secretStore) {
         this.logger = logger;
+        this.secretStore = secretStore;
     }
     /** Discover connections from the environment (see the header comment). */
-    static fromEnvironment(env, logger) {
-        const registry = new ConnectionRegistry(logger);
+    static fromEnvironment(env, logger, options = {}) {
+        const registry = new ConnectionRegistry(logger, options.secretStore);
         const explicitDir = env.TM1_CONNECTIONS_DIR;
         if (!explicitDir && env.TM1_BASE_URL) {
-            registry.addConfig("default", loadConfig(env));
+            registry.addEnv("default", env);
             return registry;
         }
         const dir = connectionsDir(env);
@@ -123,6 +132,17 @@ export class ConnectionRegistry {
         }
         return registry;
     }
+    /** Validate one connection's env; keychain secrets are read later. */
+    addEnv(name, env, dir) {
+        const keychain = usesKeychain(env);
+        const config = loadConfig(env, { deferSecrets: keychain });
+        this.addConfig(name, config, dir);
+        if (keychain) {
+            const entry = this.entries.get(name);
+            entry.env = env;
+            entry.info.secrets = "keychain";
+        }
+    }
     addConfig(name, config, dir) {
         this.entries.set(name, {
             info: {
@@ -152,10 +172,16 @@ export class ConnectionRegistry {
             .map((d) => d.name)
             .filter((name) => !only || only.has(name))
             .sort((a, b) => a.localeCompare(b));
+        const plaintext = [];
         for (const name of names) {
             const folder = join(dir, name);
             try {
-                this.addConfig(name, loadConfig(connectionEnv(folder, env)), folder);
+                const connEnv = connectionEnv(folder, env);
+                this.addEnv(name, connEnv, folder);
+                if (!this.entries.get(name).env &&
+                    plaintextSecretKeys(connEnv).length) {
+                    plaintext.push(name);
+                }
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -165,6 +191,10 @@ export class ConnectionRegistry {
                 });
             }
         }
+        if (plaintext.length > 0) {
+            this.logger.warn({ connections: plaintext }, "plaintext secrets in .env — move them to the OS keychain with " +
+                "`npx tm1-mcp-server secrets migrate <connection>`");
+        }
     }
     /** Every connection name, including ones whose config failed to load. */
     get names() {
@@ -236,6 +266,19 @@ export class ConnectionRegistry {
      */
     async get(name) {
         const entry = this.entryFor(name);
+        if (!entry.client && entry.env) {
+            // Concurrent first calls share one keychain read. A failure is not
+            // cached: the next call reads again, after the user stored the entry.
+            entry.resolving ??= this.resolveSecrets(entry)
+                .catch((err) => {
+                entry.lastError = err instanceof Error ? err.message : String(err);
+                throw err;
+            })
+                .finally(() => {
+                entry.resolving = undefined;
+            });
+            entry.config = await entry.resolving;
+        }
         if (!entry.client) {
             const config = entry.config;
             const logger = this.logger.child({ connection: entry.info.name });
@@ -258,6 +301,20 @@ export class ConnectionRegistry {
             await entry.connecting;
         return entry.client;
     }
+    /** The full config of a keychain connection, secrets included. */
+    async resolveSecrets(entry) {
+        const { name } = entry.info;
+        const env = await withKeychainSecrets(name, entry.env, this.secretStore);
+        try {
+            return loadConfig(env);
+        }
+        catch (err) {
+            throw new TM1Error({
+                code: TM1ErrorCode.VALIDATION_ERROR,
+                message: `Connection "${name}": ${err instanceof Error ? err.message : String(err)}${keychainHint(name)}`,
+            });
+        }
+    }
     /** Connection metadata for a resolved call (mode/version gates). */
     resolveInfo(name) {
         return this.entryFor(name).info;

package/dist/index.js

@@ -65,6 +65,12 @@ function buildMcpServer(registry, settings, logger) {
     };
 }
 async function main() {
+    // `tm1-mcp-server secrets …` manages keychain entries and exits; it never
+    // starts the server.
+    if (process.argv[2] === "secrets") {
+        const { runSecretsCli } = await import("./secrets-cli.js");
+        process.exit(await runSecretsCli(process.argv.slice(3), process.env));
+    }
     const settings = loadServerSettings();
     const logger = createLogger(settings);
     logger.info("Starting TM1 MCP Server");

package/dist/lib/sample-cells.js

@@ -40,7 +40,7 @@ export function buildSampleCellsMdx(args) {
     // An unfiltered Sandboxes is pinned to Base instead of crossjoined: TM1's
     // NONEMPTY() returns an empty set whenever Sandboxes is part of the row set,
     // even as {[Sandboxes].[Base]} alone, so every sample of a sandboxed cube
-    // came back empty. Measured on plapp-franz (EnableSandboxDimension=true).
+    // came back empty. Measured on a server with EnableSandboxDimension=true.
     // Base is also what every other read through this server sees.
     let sandboxPin;
     for (const dim of dimensions) {

package/dist/secrets-cli.d.ts

@@ -0,0 +1,10 @@
+import { type SecretStore } from "./secrets.js";
+export interface CliIo {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    /** Reads one secret without echoing it. */
+    readSecret: (prompt: string) => Promise<string>;
+}
+export declare function runSecretsCli(args: string[], env: NodeJS.ProcessEnv, io?: CliIo, store?: SecretStore): Promise<number>;
+export declare function stripPipedInput(raw: string): string;
+//# sourceMappingURL=secrets-cli.d.ts.map

package/dist/secrets-cli.js

@@ -0,0 +1,218 @@
+// `tm1-mcp-server secrets <command>` — manage the keychain entries of a
+// connection (see ./secrets.ts). No command ever prints a secret value.
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseDotenv } from "dotenv";
+import { connectionsDir } from "./connections.js";
+import { isSecretKey, keychainAccount, keychainStore, plaintextSecretKeys, SECRET_KEYS, } from "./secrets.js";
+const USAGE = `Usage: tm1-mcp-server secrets <command> <connection> [KEY]
+
+  set <connection> [KEY]     store a secret (prompted, or read from stdin)
+  list <connection>          show which secrets are stored (never the values)
+  delete <connection> [KEY]  remove one secret, or all of the connection's
+  migrate <connection>       move the plaintext secrets of <connection>/.env
+                             into the keychain and set TM1_SECRETS=keychain
+
+KEY is one of ${SECRET_KEYS.join(", ")} (default TM1_PASSWORD).
+<connection> is a folder under ~/.tm1/mcp-servers (or $TM1_CONNECTIONS_DIR).`;
+export async function runSecretsCli(args, env, io = processIo, store) {
+    const [command, connection, keyArg, ...extra] = args;
+    if (!command || command === "help" || command === "--help") {
+        io.out(USAGE);
+        return command ? 0 : 2;
+    }
+    if (!connection || extra.length > 0) {
+        io.err(USAGE);
+        return 2;
+    }
+    if (keyArg !== undefined && !isSecretKey(keyArg)) {
+        io.err(`Unknown KEY "${keyArg}". One of: ${SECRET_KEYS.join(", ")}.`);
+        return 2;
+    }
+    const folder = join(connectionsDir(env), connection);
+    const envFile = join(folder, ".env");
+    if (!existsSync(envFile)) {
+        io.err(`No connection "${connection}": ${envFile} does not exist.`);
+        return 2;
+    }
+    let keychain;
+    try {
+        keychain = store ?? (await keychainStore());
+    }
+    catch (err) {
+        io.err(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    switch (command) {
+        case "set": {
+            const key = keyArg ?? "TM1_PASSWORD";
+            const value = await io.readSecret(`${key} for ${connection}: `);
+            if (value === "") {
+                io.err("Empty value — nothing stored.");
+                return 1;
+            }
+            // Pasted or piped junk becomes a wrong password, and wrong passwords
+            // lock TM1 accounts.
+            if (/[\r\n]/.test(value)) {
+                io.err("The value spans several lines — nothing stored.");
+                return 1;
+            }
+            keychain.set(connection, key, value);
+            io.out(`Stored ${keychainAccount(connection, key)}.`);
+            const marker = parseDotenv(readFileSync(envFile)).TM1_SECRETS;
+            if (marker?.trim().toLowerCase() !== "keychain") {
+                io.out(`The .env does not set TM1_SECRETS=keychain yet, so the server ` +
+                    `ignores this entry. Run \`secrets migrate ${connection}\` or add it.`);
+            }
+            return 0;
+        }
+        case "list": {
+            for (const key of SECRET_KEYS) {
+                const stored = keychain.get(connection, key) !== undefined;
+                io.out(`${key.padEnd(18)} ${stored ? "stored" : "-"}`);
+            }
+            return 0;
+        }
+        case "delete": {
+            const keys = keyArg ? [keyArg] : SECRET_KEYS;
+            for (const key of keys) {
+                if (keychain.delete(connection, key)) {
+                    io.out(`Deleted ${keychainAccount(connection, key)}.`);
+                }
+                else if (keyArg) {
+                    io.out(`No entry ${keychainAccount(connection, key)}.`);
+                }
+            }
+            return 0;
+        }
+        case "migrate":
+            return migrate(connection, envFile, keychain, io);
+        default:
+            io.err(`Unknown command "${command}".\n${USAGE}`);
+            return 2;
+    }
+}
+/**
+ * Move the plaintext secrets of one `.env` into the keychain. Order matters:
+ * every secret is stored and read back BEFORE the file changes, and the new
+ * file is checked to parse to exactly the old settings minus the secrets. No
+ * plaintext backup is kept — that would defeat the point.
+ */
+function migrate(connection, envFile, keychain, io) {
+    const text = readFileSync(envFile, "utf8");
+    const before = parseDotenv(text);
+    const keys = plaintextSecretKeys(before);
+    if (keys.length === 0) {
+        io.out(`${envFile} holds no plaintext secret.`);
+        return 0;
+    }
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const kept = [];
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/.exec(line);
+        const name = match?.[1];
+        if (name && (keys.includes(name) || name === "TM1_SECRETS")) {
+            const value = match[2].trim();
+            const quote = value[0];
+            if ((quote === '"' || quote === "'" || quote === "`") &&
+                value.indexOf(quote, 1) === -1) {
+                io.err(`${name} in ${envFile} is a multi-line value; move it by hand.`);
+                return 1;
+            }
+            continue;
+        }
+        kept.push(line);
+    }
+    while (kept.length > 0 && kept[kept.length - 1] === "")
+        kept.pop();
+    kept.push("TM1_SECRETS=keychain", "");
+    const next = kept.join(eol);
+    const after = parseDotenv(next);
+    // A blank value (TM1_PASSWORD= for a blank-password account) is no secret
+    // and stays in the file.
+    const expected = {
+        ...before,
+        TM1_SECRETS: "keychain",
+    };
+    for (const key of keys)
+        delete expected[key];
+    if (JSON.stringify(sorted(after)) !== JSON.stringify(sorted(expected))) {
+        io.err(`Could not rewrite ${envFile} safely; nothing changed.`);
+        return 1;
+    }
+    for (const key of keys) {
+        const value = before[key];
+        keychain.set(connection, key, value);
+        if (keychain.get(connection, key) !== value) {
+            io.err(`Reading ${keychainAccount(connection, key)} back returned a different ` +
+                `value; ${envFile} left unchanged.`);
+            return 1;
+        }
+        io.out(`Stored ${keychainAccount(connection, key)}.`);
+    }
+    const tmp = `${envFile}.tmp`;
+    writeFileSync(tmp, next);
+    renameSync(tmp, envFile);
+    io.out(`Removed ${keys.join(", ")} from ${envFile} and set TM1_SECRETS=keychain. ` +
+        `Restart the MCP client to pick up the change.`);
+    return 0;
+}
+function sorted(obj) {
+    return Object.entries(obj).sort(([a], [b]) => a.localeCompare(b));
+}
+const processIo = {
+    out: (line) => process.stdout.write(`${line}\n`),
+    err: (line) => process.stderr.write(`${line}\n`),
+    readSecret: (prompt) => process.stdin.isTTY ? promptHidden(prompt) : readPipedStdin(),
+};
+/**
+ * `echo secret | tm1-mcp-server secrets set …` — a leading BOM (PowerShell
+ * pipes) and one trailing newline dropped. Git Bash's mintty is no TTY to
+ * Node either, so typed input lands here too, echoed: say so.
+ */
+async function readPipedStdin() {
+    process.stderr.write("Reading the secret from stdin until EOF. In a terminal that is no TTY to " +
+        "Node (Git Bash/mintty) the input is echoed; pipe the value or use " +
+        "PowerShell/cmd instead.\n");
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return stripPipedInput(Buffer.concat(chunks).toString("utf8"));
+}
+export function stripPipedInput(raw) {
+    return raw.replace(/^\uFEFF/, "").replace(/\r?\n$/, "");
+}
+function promptHidden(prompt) {
+    return new Promise((resolve, reject) => {
+        const stdin = process.stdin;
+        process.stderr.write(prompt);
+        stdin.setRawMode(true);
+        stdin.setEncoding("utf8");
+        stdin.resume();
+        let value = "";
+        const done = (err) => {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.off("data", onData);
+            process.stderr.write("\n");
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\r" || ch === "\n")
+                    return done();
+                if (ch === "\u0003")
+                    return done(new Error("Aborted."));
+                if (ch === "\u007f" || ch === "\b")
+                    value = value.slice(0, -1);
+                else
+                    value += ch;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+//# sourceMappingURL=secrets-cli.js.map

package/dist/secrets.d.ts

@@ -0,0 +1,39 @@
+/** Every `.env` key that holds a credential. */
+export declare const SECRET_KEYS: readonly ["TM1_PASSWORD", "TM1_CLIENT_SECRET", "TM1_ACCESS_TOKEN", "TM1_API_KEY", "TM1_CAM_PASSPORT"];
+export type SecretKey = (typeof SECRET_KEYS)[number];
+export declare const KEYCHAIN_SERVICE = "tm1-mcp-server";
+export declare function isSecretKey(key: string): key is SecretKey;
+export declare function keychainAccount(connection: string, key: SecretKey): string;
+/** The Windows Credential Manager target name of one entry. */
+export declare function keychainTarget(connection: string, key: SecretKey): string;
+/** Secret keys that carry a non-empty plaintext value in `env`. */
+export declare function plaintextSecretKeys(env: NodeJS.ProcessEnv): SecretKey[];
+/**
+ * True when the connection keeps its secrets in the keychain. Throws on an
+ * unknown TM1_SECRETS value, and when a keychain connection still carries a
+ * plaintext secret — which of the two should win is not guessable, and a
+ * stale one is exactly the kind of wrong password that locks an account.
+ * An empty value (`TM1_PASSWORD=`, a blank-password account) is no conflict.
+ */
+export declare function usesKeychain(env: NodeJS.ProcessEnv): boolean;
+/** The OS store, narrowed to what the server and the CLI need. */
+export interface SecretStore {
+    get(connection: string, key: SecretKey): string | undefined;
+    set(connection: string, key: SecretKey, value: string): void;
+    /** True when an entry existed. */
+    delete(connection: string, key: SecretKey): boolean;
+}
+/**
+ * The OS keychain. The native binding is imported on first use, so a
+ * platform without a prebuilt binary only breaks connections that ask for it.
+ */
+export declare function keychainStore(): Promise<SecretStore>;
+/**
+ * `env` with every secret the keychain holds for `connection` filled in. The
+ * result goes straight into loadConfig and is never written to process.env,
+ * so child processes do not inherit it.
+ */
+export declare function withKeychainSecrets(connection: string, env: NodeJS.ProcessEnv, store?: SecretStore): Promise<NodeJS.ProcessEnv>;
+/** Appended to a config error on a keychain connection: how to fix it. */
+export declare function keychainHint(connection: string): string;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.js

@@ -0,0 +1,128 @@
+// Connection secrets kept in the OS keychain instead of the `.env`.
+//
+// A connection folder opts in with `TM1_SECRETS=keychain`. Its `.env` then
+// carries no secret; each one lives in the OS store (Windows Credential
+// Manager, macOS Keychain, Linux Secret Service) under
+//
+//   service "tm1-mcp-server", account "<connection>/<KEY>"
+//   Windows target name "<connection>/<KEY>.tm1-mcp-server"
+//
+// The Windows target name is the library default ("<account>.<service>"),
+// pinned by keychainTarget() because a stdlib-only reader — the tm1-api
+// skill's tm1.py calls CredReadW via ctypes — looks the entry up by it. The
+// blob is UTF-16LE. Entry.withTarget() is deliberately not used: in
+// @napi-rs/keyring 2.1.0 on Windows a fresh Entry reads back "" for it.
+//
+// Discovery never reads the store: loadConfig(env, { deferSecrets: true })
+// accepts the folder, and the secrets are read when the connection is first
+// used (ConnectionRegistry.get). Listing connections therefore never touches
+// the keychain, and a missing entry fails that one connection, not startup.
+//
+// What this protects: the secret no longer sits in a file that gets synced,
+// backed up, committed, pasted or read into an agent's context. What it does
+// not: any process running as the same OS user can read the store too.
+import { TM1Error, TM1ErrorCode } from "./types.js";
+/** Every `.env` key that holds a credential. */
+export const SECRET_KEYS = [
+    "TM1_PASSWORD",
+    "TM1_CLIENT_SECRET",
+    "TM1_ACCESS_TOKEN",
+    "TM1_API_KEY",
+    "TM1_CAM_PASSPORT",
+];
+export const KEYCHAIN_SERVICE = "tm1-mcp-server";
+export function isSecretKey(key) {
+    return SECRET_KEYS.includes(key);
+}
+export function keychainAccount(connection, key) {
+    return `${connection}/${key}`;
+}
+/** The Windows Credential Manager target name of one entry. */
+export function keychainTarget(connection, key) {
+    return `${keychainAccount(connection, key)}.${KEYCHAIN_SERVICE}`;
+}
+/** Secret keys that carry a non-empty plaintext value in `env`. */
+export function plaintextSecretKeys(env) {
+    return SECRET_KEYS.filter((key) => Boolean(env[key]));
+}
+/**
+ * True when the connection keeps its secrets in the keychain. Throws on an
+ * unknown TM1_SECRETS value, and when a keychain connection still carries a
+ * plaintext secret — which of the two should win is not guessable, and a
+ * stale one is exactly the kind of wrong password that locks an account.
+ * An empty value (`TM1_PASSWORD=`, a blank-password account) is no conflict.
+ */
+export function usesKeychain(env) {
+    const raw = env.TM1_SECRETS?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    if (raw !== "keychain") {
+        throw new Error(`Invalid TM1_SECRETS: "${env.TM1_SECRETS}". Expected "keychain" or unset.`);
+    }
+    const plain = plaintextSecretKeys(env);
+    if (plain.length > 0) {
+        throw new Error(`TM1_SECRETS=keychain, but the .env still sets ${plain.join(", ")}. ` +
+            `Remove ${plain.length === 1 ? "it" : "them"} from the .env ` +
+            `(\`tm1-mcp-server secrets migrate <connection>\` does both steps).`);
+    }
+    return true;
+}
+let osStore;
+/**
+ * The OS keychain. The native binding is imported on first use, so a
+ * platform without a prebuilt binary only breaks connections that ask for it.
+ */
+export function keychainStore() {
+    osStore ??= import("@napi-rs/keyring").then(({ Entry }) => {
+        const entry = (connection, key) => new Entry(KEYCHAIN_SERVICE, keychainAccount(connection, key));
+        return {
+            get: (connection, key) => entry(connection, key).getPassword() ?? undefined,
+            set: (connection, key, value) => entry(connection, key).setPassword(value),
+            delete: (connection, key) => entry(connection, key).deletePassword(),
+        };
+    }, (err) => {
+        osStore = undefined;
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`The OS keychain is not available on this platform (${reason}).`);
+    });
+    return osStore;
+}
+/**
+ * `env` with every secret the keychain holds for `connection` filled in. The
+ * result goes straight into loadConfig and is never written to process.env,
+ * so child processes do not inherit it.
+ */
+export async function withKeychainSecrets(connection, env, store) {
+    let resolved;
+    try {
+        resolved = store ?? (await keychainStore());
+    }
+    catch (err) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `Connection "${connection}" keeps its secrets in the OS keychain: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    const out = { ...env };
+    for (const key of SECRET_KEYS) {
+        let value;
+        try {
+            value = resolved.get(connection, key);
+        }
+        catch (err) {
+            throw new TM1Error({
+                code: TM1ErrorCode.VALIDATION_ERROR,
+                message: `Reading ${keychainAccount(connection, key)} from the OS keychain failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** Appended to a config error on a keychain connection: how to fix it. */
+export function keychainHint(connection) {
+    return (` The secrets of "${connection}" are read from the OS keychain; store the ` +
+        `missing one with \`npx tm1-mcp-server secrets set ${connection} <KEY>\`.`);
+}
+//# sourceMappingURL=secrets.js.map

package/dist/tools/model-building/clear-cube.js

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { TM1Error, TM1ErrorCode } from "../../types.js";
 import { actionResponse } from "../format.js";
 import { CONFIRM_SCHEMA, requireConfirm } from "../confirm.js";
 import { DESTRUCTIVE } from "../annotations.js";
@@ -26,27 +25,8 @@ export const registerClearCube = defineTool({
             .max(3600000)
             .optional()
             .describe("Override the default 30s request timeout (ms, 1000–3600000). A clear that outlasts it keeps running on the server and still empties the cube; the call then reports a timeout instead of success."),
-        // Removed in 4.0.0, still DECLARED so a stored old call is refused instead
-        // of silently widened: the SDK strips properties the schema does not
-        // mention, so an undeclared field reaches the handler as if it was never
-        // sent — and a region clear would become a full wipe.
-        dimensions: z
-            .array(z.string())
-            .optional()
-            .describe("REMOVED — passing this fails the call. Do not send it."),
-        tuples: z
-            .array(z.array(z.string()))
-            .optional()
-            .describe("REMOVED — passing this fails the call. Do not send it."),
     },
-    handler: async ({ cubeName, confirm, timeoutMs, dimensions, tuples }, tm1Client) => {
-        if (dimensions !== undefined || tuples !== undefined) {
-            throw new TM1Error({
-                code: TM1ErrorCode.VALIDATION_ERROR,
-                message: "tm1_clear_cube no longer takes `dimensions`/`tuples`, and this call was NOT executed. Sending them once meant a region clear, which the server never supported; ignoring them here would empty the whole cube instead.",
-                hint: "To empty the whole cube, repeat the call with cubeName and confirm only. To empty part of it, run a TI process with CubeClearData()/view-based logic via tm1_execute_process.",
-            });
-        }
+    handler: async ({ cubeName, confirm, timeoutMs }, tm1Client) => {
         requireConfirm(confirm, cubeName, "cube");
         await tm1Client.cubes.clear(cubeName, timeoutMs !== undefined ? { timeoutMs } : undefined);
         return actionResponse({ success: true, cubeName, summary: "all cells" });

package/dist/tools/schemas/items-fileops.d.ts

@@ -6,8 +6,8 @@ export declare const FileContentResultSchema: z.ZodObject<{
     truncated: z.ZodBoolean;
     truncationReason: z.ZodOptional<z.ZodString>;
     encoding: z.ZodEnum<{
-        base64: "base64";
         text: "text";
+        base64: "base64";
     }>;
     content: z.ZodString;
 }, z.core.$strip>;

package/npm-shrinkwrap.json

@@ -1,15 +1,16 @@
 {
   "name": "@ffschrattenecker/tm1-mcp-server",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ffschrattenecker/tm1-mcp-server",
-      "version": "8.0.0",
+      "version": "8.1.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.30.1",
+        "@napi-rs/keyring": "^2.1.0",
         "dotenv": "^18.0.0",
         "pino": "^10.3.1",
         "regexp-tree": "^0.1.27",
@@ -862,6 +863,240 @@
         }
       }
     },
+    "node_modules/@napi-rs/keyring": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring/-/keyring-2.1.0.tgz",
+      "integrity": "sha512-km9J3fomkGSLpImpelq0cMvLBrJ5eVlTzuWdG3Iy0laP6gU90MmHYjqhUhG32aYq0/0++r2TLuAA9xlnh4XU1g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      },
+      "optionalDependencies": {
+        "@napi-rs/keyring-darwin-arm64": "2.1.0",
+        "@napi-rs/keyring-darwin-x64": "2.1.0",
+        "@napi-rs/keyring-freebsd-x64": "2.1.0",
+        "@napi-rs/keyring-linux-arm-gnueabihf": "2.1.0",
+        "@napi-rs/keyring-linux-arm64-gnu": "2.1.0",
+        "@napi-rs/keyring-linux-arm64-musl": "2.1.0",
+        "@napi-rs/keyring-linux-riscv64-gnu": "2.1.0",
+        "@napi-rs/keyring-linux-x64-gnu": "2.1.0",
+        "@napi-rs/keyring-linux-x64-musl": "2.1.0",
+        "@napi-rs/keyring-win32-arm64-msvc": "2.1.0",
+        "@napi-rs/keyring-win32-ia32-msvc": "2.1.0",
+        "@napi-rs/keyring-win32-x64-msvc": "2.1.0"
+      }
+    },
+    "node_modules/@napi-rs/keyring-darwin-arm64": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-darwin-arm64/-/keyring-darwin-arm64-2.1.0.tgz",
+      "integrity": "sha512-j6ATTOhmPW+N5EKwi8Yzn6P4Bz/uqnxzyYvqOL73/dgzDSYG5pS5eprqpVmOLse68WUTf79ZMqz97HnfvirJ9g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-darwin-x64": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-darwin-x64/-/keyring-darwin-x64-2.1.0.tgz",
+      "integrity": "sha512-54Q803nguiOaQzBG2h4uIkacI0eLGAlzzdpxPNi6IZtXbjqbPI4AQ86GrQy25tw3czBqRPBoGu0lHP2U+/f5iA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-freebsd-x64": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-freebsd-x64/-/keyring-freebsd-x64-2.1.0.tgz",
+      "integrity": "sha512-BL7ngJAYQBrUp1PTF8enOXOIVfxN51RbwVOEQ+8eAjWypF/5Ipqs8oQoMqkuc0wAbk+vatnNVjdKCIFa/HPglg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-linux-arm-gnueabihf": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-linux-arm-gnueabihf/-/keyring-linux-arm-gnueabihf-2.1.0.tgz",
+      "integrity": "sha512-JYgbCDk+giss7lKla8NTXhM/fLj+Hrfgr3xwKQ8jKn8qMD6vXLwYcfK8HJ9VoAcjIeYEUpCL6dRszJC5M4zFNg==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-linux-arm64-gnu": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-linux-arm64-gnu/-/keyring-linux-arm64-gnu-2.1.0.tgz",
+      "integrity": "sha512-+PMONFQ+2GkBXG7vRG2spgR73bNCMeVpNopHoSmhj2E+5Gu6zJooRBjoaIZKj6hCyrOU8pXAhoZ22EEFQ/4YeQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-linux-arm64-musl": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-linux-arm64-musl/-/keyring-linux-arm64-musl-2.1.0.tgz",
+      "integrity": "sha512-dKjiXKTHQjAS57hL0HVzLpW9XYNGFpfYkr/51FzIIvbZR08PAnzIDYKwShoNYGvjQP6+rDFf1a5Utl0aWwcFrA==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-linux-riscv64-gnu": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-linux-riscv64-gnu/-/keyring-linux-riscv64-gnu-2.1.0.tgz",
+      "integrity": "sha512-tqhb0ofhtEJ2+ZfmlKTDHbmIoNSz+SSTPWRgMfSVCgI4JVkqDdfcmIOcThZfRffJ3QI9C3Tng+rZL24acmD+GA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-linux-x64-gnu": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-linux-x64-gnu/-/keyring-linux-x64-gnu-2.1.0.tgz",
+      "integrity": "sha512-7ZA0ssxfpuGXV8S5Ct1ZJoEL3sKg/8u7mIL4SK9/PwKBhxIq7K+FVcjnggNsuFnEhHTX+HYl9hHDrlX0odZnHg==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-linux-x64-musl": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-linux-x64-musl/-/keyring-linux-x64-musl-2.1.0.tgz",
+      "integrity": "sha512-dI74Fzl03CrN2TEP7YVBtUBFgyRTRPyK1LMcIgAUfgW3o6f5SD1a8EsfT82+brpFOltjOhacIlFiYOkYtSI5Fg==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-win32-arm64-msvc": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-win32-arm64-msvc/-/keyring-win32-arm64-msvc-2.1.0.tgz",
+      "integrity": "sha512-SltrXXkEe9a+Jv8ConDkZW2Mdr0srpWurS7oYkYP1Mp07DNBpFyqawRnyo4p7ZvQU3e+R6irj/Fq0epCCvVUXA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-win32-ia32-msvc": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-win32-ia32-msvc/-/keyring-win32-ia32-msvc-2.1.0.tgz",
+      "integrity": "sha512-l5wJQhqXkAfQ4FGxoRh0wMpL9VxVmfiYI5TTeOGNupuVsQvbHmysh8gfDQBBWVhyMENHJS2OqOSYIuqVjumAtA==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@napi-rs/keyring-win32-x64-msvc": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@napi-rs/keyring-win32-x64-msvc/-/keyring-win32-x64-msvc-2.1.0.tgz",
+      "integrity": "sha512-3zYwO7dhJiUNyv2te81ujXm2vGxHwgx+z2eBm0dTYe3aWpvKQVzpfxCp/7cViJs8duVYE04wVOgXiRhRCMEq2w==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
     "node_modules/@oxc-project/types": {
       "version": "0.150.0",
       "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.150.0.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ffschrattenecker/tm1-mcp-server",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "MCP server for IBM Planning Analytics / TM1 — full model lifecycle via REST API",
   "repository": {
     "type": "git",
@@ -86,6 +86,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.1",
+    "@napi-rs/keyring": "^2.1.0",
     "dotenv": "^18.0.0",
     "pino": "^10.3.1",
     "regexp-tree": "^0.1.27",