@lightdash-tools/mcp 0.1.2 → 0.2.1

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.
 
@@ -64,7 +64,7 @@ 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`.
+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`, `list_metrics`, `list_schedulers`, `list_tags`, `search_content`.
 
 ### Destructive tools
 

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,17 @@ 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");
 /** 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 +35,27 @@ 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);
+    const mode = (0, common_1.getSafetyModeFromEnv)();
+    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_AI_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,59 @@
+"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");
+(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_AI_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_AI_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_AI_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');
+    }));
+});

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;

package/dist/tools/tags.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * MCP tools: tags (list).
+ */
+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.registerTagsTools = registerTagsTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerTagsTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'list_tags', {
+        title: 'List tags',
+        description: 'List all tags in a project',
+        inputSchema: { projectUuid: zod_1.z.string().describe('Project UUID') },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ projectUuid }) {
+        const result = yield c.v1.tags.listTags(projectUuid);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+}

package/package.json

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

package/src/tools/content.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP tools: content (search).
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+import { z } from 'zod';
+import { wrapTool, registerToolSafe, READ_ONLY_DEFAULT } from './shared.js';
+
+export function registerContentTools(server: McpServer, client: LightdashClient): void {
+  registerToolSafe(
+    server,
+    'search_content',
+    {
+      title: 'Search content',
+      description: 'Search for charts, dashboards, and spaces across projects',
+      inputSchema: {
+        search: z.string().describe('Search query'),
+        projectUuids: z.array(z.string()).optional().describe('Optional project UUIDs to filter'),
+        contentTypes: z
+          .array(z.enum(['chart', 'dashboard', 'space']))
+          .optional()
+          .describe('Optional content types to filter'),
+        page: z.number().optional().describe('Page number'),
+        pageSize: z.number().optional().describe('Page size'),
+      },
+      annotations: READ_ONLY_DEFAULT,
+    },
+    wrapTool(
+      client,
+      (c) =>
+        async (params: {
+          search: string;
+          projectUuids?: string[];
+          contentTypes?: ('chart' | 'dashboard' | 'space')[];
+          page?: number;
+          pageSize?: number;
+        }) => {
+          const result = await c.v2.content.searchContent(params);
+          return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        },
+    ),
+  );
+}

package/src/tools/explores.ts

@@ -27,7 +27,8 @@ export function registerExploresTools(server: McpServer, client: LightdashClient
     '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: z.string().describe('Project UUID'),
         exploreId: z.string().describe('Explore ID'),
@@ -43,4 +44,55 @@ export function registerExploresTools(server: McpServer, client: LightdashClient
         },
     ),
   );
+  registerToolSafe(
+    server,
+    'list_dimensions',
+    {
+      title: 'List dimensions',
+      description: 'List all dimensions for a specific explore',
+      inputSchema: {
+        projectUuid: z.string().describe('Project UUID'),
+        exploreId: z.string().describe('Explore ID'),
+      },
+      annotations: READ_ONLY_DEFAULT,
+    },
+    wrapTool(
+      client,
+      (c) =>
+        async ({ projectUuid, exploreId }: { projectUuid: string; exploreId: string }) => {
+          const result = await c.v1.explores.listDimensions(projectUuid, exploreId);
+          return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        },
+    ),
+  );
+  registerToolSafe(
+    server,
+    'get_field_lineage',
+    {
+      title: 'Get field lineage',
+      description: 'Get upstream lineage for a specific field in an explore',
+      inputSchema: {
+        projectUuid: z.string().describe('Project UUID'),
+        exploreId: z.string().describe('Explore ID'),
+        fieldId: z.string().describe('Field ID'),
+      },
+      annotations: READ_ONLY_DEFAULT,
+    },
+    wrapTool(
+      client,
+      (c) =>
+        async ({
+          projectUuid,
+          exploreId,
+          fieldId,
+        }: {
+          projectUuid: string;
+          exploreId: string;
+          fieldId: string;
+        }) => {
+          const result = await c.v1.explores.getFieldLineage(projectUuid, exploreId, fieldId);
+          return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        },
+    ),
+  );
 }

