@lightdash-tools/mcp 0.1.2 → 0.2.4

package/README.md

@@ -1,4 +1,4 @@
-# @lightdash-tools/mcp
+# [@lightdash-tools/mcp](https://www.npmjs.com/package/@lightdash-tools/mcp) <!-- markdown-link-check-disable-line -->
 
 MCP server for Lightdash: exposes projects, charts, dashboards, spaces, users, and groups as tools. Uses `@lightdash-tools/client` for all API access.
 
@@ -28,6 +28,10 @@ npm install -g @lightdash-tools/mcp
 - `LIGHTDASH_URL` — Lightdash instance base URL (e.g. `https://app.lightdash.cloud`).
 - `LIGHTDASH_API_KEY` — Personal access token or API key.
 
+### 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.
+
 ### Streamable HTTP only
 
 - `MCP_HTTP_PORT` — Port for the HTTP server (default: `3100`).
@@ -44,6 +48,12 @@ For use with Claude Desktop or IDEs, use `npx`:
 npx @lightdash-tools/mcp
 ```
 
+To hide destructive tools from the agent:
+
+```bash
+npx @lightdash-tools/mcp --safety-mode write-idempotent
+```
+
 Or if installed globally:
 
 ```bash
@@ -64,7 +74,40 @@ With auth disabled (default), any client can call the endpoint. With `MCP_AUTH_E
 
 ## Tools
 
-Same set in both modes: `list_projects`, `get_project`, `list_explores`, `get_explore`, `list_charts`, `list_charts_as_code`, `upsert_chart_as_code`, `list_dashboards`, `list_spaces`, `get_space`, `list_organization_members`, `get_member`, `delete_member`, `list_groups`, `get_group`, `compile_query`.
+The server registers the following tools (names prefixed with `lightdash_tools__`):
+
+- **Projects**: `list_projects`, `get_project`, `validate_project`, `get_validation_results`
+- **Explores**: `list_explores`, `get_explore`, `list_dimensions`, `get_field_lineage`
+- **Charts**: `list_charts`, `list_charts_as_code`, `upsert_chart_as_code`
+- **Dashboards**: `list_dashboards`
+- **Spaces**: `list_spaces`, `get_space`
+- **Users**: `list_organization_members`, `get_member`, `delete_member`
+- **Groups**: `list_groups`, `get_group`
+- **Metrics**: `list_metrics`
+- **Schedulers**: `list_schedulers`
+- **Tags**: `list_tags`
+- **Query**: `compile_query`
+- **Content**: `search_content`
+
+### CLI Options
+
+- `--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).
+
+## 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.
+
+- `read-only`: Only allows non-modifying tools (e.g., `list_*`, `get_*`).
+- `write-idempotent`: Allows read tools and non-destructive writes (e.g., `upsert_chart_as_code`).
+- `write-destructive` (default): Allows all tools, including destructive ones (e.g., `delete_member`).
+
+### 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.
+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.
 
 ### Destructive tools
 

package/dist/bin.d.ts

@@ -2,4 +2,4 @@
 /**
  * MCP server CLI entrypoint.
  */
-declare const args: string[];
+export {};

package/dist/bin.js

@@ -36,10 +36,32 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-const args = process.argv.slice(2);
-if (args.includes('--http')) {
-    void Promise.resolve().then(() => __importStar(require('./http.js')));
-}
-else {
-    void Promise.resolve().then(() => __importStar(require('./index.js')));
-}
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const common_1 = require("@lightdash-tools/common");
+const config_js_1 = require("./config.js");
+const program = new commander_1.Command();
+program
+    .name('lightdash-mcp')
+    .description('MCP server for Lightdash AI')
+    .version('0.2.3')
+    .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)')
+    .action((options) => {
+    if (options.safetyMode) {
+        if (Object.values(common_1.SafetyMode).includes(options.safetyMode)) {
+            (0, config_js_1.setStaticSafetyMode)(options.safetyMode);
+        }
+        else {
+            console.error(`Invalid safety mode: ${options.safetyMode}`);
+            process.exit(1);
+        }
+    }
+    if (options.http) {
+        void Promise.resolve().then(() => __importStar(require('./http.js')));
+    }
+    else {
+        void Promise.resolve().then(() => __importStar(require('./index.js')));
+    }
+});
+program.parse(process.argv);

