@ffschrattenecker/tm1-mcp-server 6.0.0 → 7.0.0

package/CHANGELOG.md

@@ -7,6 +7,111 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.0] - 2026-09-27
+
+### Breaking
+
+- **One server for all TM1 connections.** Without `TM1_BASE_URL`, the server discovers every
+  `<name>/.env` under `~/.tm1/mcp-servers` (or `TM1_CONNECTIONS_DIR`) and every tool takes a
+  `connection` argument. Replace the per-instance MCP entries with a single one: the client then
+  carries one tool list instead of one per TM1 instance. Setups with `TM1_BASE_URL` keep working
+  unchanged as a single connection. See docs/CONFIGURATION.md, "Several TM1 connections".
+- **`tm1_get_process_code`, `tm1_get_process_parameters`, `tm1_get_process_variables` and
+  `tm1_get_process_datasource` are removed.** `tm1_get_process` returns every part, each behind
+  an include-flag (`includeCode=false` for parameters/variables/datasource only). The datasource
+  now sits under `dataSource`.
+- **`tm1_list_processes` returns names only by default.** Pass `fields=['name','parameters']`
+  for parameter lists; TM1 is then asked for the parameters too, instead of on every listing.
+- **`tm1_list_cubes` defaults to `includeDimensions=false`.**
+
+### Added
+
+- `tm1_list_connections`: configured connections, their mode, environment, version and session state.
+- `TM1_ENVIRONMENT` / `TM1_ALLOW_PROD_WRITES` are read per connection folder, never inherited from
+  the launching shell. A prod connection forced to readonly says so in `tm1_list_connections` and in
+  the refusal hint of a write tool.
+- Oversized paginated results are cut to the items that fit, with `has_more`/`next_offset`
+  pointing at the rest, instead of failing with `RESPONSE_TOO_LARGE`.
+- Server `instructions` (≤500 characters) tell the model how to pick a connection and keep
+  results small.
+
+### Fixed
+
+- The callgraph cache is keyed per connection, so an index built for one TM1 server is never
+  answered for another.
+
+## [6.1.1] - 2026-09-26
+
+### Fixed
+
+- **Publishing.** The publish workflow handed npm the tarball as `pkg/<file>.tgz`, which npm reads
+  as a GitHub `user/repo` spec, so the 6.1.0 release failed at upload. Contents are identical to
+  6.1.0, which was tagged but never reached npm: install 6.1.1.
+
+## [6.1.0] - 2026-09-26 [not published]
+
+### Added
+
+- **`tm1_delete_dimension` / `tm1_delete_cube` `dryRun`.** Returns every process and rule that
+  references the object, per source, plus the cubes a dimension is part of. Nothing is deleted,
+  and it needs no `confirm` (the field is now optional in the schema and still required on the real
+  call). Before, the check before a delete took `tm1_analyze_object_usage` plus
+  `tm1_find_orphan_dimensions` as separate calls. Elements are not covered: the usage index does
+  not resolve element references.
+- **`TM1_ENVIRONMENT=dev|test|prod`, and `mode`/`environment` in `tm1_get_server_info`.**
+  `mcpServer` now carries `mode` (`readonly`/`readwrite`), `environment` (`unspecified` when
+  unset) and, when the mode was forced, `modeReason`. Before, a client could only guess which
+  environment it was on from free-text labels, and inferred readonly from missing tools.
+  `TM1_ENVIRONMENT=prod` forces readonly even under `TM1_MODE=readwrite`, unless
+  `TM1_ALLOW_PROD_WRITES=true` is set too. A readwrite `.env` copied from a dev instance is the
+  easy way to end up with write tools on production. An unknown value refuses to start, like
+  `TM1_MODE`.
+- **`tm1_execute_process` attaches the run's error log.** When TM1 names an error log for the run
+  (a failure, or `HasMinorErrors` on a run that committed), the last 40 lines come back as
+  `errorLog`. A run that reports `CompletedWithMessages` can still have skipped every record, and
+  telling that apart used to need a `tm1_diagnose_process_error` call on every non-clean run. That
+  tool stays for cascade siblings and older logs.
+- **`tm1_set_cube_rules` and `tm1_write_cells` read back what they wrote.** `set_cube_rules`
+  returns `verified.textMatches`; `write_cells` re-reads up to 20 of the written cells and lists
+  any whose stored value differs in `verified.mismatches` (a rule or spread overriding the value).
+  Each replaces a separate read-back call. A failed read-back is reported as `readBackError` and
+  never turns a landed write into an error.
+- **`tm1_upsert_process` `dryRun`.** Runs the syntax and the reference check on the process as it
+  would be after the call, reports both (neither stops the other), and diffs it against the
+  installed version with credentials masked. Nothing is written. It needs no `confirm` and does not
+  count as one: the real overwrite still asks. Before, a caller that wanted the findings in front of
+  the user before the overwrite needed `tm1_check_process_code`, `tm1_validate_process_refs` and a
+  diff as three separate calls, because the install preflight only runs once the write is approved.
+- **`tm1_upsert_process` reads the code back.** The result carries `verified: {codeMatches,
+  mismatchedTabs}` for the tabs it sent, so confirming the change landed no longer takes a
+  `tm1_get_process_code` call.
+
+### ⚠️ Behavior change
+
+- **Node.js 22.19 or newer is required.** Node 20 reached end of life in April 2026. CI now
+  tests Node 22 and 24.
+
+### Security
+
+- **Consumers now get the pinned dependency tree.** The package ships `npm-shrinkwrap.json`, so
+  `npx` installs the exact versions CI tested and audited. Before, the lockfile was never published
+  and dependencies resolved fresh on every install, so the 6.0.1 lockfile fixes did not reach users.
+- **Hardened release pipeline.** npm publishing runs in a separate job that holds the OIDC
+  token and only uploads the tarball built and tested in the previous job.
+
+### Note
+
+- 6.0.1 was tagged but never published to npm (the tag push did not trigger the publish
+  workflow). Its fixes ship in the next release.
+
+## [6.0.1] - 2026-09-25
+
+### Security
+
+- **Dependency advisories patched.** The lockfile now pins fixed versions of `fast-uri` (host
+  confusion / SSRF, high), `hono` and `@hono/node-server`, `qs` and `body-parser` (moderate / low),
+  all pulled in by the MCP SDK. No tool contract changes.
+
 ## [6.0.0] - 2026-09-25
 
 ### Breaking
