@outsidedata/dolex 0.1.0

package/src/mcp/tools/screenshot.ts

@@ -0,0 +1,99 @@
+/**
+ * MCP Tool: screenshot
+ * Renders a visualization to PNG via headless Chromium (Playwright).
+ * Returns a base64-encoded image that Claude can see directly.
+ *
+ * Requires: npm install playwright && npx playwright install chromium
+ */
+
+import { z } from 'zod';
+import { isCompoundSpec } from '../../types.js';
+import { buildChartHtml, isHtmlPatternSupported } from '../../renderers/html/index.js';
+import { buildCompoundHtml } from '../../renderers/html/builders/compound.js';
+import { specStore } from '../spec-store.js';
+import { errorResponse } from './shared.js';
+
+export const screenshotInputSchema = z.object({
+  specId: z.string().describe('Spec ID from a previous visualize, visualize_from_source, or refine call'),
+  width: z.number().optional().describe('Image width in pixels (default: 800)'),
+  height: z.number().optional().describe('Image height in pixels (default: 600)'),
+});
+
+type PlaywrightBrowser = {
+  isConnected(): boolean;
+  newPage(options?: { viewport?: { width: number; height: number } }): Promise<PlaywrightPage>;
+  close(): Promise<void>;
+};
+
+type PlaywrightPage = {
+  setContent(html: string, options?: { waitUntil?: string }): Promise<void>;
+  waitForTimeout(ms: number): Promise<void>;
+  screenshot(options?: { type?: string }): Promise<Buffer>;
+  close(): Promise<void>;
+};
+
+let browserInstance: PlaywrightBrowser | null = null;
+
+async function getBrowser(): Promise<PlaywrightBrowser> {
+  if (browserInstance && browserInstance.isConnected()) {
+    return browserInstance;
+  }
+  const pw = await import('playwright');
+  browserInstance = await pw.chromium.launch();
+  return browserInstance;
+}
+
+export async function closeBrowser(): Promise<void> {
+  if (browserInstance) {
+    await browserInstance.close();
+    browserInstance = null;
+  }
+}
+
+export function handleScreenshot() {
+  return async (args: z.infer<typeof screenshotInputSchema>) => {
+    const stored = specStore.get(args.specId);
+    if (!stored) {
+      return errorResponse(`Spec "${args.specId}" not found or expired. Create a new visualization first.`);
+    }
+
+    const { spec } = stored;
+    let html: string;
+
+    if (isCompoundSpec(spec)) {
+      html = buildCompoundHtml(spec);
+    } else if (isHtmlPatternSupported(spec.pattern)) {
+      html = buildChartHtml(spec);
+    } else {
+      return errorResponse(`Pattern "${spec.pattern}" does not have an HTML builder.`);
+    }
+
+    const width = args.width ?? 800;
+    const height = args.height ?? 600;
+
+    let browser: PlaywrightBrowser;
+    try {
+      browser = await getBrowser();
+    } catch {
+      return errorResponse('Playwright is not installed. Run: npm install playwright && npx playwright install chromium');
+    }
+
+    const page = await browser.newPage({ viewport: { width, height } });
+    try {
+      await page.setContent(html, { waitUntil: 'networkidle' });
+      await page.waitForTimeout(300);
+      const buffer = await page.screenshot({ type: 'png' });
+      const base64 = buffer.toString('base64');
+
+      return {
+        content: [{
+          type: 'image' as const,
+          data: base64,
+          mimeType: 'image/png',
+        }],
+      };
+    } finally {
+      await page.close();
+    }
+  };
+}

package/src/mcp/tools/server-privacy.ts

