@lightdash-tools/mcp 0.4.0 → 0.5.0

package/README.md

@@ -30,7 +30,11 @@ npm install -g @lightdash-tools/mcp
 
 ### Optional (both modes)
 
-- `LIGHTDASH_TOOL_SAFETY_MODE` — Safety mode for dynamic enforcement (`read-only`, `write-idempotent`, `write-destructive`). See [Safety Modes](#safety-modes) for details.
+- `LIGHTDASH_TOOLS_SAFETY_MODE` — Safety mode for dynamic enforcement (`read-only`, `write-idempotent`, `write-destructive`). See [Safety Modes](#safety-modes) for details.
+- `LIGHTDASH_TOOLS_ALLOWED_PROJECTS` — Comma-separated project UUIDs to restrict operations (empty = all allowed). CLI `--projects` overrides.
+- `LIGHTDASH_TOOLS_DRY_RUN` — Set to `1`, `true`, or `yes` to simulate write operations without executing.
+
+Prefer env vars from the parent process. Avoid plaintext `.env` when AI agents have file access. If using `.env`, use [dotenvx](https://dotenvx.com/) for encrypted secrets. See [docs/secrets-and-credentials.md](../../docs/secrets-and-credentials.md).
 
 ### Streamable HTTP only
 
@@ -106,12 +110,12 @@ lightdash-mcp --help
 
 - `--http` — Run as HTTP server instead of Stdio.
 - `--safety-mode <mode>` — Filter registered tools by safety mode (`read-only`, `write-idempotent`, `write-destructive`). Tools not allowed in this mode will not be registered, hiding them from AI agents (Static Filtering).
-- `--projects <uuids>` — Comma-separated list of allowed project UUIDs (overrides `LIGHTDASH_ALLOWED_PROJECTS`; empty = all allowed).
-- `--dry-run` — Simulate write operations without executing them (overrides `LIGHTDASH_DRY_RUN`).
+- `--projects <uuids>` — Comma-separated list of allowed project UUIDs (overrides `LIGHTDASH_TOOLS_ALLOWED_PROJECTS`; empty = all allowed).
+- `--dry-run` — Simulate write operations without executing them (overrides `LIGHTDASH_TOOLS_DRY_RUN`).
 
 ## Safety Modes
 
-The MCP server implements a hierarchical safety model. You can control which tools are available to AI agents using the `LIGHTDASH_TOOL_SAFETY_MODE` environment variable or the `--safety-mode` CLI option.
+The MCP server implements a hierarchical safety model. You can control which tools are available to AI agents using the `LIGHTDASH_TOOLS_SAFETY_MODE` environment variable or the `--safety-mode` CLI option.
 
 - `read-only` (default): Only allows non-modifying tools (e.g., `list_*`, `get_*`).
 - `write-idempotent`: Allows read tools and non-destructive writes (e.g., `upsert_chart_as_code`).
@@ -119,7 +123,7 @@ The MCP server implements a hierarchical safety model. You can control which too
 
 ### Enforcement Layers
 
-1. **Dynamic Enforcement (Visible but Disabled)**: Using `LIGHTDASH_TOOL_SAFETY_MODE` environment variable. Tools are registered and visible to the agent, but return an error if called. This allows agents to understand that a capability exists but is restricted.
+1. **Dynamic Enforcement (Visible but Disabled)**: Using `LIGHTDASH_TOOLS_SAFETY_MODE` environment variable. Tools are registered and visible to the agent, but return an error if called. This allows agents to understand that a capability exists but is restricted.
 2. **Static Filtering (Hidden)**: Using the `--safety-mode` CLI option. Tools not allowed in the selected mode are not registered at all. They are completely hidden from the AI agent.
 
 When a tool is disabled via dynamic enforcement, the server will return a descriptive error message if an agent attempts to call it.
@@ -128,6 +132,10 @@ When a tool is disabled via dynamic enforcement, the server will return a descri
 
 Tools with `destructiveHint: true` (e.g. `delete_member`) perform irreversible or high-impact actions. MCP clients should show a warning and/or require user confirmation before executing them. AI agents should ask the user for explicit confirmation before calling such tools.
 
+### Input validation
+
+Resource IDs (project UUIDs, slugs) are validated before execution. Invalid inputs (control characters, `?`, `#`, `%`, path traversal) are rejected. This guards against adversarial or hallucinated inputs when used by AI agents. See [docs/agent-context/CONTEXT.md](../../docs/agent-context/CONTEXT.md) for agent-specific guidance.
+
 ## Testing
 
 This package includes unit tests and integration tests. Integration tests run against a real Lightdash API and are only executed if the required environment variables are set.

package/dist/bin.js

@@ -44,11 +44,11 @@ const program = new commander_1.Command();
 program
     .name('lightdash-mcp')
     .description('MCP server for Lightdash AI')
-    .version('0.4.0')
+    .version('0.5.0')
     .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)')
+    .option('--projects <uuids>', 'Comma-separated list of allowed project UUIDs (overrides LIGHTDASH_TOOLS_ALLOWED_PROJECTS; empty = all allowed)')
+    .option('--dry-run', 'Simulate write operations without executing them (overrides LIGHTDASH_TOOLS_DRY_RUN)')
     .action((options) => {
     if (options.safetyMode) {
         if (Object.values(common_1.SafetyMode).includes(options.safetyMode)) {

package/dist/config.d.ts

@@ -24,12 +24,12 @@ export declare function setStaticSafetyMode(mode: SafetyMode): void;
  */
 export declare function getAllowedProjectUuids(): string[];
 /**
- * Sets the project UUID allowlist from the CLI (overrides LIGHTDASH_ALLOWED_PROJECTS).
+ * Sets the project UUID allowlist from the CLI (overrides LIGHTDASH_TOOLS_ALLOWED_PROJECTS).
  */
 export declare function setStaticAllowedProjectUuids(uuids: string[]): void;
 /**
  * Returns true when dry-run mode is active.
- * CLI flag overrides the LIGHTDASH_DRY_RUN environment variable.
+ * CLI flag overrides the LIGHTDASH_TOOLS_DRY_RUN environment variable.
  */
 export declare function isDryRunMode(): boolean;
 /**
@@ -37,7 +37,7 @@ export declare function isDryRunMode(): boolean;
  */
 export declare function setDryRunMode(enabled: boolean): void;
 /**
- * Returns the audit log file path from LIGHTDASH_AUDIT_LOG, or undefined to use stderr.
+ * Returns the audit log file path from LIGHTDASH_TOOLS_AUDIT_LOG, or undefined to use stderr.
  */
 export declare function getAuditLogPath(): string | undefined;
 /**

package/dist/config.js

@@ -45,19 +45,19 @@ function getAllowedProjectUuids() {
     return globalStaticAllowedProjectUuids !== null && globalStaticAllowedProjectUuids !== void 0 ? globalStaticAllowedProjectUuids : (0, common_1.getAllowedProjectUuidsFromEnv)();
 }
 /**
- * Sets the project UUID allowlist from the CLI (overrides LIGHTDASH_ALLOWED_PROJECTS).
+ * Sets the project UUID allowlist from the CLI (overrides LIGHTDASH_TOOLS_ALLOWED_PROJECTS).
  */
 function setStaticAllowedProjectUuids(uuids) {
     globalStaticAllowedProjectUuids = uuids;
 }
 /**
  * Returns true when dry-run mode is active.
- * CLI flag overrides the LIGHTDASH_DRY_RUN environment variable.
+ * CLI flag overrides the LIGHTDASH_TOOLS_DRY_RUN environment variable.
  */
 function isDryRunMode() {
     if (globalDryRunMode !== undefined)
         return globalDryRunMode;
-    const v = process.env.LIGHTDASH_DRY_RUN;
+    const v = process.env.LIGHTDASH_TOOLS_DRY_RUN;
     return v === '1' || v === 'true' || v === 'yes';
 }
 /**
@@ -67,10 +67,10 @@ function setDryRunMode(enabled) {
     globalDryRunMode = enabled;
 }
 /**
- * Returns the audit log file path from LIGHTDASH_AUDIT_LOG, or undefined to use stderr.
+ * Returns the audit log file path from LIGHTDASH_TOOLS_AUDIT_LOG, or undefined to use stderr.
  */
 function getAuditLogPath() {
-    return process.env.LIGHTDASH_AUDIT_LOG || undefined;
+    return process.env.LIGHTDASH_TOOLS_AUDIT_LOG || undefined;
 }
 /**
  * Builds a LightdashClient from environment variables (and optional overrides).

package/dist/tools/shared.d.ts

@@ -4,9 +4,10 @@
  * 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.
+ *   3. Input validation    — rejects invalid resource IDs (control chars, ?, #, %, path traversal).
+ *   4. Dry-run wrapper     — simulates writes without executing them (registration-time).
+ *   5. Safety-mode wrapper — disables tools that exceed the configured safety level.
+ *   6. Raw handler        — the actual tool implementation.
  */
 import type { LightdashClient } from '@lightdash-tools/client';
 import type { ToolAnnotations } from '@lightdash-tools/common';

package/dist/tools/shared.js

@@ -5,9 +5,10 @@
  * 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.
+ *   3. Input validation    — rejects invalid resource IDs (control chars, ?, #, %, path traversal).
+ *   4. Dry-run wrapper     — simulates writes without executing them (registration-time).
+ *   5. Safety-mode wrapper — disables tools that exceed the configured safety level.
+ *   6. 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); }); }
@@ -74,7 +75,7 @@ function registerToolSafe(server, shortName, options, handler) {
                 content: [
                     {
                         type: 'text',
-                        text: `Error: Tool '${name}' is disabled in ${mode} mode. To enable it, change LIGHTDASH_TOOL_SAFETY_MODE.`,
+                        text: `Error: Tool '${name}' is disabled in ${mode} mode. To enable it, change LIGHTDASH_TOOLS_SAFETY_MODE.`,
                     },
                 ],
                 isError: true,
@@ -98,6 +99,48 @@ function registerToolSafe(server, shortName, options, handler) {
             });
         });
     }
