@lightdash-tools/mcp 0.1.1 → 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,12 +64,32 @@ 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
 
 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.
 
+## 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.
+
+### Running unit tests
+
+```bash
+pnpm test
+```
+
+### Running integration tests
+
+To run tests against a real Lightdash instance, provide your credentials:
+
+```bash
+LIGHTDASH_URL=https://app.lightdash.cloud LIGHTDASH_API_KEY=your_api_key pnpm test
+```
+
+The integration tests will automatically detect these environment variables and run additional scenarios, such as verifying authentication and tool execution against the live API.
+
 ## License
 
 Apache-2.0

package/dist/bin.js

@@ -38,8 +38,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 const args = process.argv.slice(2);
 if (args.includes('--http')) {
-    Promise.resolve().then(() => __importStar(require('./http.js')));
+    void Promise.resolve().then(() => __importStar(require('./http.js')));
 }
 else {
-    Promise.resolve().then(() => __importStar(require('./index.js')));
+    void Promise.resolve().then(() => __importStar(require('./index.js')));
 }

package/dist/index.integration.test.d.ts

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

package/dist/index.integration.test.js

@@ -0,0 +1,58 @@
+"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 mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const inMemory_js_1 = require("@modelcontextprotocol/sdk/inMemory.js");
+const config_1 = require("./config");
+const tools_1 = require("./tools");
+const shared_1 = require("./tools/shared");
+const hasCredentials = !!process.env.LIGHTDASH_API_KEY && !!process.env.LIGHTDASH_URL;
+vitest_1.describe.runIf(hasCredentials)('MCP Integration (Real API)', () => {
+    (0, vitest_1.it)('should authenticate and fetch current organization', () => __awaiter(void 0, void 0, void 0, function* () {
+        const client = (0, config_1.getClient)();
+        // getCurrentOrganization is a better test for connectivity
+        const org = yield client.v1.organizations.getCurrentOrganization();
+        (0, vitest_1.expect)(org).toBeDefined();
+        (0, vitest_1.expect)(org.organizationUuid).toBeDefined();
+        (0, vitest_1.expect)(org.name).toBeDefined();
+        console.error(`Authenticated to organization: ${org.name}`);
+    }));
+    (0, vitest_1.it)('should execute list_projects tool with real API', () => __awaiter(void 0, void 0, void 0, function* () {
+        const client = (0, config_1.getClient)();
+        const server = new mcp_js_1.McpServer({ name: 'test-server', version: '1.0.0' });
+        (0, tools_1.registerTools)(server, client);
+        const [serverTransport, clientTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+        yield server.connect(serverTransport);
+        const mcpClient = new index_js_1.Client({ name: 'test-client', version: '1.0.0' }, { capabilities: {} });
+        yield mcpClient.connect(clientTransport);
+        // Call the tool through the MCP client
+        const result = yield mcpClient.callTool({
+            name: shared_1.TOOL_PREFIX + 'list_projects',
+            arguments: {},
+        });
+        if (result.isError) {
+            console.error('Tool execution failed:', result.content);
+        }
+        (0, vitest_1.expect)(result).toBeDefined();
+        (0, vitest_1.expect)(result.isError).toBeFalsy();
+        (0, vitest_1.expect)(Array.isArray(result.content)).toBe(true);
+        const content = result.content;
+        const textContent = content[0];
+        if (textContent && 'text' in textContent) {
+            (0, vitest_1.expect)(typeof textContent.text).toBe('string');
+            console.error(`Tool list_projects output: ${textContent.text.slice(0, 100)}...`);
+        }
+        yield mcpClient.close();
+        yield server.close();
+    }));
+});

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__";
@@ -10,17 +11,10 @@ export type TextContent = {
         type: 'text';
         text: string;
     }>;
+    isError?: boolean;
 };
 /** 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;
@@ -28,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);
@@ -62,7 +66,7 @@ function wrapTool(client, fn) {
         }
         catch (err) {
             const text = (0, errors_js_1.toMcpErrorMessage)(err);
-            return { content: [{ type: 'text', text }] };
+            return { content: [{ type: 'text', text }], isError: true };
         }
     });
 }

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.1",
+  "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.1"
+    "@lightdash-tools/client": "0.2.1",
+    "@lightdash-tools/common": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^25.2.3"

package/src/bin.ts

@@ -6,7 +6,7 @@
 const args = process.argv.slice(2);
 
 if (args.includes('--http')) {
-  import('./http.js');
+  void import('./http.js');
 } else {
-  import('./index.js');
+  void import('./index.js');
 }

package/src/index.integration.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { getClient } from './config';
+import { registerTools } from './tools';
+import { TOOL_PREFIX } from './tools/shared';
+
+const hasCredentials = !!process.env.LIGHTDASH_API_KEY && !!process.env.LIGHTDASH_URL;
+
+describe.runIf(hasCredentials)('MCP Integration (Real API)', () => {
+  it('should authenticate and fetch current organization', async () => {
+    const client = getClient();
+    // getCurrentOrganization is a better test for connectivity
+    const org = await client.v1.organizations.getCurrentOrganization();
+    expect(org).toBeDefined();
+    expect(org.organizationUuid).toBeDefined();
+    expect(org.name).toBeDefined();
+    console.error(`Authenticated to organization: ${org.name}`);
+  });
+
+  it('should execute list_projects tool with real API', async () => {
+    const client = getClient();
+    const server = new McpServer({ name: 'test-server', version: '1.0.0' });
+    registerTools(server, client);
+
+    const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
+
+    await server.connect(serverTransport);
+
+    const mcpClient = new Client({ name: 'test-client', version: '1.0.0' }, { capabilities: {} });
+    await mcpClient.connect(clientTransport);
+
+    // Call the tool through the MCP client
+    const result = await mcpClient.callTool({
+      name: TOOL_PREFIX + 'list_projects',
+      arguments: {},
+    });
+
+    if (result.isError) {
+      console.error('Tool execution failed:', result.content);
+    }
+    expect(result).toBeDefined();
+    expect(result.isError).toBeFalsy();
+    expect(Array.isArray(result.content)).toBe(true);
+    const content = result.content as { text: string }[];
+
+    const textContent = content[0];
+    if (textContent && 'text' in textContent) {
+      expect(typeof textContent.text).toBe('string');
+      console.error(`Tool list_projects output: ${textContent.text.slice(0, 100)}...`);
+    }
+
+    await mcpClient.close();
+    await server.close();
+  });
+});

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';
 
@@ -11,20 +13,12 @@ export const TOOL_PREFIX = 'lightdash_tools__';
 
 export type TextContent = {
   content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
 };
 
 /** 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;
@@ -33,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;
@@ -76,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>(
@@ -95,7 +90,7 @@ export function wrapTool<T>(
       return await handler(args as T);
     } catch (err) {
       const text = toMcpErrorMessage(err);
-      return { content: [{ type: 'text', text }] };
+      return { content: [{ type: 'text', text }], isError: true };
     }
   };
 }

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) }] };
+    }),
+  );
+}