@outsidedata/dolex 0.1.0

package/src/mcp/prompts.ts

@@ -0,0 +1,35 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+export function registerPrompts(server: McpServer) {
+  server.registerPrompt(
+    'explore-data',
+    {
+      title: 'Explore a Dataset',
+      description: 'Drop a data file and get automatic analysis — like having a data analyst at your desk',
+      argsSchema: {
+        path: z.string().describe('File path (CSV, SQLite) or connection string (Postgres, MySQL)'),
+      },
+    },
+    async ({ path }) => ({
+      messages: [{
+        role: 'user' as const,
+        content: {
+          type: 'text' as const,
+          text: [
+            `I want to explore a dataset. The file path is: ${path}`,
+            '',
+            'Please:',
+            '1. Connect it as a data source using add_source',
+            '2. Call analyze_source to get an automatic analysis plan',
+            '3. For each step in the plan, call visualize_from_source with the provided query and use one of the suggested patterns',
+            '4. After each chart, write a 2-3 sentence finding explaining what the data reveals — be specific about numbers, trends, and outliers',
+            '5. End with a "Key Takeaways" summary',
+            '',
+            'Use the full Dolex pattern library — the analysis plan suggests patterns like violin plots, sparkline grids, treemaps, and beeswarms. Use them instead of defaulting to bar charts.',
+          ].join('\n'),
+        },
+      }],
+    }),
+  );
+}

package/src/mcp/spec-store.ts

@@ -0,0 +1,141 @@
+/**
+ * SpecStore — Server-side cache for visualization specs.
+ *
+ * Stores full specs + data by ID so the MCP text response can be compact
+ * (just specId + metadata) while structuredContent still gets the full
+ * pre-rendered chart. The MCP server is long-lived per conversation,
+ * so this persists naturally across tool calls.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type {
+  VisualizationSpec,
+  CompoundVisualizationSpec,
+  DataColumn,
+} from '../types.js';
+
+export interface StoredSpec {
+  spec: VisualizationSpec | CompoundVisualizationSpec;
+  columns: DataColumn[];
+  alternatives: Map<string, VisualizationSpec>;
+  createdAt: number;
+}
+
+export interface SpecStoreStats {
+  entries: number;
+  maxEntries: number;
+  ttlMs: number;
+  totalDataRows: number;
+  oldestEntryAge: number | null;
+}
+
+const MAX_ENTRIES = 100;
+const TTL_MS = 60 * 60 * 1000; // 1 hour
+
+export class SpecStore {
+  private store = new Map<string, StoredSpec>();
+
+  private generateId(): string {
+    return `spec-${randomUUID().slice(0, 8)}`;
+  }
+
+  private isExpired(entry: StoredSpec): boolean {
+    return Date.now() - entry.createdAt > TTL_MS;
+  }
+
+  save(
+    spec: VisualizationSpec | CompoundVisualizationSpec,
+    columns: DataColumn[],
+    alternatives: Map<string, VisualizationSpec> = new Map(),
+  ): string {
+    this.purgeExpired();
+
+    if (this.store.size >= MAX_ENTRIES) {
+      const oldestKey = this.store.keys().next().value as string;
+      this.store.delete(oldestKey);
+    }
+
+    const id = this.generateId();
+    this.store.set(id, {
+      spec,
+      columns,
+      alternatives,
+      createdAt: Date.now(),
+    });
+    return id;
+  }
+
+  get(specId: string): StoredSpec | null {
+    const entry = this.store.get(specId);
+    if (!entry) return null;
+    if (this.isExpired(entry)) {
+      this.store.delete(specId);
+      return null;
+    }
+    return entry;
+  }
+
+  updateSpec(
+    specId: string,
+    newSpec: VisualizationSpec | CompoundVisualizationSpec,
+  ): string {
+    const existing = this.store.get(specId);
+    const columns = existing?.columns ?? [];
+    const alternatives = existing?.alternatives ?? new Map<string, VisualizationSpec>();
+    return this.save(newSpec, columns, alternatives);
+  }
+
+  getAlternative(specId: string, patternId: string): VisualizationSpec | null {
+    const stored = this.get(specId);
+    if (!stored) return null;
+    return stored.alternatives.get(patternId) ?? null;
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+
+  purgeExpired(): number {
+    const now = Date.now();
+    let purged = 0;
+    for (const [key, entry] of this.store) {
+      if (now - entry.createdAt > TTL_MS) {
+        this.store.delete(key);
+        purged++;
+      }
+    }
+    return purged;
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  stats(): SpecStoreStats {
+    this.purgeExpired();
+    const now = Date.now();
+    let totalDataRows = 0;
+    let oldestAge: number | null = null;
+
+    for (const entry of this.store.values()) {
+      const spec = entry.spec as any;
+      if (spec.data && Array.isArray(spec.data)) {
+        totalDataRows += spec.data.length;
+      }
+      const age = now - entry.createdAt;
+      if (oldestAge === null || age > oldestAge) {
+        oldestAge = age;
+      }
+    }
+
+    return {
+      entries: this.store.size,
+      maxEntries: MAX_ENTRIES,
+      ttlMs: TTL_MS,
+      totalDataRows,
+      oldestEntryAge: oldestAge,
+    };
+  }
+}
+
+export const specStore = new SpecStore();

package/src/mcp/tools/analyze.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP Tool: analyze_source
+ * Examines a data source and generates a structured analysis plan with DSL queries.
+ */
+
+import { z } from 'zod';
+import { buildAnalysisPlan } from '../../analysis/planner.js';
+import { errorResponse, jsonResponse } from './shared.js';
+
+export const analyzeSourceInputSchema = z.object({
+  sourceId: z.string().describe('Source ID from add_source'),
+  table: z.string().optional().describe('Table to analyze (defaults to first table)'),
+  maxSteps: z.number().min(1).max(10).optional().describe('Maximum analysis steps (default: 6)'),
+});
+
+export function handleAnalyzeSource(deps: { sourceManager: any }) {
+  return async (args: z.infer<typeof analyzeSourceInputSchema>) => {
+    const schemaResult = await deps.sourceManager.getSchema(args.sourceId);
+    if (!schemaResult.ok || !schemaResult.schema) {
+      return errorResponse(schemaResult.error ?? `Source not found: ${args.sourceId}`);
+    }
+
+    const tables = schemaResult.schema.tables;
+    const targetTable = args.table
+      ? tables.find((t: any) => t.name === args.table)
+      : tables[0];
+
+    if (!targetTable) {
+      const available = tables.map((t: any) => t.name).join(', ');
+      const message = args.table
+        ? `Table "${args.table}" not found. Available: ${available}`
+        : 'No tables found in source';
+      return errorResponse(message);
+    }
+
+    const plan = buildAnalysisPlan(
+      targetTable.columns,
+      targetTable.name,
+      schemaResult.schema.source?.name ?? args.sourceId,
+      args.maxSteps ?? 6,
+    );
+
+    return jsonResponse(plan);
+  };
+}

