@lightdash-tools/mcp 0.2.6 → 0.3.1

package/dist/tools/shared.d.ts

@@ -1,5 +1,12 @@
 /**
  * Shared types and helpers for MCP tool registration.
+ *
+ * Guardrail layers applied by registerToolSafe (outer → inner):
+ *   1. Audit log wrapper   — captures timing and outcome for every call.
+ *   2. Project allowlist   — rejects calls targeting disallowed project UUIDs at runtime.
+ *   3. Dry-run wrapper     — simulates writes without executing them (registration-time).
+ *   4. Safety-mode wrapper — disables tools that exceed the configured safety level.
+ *   5. Raw handler         — the actual tool implementation.
  */
 import type { LightdashClient } from '@lightdash-tools/client';
 import type { ToolAnnotations } from '@lightdash-tools/common';
@@ -23,6 +30,12 @@ export type ToolOptions = {
     annotations?: ToolAnnotations;
 };
 export { READ_ONLY_DEFAULT, WRITE_IDEMPOTENT, WRITE_DESTRUCTIVE } from '@lightdash-tools/common';
-/** Registers a tool with prefix and annotations. shortName is TOOL_PREFIX + shortName. Pass annotations explicitly (e.g. READ_ONLY_DEFAULT, WRITE_IDEMPOTENT, or WRITE_DESTRUCTIVE). */
+/**
+ * Registers a tool with prefix and annotations, applying all guardrail layers.
+ * shortName is prefixed to become TOOL_PREFIX + shortName.
+ * Pass annotations explicitly (e.g. READ_ONLY_DEFAULT, WRITE_IDEMPOTENT, or WRITE_DESTRUCTIVE).
+ *
+ * CLI flag --allowed-projects always takes priority over LIGHTDASH_TOOLS_ALLOWED_PROJECTS.
+ */
 export declare function registerToolSafe(server: unknown, shortName: string, options: ToolOptions, handler: ToolHandler): void;
 export declare function wrapTool<T>(client: LightdashClient, fn: (client: LightdashClient) => (args: T) => Promise<TextContent>): ToolHandler;

package/dist/tools/shared.js

@@ -1,6 +1,13 @@
 "use strict";
 /**
  * Shared types and helpers for MCP tool registration.
+ *
+ * Guardrail layers applied by registerToolSafe (outer → inner):
+ *   1. Audit log wrapper   — captures timing and outcome for every call.
+ *   2. Project allowlist   — rejects calls targeting disallowed project UUIDs at runtime.
+ *   3. Dry-run wrapper     — simulates writes without executing them (registration-time).
+ *   4. Safety-mode wrapper — disables tools that exceed the configured safety level.
+ *   5. Raw handler         — the actual tool implementation.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -31,20 +38,33 @@ const DEFAULT_ANNOTATIONS = common_1.READ_ONLY_DEFAULT;
 function mergeAnnotations(overrides) {
     return Object.assign(Object.assign({}, DEFAULT_ANNOTATIONS), overrides);
 }
-/** Registers a tool with prefix and annotations. shortName is TOOL_PREFIX + shortName. Pass annotations explicitly (e.g. READ_ONLY_DEFAULT, WRITE_IDEMPOTENT, or WRITE_DESTRUCTIVE). */
+function isGuardrailBlocked(result) {
+    return ('_lightdashBlocked' in result &&
+        result['_lightdashBlocked'] === true);
+}
+/**
+ * Registers a tool with prefix and annotations, applying all guardrail layers.
+ * shortName is prefixed to become TOOL_PREFIX + shortName.
+ * Pass annotations explicitly (e.g. READ_ONLY_DEFAULT, WRITE_IDEMPOTENT, or WRITE_DESTRUCTIVE).
+ *
+ * CLI flag --allowed-projects always takes priority over LIGHTDASH_TOOLS_ALLOWED_PROJECTS.
+ */
 function registerToolSafe(server, shortName, options, handler) {
     var _a, _b;
     const name = exports.TOOL_PREFIX + shortName;
     const annotations = mergeAnnotations(options.annotations);
-    // Static Filtering: Skip registration if not allowed in static safety mode
+    // ── Static Filtering ──────────────────────────────────────────────────────
+    // Skip registration entirely if the tool exceeds the static safety mode.
     const staticMode = (0, config_js_1.getStaticSafetyMode)();
     if (staticMode && !(0, common_1.isAllowed)(staticMode, annotations)) {
         return;
     }
-    // Dynamic Enforcement: Wrap handler if not allowed in current safety mode (env)
+    // ── Safety-mode wrapper ───────────────────────────────────────────────────
+    // Tool is registered but calls are rejected at runtime when the dynamic mode
+    // does not permit the operation.
     const mode = (0, config_js_1.getSafetyMode)();
     const isToolAllowed = (0, common_1.isAllowed)(mode, annotations);
-    // If not allowed, wrap handler to return an error and update description
+    const isReadOnly = !!annotations.readOnlyHint;
     let finalHandler = handler;
     let finalDescription = options.description;
     if (!isToolAllowed) {
@@ -58,9 +78,92 @@ function registerToolSafe(server, shortName, options, handler) {
                     },
                 ],
                 isError: true,
+                _lightdashBlocked: true,
             });
         });
     }
