@ffschrattenecker/tm1-mcp-server 6.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flameY3T1
+
+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/NOTICE

@@ -0,0 +1,34 @@
+tm1-mcp-server
+Copyright (c) 2026 flameY3T1
+
+Licensed under the MIT License. See LICENSE for the full text.
+
+-------------------------------------------------------------------------------
+Provenance
+-------------------------------------------------------------------------------
+This codebase was generated by an AI coding agent (Anthropic's Claude). It has
+been reviewed and tested, but it was not written line-by-line by a human. Treat
+it accordingly:
+
+  * Verify behavior against your own IBM Planning Analytics / TM1 instance
+    before relying on it — especially any write or destructive operation.
+  * The automated test suite is also AI-generated and runs against mocks, not a
+    live TM1 server. Passing tests do not guarantee correct REST semantics on
+    your version of Planning Analytics.
+
+-------------------------------------------------------------------------------
+Safety defaults
+-------------------------------------------------------------------------------
+The server starts in TM1_MODE=readonly. Write and destructive tools (delete,
+upsert, import, save-data, run-process, etc.) are NOT registered unless you
+explicitly set TM1_MODE=readwrite. Do not run a readwrite server against a
+production instance without reviewing the write path first.
+
+-------------------------------------------------------------------------------
+Warranty
+-------------------------------------------------------------------------------
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. This is a
+best-effort open-source project with no support guarantee. See LICENSE.
+
+IBM, Planning Analytics, and TM1 are trademarks of IBM Corp. This project is
+not affiliated with or endorsed by IBM.

package/README.md

@@ -0,0 +1,276 @@
+# tm1-mcp-server
+
+Model Context Protocol (MCP) server for IBM Planning Analytics / TM1.
+Exposes the full TM1 model lifecycle — metadata, dimensions, cubes, cell I/O,
+TI processes, chores, security, code-graph analysis — to any MCP-compatible
+LLM client (Claude Code, Claude Desktop, etc.).
+
+Tested against TM1 11.8 (REST, Basic/CAM auth) and TM1 12.5 / Planning Analytics
+Engine (rerooted REST, `s2s` auth live-validated).
+
+A fork of [flameY3T1/tm1-mcp-server](https://github.com/flameY3T1/tm1-mcp-server),
+published as `@ffschrattenecker/tm1-mcp-server`. The command is still `tm1-mcp-server`.
+
+> **Companion — TM1 IDE for VS Code.** Pair this server with the
+> [**flameY3T1.vscode-tm1-ide**](https://marketplace.visualstudio.com/items?itemName=flameY3T1.vscode-tm1-ide)
+> extension to browse and inspect the **live** data, cubes and TI code on the
+> server — an in-place view of whatever MCP just changed.
+
+## Features
+
+115 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:
+
+- **Bulk reads instead of N round-trips.** Pull every process's source or every
+  cube's rules in one call, then regex-search across them with per-process and
+  total caps.
+- **Code-graph analysis.** The ExecuteProcess/RunProcess call tree with
+  parameter propagation, a summary mode for triage and a global fan-in/fan-out
+  ranking; cube and dimension references across both TI and rules; a data-flow
+  trace saying which processes read a cube and which write it, classifying each
+  toucher of an element as source, write or zero-out.
+- **Model audits.** Naming conventions (IBM PA 2.0/3.1), TI and rule complexity,
+  feeder overfeeding (static heuristics plus `}StatsByCube` runtime evidence),
+  v12 readiness, orphan dimensions.
+- **Validation before you write.** Unbound compile of process code or a cube
+  rule without saving; a check that every cube/dimension named in TI resolves
+  live; a coordinate check that catches the silent no-op of writing to a
+  consolidated element.
+- **TI lifecycle in version control.** Import, export, diff and bundle-install
+  native `.pro` files, or the diff-friendly two-file git layout
+  (`{name}.json` + `{name}.ti`).
+- **Resources and prompts, not just tools.** Four read-only resources with name
+  autocomplete, so `#tm1://process/MyProcess/code` attaches a process as context
+  in chat, plus five starting-point prompts.
+
+> **Token tip:** every registered tool's name + input schema costs context on
+> *each* turn, so exposing all 114 is wasteful when a session needs a slice.
+> Narrow the surface with your client's tool filter; `TM1_MODE=readonly` already
+> trims it to read-only tools.
+
+## Install
+
+**Option A — npm (recommended).** No clone, no build: `npx -y @ffschrattenecker/tm1-mcp-server`
+always pulls the latest published version. Or install the CLI globally:
+
+```bash
+npm install -g @ffschrattenecker/tm1-mcp-server
+tm1-mcp-server
+```
+
+**Option B — clone and build** (source / development install):
+
+```bash
+git clone https://github.com/ffschrattenecker/tm1-mcp-server.git
+cd tm1-mcp-server
+npm install
+npm run build
+node dist/index.js
+```
+
+To update: `npx` picks up new versions on next start (if one is cached,
+`npm cache clean --force`); a global install takes
+`npm install -g @ffschrattenecker/tm1-mcp-server@latest`; a source install takes
+`git pull && npm install && npm run build`. Always **restart the MCP client**
+afterwards — the server process is only spawned at client startup.
+
+## Configure
+
+Copy `.env.example` to `.env` and set the TM1 connection details:
+
+```env
+TM1_BASE_URL=https://your-tm1-server:8010
+TM1_USER=admin
+TM1_PASSWORD=your-password
+TM1_SSL_REJECT_UNAUTHORIZED=false
+TM1_VERSION=11.8
+TM1_MODE=readonly                   # readonly (default) | readwrite
+# 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
+```
+
+`TM1_RESPONSE_MODE=structured` drops the text block and ships `structuredContent`
+alone — half the wire bytes, but clients that read `content[]` (Kiro's IDE among
+them) then see nothing. Worth it only for clients that copy the whole result into
+the model prompt. [`.env.example`](.env.example) lists every variable with
+inline comments; [docs/CONFIGURATION.md](docs/CONFIGURATION.md) covers the ones
+needing more than a comment line — CAM/LDAP login, the TM1 v12 (Planning
+Analytics Engine) connection and its auth modes, host-disk file access.
+
+> **Safe by default:** the server starts in `TM1_MODE=readonly` — only read
+> 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.
+
+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
+`TM1_LOCAL_FILE_ROOT` names an allowed directory (paths outside it, and `..`
+traversal, are rejected).
+
+### Positioning — this is a single-user tool
+
+The server holds **one TM1 identity per process** and every call runs with it.
+That is the design, not a limitation to work around, and it has consequences
+worth stating plainly:
+
+- **The HTTP transport is single-tenant.** A bearer token authenticates the
+  _endpoint_, not a caller. Everyone who reaches it shares the same TM1
+  credential, session, caches and audit identity. The "fresh MCP server per
+  request" wording in the architecture notes describes request isolation inside
+  the process — it is not a security boundary between users.
+- **`TM1_MODE=readwrite` with an admin account is a developer configuration**,
+  not a production recommendation. In production, point the server at an account
+  whose TM1 rights already match what the agent should be able to do — the
+  server enforces no per-caller authorization of its own.
+- **The confirmation guards are misuse protection, not access control.**
+  Seventeen tools require a `confirm` argument repeating the target name
+  verbatim: every `delete_*` and `clear_*`, plus `tm1_execute_process`,
+  `tm1_execute_chore`, `tm1_write_cells`, `tm1_set_cube_rules` and
+  `tm1_upload_file`. Anything that can call such a tool can also supply its
+  `confirm` value — the guard only stops an auto-approving client firing an
+  irreversible action without naming the target.
+
+If you need multi-user access with per-caller identity, run one process per
+identity behind your own front end rather than sharing one.
+
+### Secrets — `TM1_ALLOW_UNMASKED_SECRETS`
+
+Credential masking is on by default everywhere it applies. Several tools take a
+`maskSecrets` parameter, and a **model** can set it to `false` — an opt-out of a
+security control chosen by the thing being guarded against. That request is
+ignored unless the operator sets `TM1_ALLOW_UNMASKED_SECRETS=true`. The default
+degrades to "mask anyway" rather than failing the call, so an audit still gets
+its report, just redacted.
+
+## Use with Claude Code
+
+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)).
+
+For the `npx` install:
+
+```json
+{
+  "mcpServers": {
+    "tm1": {
+      "command": "npx",
+      "args": ["-y", "@ffschrattenecker/tm1-mcp-server"]
+    }
+  }
+}
+```
+
+A **global** install uses `"command": "tm1-mcp-server"` (no `args`); a **source
+build** uses `"command": "node"` with
+`"args": ["/absolute/path/to/tm1-mcp-server/dist/index.js"]`, which is what
+`mcp.json.example` shows. Restart Claude Code and the server appears as `tm1`.
+
+## HTTP transport
+
+The default transport is **stdio**, and that is the normal way to run this. For
+remote or multi-client setups, `TM1_MCP_TRANSPORT=http` switches to MCP
+Streamable HTTP (stateless, single `POST /mcp` endpoint). It is single-tenant:
+its optional bearer token authenticates the endpoint, not the caller. Setup,
+security notes and the `autoApprove` allowlist:
+[docs/HTTP-TRANSPORT.md](docs/HTTP-TRANSPORT.md).
+
+## Compatibility
+
+- Node.js >= 20
+- 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`
+- TM1 12.5 / Planning Analytics Engine — via `TM1_INSTANCE` + `TM1_DATABASE`,
+  live-validated with `s2s` auth only. `tm1_list_threads`, `tm1_cancel_thread`,
+  `tm1_save_data`, `tm1_unload_cube` and the three log readers
+  (`tm1_get_message_log`, `tm1_get_audit_log`, `tm1_get_transaction_log`) are
+  v11-only; `tm1_list_jobs` and `tm1_cancel_job` v12-only; v12 dropped demand
+  load, so unloading a cube has no successor endpoint there;
+  v12 ships no `}Stats*` control cubes, so `tm1_get_cube_stats` and
+  `tm1_audit_feeders` in `mode` `runtime`/`both` report the statistics as
+  unavailable instead of returning metrics (static feeder analysis is unaffected)
+
+<!-- TOOLS-AUTOGEN:START -->
+
+## Tools (115)
+
+Names and one-line descriptions: [docs/TOOLS.md](docs/TOOLS.md).
+
+| Category | Tools |
+|---|---|
+| analysis | 10 |
+| celldata | 10 |
+| dimension-management | 14 |
+| fileops | 5 |
+| metadata | 9 |
+| model-building | 9 |
+| operations | 15 |
+| scheduling | 5 |
+| security | 8 |
+| subsets | 5 |
+| ti-development | 21 |
+| views | 4 |
+| **Total** | **115** |
+
+<!-- TOOLS-AUTOGEN:END -->
+
+`tm1_execute_process` and `tm1_save_data` return an `outcome` — `succeeded`,
+`completed_with_errors`, `rolled_back` or `indeterminate` — and only `succeeded`
+reports `success: true`, since TM1 answers HTTP 200 whatever happened.
+`completed_with_errors` means changes **were** committed: retrying double-posts.
+
+## Troubleshooting
+
+The first connection usually fails on a self-signed dev certificate (set
+`TM1_SSL_REJECT_UNAUTHORIZED=false` — dev only) or a `401` from the wrong
+credentials, port or CAM namespace. Those, plus v11/v12 feature errors, slow
+transaction-log queries and startup validation errors, are in
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md#troubleshooting); HTTP-transport
+specifics in [docs/HTTP-TRANSPORT.md](docs/HTTP-TRANSPORT.md#troubleshooting).
+
+## Development
+
+```bash
+npm run dev             # tsx live-reload
+npm test                # vitest
+npm run lint            # tsc --noEmit && eslint .
+npm run coverage:check  # vitest --coverage + coverage ratchet gate
+npm run verify          # everything CI runs (typecheck + lint gates + coverage:check)
+```
+
+Contributions are welcome; run `npm run verify` before opening a PR.
+[CONTRIBUTING.md](CONTRIBUTING.md) documents the gates, the coverage ratchet and
+how to add a tool or service.
+
+## Documentation
+
+- [docs/TOOLS.md](docs/TOOLS.md) — every tool, grouped, with one-line descriptions
+- [docs/EXAMPLES.md](docs/EXAMPLES.md) — working JSON tool-call payloads for every major feature
+- [docs/CONFIGURATION.md](docs/CONFIGURATION.md) — CAM login, TM1 v12 connection, host-disk file access
+- [docs/HTTP-TRANSPORT.md](docs/HTTP-TRANSPORT.md) — Streamable HTTP setup, security, `autoApprove`
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — layering, service-class pattern, transports, the readonly/readwrite gate
+- [CONTRIBUTING.md](CONTRIBUTING.md) — workflow, lint gates, coverage policy, how to add a tool
+- [CHANGELOG.md](CHANGELOG.md) · [SECURITY.md](SECURITY.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+
+## Provenance
+
+This codebase was generated by an AI coding agent (Anthropic's Claude),
+reviewed and tested but not written by hand. The test suite is also
+AI-generated and runs against mocks, not a live TM1 server — passing tests do
+not guarantee correct REST semantics on your Planning Analytics version. Verify
+behavior against your own instance before relying on it, especially for any
+write or destructive operation. Provided "as is", best-effort, no support
+guarantee. See [NOTICE](NOTICE).
+
+IBM, Planning Analytics, and TM1 are trademarks of IBM Corp. This project is
+not affiliated with or endorsed by IBM.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The IBM trademarks named above are used solely to
+describe compatibility with the TM1 REST API.

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+export interface TM1Config {
+    baseUrl: string;
+    user: string;
+    password: string;
+    namespace?: string | undefined;
+    camPassport?: string | undefined;
+    ssl: {
+        rejectUnauthorized: boolean;
+    };
+    keepAliveIntervalMs: number;
+    requestTimeoutMs: number;
+    logLevel: "debug" | "info" | "warn" | "error";
+    logFile?: string | undefined;
+    tm1Version: string;
+    transport: "stdio" | "http";
+    httpHost: string;
+    httpPort: number;
+    httpAllowedOrigins: string[];
+    httpToken?: string | undefined;
+    mode: "readwrite" | "readonly";
+    responseMode: "legacy" | "structured";
+    maxResponseChars: number;
+    version: 11 | 12;
+    instance?: string | undefined;
+    database?: string | undefined;
+    authMode?: "s2s" | "basic" | "access_token" | "oidc" | "iam" | undefined;
+    clientId?: string | undefined;
+    clientSecret?: string | undefined;
+    accessToken?: string | undefined;
+    apiKey?: string | undefined;
+    iamUrl?: string | undefined;
+}
+export declare const DEFAULT_MAX_RESPONSE_CHARS = 80000;
+export declare function loadConfig(): TM1Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,238 @@
+const VALID_LOG_LEVELS = ["debug", "info", "warn", "error"];
+const VALID_TRANSPORTS = ["stdio", "http"];
+const VALID_MODES = ["readwrite", "readonly"];
+const VALID_RESPONSE_MODES = ["legacy", "structured"];
+const VALID_AUTH_MODES = [
+    "s2s",
+    "basic",
+    "access_token",
+    "oidc",
+    "iam",
+];
+// Parse a positive-integer env var. Empty/unset → default. A non-numeric or
+// non-positive value throws at startup instead of silently becoming NaN — NaN
+// makes setInterval/setTimeout fire continuously and ports resolve to ":NaN".
+export const DEFAULT_MAX_RESPONSE_CHARS = 80_000;
+function parseIntEnv(name, raw, def) {
+    if (raw === undefined || raw === "")
+        return def;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new Error(`Invalid ${name}: "${raw}". Expected a positive integer.`);
+    }
+    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";
+    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 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);
+    // 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.
+    // TM1_MCP_HTTP_ALLOWED_ORIGINS (comma-separated) appends extras and is the
+    // hook for HTTPS reverse-proxies / browser clients on a different origin.
+    const defaultOrigins = [
+        `http://127.0.0.1:${httpPort}`,
+        `http://localhost:${httpPort}`,
+    ];
+    if (httpHost !== "127.0.0.1" &&
+        httpHost !== "localhost" &&
+        httpHost !== "0.0.0.0") {
+        defaultOrigins.push(`http://${httpHost}:${httpPort}`);
+    }
+    const extraOriginsRaw = process.env.TM1_MCP_HTTP_ALLOWED_ORIGINS;
+    const extraOrigins = extraOriginsRaw
+        ? extraOriginsRaw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+    const httpAllowedOrigins = Array.from(new Set([...defaultOrigins, ...extraOrigins]));
+    const httpToken = process.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
+    // warn-only behavior (see http-transport.ts).
+    const hostLower = httpHost.toLowerCase();
+    const isLoopbackHost = hostLower === "localhost" ||
+        hostLower === "::1" ||
+        /^127\./.test(hostLower);
+    if (transport === "http" && !isLoopbackHost && !httpToken) {
+        throw new Error(`TM1_MCP_HTTP_HOST="${httpHost}" is not loopback and TM1_MCP_HTTP_TOKEN is unset. ` +
+            `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")
+        .trim()
+        .toLowerCase();
+    if (!VALID_RESPONSE_MODES.includes(responseModeRaw)) {
+        throw new Error(`Invalid TM1_RESPONSE_MODE: "${process.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);
+    // --- v12 (Planning Analytics Engine) connection ---------------------------
+    const instance = process.env.TM1_INSTANCE || undefined;
+    const database = process.env.TM1_DATABASE || undefined;
+    const versionMajor = Number.parseInt(tm1Version, 10);
+    const isV12 = Boolean(instance || database) || versionMajor === 12;
+    const version = isV12 ? 12 : 11;
+    // Keep the DISPLAY string (server_info, logs) consistent with the numeric
+    // `version`: a v12 connection (isV12, via TM1_INSTANCE/TM1_DATABASE) declared
+    // with a v11-looking TM1_VERSION="11.8" would otherwise report "11.8" to users
+    // while behaving as v12. Service branching keys off the numeric `version`
+    // (the authoritative source of truth), so this coercion is cosmetic-only — it
+    // stops the user-facing string from contradicting the real connection version.
+    const effectiveTm1Version = isV12 && versionMajor !== 12 ? "12.0" : tm1Version;
+    let authMode;
+    let clientId;
+    let clientSecret;
+    let accessToken;
+    let apiKey;
+    let iamUrl;
+    if (version === 12) {
+        if (!instance) {
+            throw new Error("v12 connection requires TM1_INSTANCE (set alongside TM1_DATABASE).");
+        }
+        if (!database) {
+            throw new Error("v12 connection requires TM1_DATABASE (set alongside TM1_INSTANCE).");
+        }
+        const authModeRaw = (process.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}". ` +
+                `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;
+        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
+        // regardless of authMode. For authMode === "basic" the v11 `missing` check
+        // above (camPassport-gated) already pushed TM1_USER and threw before this
+        // block runs when it's absent, so this only actually fires for the
+        // non-basic modes — no duplicate report.
+        if (!user)
+            missingV12.push("TM1_USER");
+        if (authMode === "s2s") {
+            if (!clientId)
+                missingV12.push("TM1_CLIENT_ID");
+            if (!clientSecret)
+                missingV12.push("TM1_CLIENT_SECRET");
+        }
+        else if (authMode === "access_token" || authMode === "oidc") {
+            if (!accessToken)
+                missingV12.push("TM1_ACCESS_TOKEN");
+        }
+        else if (authMode === "iam") {
+            if (!apiKey)
+                missingV12.push("TM1_API_KEY");
+            if (!iamUrl)
+                missingV12.push("TM1_IAM_URL");
+        }
+        if (missingV12.length > 0) {
+            throw new Error(`TM1_AUTH_MODE="${authMode}" requires: ${missingV12.join(", ")}. ` +
+                `Set them before starting the server.`);
+        }
+    }
+    return {
+        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.
+        user: user ?? "",
+        password: password ?? "",
+        namespace,
+        camPassport,
+        ssl: { rejectUnauthorized },
+        keepAliveIntervalMs,
+        requestTimeoutMs,
+        logLevel,
+        logFile,
+        tm1Version: effectiveTm1Version,
+        transport,
+        httpHost,
+        httpPort,
+        httpAllowedOrigins,
+        httpToken,
+        mode,
+        responseMode,
+        maxResponseChars,
+        version,
+        instance,
+        database,
+        authMode,
+        clientId,
+        clientSecret,
+        accessToken,
+        apiKey,
+        iamUrl,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/http-transport.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type pino from "pino";
+import type { TM1Config } from "./config.js";
+export declare function startHttpTransport(buildServer: () => {
+    server: McpServer;
+    dispose: () => void;
+}, config: TM1Config, logger: pino.Logger): Promise<() => Promise<void>>;
+//# sourceMappingURL=http-transport.d.ts.map