package/src/mcp/tools/bug-report.ts

@@ -0,0 +1,183 @@
+/**
+ * MCP Tool: report_bug
+ * Generates a sanitized bug report for GitHub issues.
+ * No data values, connection strings, or file paths leave the machine.
+ * Field names anonymized by default (opt-in to include real names).
+ */
+
+import { z } from 'zod';
+import { createRequire } from 'node:module';
+import { platform, version as nodeVersion } from 'node:process';
+import { specStore } from '../spec-store.js';
+import { resultCacheStats } from './result-cache.js';
+import { operationLog } from './operation-log.js';
+import type { OperationEntry } from './operation-log.js';
+import { formatUptime } from './shared.js';
+import type { SourceManager } from '../../connectors/manager.js';
+
+const require = createRequire(import.meta.url);
+const { version: dolexVersion } = require('../../../package.json');
+
+export const bugReportInputSchema = z.object({
+  description: z.string().describe('What went wrong — describe the issue'),
+  specId: z.string().optional().describe('Spec ID from a recent visualize/refine call to include context'),
+  includeFieldNames: z.boolean().optional().describe('Include real field names in the report (default: false — fields anonymized as col_0, col_1)'),
+});
+
+export function anonymizeColumns(
+  columns: { name: string; type: string }[],
+  include: boolean,
+): { name: string; type: string }[] {
+  return columns.map((c, i) => ({
+    name: include ? c.name : `col_${i}`,
+    type: c.type,
+  }));
+}
+
+export function sanitizeSpecConfig(config: Record<string, unknown>): Record<string, string> {
+  const safe: Record<string, string> = {};
+  for (const [key, val] of Object.entries(config)) {
+    if (key.startsWith('_')) continue;
+    if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
+      safe[key] = String(val);
+    } else if (val == null) {
+      safe[key] = 'null';
+    } else {
+      safe[key] = typeof val;
+    }
+  }
+  return safe;
+}
+
+export function sanitizeError(error: string): string {
+  return error
+    .replace(/(?:postgres|mysql|sqlite):\/\/[^\s]+/g, '<connection-string>')
+    .replace(/\/[\w/.~-]+/g, '<path>')
+    .replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}\b/gi, '<email>');
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function buildOperationsTable(entries: OperationEntry[]): string {
+  if (entries.length === 0) return '_No recent operations._';
+
+  const rows = entries.map(e => {
+    const status = e.success ? 'ok' : 'error';
+    const pattern = e.meta.pattern || '-';
+    const shape = e.meta.dataShape
+      ? `${e.meta.dataShape.rowCount}r x ${e.meta.dataShape.columnCount}c`
+      : '-';
+    return `| ${e.toolName} | ${status} | ${formatDuration(e.durationMs)} | ${pattern} | ${shape} |`;
+  });
+
+  return [
+    '| Tool | Status | Duration | Pattern | Shape |',
+    '|------|--------|----------|---------|-------|',
+    ...rows,
+  ].join('\n');
+}
+
+interface ReportDeps {
+  sourceManager: SourceManager;
+  serverStartTime: number;
+}
+
+export function handleReportBug(deps: ReportDeps) {
+  return async (args: z.infer<typeof bugReportInputSchema>) => {
+    const includeFieldNames = args.includeFieldNames ?? false;
+    const sections: string[] = [];
+
+    sections.push(`## Description\n\n${args.description}`);
+
+    sections.push([
+      '## Environment',
+      '',
+      `- **Dolex**: ${dolexVersion}`,
+      `- **Node.js**: ${nodeVersion}`,
+      `- **Platform**: ${platform}`,
+    ].join('\n'));
+
+    if (args.specId) {
+      const stored = specStore.get(args.specId);
+      if (stored) {
+        const spec = stored.spec as any;
+        const columns = anonymizeColumns(
+          stored.columns.map(c => ({ name: c.name, type: c.type })),
+          includeFieldNames,
+        );
+        const contextLines = [
+          '## Visualization Context',
+          '',
+          `- **Pattern**: ${spec.pattern}`,
+          `- **Data shape**: ${spec.data?.length ?? '?'} rows x ${columns.length} columns`,
+          `- **Columns**: ${columns.map(c => `${c.name} (${c.type})`).join(', ')}`,
+        ];
+
+        if (spec.encoding) {
+          const fieldNameMap = new Map<string, string>();
+          if (!includeFieldNames) {
+            stored.columns.forEach((c, i) => fieldNameMap.set(c.name, `col_${i}`));
+          }
+          const encodingFields: string[] = [];
+          for (const [channel, enc] of Object.entries(spec.encoding)) {
+            const field = (enc as any)?.field;
+            if (field) {
+              const displayName = fieldNameMap.get(field) ?? field;
+              encodingFields.push(`${channel}=${displayName}`);
+            }
+          }
+          if (encodingFields.length > 0) {
+            contextLines.push(`- **Encoding**: ${encodingFields.join(', ')}`);
+          }
+        }
+
+        if (spec.config) {
+          const safeConfig = sanitizeSpecConfig(spec.config);
+          const configStr = Object.entries(safeConfig)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(', ');
+          if (configStr) {
+            contextLines.push(`- **Config**: ${configStr}`);
+          }
+        }
+
+        sections.push(contextLines.join('\n'));
+      }
+    }
+
+    const ops = operationLog.getAll();
+    sections.push(`## Recent Operations\n\n${buildOperationsTable(ops)}`);
+
+    const specStats = specStore.stats();
+    const resultStats = resultCacheStats();
+    const sources = deps.sourceManager.list();
+    const sourceTypes: Record<string, number> = {};
+    for (const s of sources) {
+      sourceTypes[s.type] = (sourceTypes[s.type] || 0) + 1;
+    }
+    const sourceTypeSummary = Object.entries(sourceTypes)
+      .map(([t, c]) => `${t}: ${c}`)
+      .join(', ') || 'none';
+
+    sections.push([
+      '## Server State',
+      '',
+      `- **Uptime**: ${formatUptime(Date.now() - deps.serverStartTime)}`,
+      `- **Cached specs**: ${specStats.entries}`,
+      `- **Cached results**: ${resultStats.entries}`,
+      `- **Sources**: ${sources.length} (${sourceTypeSummary})`,
+    ].join('\n'));
+
+    const report = sections.join('\n\n');
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: report,
+      }],
+    };
+  };
+}