package/dist/config.d.ts

@@ -4,6 +4,19 @@
  */
 import { LightdashClient } from '@lightdash-tools/client';
 import type { PartialLightdashClientConfig } from '@lightdash-tools/client';
+import type { SafetyMode } from '@lightdash-tools/common';
+/**
+ * Gets the safety mode for dynamic enforcement.
+ */
+export declare function getSafetyMode(): SafetyMode;
+/**
+ * Gets the safety mode for static tool filtering (binding).
+ */
+export declare function getStaticSafetyMode(): SafetyMode | undefined;
+/**
+ * Sets the static safety mode (from CLI).
+ */
+export declare function setStaticSafetyMode(mode: SafetyMode): void;
 /**
  * Builds a LightdashClient from environment variables (and optional overrides).
  * Throws if LIGHTDASH_URL or LIGHTDASH_API_KEY are missing.

package/dist/config.js

@@ -4,8 +4,31 @@
  * Uses same env vars as CLI: LIGHTDASH_URL, LIGHTDASH_API_KEY.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSafetyMode = getSafetyMode;
+exports.getStaticSafetyMode = getStaticSafetyMode;
+exports.setStaticSafetyMode = setStaticSafetyMode;
 exports.getClient = getClient;
 const client_1 = require("@lightdash-tools/client");
+const common_1 = require("@lightdash-tools/common");
+let globalStaticSafetyMode;
+/**
+ * Gets the safety mode for dynamic enforcement.
+ */
+function getSafetyMode() {
+    return (0, common_1.getSafetyModeFromEnv)();
+}
+/**
+ * Gets the safety mode for static tool filtering (binding).
+ */
+function getStaticSafetyMode() {
+    return globalStaticSafetyMode;
+}
+/**
+ * Sets the static safety mode (from CLI).
+ */
+function setStaticSafetyMode(mode) {
+    globalStaticSafetyMode = mode;
+}
 /**
  * Builds a LightdashClient from environment variables (and optional overrides).
  * Throws if LIGHTDASH_URL or LIGHTDASH_API_KEY are missing.

package/dist/tools/content.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP tools: content (search).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+export declare function registerContentTools(server: McpServer, client: LightdashClient): void;

package/dist/tools/content.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * MCP tools: content (search).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerContentTools = registerContentTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerContentTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'search_content', {
+        title: 'Search content',
+        description: 'Search for charts, dashboards, and spaces across projects',
+        inputSchema: {
+            search: zod_1.z.string().describe('Search query'),
+            projectUuids: zod_1.z.array(zod_1.z.string()).optional().describe('Optional project UUIDs to filter'),
+            contentTypes: zod_1.z
+                .array(zod_1.z.enum(['chart', 'dashboard', 'space']))
+                .optional()
+                .describe('Optional content types to filter'),
+            page: zod_1.z.number().optional().describe('Page number'),
+            pageSize: zod_1.z.number().optional().describe('Page size'),
+        },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (params) => __awaiter(this, void 0, void 0, function* () {
+        const result = yield c.v2.content.searchContent(params);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+}

package/dist/tools/explores.js

@@ -27,7 +27,7 @@ function registerExploresTools(server, client) {
     })));
     (0, shared_js_1.registerToolSafe)(server, 'get_explore', {
         title: 'Get explore',
-        description: 'Get an explore by project UUID and explore ID',
+        description: 'Get an explore by project UUID and explore ID (includes tables, dimensions, and metrics)',
         inputSchema: {
             projectUuid: zod_1.z.string().describe('Project UUID'),
             exploreId: zod_1.z.string().describe('Explore ID'),
@@ -37,4 +37,29 @@ function registerExploresTools(server, client) {
         const explore = yield c.v1.explores.getExplore(projectUuid, exploreId);
         return { content: [{ type: 'text', text: JSON.stringify(explore, null, 2) }] };
     })));
+    (0, shared_js_1.registerToolSafe)(server, 'list_dimensions', {
+        title: 'List dimensions',
+        description: 'List all dimensions for a specific explore',
+        inputSchema: {
+            projectUuid: zod_1.z.string().describe('Project UUID'),
+            exploreId: zod_1.z.string().describe('Explore ID'),
+        },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ projectUuid, exploreId }) {
+        const result = yield c.v1.explores.listDimensions(projectUuid, exploreId);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+    (0, shared_js_1.registerToolSafe)(server, 'get_field_lineage', {
+        title: 'Get field lineage',
+        description: 'Get upstream lineage for a specific field in an explore',
+        inputSchema: {
+            projectUuid: zod_1.z.string().describe('Project UUID'),
+            exploreId: zod_1.z.string().describe('Explore ID'),
+            fieldId: zod_1.z.string().describe('Field ID'),
+        },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ projectUuid, exploreId, fieldId, }) {
+        const result = yield c.v1.explores.getFieldLineage(projectUuid, exploreId, fieldId);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
 }

package/dist/tools/index.js

@@ -12,6 +12,10 @@ const users_js_1 = require("./users.js");
 const groups_js_1 = require("./groups.js");
 const query_js_1 = require("./query.js");
 const explores_js_1 = require("./explores.js");
+const metrics_js_1 = require("./metrics.js");
+const schedulers_js_1 = require("./schedulers.js");
+const tags_js_1 = require("./tags.js");
+const content_js_1 = require("./content.js");
 function registerTools(server, client) {
     (0, projects_js_1.registerProjectTools)(server, client);
     (0, charts_js_1.registerChartTools)(server, client);
@@ -21,4 +25,8 @@ function registerTools(server, client) {
     (0, groups_js_1.registerGroupTools)(server, client);
     (0, query_js_1.registerQueryTools)(server, client);
     (0, explores_js_1.registerExploresTools)(server, client);
+    (0, metrics_js_1.registerMetricsTools)(server, client);
+    (0, schedulers_js_1.registerSchedulersTools)(server, client);
+    (0, tags_js_1.registerTagsTools)(server, client);
+    (0, content_js_1.registerContentTools)(server, client);
 }

package/dist/tools/metrics.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP tools: metrics (list, get).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+export declare function registerMetricsTools(server: McpServer, client: LightdashClient): void;

package/dist/tools/metrics.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * MCP tools: metrics (list, get).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMetricsTools = registerMetricsTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerMetricsTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'list_metrics', {
+        title: 'List metrics',
+        description: 'List metrics in a project data catalog',
+        inputSchema: {
+            projectUuid: zod_1.z.string().describe('Project UUID'),
+            search: zod_1.z.string().optional().describe('Search query'),
+            page: zod_1.z.number().optional().describe('Page number'),
+            pageSize: zod_1.z.number().optional().describe('Page size'),
+        },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, void 0, void 0, function* () {
+        var { projectUuid } = _a, params = __rest(_a, ["projectUuid"]);
+        const result = yield c.v1.metrics.listMetrics(projectUuid, params);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+}

package/dist/tools/projects.js

@@ -34,4 +34,25 @@ function registerProjectTools(server, client) {
         const project = yield c.v1.projects.getProject(projectUuid);
         return { content: [{ type: 'text', text: JSON.stringify(project, null, 2) }] };
     })));
+    (0, shared_js_1.registerToolSafe)(server, 'validate_project', {
+        title: 'Validate project',
+        description: 'Trigger a validation job for a project and return the job ID',
+        inputSchema: { projectUuid: zod_1.z.string().describe('Project UUID') },
+        annotations: shared_js_1.WRITE_IDEMPOTENT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ projectUuid }) {
+        const result = yield c.v1.validation.validateProject(projectUuid);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+    (0, shared_js_1.registerToolSafe)(server, 'get_validation_results', {
+        title: 'Get validation results',
+        description: 'Get the latest validation results for a project',
+        inputSchema: {
+            projectUuid: zod_1.z.string().describe('Project UUID'),
+            jobId: zod_1.z.string().optional().describe('Optional job ID to get results for'),
+        },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ projectUuid, jobId }) {
+        const result = yield c.v1.validation.getValidationResults(projectUuid, { jobId });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
 }

package/dist/tools/schedulers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP tools: schedulers (list, get).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+export declare function registerSchedulersTools(server: McpServer, client: LightdashClient): void;

package/dist/tools/schedulers.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * MCP tools: schedulers (list, get).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSchedulersTools = registerSchedulersTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerSchedulersTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'list_schedulers', {
+        title: 'List schedulers',
+        description: 'List scheduled deliveries in a project',
+        inputSchema: {
+            projectUuid: zod_1.z.string().describe('Project UUID'),
+            searchQuery: zod_1.z.string().optional().describe('Search query'),
+            page: zod_1.z.number().optional().describe('Page number'),
+            pageSize: zod_1.z.number().optional().describe('Page size'),
+        },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, void 0, void 0, function* () {
+        var { projectUuid } = _a, params = __rest(_a, ["projectUuid"]);
+        const result = yield c.v1.schedulers.listSchedulers(projectUuid, params);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+}

package/dist/tools/shared.d.ts

@@ -2,6 +2,7 @@
  * Shared types and helpers for MCP tool registration.
  */
 import type { LightdashClient } from '@lightdash-tools/client';