package/src/tools/index.ts

@@ -12,6 +12,10 @@ import { registerUserTools } from './users.js';
 import { registerGroupTools } from './groups.js';
 import { registerQueryTools } from './query.js';
 import { registerExploresTools } from './explores.js';
+import { registerMetricsTools } from './metrics.js';
+import { registerSchedulersTools } from './schedulers.js';
+import { registerTagsTools } from './tags.js';
+import { registerContentTools } from './content.js';
 
 export function registerTools(server: McpServer, client: LightdashClient): void {
   registerProjectTools(server, client);
@@ -22,4 +26,8 @@ export function registerTools(server: McpServer, client: LightdashClient): void
   registerGroupTools(server, client);
   registerQueryTools(server, client);
   registerExploresTools(server, client);
+  registerMetricsTools(server, client);
+  registerSchedulersTools(server, client);
+  registerTagsTools(server, client);
+  registerContentTools(server, client);
 }

package/src/tools/metrics.ts

@@ -0,0 +1,42 @@
+/**
+ * MCP tools: metrics (list, get).
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+import { z } from 'zod';
+import { wrapTool, registerToolSafe, READ_ONLY_DEFAULT } from './shared.js';
+
+export function registerMetricsTools(server: McpServer, client: LightdashClient): void {
+  registerToolSafe(
+    server,
+    'list_metrics',
+    {
+      title: 'List metrics',
+      description: 'List metrics in a project data catalog',
+      inputSchema: {
+        projectUuid: z.string().describe('Project UUID'),
+        search: z.string().optional().describe('Search query'),
+        page: z.number().optional().describe('Page number'),
+        pageSize: z.number().optional().describe('Page size'),
+      },
+      annotations: READ_ONLY_DEFAULT,
+    },
+    wrapTool(
+      client,
+      (c) =>
+        async ({
+          projectUuid,
+          ...params
+        }: {
+          projectUuid: string;
+          search?: string;
+          page?: number;
+          pageSize?: number;
+        }) => {
+          const result = await c.v1.metrics.listMetrics(projectUuid, params);
+          return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        },
+    ),
+  );
+}

package/src/tools/projects.ts

@@ -5,7 +5,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { LightdashClient } from '@lightdash-tools/client';
 import { z } from 'zod';
-import { wrapTool, registerToolSafe, READ_ONLY_DEFAULT } from './shared.js';
+import { wrapTool, registerToolSafe, READ_ONLY_DEFAULT, WRITE_IDEMPOTENT } from './shared.js';
 
 export function registerProjectTools(server: McpServer, client: LightdashClient): void {
   registerToolSafe(
@@ -36,4 +36,39 @@ export function registerProjectTools(server: McpServer, client: LightdashClient)
       return { content: [{ type: 'text', text: JSON.stringify(project, null, 2) }] };
     }),
   );
+  registerToolSafe(
+    server,
+    'validate_project',
+    {
+      title: 'Validate project',
+      description: 'Trigger a validation job for a project and return the job ID',
+      inputSchema: { projectUuid: z.string().describe('Project UUID') },
+      annotations: WRITE_IDEMPOTENT,
+    },
+    wrapTool(client, (c) => async ({ projectUuid }: { projectUuid: string }) => {
+      const result = await c.v1.validation.validateProject(projectUuid);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }),
+  );
+  registerToolSafe(
+    server,
+    'get_validation_results',
+    {
+      title: 'Get validation results',
+      description: 'Get the latest validation results for a project',
+      inputSchema: {
+        projectUuid: z.string().describe('Project UUID'),
+        jobId: z.string().optional().describe('Optional job ID to get results for'),
+      },
+      annotations: READ_ONLY_DEFAULT,
+    },
+    wrapTool(
+      client,
+      (c) =>
+        async ({ projectUuid, jobId }: { projectUuid: string; jobId?: string }) => {
+          const result = await c.v1.validation.getValidationResults(projectUuid, { jobId });
+          return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        },
+    ),
+  );
 }

package/src/tools/schedulers.ts

@@ -0,0 +1,42 @@
+/**
+ * MCP tools: schedulers (list, get).
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+import { z } from 'zod';
+import { wrapTool, registerToolSafe, READ_ONLY_DEFAULT } from './shared.js';
+
+export function registerSchedulersTools(server: McpServer, client: LightdashClient): void {
+  registerToolSafe(
+    server,
+    'list_schedulers',
+    {
+      title: 'List schedulers',
+      description: 'List scheduled deliveries in a project',
+      inputSchema: {
+        projectUuid: z.string().describe('Project UUID'),
+        searchQuery: z.string().optional().describe('Search query'),
+        page: z.number().optional().describe('Page number'),
+        pageSize: z.number().optional().describe('Page size'),
+      },
+      annotations: READ_ONLY_DEFAULT,
+    },
+    wrapTool(
+      client,
+      (c) =>
+        async ({
+          projectUuid,
+          ...params
+        }: {
+          projectUuid: string;
+          searchQuery?: string;
+          page?: number;
+          pageSize?: number;
+        }) => {
+          const result = await c.v1.schedulers.listSchedulers(projectUuid, params);
+          return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        },
+    ),
+  );
+}

package/src/tools/shared.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi } from 'vitest';
+import { registerToolSafe, READ_ONLY_DEFAULT, WRITE_DESTRUCTIVE } from './shared';
+import { SafetyMode } from '@lightdash-tools/common';
+
+describe('registerToolSafe', () => {
+  const mockServer = {
+    registerTool: vi.fn(),
+  };
+
+  const mockHandler = vi.fn().mockResolvedValue({ content: [{ type: 'text', text: 'success' }] });
+
+  it('should allow read-only tool in read-only mode', async () => {
+    process.env.LIGHTDASH_AI_MODE = SafetyMode.READ_ONLY;
+
+    registerToolSafe(
+      mockServer,
+      'test_tool',
+      {
+        description: 'Test description',
+        inputSchema: {},
+        annotations: READ_ONLY_DEFAULT,
+      },
+      mockHandler,
+    );
+
+    expect(mockServer.registerTool).toHaveBeenCalled();
+    const [name, options, handler] = mockServer.registerTool.mock.calls[0];
+
+    expect(name).toContain('test_tool');
+    expect(options.description).toBe('Test description');
+
+    const result = await handler({});
+    expect(result.content[0].text).toBe('success');
+  });
+
+  it('should block destructive tool in read-only mode', async () => {
+    process.env.LIGHTDASH_AI_MODE = SafetyMode.READ_ONLY;
+
+    registerToolSafe(
+      mockServer,
+      'delete_tool',
+      {
+        description: 'Delete something',
+        inputSchema: {},
+        annotations: WRITE_DESTRUCTIVE,
+      },
+      mockHandler,
+    );
+
+    const [, options, handler] = mockServer.registerTool.mock.calls[1];
+
+    expect(options.description).toContain('[DISABLED in read-only mode]');
+
+    const result = await handler({});
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('disabled in read-only mode');
+  });
+
+  it('should allow destructive tool in write-destructive mode', async () => {
+    process.env.LIGHTDASH_AI_MODE = SafetyMode.WRITE_DESTRUCTIVE;
+
+    registerToolSafe(
+      mockServer,
+      'delete_tool_2',
+      {
+        description: 'Delete something 2',
+        inputSchema: {},
+        annotations: WRITE_DESTRUCTIVE,
+      },
+      mockHandler,
+    );
+
+    const [, options, handler] = mockServer.registerTool.mock.calls[2];
+
+    expect(options.description).toBe('Delete something 2');
+
+    const result = await handler({});
+    expect(result.content[0].text).toBe('success');
+  });
+});

package/src/tools/shared.ts

@@ -3,6 +3,8 @@
  */
 
 import type { LightdashClient } from '@lightdash-tools/client';
