@speakai/mcp-server 1.14.0 → 1.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/index.js +394 -135
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -5359,32 +5359,114 @@ var init_users = __esm({
5359
5359
  });
5360
5360
 
5361
5361
  // src/tools/dashboard-widgets.ts
5362
- function buildDashboardWidgets(items) {
5363
- let y = 0;
5362
+ function defaultWidgetConfig(type) {
5363
+ switch (type) {
5364
+ case "narrative":
5365
+ return { focus: "Summarize the key takeaways from this data." };
5366
+ case "stat-cards":
5367
+ return {
5368
+ tiles: [
5369
+ { metric: { kind: "builtin", name: "mediaCount" }, label: "Media files" },
5370
+ { metric: { kind: "builtin", name: "totalDuration" }, label: "Total duration" },
5371
+ { metric: { kind: "builtin", name: "wordCount" }, label: "Total words" },
5372
+ { metric: { kind: "builtin", name: "speakerCount" }, label: "Unique speakers" }
5373
+ ]
5374
+ };
5375
+ case "metric-chart":
5376
+ return {
5377
+ mark: "bar",
5378
+ metric: { kind: "builtin", name: "mediaCount" },
5379
+ groupBy: { kind: "folder" }
5380
+ };
5381
+ case "table":
5382
+ return {
5383
+ rowsAre: "groups",
5384
+ groupBy: { kind: "folder" },
5385
+ columns: [
5386
+ { header: "Recordings", metric: { kind: "builtin", name: "mediaCount" } },
5387
+ { header: "Duration", metric: { kind: "builtin", name: "totalDuration" } }
5388
+ ],
5389
+ sort: { column: "Recordings", dir: "desc" }
5390
+ };
5391
+ case "comparison":
5392
+ return {
5393
+ dimension: "folder",
5394
+ a: {},
5395
+ b: {},
5396
+ metrics: [{ kind: "builtin", name: "mediaCount" }]
5397
+ };
5398
+ case "field-distribution":
5399
+ throw new Error(
5400
+ 'field-distribution requires config.fieldName (a custom field NAME \u2014 not id \u2014 from list_fields), plus measure ("count" | "percent") and chartType ("bar" | "donut").'
5401
+ );
5402
+ case "sentiment-trend":
5403
+ return { granularity: "week" };
5404
+ case "themes":
5405
+ return { limit: 10 };
5406
+ case "people":
5407
+ return { metrics: [{ kind: "builtin", name: "mediaCount" }], limit: 10 };
5408
+ case "team-activity":
5409
+ return { metrics: ["uploads", "minutes", "lastActive"] };
5410
+ case "notes":
5411
+ return { content: "Add notes or context for this dashboard." };
5412
+ }
5413
+ }
5414
+ function buildDashboardWidgets(items, sections = []) {
5415
+ for (const item of items) {
5416
+ if (item.id !== void 0 && !KEBAB_ID.test(item.id)) {
5417
+ throw new Error(
5418
+ `widget id "${item.id}" must be kebab-case (lowercase letters, digits, single dashes)`
5419
+ );
5420
+ }
5421
+ }
5422
+ const widgets = items.map((item) => makeWidget(item));
5423
+ const referenced = new Set(sections.flatMap((s) => s.widgetIds));
5424
+ const known = new Set(widgets.map((w) => w.id));
5425
+ for (const wid of referenced) {
5426
+ if (!known.has(wid)) {
5427
+ throw new Error(
5428
+ `section widgetIds reference unknown widget id "${wid}". Give each sectioned widget an explicit kebab-case \`id\` and list that id in the section.`
5429
+ );
5430
+ }
5431
+ }
5432
+ const sectionOf = /* @__PURE__ */ new Map();
5433
+ sections.forEach((s, i) => s.widgetIds.forEach((wid) => sectionOf.set(wid, i)));
5434
+ const groups = [widgets.filter((w) => !sectionOf.has(w.id))];
5435
+ sections.forEach(
5436
+ (_, i) => groups.push(widgets.filter((w) => sectionOf.get(w.id) === i))
5437
+ );
5438
+ for (const group of groups) {
5439
+ layoutGroup(group);
5440
+ }
5441
+ return widgets;
5442
+ }
5443
+ function layoutGroup(group) {
5444
+ let y = group.reduce(
5445
+ (bottom, w) => isAutoLayout(w) ? bottom : Math.max(bottom, w.layout.y + w.layout.h),
5446
+ 0
5447
+ );
5364
5448
  let rowX = 0;
5365
5449
  let rowH = 0;
5366
- return items.map((item) => {
5367
- const meta = WIDGET_META[item.type];
5450
+ for (const widget of group) {
5451
+ if (!isAutoLayout(widget)) continue;
5452
+ const meta = WIDGET_META[widget.type];
5368
5453
  const full = meta.w >= GRID_COLS;
5369
- let x;
5370
5454
  if (full) {
5371
5455
  if (rowX !== 0) {
5372
5456
  y += rowH;
5373
5457
  rowX = 0;
5374
5458
  rowH = 0;
5375
5459
  }
5376
- x = 0;
5377
- const widget2 = makeWidget(item, x, y);
5460
+ widget.layout = { x: 0, y, w: meta.w, h: meta.h };
5378
5461
  y += meta.h;
5379
- return widget2;
5462
+ continue;
5380
5463
  }
5381
5464
  if (rowX + meta.w > GRID_COLS) {
5382
5465
  y += rowH;
5383
5466
  rowX = 0;
5384
5467
  rowH = 0;
5385
5468
  }
5386
- x = rowX;
5387
- const widget = makeWidget(item, x, y);
5469
+ widget.layout = { x: rowX, y, w: meta.w, h: meta.h };
5388
5470
  rowX += meta.w;
5389
5471
  rowH = Math.max(rowH, meta.h);
5390
5472
  if (rowX >= GRID_COLS) {
@@ -5392,151 +5474,233 @@ function buildDashboardWidgets(items) {
5392
5474
  rowX = 0;
5393
5475
  rowH = 0;
5394
5476
  }
5395
- return widget;
5396
- });
5477
+ }
5478
+ }
5479
+ function isAutoLayout(widget) {
5480
+ return widget.layout.w === 0;
5397
5481
  }
5398
- function makeWidget(item, x, y) {
5482
+ function makeWidget(item) {
5399
5483
  const meta = WIDGET_META[item.type];
5400
- return {
5401
- id: (0, import_crypto.randomUUID)(),
5484
+ const widget = {
5485
+ id: item.id ?? (0, import_crypto.randomUUID)(),
5402
5486
  type: item.type,
5403
5487
  title: item.title ?? meta.titleDefault,
5404
- config: item.config ?? {},
5405
- layout: { x, y, w: meta.w, h: meta.h, minW: meta.minW, minH: meta.minH }
5488
+ config: item.config ?? defaultWidgetConfig(item.type),
5489
+ layout: item.layout ? { x: item.layout.x, y: item.layout.y, w: item.layout.w, h: item.layout.h } : { ...AUTO_LAYOUT }
5406
5490
  };
5491
+ if (item.binding && Object.keys(item.binding).length > 0) {
5492
+ widget.binding = item.binding;
5493
+ }
5494
+ return widget;
5407
5495
  }
5408
- var import_crypto, GRID_COLS, WIDGET_TYPES, WIDGET_META, WIDGET_CATALOG, COMMON_WIDGET_CONFIG, DASHBOARD_EXAMPLES;
5496
+ var import_crypto, GRID_COLS, WIDGET_TYPES, DATE_RANGE_PRESETS, WIDGET_META, KEBAB_ID, AUTO_LAYOUT, WIDGET_CATALOG, SPEC_VOCABULARY, DESIGN_RULES, DASHBOARD_EXAMPLES;
5409
5497
  var init_dashboard_widgets = __esm({
5410
5498
  "src/tools/dashboard-widgets.ts"() {
5411
5499
  "use strict";
5412
5500
  import_crypto = require("crypto");
5413
5501
  GRID_COLS = 12;
5414
5502
  WIDGET_TYPES = [
5503
+ "narrative",
5415
5504
  "stat-cards",
5416
- "sentiment",
5417
- "media-list",
5505
+ "metric-chart",
5506
+ "table",
5507
+ "comparison",
5418
5508
  "field-distribution",
5419
- "upload-timeline",
5509
+ "sentiment-trend",
5420
5510
  "themes",
5421
- "team-activity",
5422
- "kpi-trend",
5423
- "field-metric",
5424
- "metric-group",
5425
- "notes",
5426
5511
  "people",
5427
- "comparison",
5428
- "sentiment-trend"
5512
+ "team-activity",
5513
+ "notes"
5514
+ ];
5515
+ DATE_RANGE_PRESETS = [
5516
+ "last7days",
5517
+ "last30days",
5518
+ "last3months",
5519
+ "yearToDate",
5520
+ "allTime"
5429
5521
  ];
5430
5522
  WIDGET_META = {
5431
- "stat-cards": { w: GRID_COLS, h: 3, minW: 4, minH: 2, titleDefault: "Usage overview" },
5432
- sentiment: { w: 6, h: 4, minW: 3, minH: 3, titleDefault: "Sentiment" },
5433
- "media-list": { w: GRID_COLS, h: 4, minW: 4, minH: 3, titleDefault: "Recent media" },
5434
- "field-distribution": { w: 6, h: 4, minW: 3, minH: 3, titleDefault: "Field breakdown" },
5435
- "upload-timeline": { w: 6, h: 4, minW: 3, minH: 3, titleDefault: "Uploads over time" },
5436
- themes: { w: 6, h: 4, minW: 3, minH: 3, titleDefault: "Themes" },
5437
- "team-activity": { w: 6, h: 4, minW: 3, minH: 3, titleDefault: "Team activity" },
5438
- "kpi-trend": { w: 3, h: 2, minW: 2, minH: 2, titleDefault: "Total files" },
5439
- "field-metric": { w: 3, h: 2, minW: 2, minH: 2, titleDefault: "Field metric" },
5440
- "metric-group": { w: 6, h: 2, minW: 3, minH: 2, titleDefault: "Metrics" },
5441
- notes: { w: GRID_COLS, h: 2, minW: 2, minH: 1, titleDefault: "Note" },
5442
- people: { w: 6, h: 4, minW: 3, minH: 3, titleDefault: "People" },
5443
- comparison: { w: 6, h: 3, minW: 3, minH: 2, titleDefault: "Comparison" },
5444
- "sentiment-trend": { w: 6, h: 4, minW: 3, minH: 3, titleDefault: "Sentiment over time" }
5523
+ narrative: { w: GRID_COLS, h: 3, titleDefault: "Insights" },
5524
+ "stat-cards": { w: GRID_COLS, h: 3, titleDefault: "Usage overview" },
5525
+ "metric-chart": { w: 6, h: 4, titleDefault: "Metric chart" },
5526
+ table: { w: GRID_COLS, h: 4, titleDefault: "Table" },
5527
+ comparison: { w: 6, h: 3, titleDefault: "Comparison" },
5528
+ "field-distribution": { w: 6, h: 4, titleDefault: "Field breakdown" },
5529
+ "sentiment-trend": { w: 6, h: 4, titleDefault: "Sentiment over time" },
5530
+ themes: { w: 6, h: 4, titleDefault: "Themes" },
5531
+ people: { w: 6, h: 4, titleDefault: "People" },
5532
+ "team-activity": { w: 6, h: 4, titleDefault: "Team activity" },
5533
+ notes: { w: GRID_COLS, h: 2, titleDefault: "Note" }
5445
5534
  };
5535
+ KEBAB_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
5536
+ AUTO_LAYOUT = { x: 0, y: 0, w: 0, h: 0 };
5446
5537
  WIDGET_CATALOG = [
5538
+ {
5539
+ type: "narrative",
5540
+ purpose: "AI-written insight narrative for the scope (full width).",
5541
+ config: 'focus: string (1-400 chars) \u2014 what the narrative should analyse, e.g. "Summarize the key objections raised in these calls." The server generates the text.'
5542
+ },
5447
5543
  {
5448
5544
  type: "stat-cards",
5449
- purpose: "Headline totals for the scope (full width).",
5450
- config: 'metrics?: string[] \u2014 any of "media", "storage", "words", "speakers", "duration", "sentiment"'
5545
+ purpose: "Headline stat tiles for the scope (full width).",
5546
+ config: "tiles: Array<{ metric: Metric, label: string (<=40), caption?: string (<=80), thresholds?: Threshold[] }> (1-6 tiles). See metricGrammar for the Metric shape."
5451
5547
  },
5452
- { type: "sentiment", purpose: "Sentiment distribution + representative sentences.", config: "none" },
5453
- { type: "media-list", purpose: "Most recent media in scope (full width).", config: "none" },
5454
5548
  {
5455
- type: "field-distribution",
5456
- purpose: "Value-frequency breakdown for one custom field.",
5457
- config: 'fieldId: string (a custom field id from list_fields); measure?: "count" | "words" | "duration" | "avg:<numericFieldId>" | "sum:<numericFieldId>"'
5549
+ type: "metric-chart",
5550
+ purpose: "The chart workhorse: one metric, optionally grouped and split into series.",
5551
+ config: 'mark: "line" | "bar" | "area" | "donut" | "stacked-bar"; metric: Metric; groupBy?: GroupBy; series?: GroupBy (2nd dimension, e.g. one line per person); sort?: "value-desc" | "value-asc" | "label"; limit?: number (1-100); thresholds?: Threshold[]'
5458
5552
  },
5459
- { type: "upload-timeline", purpose: "Uploads over time per media type.", config: "none" },
5460
- { type: "themes", purpose: "Dominant theme clusters.", config: 'chartType?: "cloud" | "bar"' },
5461
- { type: "team-activity", purpose: "Activity by team member.", config: "none" },
5462
5553
  {
5463
- type: "kpi-trend",
5464
- purpose: "A KPI with period-over-period delta.",
5465
- config: 'metrics?: string[] \u2014 any of "totalFiles", "totalDurationSeconds", "totalWords", "uniqueSpeakers"'
5554
+ type: "table",
5555
+ purpose: "Tabular records or grouped aggregates (full width).",
5556
+ config: 'rowsAre: "records" | "groups"; groupBy?: GroupBy (required when rowsAre="groups", forbidden when "records"); columns: Array<{ header: string (<=40, unique), field: string } | { header: string, metric: Metric }> (1-12; a column is EITHER a raw field OR a metric, never both; thresholds? allowed on both forms); sort?: { column: <one of the headers>, dir: "asc" | "desc" }; limit?: number (1-500); searchable?: boolean; rowClick?: "openMedia" | "none"'
5466
5557
  },
5467
5558
  {
5468
- type: "field-metric",
5469
- purpose: "A single custom field's aggregate, with a period-over-period delta.",
5470
- config: 'fieldId: string (custom field id from list_fields); aggregator: "sum" | "avg" | "min" | "max" | "count"'
5559
+ type: "comparison",
5560
+ purpose: "Side-by-side A/B comparison of the same metrics across two scopes.",
5561
+ config: 'dimension: "folder" | "time" | "fieldValue"; a: Binding; b: Binding (the two sides \u2014 see binding; {} inherits the dashboard scope); metrics: Metric[] (1-6)'
5471
5562
  },
5472
5563
  {
5473
- type: "metric-group",
5474
- purpose: "A scorecard of several field metrics in one card.",
5475
- config: 'metrics: Array<{ fieldId: string, op: "sum"|"avg"|"min"|"max"|"count", label?: string }> (note the per-item key is `op`, not `aggregator`)'
5564
+ type: "field-distribution",
5565
+ purpose: "Value-frequency breakdown for one custom field.",
5566
+ config: 'fieldName: string \u2014 the custom field NAME (not id) from list_fields; measure: "count" | "percent"; chartType: "bar" | "donut". All three keys are required.'
5476
5567
  },
5477
5568
  {
5478
- type: "notes",
5479
- purpose: "Free-text note/context block (full width).",
5480
- config: "heading?: string; content?: string"
5569
+ type: "sentiment-trend",
5570
+ purpose: "Sentiment over time.",
5571
+ config: 'granularity: "day" | "week" | "month" (required)'
5481
5572
  },
5482
- { type: "people", purpose: "Speaker/people breakdown.", config: "none" },
5483
5573
  {
5484
- type: "comparison",
5485
- purpose: "Period-over-period comparison of KPIs.",
5486
- config: 'metrics?: string[] \u2014 any of "totalFiles", "totalDurationSeconds", "totalWords", "uniqueSpeakers"'
5574
+ type: "themes",
5575
+ purpose: "Dominant theme clusters.",
5576
+ config: "limit: number (1-50, required)"
5577
+ },
5578
+ {
5579
+ type: "people",
5580
+ purpose: "Speaker/people breakdown ranked by metrics.",
5581
+ config: "metrics: Metric[] (1-6, required); limit: number (1-100, required)"
5487
5582
  },
5488
- { type: "sentiment-trend", purpose: "Sentiment over time.", config: "none" }
5489
- ];
5490
- COMMON_WIDGET_CONFIG = [
5491
5583
  {
5492
- key: "accentColor",
5493
- appliesTo: "any widget",
5494
- description: 'Hex color for the widget accent, e.g. "#6366F1". Omit for the default.'
5584
+ type: "team-activity",
5585
+ purpose: `Activity by team member. ONLY valid when the effective source is {type:"team"} (dashboard source or the widget's binding.source).`,
5586
+ config: 'metrics: Array<"uploads" | "minutes" | "meetings" | "chatUsage" | "lastActive"> (1-5, required)'
5495
5587
  },
5496
5588
  {
5497
- key: "scopeOverride",
5498
- appliesTo: "any widget except notes",
5499
- description: "Override the dashboard's scope for just this widget: { datePreset: string, folderId: string }. Omit to inherit the dashboard scope."
5589
+ type: "notes",
5590
+ purpose: "Free-text note/context block (full width).",
5591
+ config: "content: string (1-4000 chars, required)"
5500
5592
  }
5501
5593
  ];
5594
+ SPEC_VOCABULARY = {
5595
+ metricGrammar: {
5596
+ builtin: '{ kind: "builtin", name: "mediaCount" | "totalDuration" | "avgSentiment" | "speakerCount" | "wordCount", filter?: Filter }',
5597
+ field: '{ kind: "field", fieldName: string (custom field NAME from list_fields), agg: "sum" | "avg" | "min" | "max" | "median" | "count" | "countDistinct", filter?: Filter } \u2014 sum/avg/median/min/max require a number or currency field',
5598
+ expr: '{ kind: "expr", expr: <one of the four ops>, filter?: Filter }. Ops (operands are builtin/field metrics, never nested exprs): { op: "ratio", numerator: Metric, denominator: Metric } | { op: "diff", a: Metric, b: Metric } | { op: "delta", metric: Metric, over: "first-to-last" | "prev-period" } | { op: "rank", metric: Metric, direction: "desc" | "asc" }'
5599
+ },
5600
+ groupBy: '{ kind: "field", fieldName } (non-date fields) | { kind: "time", fieldName, granularity: "record" | "day" | "week" | "month" | "quarter" } (date/datetime fields only) | { kind: "folder" } | { kind: "speaker" }',
5601
+ binding: "Per-widget scope override, set as `binding` on any widget (omit a key to inherit the dashboard's value): { source?: Source, dateRange?: { preset }, filter?: Filter }",
5602
+ filter: 'Predicate tree: { field, op: "eq" | "neq" | "in" | "gt" | "gte" | "lt" | "lte" | "exists" | "notExists", value? } (op "in" takes an array value; "exists"/"notExists" take none) \u2014 or { and: Filter[] } / { or: Filter[] } (1-10 branches, max depth 5)',
5603
+ thresholds: 'Color bands for stat tiles, chart marks, and table columns (max 8): { when: { op: "gte" | "gt" | "lt" | "lte", value: number } | { op: "between", value: [low, high] }, status: "good" | "warn" | "critical" | "neutral", label?: string (<=40) }',
5604
+ source: 'Dashboard data source: { type: "folders", folderIds: string[] (1-50) } | { type: "team" } | { type: "workspace" }',
5605
+ dateRangePresets: DATE_RANGE_PRESETS,
5606
+ sections: "Optional named groups of widgets rendered as tabs/sections (max 12): { id: kebab-case string, title: string (<=24), icon: kebab-case lucide icon name, widgetIds: string[] (<=24) }. Widget ids in sections must match explicit `id`s you set on the widgets; a widget may appear in at most one section; widgets in no section form the implicit Overview group."
5607
+ };
5608
+ DESIGN_RULES = [
5609
+ "Lead with a narrative widget: on a new dashboard, make it the first widget of the first section \u2014 it is the headline insight.",
5610
+ 'Sections group widgets by the QUESTION they answer (e.g. "How is pipeline trending?"), not by widget type.',
5611
+ "Layout must never overlap within a section; side-by-side is x:0,w:6 and x:6,w:6, and y restarts at 0 in each section. Omit `layout` and the auto-layout guarantees this \u2014 only pass explicit layout when you need a non-default arrangement.",
5612
+ "Don't pad \u2014 every widget earns its place. Aim for 4-16 widgets on a full build.",
5613
+ "If something can't be computed by the widget catalog, put it in a narrative widget's focus instead of faking it with the wrong widget."
5614
+ ];
5502
5615
  DASHBOARD_EXAMPLES = [
5503
5616
  {
5504
5617
  name: "Sales calls overview",
5505
5618
  payload: {
5506
5619
  title: "Customer Calls Overview",
5507
- folderScope: ["<folderId>"],
5620
+ description: "Volume, sentiment, and themes for closed-won calls",
5621
+ source: { type: "folders", folderIds: ["<folderId>"] },
5508
5622
  dateRange: { preset: "last30days" },
5509
- filters: { filterList: [{ fieldName: "Stage", fieldOperator: "is", fieldValue: ["Closed Won"] }] },
5510
5623
  widgets: [
5511
- { type: "stat-cards", config: { metrics: ["media", "words", "speakers"] } },
5512
- { type: "sentiment", config: { accentColor: "#6366F1" } },
5513
- { type: "field-distribution", title: "Deals by stage", config: { fieldId: "<fieldId>", measure: "count" } },
5514
- { type: "themes", config: { chartType: "bar" } },
5515
- { type: "media-list" }
5624
+ { type: "narrative", config: { focus: "Summarize the key wins and objections in these calls." } },
5625
+ { type: "stat-cards" },
5626
+ {
5627
+ type: "metric-chart",
5628
+ title: "Calls per week",
5629
+ config: {
5630
+ mark: "line",
5631
+ metric: { kind: "builtin", name: "mediaCount" },
5632
+ groupBy: { kind: "time", fieldName: "createdAt", granularity: "week" }
5633
+ }
5634
+ },
5635
+ {
5636
+ type: "field-distribution",
5637
+ title: "Deals by stage",
5638
+ config: { fieldName: "Stage", measure: "count", chartType: "bar" }
5639
+ },
5640
+ { type: "themes", config: { limit: 10 } },
5641
+ { type: "sentiment-trend", config: { granularity: "week" } }
5516
5642
  ]
5517
5643
  }
5518
5644
  },
5519
5645
  {
5520
- name: "Field-metrics scorecard (new widgets)",
5646
+ name: "Sectioned revenue dashboard (explicit widget ids + sections)",
5521
5647
  payload: {
5522
5648
  title: "Deal Metrics",
5523
- folderScope: ["<folderId>"],
5524
- dateRange: { preset: "thisQuarter" },
5649
+ source: { type: "workspace" },
5650
+ dateRange: { preset: "last3months" },
5525
5651
  widgets: [
5526
- { type: "kpi-trend", title: "Total calls", config: { metrics: ["totalFiles"] } },
5527
- { type: "field-metric", title: "Avg deal size", config: { fieldId: "<dealSizeFieldId>", aggregator: "avg" } },
5528
5652
  {
5529
- type: "metric-group",
5653
+ id: "pipeline-stats",
5654
+ type: "stat-cards",
5530
5655
  title: "Pipeline",
5531
5656
  config: {
5532
- metrics: [
5533
- { fieldId: "<dealSizeFieldId>", op: "sum", label: "Total pipeline" },
5534
- { fieldId: "<dealSizeFieldId>", op: "max", label: "Largest deal" }
5657
+ tiles: [
5658
+ { metric: { kind: "field", fieldName: "Deal Size", agg: "sum" }, label: "Total pipeline" },
5659
+ { metric: { kind: "field", fieldName: "Deal Size", agg: "max" }, label: "Largest deal" },
5660
+ {
5661
+ metric: {
5662
+ kind: "expr",
5663
+ expr: {
5664
+ op: "ratio",
5665
+ numerator: { kind: "field", fieldName: "Deal Size", agg: "sum" },
5666
+ denominator: { kind: "builtin", name: "mediaCount" }
5667
+ }
5668
+ },
5669
+ label: "Revenue per call",
5670
+ thresholds: [{ when: { op: "gte", value: 5e3 }, status: "good" }]
5671
+ }
5535
5672
  ]
5536
5673
  }
5537
5674
  },
5538
- // Per-widget scope override: this card ignores the dashboard scope.
5539
- { type: "field-metric", title: "EMEA avg", config: { fieldId: "<dealSizeFieldId>", aggregator: "avg", scopeOverride: { datePreset: "last7days", folderId: "<emeaFolderId>" } } }
5675
+ {
5676
+ id: "deals-table",
5677
+ type: "table",
5678
+ title: "Deals by folder",
5679
+ config: {
5680
+ rowsAre: "groups",
5681
+ groupBy: { kind: "folder" },
5682
+ columns: [
5683
+ { header: "Calls", metric: { kind: "builtin", name: "mediaCount" } },
5684
+ { header: "Pipeline", metric: { kind: "field", fieldName: "Deal Size", agg: "sum" } }
5685
+ ],
5686
+ sort: { column: "Pipeline", dir: "desc" }
5687
+ }
5688
+ },
5689
+ {
5690
+ id: "emea-vs-na",
5691
+ type: "comparison",
5692
+ title: "EMEA vs NA",
5693
+ config: {
5694
+ dimension: "folder",
5695
+ a: { source: { type: "folders", folderIds: ["<emeaFolderId>"] } },
5696
+ b: { source: { type: "folders", folderIds: ["<naFolderId>"] } },
5697
+ metrics: [{ kind: "builtin", name: "mediaCount" }]
5698
+ }
5699
+ }
5700
+ ],
5701
+ sections: [
5702
+ { id: "revenue", title: "Revenue", icon: "dollar-sign", widgetIds: ["pipeline-stats", "deals-table"] },
5703
+ { id: "regions", title: "Regions", icon: "globe", widgetIds: ["emea-vs-na"] }
5540
5704
  ]
5541
5705
  }
5542
5706
  }
@@ -5549,18 +5713,41 @@ var dashboards_exports = {};
5549
5713
  __export(dashboards_exports, {
5550
5714
  register: () => register16
5551
5715
  });
5552
- function withBuiltWidgets(body) {
5553
- if (Array.isArray(body.widgets)) {
5554
- return { ...body, widgets: buildDashboardWidgets(body.widgets) };
5716
+ function buildSource(source) {
5717
+ if (source.type === "folders") {
5718
+ if (!source.folderIds?.length) {
5719
+ throw new Error('source.type "folders" requires source.folderIds (1-50 folder ids)');
5720
+ }
5721
+ return { type: "folders", folderIds: source.folderIds };
5555
5722
  }
5556
- return body;
5723
+ return { type: source.type };
5724
+ }
5725
+ function buildSpec(input) {
5726
+ const sections = input.sections ?? [];
5727
+ const spec = {
5728
+ title: input.title,
5729
+ source: buildSource(input.source ?? { type: "workspace" }),
5730
+ dateRange: input.dateRange ?? { preset: "last30days" },
5731
+ sections,
5732
+ widgets: buildDashboardWidgets(input.widgets ?? [], sections)
5733
+ };
5734
+ if (input.description !== void 0) spec.description = input.description;
5735
+ return spec;
5736
+ }
5737
+ function pickMetadata(body) {
5738
+ const out = {};
5739
+ if (body.icon !== void 0) out.icon = body.icon;
5740
+ if (body.assignTo !== void 0) out.assignTo = body.assignTo;
5741
+ if (body.filters !== void 0) out.filters = body.filters;
5742
+ if (body.isDefault !== void 0) out.isDefault = body.isDefault;
5743
+ return out;
5557
5744
  }
5558
5745
  function register16(server, client) {
5559
5746
  const api = client ?? speakClient;
5560
5747
  registerSpeakTool(
5561
5748
  server,
5562
5749
  "list_dashboards",
5563
- "List all analytics dashboards the caller can access, including share state.",
5750
+ "List all analytics dashboards the caller can access, including share state and each dashboard's current `revision` (needed for update_dashboard).",
5564
5751
  {},
5565
5752
  {
5566
5753
  title: "List Dashboards",
@@ -5586,7 +5773,7 @@ function register16(server, client) {
5586
5773
  registerSpeakTool(
5587
5774
  server,
5588
5775
  "get_dashboard",
5589
- "Get a single dashboard's full config (widgets, filters, date range, folder scope).",
5776
+ "Get a single dashboard's full spec: title, description, source, date range, sections, widgets, and the current `revision` (pass that revision back to update_dashboard).",
5590
5777
  {
5591
5778
  dashboardId: import_zod17.z.string().min(1).describe("Dashboard business id (the dashboardId field from list_dashboards, not the Mongo _id)")
5592
5779
  },
@@ -5614,7 +5801,7 @@ function register16(server, client) {
5614
5801
  registerSpeakTool(
5615
5802
  server,
5616
5803
  "list_dashboard_widgets",
5617
- "Discovery + how-to helper for building and customizing dashboards. Returns every widget type with what it shows and the exact `config` keys it accepts (metrics, fieldId, aggregator, chartType, accentColor, scopeOverride, \u2026), the config that applies to all widgets, two complete worked example payloads (including the field-metric and metric-group cards), and tips for managing dashboards. Call this before create_dashboard / update_dashboard.",
5804
+ "Discovery + how-to helper for building and customizing dashboards. Returns every widget type with what it shows and the exact strict `config` shape it accepts, the shared vocabulary (metric grammar, groupBy, per-widget binding, filters, thresholds, sources, date-range presets, sections), design rules for composing a dashboard that reads well, two complete worked example payloads, and tips for managing dashboards. Call this before create_dashboard / update_dashboard.",
5618
5805
  {},
5619
5806
  {
5620
5807
  title: "List Dashboard Widgets",
@@ -5626,16 +5813,17 @@ function register16(server, client) {
5626
5813
  async () => {
5627
5814
  const data = {
5628
5815
  widgets: WIDGET_CATALOG,
5629
- commonConfig: COMMON_WIDGET_CONFIG,
5816
+ vocabulary: SPEC_VOCABULARY,
5817
+ designRules: DESIGN_RULES,
5630
5818
  notes: [
5631
5819
  "Pass widgets to create_dashboard as a simple ordered list; ids and grid layout are computed for you.",
5632
- "Field-driven widgets (field-distribution, field-metric, metric-group) need custom field ids from list_fields in their config.",
5633
- "field-metric uses config.aggregator; metric-group items use the key `op` (both: sum|avg|min|max|count).",
5634
- "accentColor (hex) and scopeOverride ({datePreset, folderId}) can be set on any widget's config to customize it.",
5635
- "Most other widgets render on sensible defaults with no config."
5820
+ "Widget configs are STRICT: unknown keys are rejected. Metrics reference custom fields by NAME (list_fields), not id.",
5821
+ "field-distribution requires config.fieldName; most other widgets render on valid defaults with no config.",
5822
+ `team-activity is only valid when the dashboard source (or the widget's binding.source) is {type:"team"}.`,
5823
+ "To group widgets into sections, give each sectioned widget an explicit kebab-case `id` and reference those ids in sections[].widgetIds."
5636
5824
  ],
5637
5825
  managing: [
5638
- "To customize an existing dashboard, call get_dashboard, edit the widgets array, and send the full array to update_dashboard (widgets are replaced, not merged).",
5826
+ "To edit an existing dashboard, call get_dashboard, modify the widgets/sections, and send the FULL spec to update_dashboard including the `revision` you loaded (widgets are replaced, not merged).",
5639
5827
  "To start from a working layout, duplicate_dashboard a good one, then update_dashboard to tweak it.",
5640
5828
  "share_dashboard returns a public token; chain it after the dashboard is built."
5641
5829
  ],
@@ -5647,10 +5835,11 @@ function register16(server, client) {
5647
5835
  registerSpeakTool(
5648
5836
  server,
5649
5837
  "create_dashboard",
5650
- "Create an analytics dashboard. Only `title` is required. Add widgets by listing their types (the MCP assigns ids and lays them out automatically) and scope with folderScope, dateRange, and filters. Call list_dashboard_widgets first to see the available widget types and their config keys, plus a full example.",
5838
+ `Create an analytics dashboard. Only \`title\` is required \u2014 source defaults to the whole workspace and dateRange to last30days. Add widgets by listing their types (the MCP assigns ids and lays them out automatically), scope with source ({type:"folders",folderIds} | {type:"team"} | {type:"workspace"}) and dateRange ({preset}), and optionally group widgets into sections. Design guidance: lead with a narrative widget as the first widget; group sections by the QUESTION they answer, not by widget type; don't pad \u2014 every widget earns its place (aim for 4-16 widgets on a full build); if something can't be expressed by the widget catalog, put it in a narrative widget's focus instead of faking it. Call list_dashboard_widgets first for the widget catalog, config vocabulary, design rules, and full examples.`,
5651
5839
  {
5652
- title: import_zod17.z.string().min(1).max(200).describe("Dashboard name (the only required field)"),
5653
- ...writeFields
5840
+ title: import_zod17.z.string().min(1).max(60).describe("Dashboard name, max 60 chars (the only required field)"),
5841
+ ...specFields,
5842
+ ...metadataFields
5654
5843
  },
5655
5844
  {
5656
5845
  title: "Create Dashboard",
@@ -5659,9 +5848,20 @@ function register16(server, client) {
5659
5848
  idempotentHint: false,
5660
5849
  openWorldHint: false
5661
5850
  },
5662
- async (body) => {
5851
+ async ({ title, description, source, dateRange, sections, widgets, ...metadata }) => {
5663
5852
  try {
5664
- const result = await api.post("/v1/dashboards", withBuiltWidgets(body));
5853
+ const body = {
5854
+ spec: buildSpec({
5855
+ title,
5856
+ description,
5857
+ source,
5858
+ dateRange,
5859
+ sections,
5860
+ widgets
5861
+ }),
5862
+ ...pickMetadata(metadata)
5863
+ };
5864
+ const result = await api.post("/v1/dashboards", body);
5665
5865
  return {
5666
5866
  content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }]
5667
5867
  };
@@ -5676,22 +5876,49 @@ function register16(server, client) {
5676
5876
  registerSpeakTool(
5677
5877
  server,
5678
5878
  "update_dashboard",
5679
- "Update a dashboard. Only the fields you pass are changed (partial update). NOTE: passing `widgets` replaces the entire widget set \u2014 fetch the dashboard first if you want to preserve existing widgets.",
5879
+ "Update a dashboard. Two modes. (1) Metadata-only: pass just icon/assignTo/filters/isDefault \u2014 no spec fields, no revision needed. (2) Spec update: pass the FULL spec \u2014 title, source, dateRange, sections, widgets \u2014 plus `revision`. Widgets and sections are REPLACED, not merged, so call get_dashboard first and resend everything you want to keep. `revision` is the optimistic-concurrency token from get_dashboard/list_dashboards: the server accepts the write only if it still matches, then increments it. A 409 conflict means another writer saved first \u2014 re-fetch with get_dashboard, rebuild your changes on the fresh spec, and retry with the new revision.",
5680
5880
  {
5681
5881
  dashboardId: import_zod17.z.string().min(1).describe("Dashboard business id"),
5682
- title: import_zod17.z.string().min(1).max(200).optional().describe("New dashboard name"),
5683
- ...writeFields
5882
+ title: import_zod17.z.string().min(1).max(60).optional().describe("Dashboard name \u2014 required (with revision) when updating the spec"),
5883
+ revision: import_zod17.z.number().int().nonnegative().optional().describe(
5884
+ "The revision loaded from get_dashboard. Required for spec updates; mismatch returns a 409 conflict."
5885
+ ),
5886
+ ...specFields,
5887
+ ...metadataFields
5684
5888
  },
5685
5889
  {
5686
5890
  title: "Update Dashboard",
5687
5891
  readOnlyHint: false,
5688
5892
  destructiveHint: true,
5689
- idempotentHint: true,
5893
+ idempotentHint: false,
5690
5894
  openWorldHint: false
5691
5895
  },
5692
- async ({ dashboardId, ...body }) => {
5896
+ async ({ dashboardId, title, revision, description, source, dateRange, sections, widgets, ...metadata }) => {
5693
5897
  try {
5694
- const result = await api.put(`/v1/dashboards/${dashboardId}`, withBuiltWidgets(body));
5898
+ const specTouched = title !== void 0 || description !== void 0 || source !== void 0 || dateRange !== void 0 || sections !== void 0 || widgets !== void 0;
5899
+ const body = pickMetadata(metadata);
5900
+ if (specTouched) {
5901
+ if (title === void 0 || revision === void 0) {
5902
+ throw new Error(
5903
+ "Spec updates replace the whole spec: call get_dashboard first, then pass the FULL spec (title, source, dateRange, sections, widgets) together with the loaded `revision`."
5904
+ );
5905
+ }
5906
+ body.spec = {
5907
+ ...buildSpec({
5908
+ title,
5909
+ description,
5910
+ source,
5911
+ dateRange,
5912
+ sections,
5913
+ widgets
5914
+ }),
5915
+ revision
5916
+ };
5917
+ }
5918
+ if (Object.keys(body).length === 0) {
5919
+ throw new Error("Nothing to update: pass spec fields (with revision) or metadata fields.");
5920
+ }
5921
+ const result = await api.put(`/v1/dashboards/${dashboardId}`, body);
5695
5922
  return {
5696
5923
  content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }]
5697
5924
  };
@@ -5734,7 +5961,7 @@ function register16(server, client) {
5734
5961
  registerSpeakTool(
5735
5962
  server,
5736
5963
  "duplicate_dashboard",
5737
- 'Clone an existing dashboard. The copy gets fresh widget ids, a "<name> (copy)" title, and cleared sharing. Ideal for cloning a fully-configured dashboard, then tweaking it via update_dashboard.',
5964
+ 'Clone an existing dashboard. The copy gets fresh widget ids, a "<name> (copy)" title, cleared sharing, and its revision reset to 0. Ideal for cloning a fully-configured dashboard, then tweaking it via update_dashboard.',
5738
5965
  {
5739
5966
  dashboardId: import_zod17.z.string().min(1).describe("Source dashboard business id to clone")
5740
5967
  },
@@ -5814,7 +6041,7 @@ function register16(server, client) {
5814
6041
  }
5815
6042
  );
5816
6043
  }
5817
- var import_zod17, FILTER_LIST_DESCRIPTION, widgetInputSchema, writeFields, SPEAKERS_FILTER_SCHEMA;
6044
+ var import_zod17, FILTER_LIST_DESCRIPTION, widgetInputSchema, sectionInputSchema, sourceInputSchema, dateRangeInputSchema, metadataFields, specFields, SPEAKERS_FILTER_SCHEMA;
5818
6045
  var init_dashboards = __esm({
5819
6046
  "src/tools/dashboards.ts"() {
5820
6047
  "use strict";
@@ -5825,29 +6052,61 @@ var init_dashboards = __esm({
5825
6052
  FILTER_LIST_DESCRIPTION = "Field filters. filters.filterList is an array of { fieldName, fieldOperator?, fieldValue?: string[], fieldCondition? }. Other keys pass through but only filterList is enforced.";
5826
6053
  widgetInputSchema = import_zod17.z.object({
5827
6054
  type: import_zod17.z.enum(WIDGET_TYPES).describe(
5828
- "Widget type: stat-cards | sentiment | media-list | field-distribution | upload-timeline | themes | team-activity | kpi-trend | field-metric | metric-group | notes | people | comparison | sentiment-trend"
6055
+ "Widget type: narrative | stat-cards | metric-chart | table | comparison | field-distribution | sentiment-trend | themes | people | team-activity | notes"
6056
+ ),
6057
+ id: import_zod17.z.string().max(64).optional().describe(
6058
+ "Optional explicit widget id (kebab-case). Required if you reference the widget from sections[].widgetIds; auto-generated otherwise."
5829
6059
  ),
5830
- title: import_zod17.z.string().max(200).optional().describe("Widget title (defaults to a per-type label)"),
6060
+ title: import_zod17.z.string().min(1).max(40).optional().describe("Widget title, max 40 chars (defaults to a per-type label)"),
5831
6061
  config: import_zod17.z.record(import_zod17.z.unknown()).optional().describe(
5832
- "Optional render settings. Per-type: fieldId+measure (field-distribution), fieldId+aggregator (field-metric), metrics list (stat-cards, kpi-trend, comparison, metric-group), chartType (themes), heading+content (notes). Any widget also accepts accentColor (hex) and scopeOverride ({datePreset, folderId}). Call list_dashboard_widgets for the full catalog + examples. Leave empty for sensible defaults."
6062
+ "Per-type config (STRICT \u2014 unknown keys are rejected). metric-chart: mark (line|bar|area|donut|stacked-bar) + metric + groupBy/series + thresholds; table: rowsAre + columns [{header, field|metric}]; stat-cards: tiles; field-distribution: fieldName+measure+chartType (required); narrative: focus; notes: content. Call list_dashboard_widgets for the full per-type vocabulary + metric/filter grammar. Omit for a sensible valid default (except field-distribution, which needs fieldName)."
6063
+ ),
6064
+ binding: import_zod17.z.record(import_zod17.z.unknown()).optional().describe(
6065
+ "Per-widget scope override: { source?, dateRange?: {preset}, filter? }. Omit any key to inherit the dashboard's value."
6066
+ ),
6067
+ layout: import_zod17.z.object({
6068
+ x: import_zod17.z.number().int().min(0).max(11),
6069
+ y: import_zod17.z.number().int().min(0).max(200),
6070
+ w: import_zod17.z.number().int().min(1).max(12),
6071
+ h: import_zod17.z.number().int().min(1).max(40)
6072
+ }).optional().describe(
6073
+ "Explicit 12-column grid position. Omit to auto-place two-per-row like the UI. Widgets must not overlap within a section group."
5833
6074
  )
5834
6075
  });
5835
- writeFields = {
5836
- description: import_zod17.z.string().max(2e3).optional().describe("Dashboard description"),
6076
+ sectionInputSchema = import_zod17.z.object({
6077
+ id: import_zod17.z.string().min(1).max(64).describe("Section id (kebab-case)"),
6078
+ title: import_zod17.z.string().min(1).max(24).describe("Section title, max 24 chars"),
6079
+ icon: import_zod17.z.string().min(1).max(40).describe('Kebab-case lucide icon name, e.g. "dollar-sign"'),
6080
+ widgetIds: import_zod17.z.array(import_zod17.z.string().max(64)).max(24).describe("Widget ids in this section \u2014 must match explicit `id`s set on widgets[]")
6081
+ });
6082
+ sourceInputSchema = import_zod17.z.object({
6083
+ type: import_zod17.z.enum(["folders", "team", "workspace"]).describe(
6084
+ "folders = specific folder ids; team = the caller's team scope; workspace = everything accessible"
6085
+ ),
6086
+ folderIds: import_zod17.z.array(import_zod17.z.string().min(1).max(64)).min(1).max(50).optional().describe('Folder ids \u2014 required when type is "folders", forbidden otherwise')
6087
+ }).describe(
6088
+ 'Data source: {type:"folders", folderIds:[...]} | {type:"team"} | {type:"workspace"}'
6089
+ );
6090
+ dateRangeInputSchema = import_zod17.z.object({
6091
+ preset: import_zod17.z.enum(DATE_RANGE_PRESETS).describe("One of: last7days | last30days | last3months | yearToDate | allTime")
6092
+ }).describe("Date range \u2014 strict preset only, no free-form start/end dates");
6093
+ metadataFields = {
5837
6094
  icon: import_zod17.z.string().max(200).optional().describe("Icon identifier"),
5838
- folderScope: import_zod17.z.array(import_zod17.z.string().max(100)).max(100).optional().describe("Folder ids to scope analytics to. Empty/omitted = all accessible folders."),
5839
6095
  assignTo: import_zod17.z.array(import_zod17.z.string()).max(100).optional().describe('User ids, or group ids in the "<groupId> (G)" convention, to share view access with'),
5840
- dateRange: import_zod17.z.object({
5841
- preset: import_zod17.z.string().max(50).optional(),
5842
- startDate: import_zod17.z.string().optional(),
5843
- endDate: import_zod17.z.string().optional()
5844
- }).optional().describe("Date range: { preset?, startDate?, endDate? }"),
5845
6096
  filters: import_zod17.z.record(import_zod17.z.unknown()).optional().describe(FILTER_LIST_DESCRIPTION),
5846
- widgets: import_zod17.z.array(widgetInputSchema).max(50).optional().describe(
5847
- "Widgets to place on the dashboard, in order. The MCP assigns ids and computes a tidy two-per-row grid layout matching the Speak UI. Just list the widget types you want."
5848
- ),
5849
6097
  isDefault: import_zod17.z.boolean().optional().describe("Make this the company default dashboard")
5850
6098
  };
6099
+ specFields = {
6100
+ description: import_zod17.z.string().max(280).optional().describe("Dashboard description, max 280 chars"),
6101
+ source: sourceInputSchema.optional(),
6102
+ dateRange: dateRangeInputSchema.optional(),
6103
+ sections: import_zod17.z.array(sectionInputSchema).max(12).optional().describe(
6104
+ "Optional named widget groups (tabs). Each references widgets by their explicit ids; widgets in no section form the implicit Overview group."
6105
+ ),
6106
+ widgets: import_zod17.z.array(widgetInputSchema).max(24).optional().describe(
6107
+ "Widgets to place on the dashboard, in order (max 24). The MCP assigns ids and computes a tidy two-per-row grid layout matching the Speak UI unless you pass explicit id/layout."
6108
+ )
6109
+ };
5851
6110
  SPEAKERS_FILTER_SCHEMA = {
5852
6111
  folderScope: import_zod17.z.array(import_zod17.z.string().max(100)).max(100).optional().describe("Folder ids to scope to"),
5853
6112
  startDate: import_zod17.z.string().optional().describe("ISO start date"),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@speakai/mcp-server",
3
- "version": "1.14.0",
3
+ "version": "1.15.0",
4
4
  "mcpName": "io.github.speakai/mcp-server",
5
5
  "description": "Official Speak AI MCP Server — capture meetings, search thousands of recordings, run async voice and video surveys, create clips, and automate workflows from your AI assistant.",
6
6
  "homepage": "https://mcp.speakai.co",