@lightdash-tools/mcp 0.1.0

package/dist/tools/explores.d.ts

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

package/dist/tools/explores.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * MCP tools: explores (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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExploresTools = registerExploresTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerExploresTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'list_explores', {
+        title: 'List explores',
+        description: 'List all explores 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 explores = yield c.v1.explores.listExplores(projectUuid);
+        return { content: [{ type: 'text', text: JSON.stringify(explores, null, 2) }] };
+    })));
+    (0, shared_js_1.registerToolSafe)(server, 'get_explore', {
+        title: 'Get explore',
+        description: 'Get an explore by project UUID and explore ID',
+        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 explore = yield c.v1.explores.getExplore(projectUuid, exploreId);
+        return { content: [{ type: 'text', text: JSON.stringify(explore, null, 2) }] };
+    })));
+}

package/dist/tools/groups.d.ts

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

package/dist/tools/groups.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * MCP tools: groups (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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerGroupTools = registerGroupTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerGroupTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'list_groups', {
+        title: 'List groups',
+        description: 'List organization groups (one page)',
+        inputSchema: {
+            page: zod_1.z.number().optional().describe('Page number'),
+            pageSize: zod_1.z.number().optional().describe('Page size'),
+            searchQuery: zod_1.z.string().optional().describe('Search query'),
+        },
+        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.v1.groups.listGroups(params !== null && params !== void 0 ? params : {});
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+    (0, shared_js_1.registerToolSafe)(server, 'get_group', {
+        title: 'Get group',
+        description: 'Get a group by UUID',
+        inputSchema: { groupUuid: zod_1.z.string().describe('Group UUID') },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ groupUuid }) {
+        const group = yield c.v1.groups.getGroup(groupUuid);
+        return { content: [{ type: 'text', text: JSON.stringify(group, null, 2) }] };
+    })));
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP tool registration: barrel that delegates to domain modules.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LightdashClient } from '@lightdash-tools/client';
+export declare function registerTools(server: McpServer, client: LightdashClient): void;

package/dist/tools/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * MCP tool registration: barrel that delegates to domain modules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTools = registerTools;
+const projects_js_1 = require("./projects.js");
+const charts_js_1 = require("./charts.js");
+const dashboards_js_1 = require("./dashboards.js");
+const spaces_js_1 = require("./spaces.js");
+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");
+function registerTools(server, client) {
+    (0, projects_js_1.registerProjectTools)(server, client);
+    (0, charts_js_1.registerChartTools)(server, client);
+    (0, dashboards_js_1.registerDashboardTools)(server, client);
+    (0, spaces_js_1.registerSpaceTools)(server, client);
+    (0, users_js_1.registerUserTools)(server, client);
+    (0, groups_js_1.registerGroupTools)(server, client);
+    (0, query_js_1.registerQueryTools)(server, client);
+    (0, explores_js_1.registerExploresTools)(server, client);
+}

package/dist/tools/projects.d.ts

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

package/dist/tools/projects.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * MCP tools: projects (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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerProjectTools = registerProjectTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerProjectTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'list_projects', {
+        title: 'List projects',
+        description: 'List all projects in the current organization',
+        inputSchema: {},
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, () => () => __awaiter(this, void 0, void 0, function* () {
+        const projects = yield client.v1.projects.listProjects();
+        return { content: [{ type: 'text', text: JSON.stringify(projects, null, 2) }] };
+    })));
+    (0, shared_js_1.registerToolSafe)(server, 'get_project', {
+        title: 'Get project',
+        description: 'Get a project by UUID',
+        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 project = yield c.v1.projects.getProject(projectUuid);
+        return { content: [{ type: 'text', text: JSON.stringify(project, null, 2) }] };
+    })));
+}

package/dist/tools/query.d.ts

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

package/dist/tools/query.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * MCP tools: query (compile).
+ */
+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.registerQueryTools = registerQueryTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerQueryTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'compile_query', {
+        title: 'Compile query',
+        description: 'Compile a metric query for an explore without executing it',
+        inputSchema: {
+            projectUuid: zod_1.z.string().describe('Project UUID'),
+            exploreId: zod_1.z.string().describe('Explore ID'),
+            metricQuery: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.unknown())
+                .describe('Metric query object (dimensions, metrics, filters, etc.)'),
+        },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ projectUuid, exploreId, metricQuery, }) {
+        const result = yield c.v1.query.compileQuery(projectUuid, exploreId, metricQuery);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared types and helpers for MCP tool registration.
+ */
+import type { LightdashClient } from '@lightdash-tools/client';
+import type { z } from 'zod';
+/** Prefix for all MCP tool names (disambiguation when multiple servers are connected). */
+export declare const TOOL_PREFIX = "lightdash_tools__";
+export type TextContent = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/** 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;
+    inputSchema: Record<string, z.ZodTypeAny>;
+    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;
+/** 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

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Shared types and helpers for MCP tool registration.
+ */
+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.WRITE_DESTRUCTIVE = exports.WRITE_IDEMPOTENT = exports.READ_ONLY_DEFAULT = exports.TOOL_PREFIX = void 0;
+exports.registerToolSafe = registerToolSafe;
+exports.wrapTool = wrapTool;
+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,
+};
+/** Internal default for mergeAnnotations; READ_ONLY_DEFAULT is the exported preset. */
+const DEFAULT_ANNOTATIONS = exports.READ_ONLY_DEFAULT;
+/** Merges per-tool annotations with defaults; per-tool values win. */
+function mergeAnnotations(overrides) {
+    return Object.assign(Object.assign({}, DEFAULT_ANNOTATIONS), overrides);
+}
+/** Registers a tool with prefix and annotations. shortName is TOOL_PREFIX + shortName. Pass annotations explicitly (e.g. READ_ONLY_DEFAULT, WRITE_IDEMPOTENT, or WRITE_DESTRUCTIVE). */
+function 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);
+}
+function wrapTool(client, fn) {
+    const handler = fn(client);
+    return (args, extra) => __awaiter(this, void 0, void 0, function* () {
+        void extra;
+        try {
+            return yield handler(args);
+        }
+        catch (err) {
+            const text = (0, errors_js_1.toMcpErrorMessage)(err);
+            return { content: [{ type: 'text', text }] };
+        }
+    });
+}