+import type { ToolAnnotations } from '@lightdash-tools/common';
 import type { z } from 'zod';
 /** Prefix for all MCP tool names (disambiguation when multiple servers are connected). */
 export declare const TOOL_PREFIX = "lightdash_tools__";
@@ -14,14 +15,6 @@ export type TextContent = {
 };
 /** Tool handler type used to avoid deep instantiation with SDK/Zod. Accepts (args, extra) for SDK compatibility. */
 export type ToolHandler = (args: unknown, extra?: unknown) => Promise<TextContent>;
-/** MCP tool annotations (hints for client display and approval). See MCP spec Tool annotations. */
-export type ToolAnnotations = {
-    title?: string;
-    readOnlyHint?: boolean;
-    destructiveHint?: boolean;
-    idempotentHint?: boolean;
-    openWorldHint?: boolean;
-};
 /** Options for registerTool; inputSchema typed as ZodRawShapeCompat for SDK compatibility. Pass annotations explicitly (e.g. READ_ONLY_DEFAULT or WRITE_IDEMPOTENT) for visibility. */
 export type ToolOptions = {
     description: string;
@@ -29,12 +22,7 @@ export type ToolOptions = {
     title?: string;
     annotations?: ToolAnnotations;
 };
-/** Preset: read-only, non-destructive, idempotent, closed-world. Use for list/get/compile tools. */
-export declare const READ_ONLY_DEFAULT: ToolAnnotations;
-/** Preset: write, non-destructive, idempotent (e.g. upsert by slug). Use for create/update tools. */
-export declare const WRITE_IDEMPOTENT: ToolAnnotations;
-/** Preset: write, destructive, non-idempotent. Use for delete/remove tools; clients should prompt for user confirmation. */
-export declare const WRITE_DESTRUCTIVE: 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). */
 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