@@ -0,0 +1,92 @@
+/**
+ * Server privacy tools — inspect and clear cached data.
+ *
+ * server_status: Shows what data is currently held in memory.
+ * clear_cache: Clears cached specs and query results.
+ */
+
+import { z } from 'zod';
+import { specStore } from '../spec-store.js';
+import { clearResultCache, resultCacheStats } from './result-cache.js';
+import { operationLog } from './operation-log.js';
+import type { SourceManager } from '../../connectors/manager.js';
+import { jsonResponse, formatUptime } from './shared.js';
+
+export const clearCacheInputSchema = z.object({
+  scope: z.enum(['all', 'specs', 'results']).default('all')
+    .describe('What to clear: "all" (everything), "specs" (visualization specs + data), "results" (query result cache).'),
+});
+
+interface PrivacyDeps {
+  sourceManager: SourceManager;
+  serverStartTime: number;
+}
+
+export function handleServerStatus(deps: PrivacyDeps) {
+  return async () => {
+    const specStats = specStore.stats();
+    const resultStats = resultCacheStats();
+
+    const sources = deps.sourceManager.list();
+    const sourcesSummary = sources.map(s => ({
+      id: s.id,
+      name: s.name,
+      type: s.type,
+      connected: deps.sourceManager.isConnected(s.id),
+    }));
+
+    return jsonResponse({
+      uptime: formatUptime(Date.now() - deps.serverStartTime),
+      specStore: {
+        cachedSpecs: specStats.entries,
+        maxSpecs: specStats.maxEntries,
+        totalDataRows: specStats.totalDataRows,
+        ttl: '1 hour',
+        oldestEntryAge: specStats.oldestEntryAge
+          ? `${Math.floor(specStats.oldestEntryAge / 60000)} minutes`
+          : null,
+      },
+      resultCache: {
+        cachedResults: resultStats.entries,
+        maxResults: resultStats.maxEntries,
+        totalDataRows: resultStats.totalRows,
+        ttl: '10 minutes',
+      },
+      sources: {
+        registered: sources.length,
+        connected: sourcesSummary.filter(s => s.connected).length,
+        list: sourcesSummary,
+      },
+    });
+  };
+}
+
+export function handleClearCache(deps: PrivacyDeps) {
+  return async ({ scope }: z.infer<typeof clearCacheInputSchema>) => {
+    const cleared: string[] = [];
+
+    if (scope === 'all' || scope === 'specs') {
+      const count = specStore.size;
+      specStore.clear();
+      cleared.push(`Cleared ${count} cached visualization specs`);
+    }
+
+    if (scope === 'all' || scope === 'results') {
+      const stats = resultCacheStats();
+      clearResultCache();
+      cleared.push(`Cleared ${stats.entries} cached query results`);
+    }
+
+    if (scope === 'all') {
+      operationLog.clear();
+      cleared.push('Cleared operation log');
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: cleared.join('\n'),
+      }],
+    };
+  };
+}

package/src/mcp/tools/shared.ts