@@ -1194,7 +1299,11 @@ 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/v6.0.0...HEAD
+[Unreleased]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v7.0.0...HEAD
+[7.0.0]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v6.1.1...v7.0.0
+[6.1.1]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v6.1.0...v6.1.1
+[6.1.0]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v6.0.1...v6.1.0
+[6.0.1]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v6.0.0...v6.0.1
 [6.0.0]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v5.0.0...v6.0.0
 [5.0.0]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v4.1.0...v5.0.0
 [4.1.0]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v4.0.0...v4.1.0

package/README.md

@@ -18,7 +18,7 @@ published as `@ffschrattenecker/tm1-mcp-server`. The command is still `tm1-mcp-s
 
 ## Features
 
-115 tools across 12 categories — every one listed in
+112 tools across 12 categories — every one listed in
 [docs/TOOLS.md](docs/TOOLS.md), with working JSON payloads in
 [docs/EXAMPLES.md](docs/EXAMPLES.md). Past plain CRUD over the REST API:
 
@@ -86,6 +86,7 @@ TM1_PASSWORD=your-password
 TM1_SSL_REJECT_UNAUTHORIZED=false
 TM1_VERSION=11.8
 TM1_MODE=readonly                   # readonly (default) | readwrite
+# TM1_ENVIRONMENT=prod              # dev | test | prod; prod forces readonly
 # TM1_RESPONSE_MODE=structured      # legacy (default) | structured
 # TM1_MAX_RESPONSE_CHARS=80000      # larger results fail with RESPONSE_TOO_LARGE
 # TM1_LOCAL_FILE_ROOT=/srv/tm1-git  # optional; enables host-disk file params
@@ -103,7 +104,27 @@ Analytics Engine) connection and its auth modes, host-disk file access.
 > tools are registered, so it cannot mutate or delete anything. Set
 > `TM1_MODE=readwrite` explicitly to enable the full lifecycle (cell writes,
 > cube/dimension/process deletion, TI execution), and never point a `readwrite`
-> server at production without reviewing the write path first.
+> server at production without reviewing the write path first. Label production
+> with `TM1_ENVIRONMENT=prod`: it then stays readonly even under
+> `TM1_MODE=readwrite`, unless `TM1_ALLOW_PROD_WRITES=true` is set as well.
+
+### Several TM1 servers — one process
+
+Give each connection its own folder with a `.env` under `~/.tm1/mcp-servers/`
+(or the folder named by `TM1_CONNECTIONS_DIR`) and leave `TM1_BASE_URL` unset:
+
+```text
+~/.tm1/mcp-servers/
+  dev/.env        # TM1_BASE_URL=…  TM1_MODE=readwrite
+  prod/.env       # TM1_BASE_URL=…  (readonly: the default)
+```
+
+One server then serves them all: every tool takes a `connection` argument and
+`tm1_list_connections` shows what is configured. Each folder sets its own
+`TM1_MODE` — a write against a readonly connection is refused per call — and
+no connection logs in before its first use. One entry replaces one MCP server
+per TM1 instance, so the client carries one tool list instead of N.
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md#several-tm1-connections) has the details.
 
 Host-disk file access is default-off in the same spirit: the `.pro` and git
 tools accept inline content, and touch host paths only once
@@ -181,7 +202,7 @@ security notes and the `autoApprove` allowlist:
 
 ## Compatibility
 
-- Node.js >= 20
+- Node.js >= 22.19
 - TM1 11.8 / Planning Analytics 2.0 — the primary target; some metadata-write
   paths assume 11.x semantics, and v12-only fields (e.g.
   `DataSource.usesUnicode`) are dropped when `TM1_VERSION` says `11.x`
@@ -197,7 +218,7 @@ security notes and the `autoApprove` allowlist:
 
 <!-- TOOLS-AUTOGEN:START -->
 
-## Tools (115)
+## Tools (112)
 
 Names and one-line descriptions: [docs/TOOLS.md](docs/TOOLS.md).
 
@@ -209,13 +230,13 @@ Names and one-line descriptions: [docs/TOOLS.md](docs/TOOLS.md).
 | fileops | 5 |
 | metadata | 9 |
 | model-building | 9 |
-| operations | 15 |
+| operations | 16 |
 | scheduling | 5 |
 | security | 8 |
 | subsets | 5 |
-| ti-development | 21 |
+| ti-development | 17 |
 | views | 4 |
-| **Total** | **115** |
+| **Total** | **112** |
 
 <!-- TOOLS-AUTOGEN:END -->
 

package/dist/config.d.ts

@@ -18,6 +18,8 @@ export interface TM1Config {
     httpAllowedOrigins: string[];
     httpToken?: string | undefined;
     mode: "readwrite" | "readonly";
+    environment?: "dev" | "test" | "prod" | undefined;
+    modeReason?: string | undefined;
     responseMode: "legacy" | "structured";
     maxResponseChars: number;
     version: 11 | 12;
@@ -31,5 +33,14 @@ export interface TM1Config {
     iamUrl?: string | undefined;
 }
 export declare const DEFAULT_MAX_RESPONSE_CHARS = 80000;
-export declare function loadConfig(): TM1Config;
+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;
+/**
+ * Stable label for a connection: host and port, plus the v12
+ * instance/database. Keys per-connection state (process backups, the callgraph
+ * cache, mutation events) — two folders pointing at the same server share it,
+ * which is correct: they see the same objects.
+ */
+export declare function connectionIdOf(config: Pick<TM1Config, "baseUrl" | "instance" | "database">): string;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -1,6 +1,7 @@
 const VALID_LOG_LEVELS = ["debug", "info", "warn", "error"];
 const VALID_TRANSPORTS = ["stdio", "http"];
 const VALID_MODES = ["readwrite", "readonly"];
+const VALID_ENVIRONMENTS = ["dev", "test", "prod"];
 const VALID_RESPONSE_MODES = ["legacy", "structured"];
 const VALID_AUTH_MODES = [
     "s2s",
@@ -22,59 +23,20 @@ function parseIntEnv(name, raw, def) {
     }
     return n;
 }
-export function loadConfig() {
-    const baseUrl = process.env.TM1_BASE_URL;
-    const user = process.env.TM1_USER;
-    const password = process.env.TM1_PASSWORD;
-    // CAM auth (mirrors TM1py's RestService._build_authorization_token):
-    //   TM1_CAM_PASSPORT set → "CAMPassport <token>"      (no user/password round-trip)
-    //   TM1_NAMESPACE set     → "CAMNamespace b64(u:p:ns)" (needs user + password + namespace)
-    //   neither               → "Basic b64(u:p)"           (native TM1)
-    // SSO/gateway (Windows SSPI) is intentionally unsupported here: TM1py only does
-    // it via the Windows-only requests_negotiate_sspi package. Supply a passport
-    // obtained out-of-band via TM1_CAM_PASSPORT instead.
-    const namespace = process.env.TM1_NAMESPACE || undefined;
-    const camPassport = process.env.TM1_CAM_PASSPORT || undefined;
-    // Required: baseUrl always. user/password only when NOT using a passport — a
-    // passport carries the authenticated identity, so TM1 needs no credentials.
-    // Empty strings are rejected (treated as unset). Password may be empty — some
-    // TM1 setups allow a blank password for the admin account — so we warn but
-    // don't block, letting the real 401 (if any) surface with context.
-    const missing = [];
-    if (!baseUrl)
-        missing.push("TM1_BASE_URL");
-    if (!camPassport) {
-        if (!user)
-            missing.push("TM1_USER");
-        if (password === undefined)
-            missing.push("TM1_PASSWORD");
-    }
-    if (missing.length > 0) {
-        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 && 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");
-    }
-    const sslRaw = process.env.TM1_SSL_REJECT_UNAUTHORIZED;
-    const rejectUnauthorized = sslRaw === undefined ? true : sslRaw !== "false";
-    const keepAliveIntervalMs = parseIntEnv("TM1_KEEP_ALIVE_INTERVAL", process.env.TM1_KEEP_ALIVE_INTERVAL, 60000);
-    const requestTimeoutMs = parseIntEnv("TM1_REQUEST_TIMEOUT", process.env.TM1_REQUEST_TIMEOUT, 30000);
-    const logLevelRaw = process.env.TM1_LOG_LEVEL ?? "info";
+export function loadServerSettings(env = process.env) {
+    const logLevelRaw = env.TM1_LOG_LEVEL ?? "info";
     const logLevel = VALID_LOG_LEVELS.includes(logLevelRaw)
         ? logLevelRaw
         : "info";
-    const logFile = process.env.TM1_LOG_FILE || undefined;
-    const tm1Version = process.env.TM1_VERSION || "11.8";
-    const transportRaw = process.env.TM1_MCP_TRANSPORT ?? "stdio";
+    const logFile = env.TM1_LOG_FILE || undefined;
+    const transportRaw = env.TM1_MCP_TRANSPORT ?? "stdio";
     const transport = VALID_TRANSPORTS.includes(transportRaw)
         ? transportRaw
         : "stdio";
     // Default to loopback. Binding to 0.0.0.0 must be opt-in to avoid exposing
     // a TM1-credentialed MCP server to the LAN by accident.
-    const httpHost = process.env.TM1_MCP_HTTP_HOST || "127.0.0.1";
-    const httpPort = parseIntEnv("TM1_MCP_HTTP_PORT", process.env.TM1_MCP_HTTP_PORT, 3000);
+    const httpHost = env.TM1_MCP_HTTP_HOST || "127.0.0.1";
+    const httpPort = parseIntEnv("TM1_MCP_HTTP_PORT", env.TM1_MCP_HTTP_PORT, 3000);
     // Origin allow-list for DNS-rebinding protection. Loopback origins are
     // always included so localhost dev clients work out of the box; if the
     // server binds to a non-loopback host we add http://<host>:<port> too.
@@ -89,7 +51,7 @@ export function loadConfig() {
         httpHost !== "0.0.0.0") {
         defaultOrigins.push(`http://${httpHost}:${httpPort}`);
     }