+import { isAllowed, getSafetyModeFromEnv, READ_ONLY_DEFAULT } from '@lightdash-tools/common';
+import type { ToolAnnotations } from '@lightdash-tools/common';
 import type { z } from 'zod';
 import { toMcpErrorMessage } from '../errors.js';
 
@@ -17,15 +19,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;
@@ -34,29 +27,8 @@ export type ToolOptions = {
   annotations?: ToolAnnotations;
 };
 
-/** Preset: read-only, non-destructive, idempotent, closed-world. Use for list/get/compile tools. */
-export const READ_ONLY_DEFAULT: ToolAnnotations = {
-  readOnlyHint: true,
-  openWorldHint: false,
-  destructiveHint: false,
-  idempotentHint: true,
-};
-
-/** Preset: write, non-destructive, idempotent (e.g. upsert by slug). Use for create/update tools. */
-export const WRITE_IDEMPOTENT: ToolAnnotations = {
-  readOnlyHint: false,
-  openWorldHint: false,
-  destructiveHint: false,
-  idempotentHint: true,
-};
-
-/** Preset: write, destructive, non-idempotent. Use for delete/remove tools; clients should prompt for user confirmation. */
-export const WRITE_DESTRUCTIVE: ToolAnnotations = {
-  readOnlyHint: false,
-  openWorldHint: false,
-  destructiveHint: true,
-  idempotentHint: false,
-};
+// Re-export presets for convenience and backward compatibility in tools
+export { READ_ONLY_DEFAULT, WRITE_IDEMPOTENT, WRITE_DESTRUCTIVE } from '@lightdash-tools/common';
 
 /** Internal default for mergeAnnotations; READ_ONLY_DEFAULT is the exported preset. */
 const DEFAULT_ANNOTATIONS: ToolAnnotations = READ_ONLY_DEFAULT;