+    else if ((0, config_js_1.isDryRunMode)() && !isReadOnly) {
+        // ── Dry-run wrapper ─────────────────────────────────────────────────────
+        // Write operations are simulated; no API calls are made.
+        finalDescription = `[DRY-RUN] ${options.description}`;
+        finalHandler = (args) => __awaiter(this, void 0, void 0, function* () {
+            return ({
+                content: [
+                    {
+                        type: 'text',
+                        text: `[DRY-RUN] Tool '${name}' would be called with: ${JSON.stringify(args, null, 2)}. No changes were made.`,
+                    },
+                ],
+                _lightdashBlocked: true,
+            });
+        });
+    }
+    // ── Project allowlist wrapper ─────────────────────────────────────────────
+    // Reject calls targeting project UUIDs not in the configured allowlist.
+    // Covers both singular (projectUuid) and plural (projectUuids[]) arg shapes.
+    // CLI --allowed-projects takes priority over LIGHTDASH_TOOLS_ALLOWED_PROJECTS.
+    const allowedProjects = (0, config_js_1.getAllowedProjectUuids)();
+    if (allowedProjects.length > 0) {
+        const innerHandler = finalHandler;
+        finalHandler = (args, extra) => __awaiter(this, void 0, void 0, function* () {
+            const projectUuids = (0, common_1.extractProjectUuids)(args);
+            const deniedUuids = projectUuids.filter((uuid) => !(0, common_1.areAllProjectsAllowed)(allowedProjects, [uuid]));
+            if (deniedUuids.length > 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: Project(s) [${deniedUuids.join(', ')}] are not in the list of allowed projects. Allowed: [${allowedProjects.join(', ')}].`,
+                        },
+                    ],
+                    isError: true,
+                    _lightdashBlocked: true,
+                };
+            }
+            return innerHandler(args, extra);
+        });
+    }
+    // ── Audit log wrapper ─────────────────────────────────────────────────────
+    // Outermost layer: records timing and outcome for every call.
+    const auditedInner = finalHandler;
+    finalHandler = (args, extra) => __awaiter(this, void 0, void 0, function* () {
+        const start = Date.now();
+        const projectUuids = (0, common_1.extractProjectUuids)(args);
+        let status = 'success';
+        let result;
+        try {
+            result = yield auditedInner(args, extra);
+            if (isGuardrailBlocked(result)) {
+                status = 'blocked';
+            }
+            else if (result.isError) {
+                status = 'error';
+            }
+        }
+        catch (err) {
+            status = 'error';
+            (0, common_1.logAuditEntry)({
+                timestamp: new Date().toISOString(),
+                sessionId: (0, common_1.getSessionId)(),
+                tool: name,
+                projectUuids: projectUuids.length > 0 ? projectUuids : undefined,
+                status,
+                durationMs: Date.now() - start,
+            });
+            throw err;
+        }
+        (0, common_1.logAuditEntry)({
+            timestamp: new Date().toISOString(),
+            sessionId: (0, common_1.getSessionId)(),
+            tool: name,
+            projectUuids: projectUuids.length > 0 ? projectUuids : undefined,
+            status,
+            durationMs: Date.now() - start,
+        });
+        // Strip the internal marker before returning to the MCP client.
+        const { content, isError } = result;
+        return { content, isError };
+    });
     const mergedOptions = Object.assign(Object.assign({}, options), { description: finalDescription, title: (_a = options.title) !== null && _a !== void 0 ? _a : (_b = options.annotations) === null || _b === void 0 ? void 0 : _b.title, annotations });
     server.registerTool(name, mergedOptions, finalHandler);
 }

package/dist/tools/shared.test.js

@@ -13,13 +13,34 @@ const vitest_1 = require("vitest");
 const shared_1 = require("./shared");
 const common_1 = require("@lightdash-tools/common");
 const config_js_1 = require("../config.js");
+// Silence audit log output during tests
+vitest_1.vi.mock('@lightdash-tools/common', (importOriginal) => __awaiter(void 0, void 0, void 0, function* () {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const actual = yield importOriginal();
+    return Object.assign(Object.assign({}, actual), { getSessionId: () => 'test-session', logAuditEntry: vitest_1.vi.fn(), initAuditLog: vitest_1.vi.fn() });
+}));
 (0, vitest_1.describe)('registerToolSafe', () => {
     const mockServer = {
         registerTool: vitest_1.vi.fn(),
     };
     const mockHandler = vitest_1.vi.fn().mockResolvedValue({ content: [{ type: 'text', text: 'success' }] });
+    (0, vitest_1.beforeEach)(() => {
+        mockServer.registerTool.mockClear();
+        mockHandler.mockClear();
+        // Reset globals to safe defaults
+        (0, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.WRITE_DESTRUCTIVE);
+        (0, config_js_1.setStaticAllowedProjectUuids)([]);
+        (0, config_js_1.setDryRunMode)(false);
+        process.env.LIGHTDASH_TOOL_SAFETY_MODE = common_1.SafetyMode.WRITE_DESTRUCTIVE;
+        delete process.env.LIGHTDASH_TOOLS_ALLOWED_PROJECTS;
+        delete process.env.LIGHTDASH_DRY_RUN;
+    });
+    (0, vitest_1.afterEach)(() => {
+        delete process.env.LIGHTDASH_TOOL_SAFETY_MODE;
+    });
     (0, vitest_1.it)('should allow read-only tool in read-only mode', () => __awaiter(void 0, void 0, void 0, function* () {
         process.env.LIGHTDASH_TOOL_SAFETY_MODE = common_1.SafetyMode.READ_ONLY;
+        (0, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.WRITE_DESTRUCTIVE); // static = allow all
         (0, shared_1.registerToolSafe)(mockServer, 'test_tool', {
             description: 'Test description',
             inputSchema: {},
@@ -34,12 +55,13 @@ const config_js_1 = require("../config.js");
     }));
     (0, vitest_1.it)('should block destructive tool in read-only mode', () => __awaiter(void 0, void 0, void 0, function* () {
         process.env.LIGHTDASH_TOOL_SAFETY_MODE = common_1.SafetyMode.READ_ONLY;
+        (0, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.WRITE_DESTRUCTIVE);
         (0, shared_1.registerToolSafe)(mockServer, 'delete_tool', {
             description: 'Delete something',
             inputSchema: {},
             annotations: shared_1.WRITE_DESTRUCTIVE,
         }, mockHandler);
-        const [, options, handler] = mockServer.registerTool.mock.calls[1];
+        const [, options, handler] = mockServer.registerTool.mock.calls[0];
         (0, vitest_1.expect)(options.description).toContain('[DISABLED in read-only mode]');
         const result = yield handler({});
         (0, vitest_1.expect)(result.isError).toBe(true);
@@ -47,19 +69,19 @@ const config_js_1 = require("../config.js");
     }));
     (0, vitest_1.it)('should allow destructive tool in write-destructive mode', () => __awaiter(void 0, void 0, void 0, function* () {
         process.env.LIGHTDASH_TOOL_SAFETY_MODE = common_1.SafetyMode.WRITE_DESTRUCTIVE;
+        (0, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.WRITE_DESTRUCTIVE);
         (0, shared_1.registerToolSafe)(mockServer, 'delete_tool_2', {
             description: 'Delete something 2',
             inputSchema: {},
             annotations: shared_1.WRITE_DESTRUCTIVE,
         }, mockHandler);
-        const [, options, handler] = mockServer.registerTool.mock.calls[2];
+        const [, options, handler] = mockServer.registerTool.mock.calls[0];
         (0, vitest_1.expect)(options.description).toBe('Delete something 2');
         const result = yield handler({});
         (0, vitest_1.expect)(result.content[0].text).toBe('success');
     }));
     (0, vitest_1.describe)('static filtering (safety-mode)', () => {
         (0, vitest_1.it)('should skip registration if tool is more permissive than binded mode', () => {
-            // Set binded mode to READ_ONLY
             (0, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.READ_ONLY);
             mockServer.registerTool.mockClear();
             (0, shared_1.registerToolSafe)(mockServer, 'destructive_tool_static', {
@@ -79,10 +101,7 @@ const config_js_1 = require("../config.js");
             }, mockHandler);
             (0, vitest_1.expect)(mockServer.registerTool).toHaveBeenCalled();
         });
-        (0, vitest_1.it)('should allow everything if binded mode is undefined', () => {
-            // This is a bit tricky since it's a global. We might need a way to reset it.
-            // For now, let's assume we can just pass a permissive mode or it was undefined initially.
-            // Since we don't have a reset, let's just test that it works when set to DESTRUCTIVE.
+        (0, vitest_1.it)('should allow everything if binded mode is write-destructive', () => {
             (0, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.WRITE_DESTRUCTIVE);
             mockServer.registerTool.mockClear();
             (0, shared_1.registerToolSafe)(mockServer, 'any_tool_static', {
@@ -93,4 +112,98 @@ const config_js_1 = require("../config.js");
             (0, vitest_1.expect)(mockServer.registerTool).toHaveBeenCalled();
         });
     });
+    (0, vitest_1.describe)('project UUID allowlist', () => {
+        (0, vitest_1.it)('should allow calls when allowlist is empty (all projects permitted)', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setStaticAllowedProjectUuids)([]);
+            (0, shared_1.registerToolSafe)(mockServer, 'list_charts', { description: 'List charts', inputSchema: {}, annotations: shared_1.READ_ONLY_DEFAULT }, mockHandler);
+            const [, , handler] = mockServer.registerTool.mock.calls[0];
+            const result = yield handler({ projectUuid: 'any-uuid' });
+            (0, vitest_1.expect)(result.isError).toBeUndefined();
+            (0, vitest_1.expect)(result.content[0].text).toBe('success');
+        }));
+        (0, vitest_1.it)('should allow calls for a singular projectUuid in the allowlist', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setStaticAllowedProjectUuids)(['uuid-allowed', 'uuid-other']);
+            (0, shared_1.registerToolSafe)(mockServer, 'list_charts_allowed', { description: 'List charts', inputSchema: {}, annotations: shared_1.READ_ONLY_DEFAULT }, mockHandler);
+            const [, , handler] = mockServer.registerTool.mock.calls[0];
+            const result = yield handler({ projectUuid: 'uuid-allowed' });
+            (0, vitest_1.expect)(result.isError).toBeUndefined();
+            (0, vitest_1.expect)(result.content[0].text).toBe('success');
+        }));
+        (0, vitest_1.it)('should block calls for a singular projectUuid not in the allowlist', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setStaticAllowedProjectUuids)(['uuid-allowed']);
+            (0, shared_1.registerToolSafe)(mockServer, 'list_charts_blocked', { description: 'List charts', inputSchema: {}, annotations: shared_1.READ_ONLY_DEFAULT }, mockHandler);
+            const [, , handler] = mockServer.registerTool.mock.calls[0];
+            const result = yield handler({ projectUuid: 'uuid-denied' });
+            (0, vitest_1.expect)(result.isError).toBe(true);
+            (0, vitest_1.expect)(result.content[0].text).toContain('not in the list of allowed projects');
+            (0, vitest_1.expect)(result.content[0].text).toContain('uuid-denied');
+        }));
+        (0, vitest_1.it)('should allow calls with no projectUuid arg even when allowlist is set', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setStaticAllowedProjectUuids)(['uuid-allowed']);
+            (0, shared_1.registerToolSafe)(mockServer, 'list_projects_no_uuid', { description: 'List projects', inputSchema: {}, annotations: shared_1.READ_ONLY_DEFAULT }, mockHandler);
+            const [, , handler] = mockServer.registerTool.mock.calls[0];
+            // No projectUuid in args → allowlist does not apply
+            const result = yield handler({});
+            (0, vitest_1.expect)(result.isError).toBeUndefined();
+            (0, vitest_1.expect)(result.content[0].text).toBe('success');
+        }));
+        (0, vitest_1.it)('should allow when all projectUuids[] are in the allowlist', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setStaticAllowedProjectUuids)(['uuid-a', 'uuid-b']);
+            (0, shared_1.registerToolSafe)(mockServer, 'search_content_allowed', { description: 'Search content', inputSchema: {}, annotations: shared_1.READ_ONLY_DEFAULT }, mockHandler);
+            const [, , handler] = mockServer.registerTool.mock.calls[0];
+            const result = yield handler({ projectUuids: ['uuid-a', 'uuid-b'] });
+            (0, vitest_1.expect)(result.isError).toBeUndefined();
+            (0, vitest_1.expect)(result.content[0].text).toBe('success');
+        }));
+        (0, vitest_1.it)('should block when any UUID in projectUuids[] is not in the allowlist', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setStaticAllowedProjectUuids)(['uuid-a']);
+            (0, shared_1.registerToolSafe)(mockServer, 'search_content_blocked', { description: 'Search content', inputSchema: {}, annotations: shared_1.READ_ONLY_DEFAULT }, mockHandler);
+            const [, , handler] = mockServer.registerTool.mock.calls[0];
+            const result = yield handler({ projectUuids: ['uuid-a', 'uuid-denied'] });
+            (0, vitest_1.expect)(result.isError).toBe(true);
+            (0, vitest_1.expect)(result.content[0].text).toContain('uuid-denied');
+            (0, vitest_1.expect)(result.content[0].text).toContain('not in the list of allowed projects');
+        }));
+        (0, vitest_1.it)('should block when all projectUuids[] are outside the allowlist', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setStaticAllowedProjectUuids)(['uuid-allowed']);
+            (0, shared_1.registerToolSafe)(mockServer, 'search_content_all_blocked', { description: 'Search content', inputSchema: {}, annotations: shared_1.READ_ONLY_DEFAULT }, mockHandler);
+            const [, , handler] = mockServer.registerTool.mock.calls[0];
+            const result = yield handler({ projectUuids: ['uuid-x', 'uuid-y'] });
+            (0, vitest_1.expect)(result.isError).toBe(true);
+            (0, vitest_1.expect)(result.content[0].text).toContain('not in the list of allowed projects');
+        }));
+    });
+    (0, vitest_1.describe)('dry-run mode', () => {
+        (0, vitest_1.it)('should not affect read-only tools in dry-run mode', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setDryRunMode)(true);
+            (0, shared_1.registerToolSafe)(mockServer, 'list_things_dry', { description: 'List things', inputSchema: {}, annotations: shared_1.READ_ONLY_DEFAULT }, mockHandler);
+            const [, options, handler] = mockServer.registerTool.mock.calls[0];
+            (0, vitest_1.expect)(options.description).not.toContain('[DRY-RUN]');
+            const result = yield handler({});
+            (0, vitest_1.expect)(result.content[0].text).toBe('success');
+        }));
+        (0, vitest_1.it)('should simulate write-idempotent tools in dry-run mode', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setDryRunMode)(true);
+            process.env.LIGHTDASH_TOOL_SAFETY_MODE = common_1.SafetyMode.WRITE_DESTRUCTIVE;
+            (0, shared_1.registerToolSafe)(mockServer, 'upsert_thing_dry', { description: 'Upsert thing', inputSchema: {}, annotations: shared_1.WRITE_IDEMPOTENT }, mockHandler);
+            const [, options, handler] = mockServer.registerTool.mock.calls[0];
+            (0, vitest_1.expect)(options.description).toContain('[DRY-RUN]');
+            const result = yield handler({ projectUuid: 'uuid-x', slug: 'my-chart' });
+            (0, vitest_1.expect)(result.isError).toBeUndefined();
+            (0, vitest_1.expect)(result.content[0].text).toContain('[DRY-RUN]');
+            (0, vitest_1.expect)(result.content[0].text).toContain('No changes were made');
+            // Verify the underlying handler was NOT called
+            (0, vitest_1.expect)(mockHandler).not.toHaveBeenCalled();
+        }));
+        (0, vitest_1.it)('should simulate destructive tools in dry-run mode', () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, config_js_1.setDryRunMode)(true);
+            process.env.LIGHTDASH_TOOL_SAFETY_MODE = common_1.SafetyMode.WRITE_DESTRUCTIVE;
+            (0, shared_1.registerToolSafe)(mockServer, 'delete_thing_dry', { description: 'Delete thing', inputSchema: {}, annotations: shared_1.WRITE_DESTRUCTIVE }, mockHandler);
+            const [, options, handler] = mockServer.registerTool.mock.calls[0];
+            (0, vitest_1.expect)(options.description).toContain('[DRY-RUN]');
+            const result = yield handler({ projectUuid: 'uuid-x' });
+            (0, vitest_1.expect)(result.content[0].text).toContain('No changes were made');
+            (0, vitest_1.expect)(mockHandler).not.toHaveBeenCalled();
+        }));
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash-tools/mcp",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "MCP server and utilities for Lightdash AI.",
   "keywords": [],
   "license": "Apache-2.0",
@@ -14,8 +14,8 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "commander": "^14.0.3",
     "zod": "^4.3.6",
-    "@lightdash-tools/common": "0.2.6",
-    "@lightdash-tools/client": "0.2.6"
+    "@lightdash-tools/client": "0.3.1",
+    "@lightdash-tools/common": "0.3.1"
   },
   "devDependencies": {
     "@types/node": "^25.2.3"

package/src/audit.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-exports the shared audit logger from @lightdash-tools/common.
+ * The canonical implementation lives in common so the CLI can also use it.
+ */
+export { getSessionId, initAuditLog, logAuditEntry } from '@lightdash-tools/common';
+export type { AuditLogEntry, AuditStatus } from '@lightdash-tools/common';

package/src/bin.ts

@@ -5,19 +5,27 @@
 
 import { Command } from 'commander';
 import { SafetyMode } from '@lightdash-tools/common';
-import { setStaticSafetyMode } from './config.js';
+import { setStaticSafetyMode, setStaticAllowedProjectUuids, setDryRunMode } from './config.js';
 
 const program = new Command();
 
 program
   .name('lightdash-mcp')
   .description('MCP server for Lightdash AI')
-  .version('0.2.6')
+  .version('0.3.1')
   .option('--http', 'Run as HTTP server instead of Stdio')
   .option(
     '--safety-mode <mode>',
     'Filter registered tools by safety mode (read-only, write-idempotent, write-destructive)',
   )
+  .option(
+    '--projects <uuids>',
+    'Comma-separated list of allowed project UUIDs (overrides LIGHTDASH_ALLOWED_PROJECTS; empty = all allowed)',
+  )
+  .option(
+    '--dry-run',
+    'Simulate write operations without executing them (overrides LIGHTDASH_DRY_RUN)',
+  )
   .action((options) => {
     if (options.safetyMode) {
       if (Object.values(SafetyMode).includes(options.safetyMode)) {
@@ -28,6 +36,18 @@ program
       }
     }
 
+    if (options.projects) {
+      const uuids = (options.projects as string)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      setStaticAllowedProjectUuids(uuids);
+    }
+
+    if (options.dryRun) {
+      setDryRunMode(true);
+    }
+
     if (options.http) {
       void import('./http.js');
     } else {

package/src/config.ts

@@ -5,10 +5,12 @@
 
 import { LightdashClient, mergeConfig } from '@lightdash-tools/client';
 import type { PartialLightdashClientConfig } from '@lightdash-tools/client';
-import { getSafetyModeFromEnv } from '@lightdash-tools/common';
+import { getSafetyModeFromEnv, getAllowedProjectUuidsFromEnv } from '@lightdash-tools/common';
 import type { SafetyMode } from '@lightdash-tools/common';
 
 let globalStaticSafetyMode: SafetyMode | undefined;
+let globalStaticAllowedProjectUuids: string[] | undefined;
+let globalDryRunMode: boolean | undefined;
 
 /**
  * Gets the safety mode for dynamic enforcement.
@@ -31,6 +33,46 @@ export function setStaticSafetyMode(mode: SafetyMode): void {
   globalStaticSafetyMode = mode;
 }
 
+/**
+ * Returns the effective project UUID allowlist.
+ * CLI-provided values override the environment variable.
+ * An empty array means all projects are allowed.
+ */
+export function getAllowedProjectUuids(): string[] {
+  return globalStaticAllowedProjectUuids ?? getAllowedProjectUuidsFromEnv();
+}
+
+/**
+ * Sets the project UUID allowlist from the CLI (overrides LIGHTDASH_ALLOWED_PROJECTS).
+ */
+export function setStaticAllowedProjectUuids(uuids: string[]): void {
+  globalStaticAllowedProjectUuids = uuids;
+}
+
+/**
+ * Returns true when dry-run mode is active.
+ * CLI flag overrides the LIGHTDASH_DRY_RUN environment variable.
+ */
+export function isDryRunMode(): boolean {
+  if (globalDryRunMode !== undefined) return globalDryRunMode;
+  const v = process.env.LIGHTDASH_DRY_RUN;
+  return v === '1' || v === 'true' || v === 'yes';
+}
+
+/**
+ * Enables or disables dry-run mode (from CLI).
+ */
+export function setDryRunMode(enabled: boolean): void {
+  globalDryRunMode = enabled;
+}
+
+/**
+ * Returns the audit log file path from LIGHTDASH_AUDIT_LOG, or undefined to use stderr.
+ */
+export function getAuditLogPath(): string | undefined {
+  return process.env.LIGHTDASH_AUDIT_LOG || undefined;
+}
+
 /**
  * Builds a LightdashClient from environment variables (and optional overrides).
  * Throws if LIGHTDASH_URL or LIGHTDASH_API_KEY are missing.

package/src/http.ts

@@ -7,7 +7,8 @@ import { createServer, type IncomingMessage, type ServerResponse } from 'node:ht
 import { randomUUID } from 'node:crypto';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { getClient } from './config.js';
+import { getClient, getAuditLogPath } from './config.js';
+import { initAuditLog } from './audit.js';
 import { registerTools } from './tools/index.js';
 
 const MCP_PATH = '/mcp';
@@ -165,6 +166,8 @@ async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise
 }
 
 function main(): void {
+  initAuditLog(getAuditLogPath());
+
   const server = createServer((req, res) => {
     handleRequest(req, res).catch((err) => {
       console.error('MCP HTTP handler error:', err);

package/src/index.ts

@@ -5,10 +5,13 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { getClient } from './config';
-import { registerTools } from './tools';
+import { getClient, getAuditLogPath } from './config.js';
+import { initAuditLog } from './audit.js';
+import { registerTools } from './tools/index.js';
 
 async function main(): Promise<void> {
+  initAuditLog(getAuditLogPath());
+
   const client = getClient();
   const server = new McpServer({
     name: 'lightdash-mcp',