@@ -0,0 +1,220 @@
+/**
+ * Shared utilities for MCP tool handlers.
+ *
+ * Consolidates duplicated logic:
+ * - MCP response builders (error/success/html patterns)
+ * - Column inference from data rows
+ * - Color preference application to visualization specs
+ * - Dashboard-specific helpers (time bucket handling, auto layout)
+ * - Dashboard view execution (query + pattern selection + overrides)
+ */
+
+import type {
+  DataColumn,
+  DslGroupByField,
+  VisualizationSpec,
+  ColorPaletteName,
+  DashboardViewSpec,
+} from '../../types.js';
+import { selectPattern } from '../../patterns/selector.js';
+import type { DashboardViewData } from '../../renderers/html/builders/dashboard.js';
+
+// ─── MCP RESPONSE BUILDERS ─────────────────────────────────────────────────
+
+type McpTextContent = { type: 'text'; text: string };
+
+export interface McpResponse {
+  [key: string]: unknown;
+  content: McpTextContent[];
+  isError?: boolean;
+  structuredContent?: { html: string };
+}
+
+export function errorResponse(message: string): McpResponse {
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+    isError: true,
+  };
+}
+
+export function jsonResponse(body: unknown): McpResponse {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(body, null, 2) }],
+  };
+}
+
+export function htmlResponse(body: unknown, html: string): McpResponse {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(body, null, 2) }],
+    structuredContent: { html },
+  };
+}
+
+// ─── COLUMN INFERENCE ───────────────────────────────────────────────────────
+
+export function inferColumns(data: Record<string, any>[]): DataColumn[] {
+  if (data.length === 0) return [];
+  const keys = Object.keys(data[0]);
+  return keys.map(key => {
+    const values = data.map(r => r[key]).filter(v => v != null);
+    const stringValues = values.map(String);
+    const uniqueValues = [...new Set(stringValues)];
+    const numericCount = values.filter(v =>
+      typeof v === 'number' || (typeof v === 'string' && !isNaN(Number(v)) && v !== '')
+    ).length;
+    const isNumeric = numericCount > values.length * 0.7;
+    const isDate = /date|time|year|month|day/i.test(key) ||
+      values.every(v => /^\d{4}[-/]/.test(String(v)));
+    const isId = /^id$|_id$|Id$/i.test(key) && uniqueValues.length > data.length * 0.5;
+
+    let type: DataColumn['type'] = 'categorical';
+    if (isId) type = 'id';
+    else if (isDate) type = 'date';
+    else if (isNumeric) type = 'numeric';
+
+    return {
+      name: key,
+      type,
+      sampleValues: uniqueValues.slice(0, 20),
+      uniqueCount: uniqueValues.length,
+      nullCount: data.length - values.length,
+      totalCount: data.length,
+    };
+  });
+}
+
+// ─── COLOR PREFERENCES ─────────────────────────────────────────────────────
+
+export function applyColorPreferences(
+  spec: VisualizationSpec,
+  prefs?: DashboardViewSpec['colorPreferences'],
+): void {
+  if (!prefs) return;
+  if (!spec.encoding.color) spec.encoding.color = {};
+
+  if (prefs.palette) {
+    spec.encoding.color.palette = prefs.palette as ColorPaletteName;
+  }
+  if (prefs.highlight) {
+    spec.encoding.color.highlight = {
+      values: prefs.highlight.values,
+      ...(prefs.highlight.color != null ? { color: prefs.highlight.color } : {}),
+      ...(prefs.highlight.mutedColor != null ? { mutedColor: prefs.highlight.mutedColor } : {}),
+      ...(prefs.highlight.mutedOpacity != null ? { mutedOpacity: prefs.highlight.mutedOpacity } : {}),
+    };
+  }
+  if (prefs.colorField) {
+    spec.encoding.color.field = prefs.colorField;
+    if (!spec.encoding.color.type) spec.encoding.color.type = 'nominal';
+  }
+}
+
+// ─── TIME BUCKET HELPERS ────────────────────────────────────────────────────
+
+function getTimeBucketedFields(groupBy?: DslGroupByField[]): string[] {
+  if (!groupBy) return [];
+  return groupBy
+    .filter((g): g is Exclude<DslGroupByField, string> => typeof g === 'object' && 'bucket' in g)
+    .map(g => g.field);
+}
+
+function enhanceIntentForTimeBucket(intent: string, groupBy?: DslGroupByField[]): string {
+  const bucketedFields = getTimeBucketedFields(groupBy);
+  if (bucketedFields.length > 0 && !/time.series|trend|over.time/i.test(intent)) {
+    return intent + ' (time series trend)';
+  }
+  return intent;
+}
+
+function applyTimeBucketColumnTypes(columns: DataColumn[], groupBy?: DslGroupByField[]): void {
+  const bucketedFields = getTimeBucketedFields(groupBy);
+  for (const col of columns) {
+    if (bucketedFields.some(f => col.name.includes(f) || f.includes(col.name))) {
+      col.type = 'date';
+    }
+  }
+}
+
+// ─── FORMATTING ─────────────────────────────────────────────────────────────
+
+export function formatUptime(ms: number): string {
+  const min = Math.floor(ms / 60000);
+  if (min < 60) return `${min} minutes`;
+  return `${Math.floor(min / 60)}h ${min % 60}m`;
+}
+
+// ─── DASHBOARD LAYOUT ───────────────────────────────────────────────────────
+
+export function autoLayout(viewCount: number): { columns: number } {
+  if (viewCount <= 1) return { columns: 1 };
+  if (viewCount <= 4) return { columns: 2 };
+  return { columns: 3 };
+}
+
+// ─── DASHBOARD VIEW EXECUTION ───────────────────────────────────────────────
+
+export interface ViewExecutionResult {
+  viewData: DashboardViewData[];
+  viewReasonings: { viewId: string; pattern: string; reasoning: string }[];
+}
+
+/**
+ * Execute queries and select patterns for each dashboard view.
+ * Shared between create_dashboard and refine_dashboard.
+ */
+export async function executeDashboardViews(
+  views: DashboardViewSpec[],
+  sourceId: string,
+  table: string,
+  sourceManager: any,
+): Promise<ViewExecutionResult | McpResponse> {
+  const viewData: DashboardViewData[] = [];
+  const viewReasonings: { viewId: string; pattern: string; reasoning: string }[] = [];
+
+  for (const view of views) {
+    const result = await sourceManager.queryDsl(sourceId, table, view.query);
+    if (!result.ok) {
+      return errorResponse(`Query failed for view "${view.id}": ${result.error}`);
+    }
+
+    const data = result.rows!;
+    const columns = inferColumns(data);
+    applyTimeBucketColumnTypes(columns, view.query.groupBy);
+    const intent = enhanceIntentForTimeBucket(view.intent, view.query.groupBy);
+
+    const selection = selectPattern(data, columns, intent);
+    let spec: VisualizationSpec;
+    let reasoning: string;
+
+    if (view.pattern) {
+      const match = [selection.recommended, ...selection.alternatives]
+        .find(r => r.pattern.id === view.pattern);
+      if (match) {
+        spec = match.spec;
+        reasoning = `Pattern: ${view.pattern}`;
+      } else {
+        spec = selection.recommended.spec;
+        spec.pattern = view.pattern;
+        reasoning = `Pattern: ${view.pattern} (fallback)`;
+      }
+    } else {
+      spec = selection.recommended.spec;
+      reasoning = selection.recommended.reasoning;
+    }
+
+    spec.title = view.title;
+    if (view.config) {
+      spec.config = { ...spec.config, ...view.config };
+    }
+    applyColorPreferences(spec, view.colorPreferences);
+
+    viewData.push({ viewId: view.id, data, spec });
+    viewReasonings.push({ viewId: view.id, pattern: spec.pattern, reasoning });
+  }
+
+  return { viewData, viewReasonings };
+}
+
+export function isViewExecutionError(result: ViewExecutionResult | McpResponse): result is McpResponse {
+  return 'content' in result;
+}