@@ -77,12 +49,34 @@ export function registerToolSafe(
 ): void {
   const name = TOOL_PREFIX + shortName;
   const annotations = mergeAnnotations(options.annotations);
+  const mode = getSafetyModeFromEnv();
+
+  const isToolAllowed = 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 = async () => ({
+      content: [
+        {
+          type: 'text',
+          text: `Error: Tool '${name}' is disabled in ${mode} mode. To enable it, change LIGHTDASH_AI_MODE.`,
+        },
+      ],
+      isError: true,
+    });
+  }
+
   const mergedOptions: ToolOptions = {
     ...options,
+    description: finalDescription,
     title: options.title ?? options.annotations?.title,
     annotations,
   };
-  (server as { registerTool: RegisterToolFn }).registerTool(name, mergedOptions, handler);
+  (server as { registerTool: RegisterToolFn }).registerTool(name, mergedOptions, finalHandler);
 }
 
 export function wrapTool<T>(

package/src/tools/tags.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP tools: tags (list).
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+import { z } from 'zod';
+import { wrapTool, registerToolSafe, READ_ONLY_DEFAULT } from './shared.js';
+
+export function registerTagsTools(server: McpServer, client: LightdashClient): void {
+  registerToolSafe(
+    server,
+    'list_tags',
+    {
+      title: 'List tags',
+      description: 'List all tags in a project',
+      inputSchema: { projectUuid: z.string().describe('Project UUID') },
+      annotations: READ_ONLY_DEFAULT,
+    },
+    wrapTool(client, (c) => async ({ projectUuid }: { projectUuid: string }) => {
+      const result = await c.v1.tags.listTags(projectUuid);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }),
+  );
+}