+    // ── Input validation wrapper ─────────────────────────────────────────────
+    // Validate resource IDs (projectUuid, slug, etc.) before handler.
+    const validatedInner = finalHandler;
+    finalHandler = (args, extra) => __awaiter(this, void 0, void 0, function* () {
+        const projectUuids = (0, common_1.extractProjectUuids)(args);
+        for (const uuid of projectUuids) {
+            try {
+                (0, common_1.validateResourceId)(uuid);
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: Invalid resource ID: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                    _lightdashBlocked: true,
+                };
+            }
+        }
+        const a = args;
+        if (typeof (a === null || a === void 0 ? void 0 : a.slug) === 'string') {
+            try {
+                (0, common_1.validateResourceId)(a.slug);
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: Invalid slug: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                    _lightdashBlocked: true,
+                };
+            }
+        }
+        return validatedInner(args, extra);
+    });
     // ── Project allowlist wrapper ─────────────────────────────────────────────
     // Reject calls targeting project UUIDs not in the configured allowlist.
     // Covers both singular (projectUuid) and plural (projectUuids[]) arg shapes.

package/dist/tools/shared.test.js

@@ -31,15 +31,15 @@ vitest_1.vi.mock('@lightdash-tools/common', (importOriginal) => __awaiter(void 0
         (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;
+        process.env.LIGHTDASH_TOOLS_SAFETY_MODE = common_1.SafetyMode.WRITE_DESTRUCTIVE;
         delete process.env.LIGHTDASH_TOOLS_ALLOWED_PROJECTS;
-        delete process.env.LIGHTDASH_DRY_RUN;
+        delete process.env.LIGHTDASH_TOOLS_DRY_RUN;
     });
     (0, vitest_1.afterEach)(() => {
-        delete process.env.LIGHTDASH_TOOL_SAFETY_MODE;
+        delete process.env.LIGHTDASH_TOOLS_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;
+        process.env.LIGHTDASH_TOOLS_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',
@@ -54,7 +54,7 @@ vitest_1.vi.mock('@lightdash-tools/common', (importOriginal) => __awaiter(void 0
         (0, vitest_1.expect)(result.content[0].text).toBe('success');
     }));
     (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;
+        process.env.LIGHTDASH_TOOLS_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',
@@ -68,7 +68,7 @@ vitest_1.vi.mock('@lightdash-tools/common', (importOriginal) => __awaiter(void 0
         (0, vitest_1.expect)(result.content[0].text).toContain('disabled in read-only mode');
     }));
     (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;
+        process.env.LIGHTDASH_TOOLS_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',
@@ -80,6 +80,18 @@ vitest_1.vi.mock('@lightdash-tools/common', (importOriginal) => __awaiter(void 0
         const result = yield handler({});
         (0, vitest_1.expect)(result.content[0].text).toBe('success');
     }));
+    (0, vitest_1.it)('should reject invalid projectUuid before calling handler', () => __awaiter(void 0, void 0, void 0, function* () {
+        (0, shared_1.registerToolSafe)(mockServer, 'list_tool', {
+            description: 'List something',
+            inputSchema: {},
+            annotations: shared_1.READ_ONLY_DEFAULT,
+        }, mockHandler);
+        const [, , handler] = mockServer.registerTool.mock.calls[0];
+        const result = yield handler({ projectUuid: 'uuid?fields=name' });
+        (0, vitest_1.expect)(mockHandler).not.toHaveBeenCalled();
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toContain('Invalid resource ID');
+    }));
     (0, vitest_1.describe)('static filtering (safety-mode)', () => {
         (0, vitest_1.it)('should skip registration if tool is more permissive than binded mode', () => {
             (0, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.READ_ONLY);
@@ -184,7 +196,7 @@ vitest_1.vi.mock('@lightdash-tools/common', (importOriginal) => __awaiter(void 0
         }));
         (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;
+            process.env.LIGHTDASH_TOOLS_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]');
@@ -197,7 +209,7 @@ vitest_1.vi.mock('@lightdash-tools/common', (importOriginal) => __awaiter(void 0
         }));
         (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;
+            process.env.LIGHTDASH_TOOLS_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]');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash-tools/mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server and utilities for Lightdash AI.",
   "keywords": [],
   "license": "Apache-2.0",
@@ -14,11 +14,11 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "commander": "^14.0.3",
     "zod": "^4.3.6",
-    "@lightdash-tools/client": "0.4.0",
-    "@lightdash-tools/common": "0.4.0"
+    "@lightdash-tools/client": "0.5.0",
+    "@lightdash-tools/common": "0.5.0"
   },
   "devDependencies": {
-    "@types/node": "^25.2.3"
+    "@types/node": "^25.3.4"
   },
   "scripts": {
     "build": "tsc",

package/src/bin.ts

@@ -12,7 +12,7 @@ const program = new Command();
 program
   .name('lightdash-mcp')
   .description('MCP server for Lightdash AI')
-  .version('0.4.0')
+  .version('0.5.0')
   .option('--http', 'Run as HTTP server instead of Stdio')
   .option(
     '--safety-mode <mode>',
@@ -20,11 +20,11 @@ program
   )
   .option(
     '--projects <uuids>',
-    'Comma-separated list of allowed project UUIDs (overrides LIGHTDASH_ALLOWED_PROJECTS; empty = all allowed)',
+    'Comma-separated list of allowed project UUIDs (overrides LIGHTDASH_TOOLS_ALLOWED_PROJECTS; empty = all allowed)',
   )
   .option(
     '--dry-run',
-    'Simulate write operations without executing them (overrides LIGHTDASH_DRY_RUN)',
+    'Simulate write operations without executing them (overrides LIGHTDASH_TOOLS_DRY_RUN)',
   )
   .action((options) => {
     if (options.safetyMode) {

package/src/config.ts

@@ -43,7 +43,7 @@ export function getAllowedProjectUuids(): string[] {
 }
 
 /**
- * Sets the project UUID allowlist from the CLI (overrides LIGHTDASH_ALLOWED_PROJECTS).
+ * Sets the project UUID allowlist from the CLI (overrides LIGHTDASH_TOOLS_ALLOWED_PROJECTS).
  */
 export function setStaticAllowedProjectUuids(uuids: string[]): void {
   globalStaticAllowedProjectUuids = uuids;
@@ -51,11 +51,11 @@ export function setStaticAllowedProjectUuids(uuids: string[]): void {
 
 /**
  * Returns true when dry-run mode is active.
- * CLI flag overrides the LIGHTDASH_DRY_RUN environment variable.
+ * CLI flag overrides the LIGHTDASH_TOOLS_DRY_RUN environment variable.
  */
 export function isDryRunMode(): boolean {
   if (globalDryRunMode !== undefined) return globalDryRunMode;
-  const v = process.env.LIGHTDASH_DRY_RUN;
+  const v = process.env.LIGHTDASH_TOOLS_DRY_RUN;
   return v === '1' || v === 'true' || v === 'yes';
 }
 
@@ -67,10 +67,10 @@ export function setDryRunMode(enabled: boolean): void {
 }
 
 /**
- * Returns the audit log file path from LIGHTDASH_AUDIT_LOG, or undefined to use stderr.
+ * Returns the audit log file path from LIGHTDASH_TOOLS_AUDIT_LOG, or undefined to use stderr.
  */
 export function getAuditLogPath(): string | undefined {
-  return process.env.LIGHTDASH_AUDIT_LOG || undefined;
+  return process.env.LIGHTDASH_TOOLS_AUDIT_LOG || undefined;
 }
 
 /**

package/src/tools/shared.test.ts

@@ -29,17 +29,17 @@ describe('registerToolSafe', () => {
     setStaticSafetyMode(SafetyMode.WRITE_DESTRUCTIVE);
     setStaticAllowedProjectUuids([]);
     setDryRunMode(false);
-    process.env.LIGHTDASH_TOOL_SAFETY_MODE = SafetyMode.WRITE_DESTRUCTIVE;
+    process.env.LIGHTDASH_TOOLS_SAFETY_MODE = SafetyMode.WRITE_DESTRUCTIVE;
     delete process.env.LIGHTDASH_TOOLS_ALLOWED_PROJECTS;
-    delete process.env.LIGHTDASH_DRY_RUN;
+    delete process.env.LIGHTDASH_TOOLS_DRY_RUN;
   });
 
   afterEach(() => {
-    delete process.env.LIGHTDASH_TOOL_SAFETY_MODE;
+    delete process.env.LIGHTDASH_TOOLS_SAFETY_MODE;
   });
 
   it('should allow read-only tool in read-only mode', async () => {
-    process.env.LIGHTDASH_TOOL_SAFETY_MODE = SafetyMode.READ_ONLY;
+    process.env.LIGHTDASH_TOOLS_SAFETY_MODE = SafetyMode.READ_ONLY;
     setStaticSafetyMode(SafetyMode.WRITE_DESTRUCTIVE); // static = allow all
 
     registerToolSafe(
@@ -64,7 +64,7 @@ describe('registerToolSafe', () => {
   });
 
   it('should block destructive tool in read-only mode', async () => {
-    process.env.LIGHTDASH_TOOL_SAFETY_MODE = SafetyMode.READ_ONLY;
+    process.env.LIGHTDASH_TOOLS_SAFETY_MODE = SafetyMode.READ_ONLY;
     setStaticSafetyMode(SafetyMode.WRITE_DESTRUCTIVE);
 
     registerToolSafe(
@@ -88,7 +88,7 @@ describe('registerToolSafe', () => {
   });
 
   it('should allow destructive tool in write-destructive mode', async () => {
-    process.env.LIGHTDASH_TOOL_SAFETY_MODE = SafetyMode.WRITE_DESTRUCTIVE;
+    process.env.LIGHTDASH_TOOLS_SAFETY_MODE = SafetyMode.WRITE_DESTRUCTIVE;
     setStaticSafetyMode(SafetyMode.WRITE_DESTRUCTIVE);
 
     registerToolSafe(
@@ -110,6 +110,26 @@ describe('registerToolSafe', () => {
     expect(result.content[0].text).toBe('success');
   });
 
+  it('should reject invalid projectUuid before calling handler', async () => {
+    registerToolSafe(
+      mockServer,
+      'list_tool',
+      {
+        description: 'List something',
+        inputSchema: {},
+        annotations: READ_ONLY_DEFAULT,
+      },
+      mockHandler,
+    );
+
+    const [, , handler] = mockServer.registerTool.mock.calls[0];
+    const result = await handler({ projectUuid: 'uuid?fields=name' });
+
+    expect(mockHandler).not.toHaveBeenCalled();
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Invalid resource ID');
+  });
+
   describe('static filtering (safety-mode)', () => {
     it('should skip registration if tool is more permissive than binded mode', () => {
       setStaticSafetyMode(SafetyMode.READ_ONLY);
@@ -303,7 +323,7 @@ describe('registerToolSafe', () => {
 
     it('should simulate write-idempotent tools in dry-run mode', async () => {
       setDryRunMode(true);
-      process.env.LIGHTDASH_TOOL_SAFETY_MODE = SafetyMode.WRITE_DESTRUCTIVE;
+      process.env.LIGHTDASH_TOOLS_SAFETY_MODE = SafetyMode.WRITE_DESTRUCTIVE;
 
       registerToolSafe(
         mockServer,
@@ -325,7 +345,7 @@ describe('registerToolSafe', () => {
 
     it('should simulate destructive tools in dry-run mode', async () => {
       setDryRunMode(true);
-      process.env.LIGHTDASH_TOOL_SAFETY_MODE = SafetyMode.WRITE_DESTRUCTIVE;
+      process.env.LIGHTDASH_TOOLS_SAFETY_MODE = SafetyMode.WRITE_DESTRUCTIVE;
 
       registerToolSafe(
         mockServer,

package/src/tools/shared.ts

@@ -4,9 +4,10 @@
  * 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.
+ *   3. Input validation    — rejects invalid resource IDs (control chars, ?, #, %, path traversal).
+ *   4. Dry-run wrapper     — simulates writes without executing them (registration-time).
+ *   5. Safety-mode wrapper — disables tools that exceed the configured safety level.
+ *   6. Raw handler        — the actual tool implementation.
  */
 
 import type { LightdashClient } from '@lightdash-tools/client';
@@ -17,6 +18,7 @@ import {
   READ_ONLY_DEFAULT,
   logAuditEntry,
   getSessionId,
+  validateResourceId,
 } from '@lightdash-tools/common';
 import type { ToolAnnotations } from '@lightdash-tools/common';
 import type { z } from 'zod';
@@ -113,7 +115,7 @@ export function registerToolSafe(
       content: [
         {
           type: 'text',
-          text: `Error: Tool '${name}' is disabled in ${mode} mode. To enable it, change LIGHTDASH_TOOL_SAFETY_MODE.`,
+          text: `Error: Tool '${name}' is disabled in ${mode} mode. To enable it, change LIGHTDASH_TOOLS_SAFETY_MODE.`,
         },
       ],
       isError: true,
@@ -134,6 +136,47 @@ export function registerToolSafe(
     });
   }
 
+  // ── Input validation wrapper ─────────────────────────────────────────────
+  // Validate resource IDs (projectUuid, slug, etc.) before handler.
+  const validatedInner = finalHandler;
+  finalHandler = async (args, extra): Promise<TextContent> => {
+    const projectUuids = extractProjectUuids(args);
+    for (const uuid of projectUuids) {
+      try {
+        validateResourceId(uuid);
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: Invalid resource ID: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+          _lightdashBlocked: true,
+        } as BlockedContent;
+      }
+    }
+    const a = args as Record<string, unknown>;
+    if (typeof a?.slug === 'string') {
+      try {
+        validateResourceId(a.slug);
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: Invalid slug: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+          _lightdashBlocked: true,
+        } as BlockedContent;
+      }
+    }
+    return validatedInner(args, extra);
+  };
+
   // ── Project allowlist wrapper ─────────────────────────────────────────────
   // Reject calls targeting project UUIDs not in the configured allowlist.
   // Covers both singular (projectUuid) and plural (projectUuids[]) arg shapes.