@@ -15,32 +15,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WRITE_DESTRUCTIVE = exports.WRITE_IDEMPOTENT = exports.READ_ONLY_DEFAULT = exports.TOOL_PREFIX = void 0;
 exports.registerToolSafe = registerToolSafe;
 exports.wrapTool = wrapTool;
+const common_1 = require("@lightdash-tools/common");
 const errors_js_1 = require("../errors.js");
+const config_js_1 = require("../config.js");
 /** Prefix for all MCP tool names (disambiguation when multiple servers are connected). */
 exports.TOOL_PREFIX = 'lightdash_tools__';
-/** Preset: read-only, non-destructive, idempotent, closed-world. Use for list/get/compile tools. */
-exports.READ_ONLY_DEFAULT = {
-    readOnlyHint: true,
-    openWorldHint: false,
-    destructiveHint: false,
-    idempotentHint: true,
-};
-/** Preset: write, non-destructive, idempotent (e.g. upsert by slug). Use for create/update tools. */
-exports.WRITE_IDEMPOTENT = {
-    readOnlyHint: false,
-    openWorldHint: false,
-    destructiveHint: false,
-    idempotentHint: true,
-};
-/** Preset: write, destructive, non-idempotent. Use for delete/remove tools; clients should prompt for user confirmation. */
-exports.WRITE_DESTRUCTIVE = {
-    readOnlyHint: false,
-    openWorldHint: false,
-    destructiveHint: true,
-    idempotentHint: false,
-};
+// Re-export presets for convenience and backward compatibility in tools
+var common_2 = require("@lightdash-tools/common");
+Object.defineProperty(exports, "READ_ONLY_DEFAULT", { enumerable: true, get: function () { return common_2.READ_ONLY_DEFAULT; } });
+Object.defineProperty(exports, "WRITE_IDEMPOTENT", { enumerable: true, get: function () { return common_2.WRITE_IDEMPOTENT; } });
+Object.defineProperty(exports, "WRITE_DESTRUCTIVE", { enumerable: true, get: function () { return common_2.WRITE_DESTRUCTIVE; } });
 /** Internal default for mergeAnnotations; READ_ONLY_DEFAULT is the exported preset. */