package/src/mcp/tools/sources.ts

@@ -0,0 +1,203 @@
+/**
+ * MCP Tools: list_sources, add_source, remove_source, describe_source
+ * Manage data source connections.
+ */
+
+import { z } from 'zod';
+import { errorResponse, jsonResponse } from './shared.js';
+
+const SANDBOX_PATH_PATTERNS = [
+  /^\/mnt\/user-data\//,
+  /^\/home\/claude\//,
+  /^\/tmp\/uploads\//,
+  /^\/mnt\/uploads\//,
+];
+
+export function isSandboxPath(filePath: string): boolean {
+  return SANDBOX_PATH_PATTERNS.some(p => p.test(filePath));
+}
+
+export const addSourceInputSchema = z.object({
+  name: z.string().describe('Human-readable name for this data source'),
+  type: z.enum(['csv', 'sqlite', 'postgres', 'mysql']).describe('Type of data source'),
+  config: z.union([
+    z.object({
+      type: z.literal('csv'),
+      path: z.string().describe('Path to CSV file or directory of CSV files'),
+    }),
+    z.object({
+      type: z.literal('sqlite'),
+      path: z.string().describe('Path to SQLite database file'),
+    }),
+    z.object({
+      type: z.literal('postgres'),
+      host: z.string(),
+      port: z.number().default(5432),
+      database: z.string(),
+      user: z.string(),
+      password: z.string(),
+      ssl: z.boolean().optional(),
+    }),
+    z.object({
+      type: z.literal('mysql'),
+      host: z.string(),
+      port: z.number().default(3306),
+      database: z.string(),
+      user: z.string(),
+      password: z.string(),
+    }),
+  ]).describe('Connection configuration'),
+  detail: z.enum(['compact', 'full']).default('full').describe('Schema detail level: "compact" returns just column names/types + row counts (saves tokens); "full" (default) includes stats, top values, and sample rows'),
+});
+
+export const removeSourceInputSchema = z.object({
+  sourceId: z.string().describe('ID of the data source to remove'),
+});
+
+export const describeSourceInputSchema = z.object({
+  sourceId: z.string().describe('Source ID from add_source'),
+  table: z.string().optional().describe('Table name (optional — if omitted, returns all tables)'),
+  detail: z.enum(['compact', 'full']).default('full').describe('Schema detail level: "compact" returns just column names/types + row counts; "full" (default) includes stats, top values, and sample rows'),
+});
+
+/** Build a table profile from schema table + connected source */
+async function buildTableProfile(t: any, connectedSource: any, detail: 'compact' | 'full' = 'full') {
+  if (detail === 'compact') {
+    return {
+      name: t.name,
+      rowCount: t.rowCount,
+      columns: t.columns.map((c: any) => ({ name: c.name, type: c.type })),
+    };
+  }
+  const sampleRows = connectedSource
+    ? await connectedSource.getSampleRows(t.name, 5)
+    : [];
+  return {
+    name: t.name,
+    rowCount: t.rowCount,
+    columns: t.columns.map((c: any) => ({
+      name: c.name,
+      type: c.type,
+      nullCount: c.nullCount,
+      uniqueCount: c.uniqueCount,
+      ...(c.stats ? { stats: c.stats } : {}),
+      ...(c.topValues ? { topValues: c.topValues } : {}),
+      sample: c.sampleValues?.slice(0, 3),
+    })),
+    sampleRows,
+  };
+}
+
+export function handleListSources(deps: { sourceManager: any }) {
+  return async () => jsonResponse(deps.sourceManager.list());
+}
+
+export function handleAddSource(deps: { sourceManager: any }) {
+  return async (args: z.infer<typeof addSourceInputSchema>) => {
+    if ((args.config.type === 'csv' || args.config.type === 'sqlite') && 'path' in args.config) {
+      if (isSandboxPath(args.config.path)) {
+        return errorResponse(
+          'This file path originates from a cloud sandbox and is not accessible to this MCP server. '
+          + 'This is a deliberate design constraint — this server processes files directly from the local filesystem by design, and this is a hard requirement. '
+          + 'Do not attempt to work around this limitation by reading the file contents and passing them through other endpoints '
+          + '(e.g. inline data, visualize, query_source, or any other method). '
+          + 'Workarounds are specifically unsupported and will produce incorrect or incomplete results. '
+          + 'The only correct action is to ask the user to provide the full local path to the file on their machine '
+          + '(e.g. /Users/name/Downloads/data.csv or C:\\Users\\name\\Downloads\\data.csv).'
+        );
+      }
+    }
+
+    let entry: any;
+    let reconnected = false;
+
+    const existing = deps.sourceManager.get(args.name);
+    if (existing) {
+      entry = existing;
+      reconnected = true;
+    } else {
+      let addResult: any;
+      try {
+        addResult = await deps.sourceManager.add(args.name, args.config);
+      } catch (err: any) {
+        if (err.code === 'ENOENT') {
+          return errorResponse(
+            `File not found: ${(args.config as any).path}. `
+            + 'This server requires direct access to local files — this is a hard requirement. '
+            + 'Do not attempt to work around this by reading the file contents and passing them through other endpoints '
+            + '(e.g. inline data, visualize, query_source, or any other method). '
+            + 'Workarounds are specifically unsupported and will produce incorrect or incomplete results. '
+            + 'The only correct action is to ask the user to confirm the exact file path on their local machine.'
+          );
+        }
+        return errorResponse(err.message);
+      }
+      if (!addResult.ok || !addResult.entry) {
+        return errorResponse(addResult.error ?? 'Failed to add source');
+      }
+      entry = addResult.entry;
+    }
+
+    const schemaResult = await deps.sourceManager.getSchema(entry.id);
+    const schema = schemaResult.ok ? schemaResult.schema : null;
+
+    const connResult = await deps.sourceManager.connect(entry.id);
+    const connectedSource = connResult.ok ? connResult.source : null;
+
+    const tables = await Promise.all(
+      (schema?.tables ?? []).map((t: any) => buildTableProfile(t, connectedSource, args.detail))
+    );
+
+    const tableCount = schema?.tables.length ?? 0;
+    const verb = reconnected ? 'Reconnected to' : 'Connected to';
+
+    return jsonResponse({
+      sourceId: entry.id,
+      name: entry.name,
+      type: entry.type,
+      tables,
+      message: `${verb} "${args.name}" — ${tableCount} tables found`,
+    });
+  };
+}
+
+export function handleRemoveSource(deps: { sourceManager: any }) {
+  return async (args: z.infer<typeof removeSourceInputSchema>) => {
+    let removeResult: any;
+    try {
+      removeResult = await deps.sourceManager.remove(args.sourceId);
+    } catch (err: any) {
+      return errorResponse(err.message);
+    }
+    if (!removeResult.ok) {
+      return errorResponse(removeResult.error ?? 'Failed to remove source');
+    }
+    return jsonResponse({ message: `Source "${args.sourceId}" removed` });
+  };
+}
+
+export function handleDescribeSource(deps: { sourceManager: any }) {
+  return async (args: z.infer<typeof describeSourceInputSchema>) => {
+    const schemaResult = await deps.sourceManager.getSchema(args.sourceId);
+    if (!schemaResult.ok || !schemaResult.schema) {
+      return errorResponse(schemaResult.error ?? `Source not found: ${args.sourceId}`);
+    }
+
+    const connResult = await deps.sourceManager.connect(args.sourceId);
+    const connectedSource = connResult.ok ? connResult.source : null;
+
+    let tables = schemaResult.schema.tables;
+    if (args.table) {
+      tables = tables.filter((t: any) => t.name === args.table);
+      if (tables.length === 0) {
+        return errorResponse(`Table "${args.table}" not found. Available: ${schemaResult.schema.tables.map((t: any) => t.name).join(', ')}`);
+      }
+    }
+
+    const profiles = await Promise.all(
+      tables.map((t: any) => buildTableProfile(t, connectedSource, args.detail))
+    );
+
+    return jsonResponse(args.table ? profiles[0] : profiles);
+  };
+}