-    const extraOriginsRaw = process.env.TM1_MCP_HTTP_ALLOWED_ORIGINS;
+    const extraOriginsRaw = env.TM1_MCP_HTTP_ALLOWED_ORIGINS;
     const extraOrigins = extraOriginsRaw
         ? extraOriginsRaw
             .split(",")
@@ -97,7 +59,7 @@ export function loadConfig() {
             .filter(Boolean)
         : [];
     const httpAllowedOrigins = Array.from(new Set([...defaultOrigins, ...extraOrigins]));
-    const httpToken = process.env.TM1_MCP_HTTP_TOKEN || undefined;
+    const httpToken = env.TM1_MCP_HTTP_TOKEN || undefined;
     // Refuse a non-loopback HTTP bind without transport auth: TM1_MCP_HTTP_HOST=0.0.0.0
     // (or any LAN address) with no bearer token would expose an unauthenticated,
     // TM1-credentialed /mcp endpoint to the network. Loopback binds keep the
@@ -111,31 +73,99 @@ export function loadConfig() {
             `Refusing to expose an unauthenticated /mcp endpoint beyond localhost — set ` +
             `TM1_MCP_HTTP_TOKEN, or bind to 127.0.0.1/localhost.`);
     }
-    // Case-insensitive so a `TM1_MODE=ReadWrite` typo resolves to readwrite rather
-    // than silently falling back to readonly (dropping every write tool without a
-    // word). A genuinely-unknown value throws at startup — parity with the numeric
-    // env vars — instead of failing quietly.
-    const modeRaw = (process.env.TM1_MODE ?? "readonly").trim().toLowerCase();
-    if (!VALID_MODES.includes(modeRaw)) {
-        throw new Error(`Invalid TM1_MODE: "${process.env.TM1_MODE}". Expected "readwrite" or "readonly".`);
-    }
-    const mode = modeRaw;
     // Same parse shape as TM1_MODE: case-insensitive, unknown value throws at
     // startup rather than silently picking a wire format the operator did not ask
     // for.