-const DEFAULT_ANNOTATIONS = exports.READ_ONLY_DEFAULT;
+const DEFAULT_ANNOTATIONS = common_1.READ_ONLY_DEFAULT;
 /** Merges per-tool annotations with defaults; per-tool values win. */
 function mergeAnnotations(overrides) {
     return Object.assign(Object.assign({}, DEFAULT_ANNOTATIONS), overrides);
@@ -50,8 +36,33 @@ function registerToolSafe(server, shortName, options, handler) {
     var _a, _b;
     const name = exports.TOOL_PREFIX + shortName;
     const annotations = mergeAnnotations(options.annotations);
-    const mergedOptions = Object.assign(Object.assign({}, options), { 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, handler);
+    // Static Filtering: Skip registration if not allowed in 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)
+    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
+    let finalHandler = handler;
+    let finalDescription = options.description;
+    if (!isToolAllowed) {
+        finalDescription = `[DISABLED in ${mode} mode] ${options.description}`;
+        finalHandler = () => __awaiter(this, void 0, void 0, function* () {
+            return ({
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: Tool '${name}' is disabled in ${mode} mode. To enable it, change LIGHTDASH_TOOL_SAFETY_MODE.`,
+                    },
+                ],
+                isError: true,
+            });
+        });
+    }
+    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);
 }
 function wrapTool(client, fn) {
     const handler = fn(client);

package/dist/tools/shared.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/shared.test.js

@@ -0,0 +1,96 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const shared_1 = require("./shared");
+const common_1 = require("@lightdash-tools/common");
+const config_js_1 = require("../config.js");
+(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.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, shared_1.registerToolSafe)(mockServer, 'test_tool', {
+            description: 'Test description',
+            inputSchema: {},
+            annotations: shared_1.READ_ONLY_DEFAULT,
+        }, mockHandler);
+        (0, vitest_1.expect)(mockServer.registerTool).toHaveBeenCalled();
+        const [name, options, handler] = mockServer.registerTool.mock.calls[0];
+        (0, vitest_1.expect)(name).toContain('test_tool');
+        (0, vitest_1.expect)(options.description).toBe('Test description');
+        const result = yield handler({});
+        (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;
+        (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];
+        (0, vitest_1.expect)(options.description).toContain('[DISABLED in read-only mode]');
+        const result = yield handler({});
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (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;
+        (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];
+        (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', {
+                description: 'Destructive',
+                inputSchema: {},
+                annotations: shared_1.WRITE_DESTRUCTIVE,
+            }, mockHandler);
+            (0, vitest_1.expect)(mockServer.registerTool).not.toHaveBeenCalled();
+        });
+        (0, vitest_1.it)('should allow registration if tool matches binded mode', () => {
+            (0, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.READ_ONLY);
+            mockServer.registerTool.mockClear();
+            (0, shared_1.registerToolSafe)(mockServer, 'readonly_tool_static', {
+                description: 'Read-only',
+                inputSchema: {},
+                annotations: shared_1.READ_ONLY_DEFAULT,
+            }, 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, config_js_1.setStaticSafetyMode)(common_1.SafetyMode.WRITE_DESTRUCTIVE);
+            mockServer.registerTool.mockClear();
+            (0, shared_1.registerToolSafe)(mockServer, 'any_tool_static', {
+                description: 'Any',
+                inputSchema: {},
+                annotations: shared_1.WRITE_DESTRUCTIVE,
+            }, mockHandler);
+            (0, vitest_1.expect)(mockServer.registerTool).toHaveBeenCalled();
+        });
+    });
+});

package/dist/tools/tags.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP tools: tags (list).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+export declare function registerTagsTools(server: McpServer, client: LightdashClient): void;