package/src/mcp/tools/visualize-from-source.ts

@@ -0,0 +1,77 @@
+/**
+ * MCP Tool: visualize_from_source
+ * Takes a data source + DSL query + intent and returns visualization
+ * recommendations from the handcrafted pattern library.
+ *
+ * For inline data, use the `visualize` tool instead.
+ */
+
+import { z } from 'zod';
+import type { VisualizeInput, VisualizeOutput } from '../../types.js';
+import { dslQuerySchema } from './dsl-schemas.js';
+import {
+  colorPreferencesSchema,
+  columnsSchema,
+  dataShapeHintsSchema,
+  handleVisualizeCore,
+} from './visualize.js';
+import { errorResponse } from './shared.js';
+import { logOperation, extractDslStructure } from './operation-log.js';
+
+export const visualizeFromSourceInputSchema = z.object({
+  sourceId: z.string().describe('Source ID from add_source'),
+  table: z.string().describe('Base table within the source'),
+  query: dslQuerySchema.describe('Declarative query to slice/aggregate the data before visualizing'),
+  intent: z.string().describe('What the user wants to see — e.g., "compare sales by region", "show distribution of ages", "how do rankings change over time"'),
+  columns: columnsSchema,
+  dataShapeHints: dataShapeHintsSchema,
+  pattern: z.string().optional().describe('Force a specific chart pattern by ID (e.g. "bar", "beeswarm", "stream-graph"). Use list_patterns to discover IDs. Bypasses scoring; alternatives still returned.'),
+  title: z.string().optional().describe('Chart title — set upfront to avoid a refine round-trip'),
+  subtitle: z.string().optional().describe('Chart subtitle — set upfront to avoid a refine round-trip'),
+  includeDataTable: z.boolean().optional().describe('Whether to add a companion sortable data table with linked highlighting below the chart. Default: true'),
+  colorPreferences: colorPreferencesSchema,
+  maxAlternativeChartTypes: z.number().optional().describe('Max alternative chart type recommendations to return (default: 2, set 0 for none)'),
+  geoLevel: z.enum(['country', 'subdivision']).optional()
+    .describe('Geographic level: "country" (each row = a nation) or "subdivision" (each row = a state/province). Auto-detected if omitted.'),
+  geoRegion: z.string().optional()
+    .describe('Geographic region code: "world", ISO country code (US, CN, AU, etc.), or continent (EU, AF, AS, SA, NA, OC). Auto-detected if omitted.'),
+});
+
+export function handleVisualizeFromSource(
+  selectPatterns: (input: VisualizeInput) => VisualizeOutput,
+  deps: { sourceManager: any },
+) {
+  const core = handleVisualizeCore(selectPatterns, 'visualize_from_source');
+
+  return async (args: z.infer<typeof visualizeFromSourceInputSchema>) => {
+    const start = Date.now();
+
+    if (!deps.sourceManager) {
+      return errorResponse('Source manager not available.');
+    }
+
+    const source = deps.sourceManager.get?.(args.sourceId);
+    const sourceType = source?.type;
+
+    const result = await deps.sourceManager.queryDsl(args.sourceId, args.table, args.query);
+    if (!result.ok) {
+      logOperation({
+        toolName: 'visualize_from_source',
+        timestamp: start,
+        durationMs: Date.now() - start,
+        success: false,
+        meta: {
+          dslStructure: extractDslStructure(args.query),
+          sourceType,
+          error: result.error,
+        },
+      });
+      return errorResponse(result.error);
+    }
+
+    return core(result.rows, args, { truncated: result.truncated, totalSourceRows: result.totalRows }, {
+      dslStructure: extractDslStructure(args.query),
+      sourceType,
+    });
+  };
+}