-    const responseModeRaw = (process.env.TM1_RESPONSE_MODE ?? "legacy")
+    const responseModeRaw = (env.TM1_RESPONSE_MODE ?? "legacy")
         .trim()
         .toLowerCase();
     if (!VALID_RESPONSE_MODES.includes(responseModeRaw)) {
-        throw new Error(`Invalid TM1_RESPONSE_MODE: "${process.env.TM1_RESPONSE_MODE}". Expected "legacy" or "structured".`);
+        throw new Error(`Invalid TM1_RESPONSE_MODE: "${env.TM1_RESPONSE_MODE}". Expected "legacy" or "structured".`);
     }
     const responseMode = responseModeRaw;
     // ~80k characters sits under Claude Code's default MCP output cap (25k
     // tokens) with room for the envelope; 23 recorded results overflowed it.
-    const maxResponseChars = parseIntEnv("TM1_MAX_RESPONSE_CHARS", process.env.TM1_MAX_RESPONSE_CHARS, DEFAULT_MAX_RESPONSE_CHARS);
+    const maxResponseChars = parseIntEnv("TM1_MAX_RESPONSE_CHARS", env.TM1_MAX_RESPONSE_CHARS, DEFAULT_MAX_RESPONSE_CHARS);
+    return {
+        logLevel,
+        logFile,
+        transport,
+        httpHost,
+        httpPort,
+        httpAllowedOrigins,
+        httpToken,
+        responseMode,
+        maxResponseChars,
+    };
+}
+// `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) {
+    const baseUrl = env.TM1_BASE_URL;
+    const user = env.TM1_USER;
+    const password = env.TM1_PASSWORD;
+    // CAM auth (mirrors TM1py's RestService._build_authorization_token):
+    //   TM1_CAM_PASSPORT set → "CAMPassport <token>"      (no user/password round-trip)
+    //   TM1_NAMESPACE set     → "CAMNamespace b64(u:p:ns)" (needs user + password + namespace)
+    //   neither               → "Basic b64(u:p)"           (native TM1)
+    // SSO/gateway (Windows SSPI) is intentionally unsupported here: TM1py only does
+    // it via the Windows-only requests_negotiate_sspi package. Supply a passport
+    // obtained out-of-band via TM1_CAM_PASSPORT instead.
+    const namespace = env.TM1_NAMESPACE || undefined;
+    const camPassport = env.TM1_CAM_PASSPORT || undefined;
+    // Required: baseUrl always. user/password only when NOT using a passport — a
+    // passport carries the authenticated identity, so TM1 needs no credentials.
+    // Empty strings are rejected (treated as unset). Password may be empty — some
+    // TM1 setups allow a blank password for the admin account — so we warn but
+    // don't block, letting the real 401 (if any) surface with context.
+    const missing = [];
+    if (!baseUrl)
+        missing.push("TM1_BASE_URL");
+    if (!camPassport) {
+        if (!user)
+            missing.push("TM1_USER");
+        if (password === undefined)
+            missing.push("TM1_PASSWORD");
+    }
+    if (missing.length > 0) {
+        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 && 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");
+    }
+    const sslRaw = env.TM1_SSL_REJECT_UNAUTHORIZED;
+    const rejectUnauthorized = sslRaw === undefined ? true : sslRaw !== "false";
+    const keepAliveIntervalMs = parseIntEnv("TM1_KEEP_ALIVE_INTERVAL", env.TM1_KEEP_ALIVE_INTERVAL, 60000);
+    const requestTimeoutMs = parseIntEnv("TM1_REQUEST_TIMEOUT", env.TM1_REQUEST_TIMEOUT, 30000);
+    const server = loadServerSettings(env);
+    const tm1Version = env.TM1_VERSION || "11.8";
+    // Case-insensitive so a `TM1_MODE=ReadWrite` typo resolves to readwrite rather
+    // than silently falling back to readonly (dropping every write tool without a
+    // word). A genuinely-unknown value throws at startup — parity with the numeric
+    // env vars — instead of failing quietly.
+    const modeRaw = (env.TM1_MODE ?? "readonly").trim().toLowerCase();
+    if (!VALID_MODES.includes(modeRaw)) {
+        throw new Error(`Invalid TM1_MODE: "${env.TM1_MODE}". Expected "readwrite" or "readonly".`);
+    }
+    const envRaw = env.TM1_ENVIRONMENT?.trim().toLowerCase() || undefined;
+    if (envRaw !== undefined &&
+        !VALID_ENVIRONMENTS.includes(envRaw)) {
+        throw new Error(`Invalid TM1_ENVIRONMENT: "${env.TM1_ENVIRONMENT}". Expected "dev", "test" or "prod".`);
+    }
+    const environment = envRaw;
+    const allowProdWrites = env.TM1_ALLOW_PROD_WRITES?.trim().toLowerCase() === "true";
+    let mode = modeRaw;
+    let modeReason;
+    if (environment === "prod" && mode === "readwrite" && !allowProdWrites) {
+        mode = "readonly";
+        modeReason =
+            "TM1_ENVIRONMENT=prod forces readonly; set TM1_ALLOW_PROD_WRITES=true to allow writes.";
+    }
     // --- v12 (Planning Analytics Engine) connection ---------------------------