package/dist/tools/spaces.d.ts

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

package/dist/tools/spaces.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * MCP tools: spaces (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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSpaceTools = registerSpaceTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerSpaceTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'list_spaces', {
+        title: 'List spaces',
+        description: 'List spaces 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 spaces = yield c.v1.spaces.listSpacesInProject(projectUuid);
+        return { content: [{ type: 'text', text: JSON.stringify(spaces, null, 2) }] };
+    })));
+    (0, shared_js_1.registerToolSafe)(server, 'get_space', {
+        title: 'Get space',
+        description: 'Get a space by project and space UUID',
+        inputSchema: {
+            projectUuid: zod_1.z.string().describe('Project UUID'),
+            spaceUuid: zod_1.z.string().describe('Space UUID'),
+        },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ projectUuid, spaceUuid }) {
+        const space = yield c.v1.spaces.getSpace(projectUuid, spaceUuid);
+        return { content: [{ type: 'text', text: JSON.stringify(space, null, 2) }] };
+    })));
+}

package/dist/tools/users.d.ts

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

package/dist/tools/users.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * MCP tools: users / organization members (list, get, delete).
+ */
+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.registerUserTools = registerUserTools;
+const zod_1 = require("zod");
+const shared_js_1 = require("./shared.js");
+function registerUserTools(server, client) {
+    (0, shared_js_1.registerToolSafe)(server, 'list_organization_members', {
+        title: 'List organization members',
+        description: 'List organization members (one page)',
+        inputSchema: {
+            page: zod_1.z.number().optional().describe('Page number'),
+            pageSize: zod_1.z.number().optional().describe('Page size'),
+            searchQuery: zod_1.z.string().optional().describe('Search query'),
+        },
+        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.v1.users.listMembers(params !== null && params !== void 0 ? params : {});
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    })));
+    (0, shared_js_1.registerToolSafe)(server, 'get_member', {
+        title: 'Get member',
+        description: 'Get an organization member by UUID',
+        inputSchema: { userUuid: zod_1.z.string().describe('User UUID') },
+        annotations: shared_js_1.READ_ONLY_DEFAULT,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ userUuid }) {
+        const member = yield c.v1.users.getMemberByUuid(userUuid);
+        return { content: [{ type: 'text', text: JSON.stringify(member, null, 2) }] };
+    })));
+    (0, shared_js_1.registerToolSafe)(server, 'delete_member', {
+        title: 'Delete member (destructive)',
+        description: 'Permanently remove a user from the organization. Destructive; clients and agents should obtain explicit user confirmation before calling.',
+        inputSchema: { userUuid: zod_1.z.string().describe('User UUID') },
+        annotations: shared_js_1.WRITE_DESTRUCTIVE,
+    }, (0, shared_js_1.wrapTool)(client, (c) => (_a) => __awaiter(this, [_a], void 0, function* ({ userUuid }) {
+        yield c.v1.users.deleteMember(userUuid);
+        return { content: [{ type: 'text', text: 'Member deleted.' }] };
+    })));
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lightdash-tools/mcp",
+  "version": "0.1.0",
+  "description": "MCP server and utilities for Lightdash AI.",
+  "keywords": [],
+  "license": "ISC",
+  "author": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6",
+    "@lightdash-tools/client": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js"
+  }
+}

package/src/config.ts

@@ -0,0 +1,16 @@
+/**
+ * MCP server config: build Lightdash client config from environment.
+ * Uses same env vars as CLI: LIGHTDASH_URL, LIGHTDASH_API_KEY.
+ */
+
+import { LightdashClient, mergeConfig } from '@lightdash-tools/client';
+import type { PartialLightdashClientConfig } from '@lightdash-tools/client';
+
+/**
+ * Builds a LightdashClient from environment variables (and optional overrides).
+ * Throws if LIGHTDASH_URL or LIGHTDASH_API_KEY are missing.
+ */
+export function getClient(config?: PartialLightdashClientConfig): LightdashClient {
+  const merged = mergeConfig(config);
+  return new LightdashClient(merged);
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+/**
+ * Map Lightdash client errors to safe user-facing messages for MCP responses.
+ * Never expose stack traces or tokens.
+ */
+
+import { LightdashApiError, RateLimitError, NetworkError } from '@lightdash-tools/client';
+
+/**
+ * Returns a short, safe message for MCP content from a client error.
+ */
+export function toMcpErrorMessage(err: unknown): string {
+  if (err instanceof RateLimitError) {
+    const after = err.retryAfter != null ? ` Retry after ${err.retryAfter}s.` : '';
+    return `Rate limited (${err.statusCode}).${after}`;
+  }
+  if (err instanceof LightdashApiError) {
+    const msg = err.error?.message ?? `HTTP ${err.statusCode}`;
+    return `Lightdash API error: ${msg}`;
+  }
+  if (err instanceof NetworkError) {
+    return `Network error: ${err.message}`;
+  }
+  if (err instanceof Error) {
+    return err.message || 'Unknown error';
+  }
+  return String(err);
+}