-    const instance = process.env.TM1_INSTANCE || undefined;
-    const database = process.env.TM1_DATABASE || undefined;
+    const instance = env.TM1_INSTANCE || undefined;
+    const database = env.TM1_DATABASE || undefined;
     const versionMajor = Number.parseInt(tm1Version, 10);
     const isV12 = Boolean(instance || database) || versionMajor === 12;
     const version = isV12 ? 12 : 11;
@@ -159,19 +189,17 @@ export function loadConfig() {
         if (!database) {
             throw new Error("v12 connection requires TM1_DATABASE (set alongside TM1_INSTANCE).");
         }
-        const authModeRaw = (process.env.TM1_AUTH_MODE ?? "s2s")
-            .trim()
-            .toLowerCase();
+        const authModeRaw = (env.TM1_AUTH_MODE ?? "s2s").trim().toLowerCase();
         if (!VALID_AUTH_MODES.includes(authModeRaw)) {
-            throw new Error(`Invalid TM1_AUTH_MODE: "${process.env.TM1_AUTH_MODE}". ` +
+            throw new Error(`Invalid TM1_AUTH_MODE: "${env.TM1_AUTH_MODE}". ` +
                 `Expected one of: ${VALID_AUTH_MODES.join(", ")}.`);
         }
         authMode = authModeRaw;
-        clientId = process.env.TM1_CLIENT_ID || undefined;
-        clientSecret = process.env.TM1_CLIENT_SECRET || undefined;
-        accessToken = process.env.TM1_ACCESS_TOKEN || undefined;
-        apiKey = process.env.TM1_API_KEY || undefined;
-        iamUrl = process.env.TM1_IAM_URL || undefined;
+        clientId = env.TM1_CLIENT_ID || undefined;
+        clientSecret = env.TM1_CLIENT_SECRET || undefined;
+        accessToken = env.TM1_ACCESS_TOKEN || undefined;
+        apiKey = env.TM1_API_KEY || undefined;
+        iamUrl = env.TM1_IAM_URL || undefined;
         const missingV12 = [];
         // Every v12 mode — not just "basic" — sends `{ User: config.user }` in the
         // session login body (profile.ts buildLoginRequest), so TM1_USER is required
@@ -203,6 +231,7 @@ export function loadConfig() {
         }
     }
     return {
+        ...server,
         baseUrl: baseUrl,
         // In passport mode user/password are unused; default to "" so the type stays
         // a plain string and the Authorization header is built from the passport.
@@ -213,17 +242,10 @@ export function loadConfig() {
         ssl: { rejectUnauthorized },
         keepAliveIntervalMs,
         requestTimeoutMs,
-        logLevel,
-        logFile,
         tm1Version: effectiveTm1Version,
-        transport,
-        httpHost,
-        httpPort,
-        httpAllowedOrigins,
-        httpToken,
         mode,
-        responseMode,
-        maxResponseChars,
+        ...(environment !== undefined ? { environment } : {}),
+        ...(modeReason !== undefined ? { modeReason } : {}),
         version,
         instance,
         database,
@@ -235,4 +257,23 @@ export function loadConfig() {
         iamUrl,
     };
 }
+/**
+ * Stable label for a connection: host and port, plus the v12
+ * instance/database. Keys per-connection state (process backups, the callgraph
+ * cache, mutation events) — two folders pointing at the same server share it,
+ * which is correct: they see the same objects.
+ */
+export function connectionIdOf(config) {
+    let host;
+    try {
+        const url = new URL(config.baseUrl);
+        host = url.port ? `${url.hostname}_${url.port}` : url.hostname;
+    }
+    catch {
+        host = config.baseUrl;
+    }
+    return [host, config.instance, config.database]
+        .filter((part) => Boolean(part))
+        .join("_");
+}
 //# sourceMappingURL=config.js.map

package/dist/connections.d.ts

@@ -0,0 +1,69 @@
+import pino from "pino";
+import { type TM1Config } from "./config.js";
+import { TM1Client } from "./tm1-client.js";
+export interface ConnectionInfo {
+    name: string;
+    /** Folder the `.env` came from; undefined for the legacy single connection. */
+    dir?: string | undefined;
+    mode?: TM1Config["mode"] | undefined;
+    environment?: TM1Config["environment"];
+    /** Why mode differs from TM1_MODE (prod forces readonly). */
+    modeReason?: string | undefined;
+    version?: 11 | 12 | undefined;
+    tm1Version?: string | undefined;
+    baseUrl?: string | undefined;
+    /** connectionIdOf() — what mutation events and caches are keyed by. */
+    connectionId?: string | undefined;
+    /** Set when the folder's `.env` could not be turned into a config. */
+    configError?: string | undefined;
+}
+export interface ConnectionStatus extends ConnectionInfo {
+    connected: boolean;
+    lastError?: string | undefined;
+}
+export declare class ConnectionRegistry {
+    private readonly logger;
+    private readonly entries;
+    private constructor();
+    /** Discover connections from the environment (see the header comment). */
+    static fromEnvironment(env: NodeJS.ProcessEnv, logger: pino.Logger): ConnectionRegistry;
+    /** Wrap one prebuilt client (tests, embedders). */
+    static single(client: TM1Client, logger?: pino.Logger): ConnectionRegistry;
+    /**
+     * Prebuilt clients under explicit names. The owner keeps the clients'
+     * lifecycle: disconnectAll() leaves them alone. Mode defaults to readwrite
+     * because the registration-time gate (TM1_MODE via withAnnotations) already
+     * decided what an embedder may call.
+     */
+    static of(clients: ReadonlyArray<{
+        name: string;
+        client: TM1Client;
+        mode?: TM1Config["mode"];
+    }>, logger?: pino.Logger): ConnectionRegistry;
+    private addConfig;
+    private discover;
+    /** Every connection name, including ones whose config failed to load. */
+    get names(): string[];
+    /** Connections that can actually be used. */
+    get usableNames(): string[];
+    /** True when tools should not expose a `connection` argument at all. */
+    get isSingle(): boolean;
+    get anyReadwrite(): boolean;
+    hasVersion(version: 11 | 12): boolean;
+    /** A client exists and is not mid-login. Never triggers a login itself. */
+    isConnected(name: string): boolean;
+    info(name: string): ConnectionInfo | undefined;
+    status(): ConnectionStatus[];
+    /** Resolve a connection name (optional when there is only one). */
+    private entryFor;
+    /**
+     * The client for a connection, built and logged in on first use. A failed
+     * login does not poison the entry: the client's own request path retries
+     * authentication, so the next call gets a fresh attempt.
+     */
+    get(name: string | undefined): Promise<TM1Client>;
+    /** Connection metadata for a resolved call (mode/version gates). */
+    resolveInfo(name: string | undefined): ConnectionInfo;
+    disconnectAll(): Promise<void>;
+}
+//# sourceMappingURL=connections.d.ts.map