@speakai/mcp-server 1.34.0 → 1.34.1

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 +34 -16
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -245,7 +245,7 @@ function registerSpeakTool(server, name, description, inputSchema, annotations,
245
245
  })
246
246
  );
247
247
  }
248
- var import_zod, passthroughOutputSchema;
248
+ var import_zod, passthroughOutputSchema, fieldIdSchema, SHARED_DASHBOARD_CACHE_NOTE;
249
249
  var init_helpers = __esm({
250
250
  "src/tools/_helpers.ts"() {
251
251
  "use strict";
@@ -254,6 +254,10 @@ var init_helpers = __esm({
254
254
  passthroughOutputSchema = {
255
255
  data: import_zod.z.unknown().describe("Response payload from the Speak AI API")
256
256
  };
257
+ fieldIdSchema = import_zod.z.string().min(1).refine((value) => !/^[0-9a-fA-F]{24}$/.test(value), {
258
+ message: "This looks like the field's database _id. Use the field `id` from list_fields or create_field (12 characters)."
259
+ }).describe("Field `id` from list_fields or create_field (12 characters), never the database `_id`");
260
+ SHARED_DASHBOARD_CACHE_NOTE = "Shared dashboard links cache widget data, so field and media edits can take up to about 5 minutes to show for date ranges that include today (15 at most) and up to about 17 minutes for past ranges (60 at most); any dashboard update refreshes it at once.";
257
261
  }
258
262
  });
259
263
 
@@ -4897,7 +4901,7 @@ function register2(server, client) {
4897
4901
  callbackUrl: import_zod3.z.string().optional().describe("URL that replaces the workspace webhook's destination for this note's webhook events. It takes effect only when the workspace already has an active webhook for the event; on its own it does not create a webhook or send anything."),
4898
4902
  fields: import_zod3.z.array(
4899
4903
  import_zod3.z.object({
4900
- id: import_zod3.z.string().min(1).describe("Custom field ID"),
4904
+ id: fieldIdSchema,
4901
4905
  value: import_zod3.z.string().min(1).describe("Custom field value")
4902
4906
  })
4903
4907
  ).optional().describe("Custom field values to attach to the text note")
@@ -6724,7 +6728,7 @@ function register9(server, client) {
6724
6728
  registerSpeakTool(
6725
6729
  server,
6726
6730
  "list_fields",
6727
- "List all custom fields defined in the workspace. Each field returns a `slug` (for example `regulator_comment`) alongside its `id`, `name`, and `type`. Put `{{field.<slug>}}` in the prompt text you send and Speak substitutes that field's value for the media before the model sees it. A slug is unique per company and never changes when the field is renamed, so prefer it over the field name. A field with no slug yet resolves by `id` in the same token.",
6731
+ "List all custom fields defined in the workspace. Each field returns a `slug` (for example `regulator_comment`) alongside its `id`, `name`, and `type`. Put `{{field.<slug>}}` in the prompt text you send and Speak substitutes that field's value for the media before the model sees it. A slug is unique per company and never changes when the field is renamed, so prefer it over the field name. A field with no slug yet resolves by `id` in the same token. Every other tool that takes a field id wants this `id` (12 characters), never the database `_id`.",
6728
6732
  {},
6729
6733
  {
6730
6734
  title: "List Custom Fields",
@@ -6750,7 +6754,7 @@ function register9(server, client) {
6750
6754
  registerSpeakTool(
6751
6755
  server,
6752
6756
  "create_field",
6753
- "Create a new custom field for categorizing and tagging media.",
6757
+ "Create a new custom field for categorizing and tagging media. The response starts with the new field's `id`; use that `id` (not `_id`) wherever a field id is needed.",
6754
6758
  {
6755
6759
  name: import_zod10.z.string().min(1).describe("Display name for the field"),
6756
6760
  type: import_zod10.z.string().describe("Field type (text, number, select, etc.)"),
@@ -6772,8 +6776,12 @@ function register9(server, client) {
6772
6776
  async (body) => {
6773
6777
  try {
6774
6778
  const result = await api.post("/v1/fields", body);
6779
+ const fieldId = result.data?.data?.id;
6780
+ const idLine = fieldId ? `Field id: ${fieldId} (use this id, not _id, in other tools)
6781
+
6782
+ ` : "";
6775
6783
  return {
6776
- content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }]
6784
+ content: [{ type: "text", text: idLine + JSON.stringify(result.data, null, 2) }]
6777
6785
  };
6778
6786
  } catch (err2) {
6779
6787
  return {
@@ -6786,13 +6794,13 @@ function register9(server, client) {
6786
6794
  registerSpeakTool(
6787
6795
  server,
6788
6796
  "update_multiple_fields",
6789
- "Set custom field values across media in a single batch operation, overwriting existing values. Scope the update with `mediaIds`, or with `folderId` to update every media in that folder; when both are given only `mediaIds` is used. Empty values are skipped, so this cannot clear a field. Each value that changes fires your field_updated automations, whose steps can send email, post to Slack, call webhook URLs or run connected third-party app actions.",
6797
+ "Set custom field values across media in a single batch operation, overwriting existing values. Scope the update with `mediaIds`, or with `folderId` to update every media in that folder; when both are given only `mediaIds` is used. Empty values are skipped, so this cannot clear a field. Each value that changes fires your field_updated automations, whose steps can send email, post to Slack, call webhook URLs or run connected third-party app actions. " + SHARED_DASHBOARD_CACHE_NOTE,
6790
6798
  {
6791
6799
  folderId: import_zod10.z.string().optional().describe("Apply the field values to all media in this folder"),
6792
6800
  mediaIds: import_zod10.z.array(import_zod10.z.string()).optional().describe("Apply the field values to these specific media files"),
6793
6801
  fields: import_zod10.z.array(
6794
6802
  import_zod10.z.object({
6795
- id: import_zod10.z.string().min(1).describe("Custom field ID"),
6803
+ id: fieldIdSchema,
6796
6804
  value: import_zod10.z.unknown().describe("Value to set for the field")
6797
6805
  })
6798
6806
  ).describe("Array of field id/value pairs to set")
@@ -6823,7 +6831,7 @@ function register9(server, client) {
6823
6831
  "update_field",
6824
6832
  "Update a specific custom field by ID. `name` must always be supplied (the server replaces the field config).",
6825
6833
  {
6826
- id: import_zod10.z.string().min(1).describe("Unique identifier of the field"),
6834
+ id: fieldIdSchema,
6827
6835
  name: import_zod10.z.string().describe("Display name for the field"),
6828
6836
  type: import_zod10.z.string().optional().describe("Field type"),
6829
6837
  description: import_zod10.z.string().optional().describe("Optional description for the field"),
@@ -10191,7 +10199,7 @@ function makeWidget(item) {
10191
10199
  }
10192
10200
  return widget;
10193
10201
  }
10194
- var import_crypto, GRID_COLS, WIDGET_TYPES, DATE_RANGE_PRESETS, WIDGET_META, KEBAB_ID, AUTO_LAYOUT, WIDGET_CATALOG, SPEC_VOCABULARY, DESIGN_RULES, DASHBOARD_EXAMPLES;
10202
+ var import_crypto, GRID_COLS, WIDGET_TYPES, DATE_RANGE_PRESETS, SECTION_ICON_DESCRIPTION, WIDGET_META, KEBAB_ID, AUTO_LAYOUT, WIDGET_CATALOG, SPEC_VOCABULARY, DESIGN_RULES, DASHBOARD_EXAMPLES;
10195
10203
  var init_dashboard_widgets = __esm({
10196
10204
  "src/tools/dashboard-widgets.ts"() {
10197
10205
  "use strict";
@@ -10218,6 +10226,7 @@ var init_dashboard_widgets = __esm({
10218
10226
  "yearToDate",
10219
10227
  "allTime"
10220
10228
  ];
10229
+ SECTION_ICON_DESCRIPTION = 'Kebab-case lucide icon name. Known good: "dollar-sign", "globe", "users", "trending-up", "message-square", "star", "target", "calendar", "chart-line", "circle-play", "circle-check", "circle-alert". Lucide renamed its "<thing>-circle" icons to "circle-<thing>" (use "circle-play", not "play-circle"); an unknown name shows a blank dot.';
10221
10230
  WIDGET_META = {
10222
10231
  narrative: { w: GRID_COLS, h: 3, titleDefault: "Insights" },
10223
10232
  "stat-cards": { w: GRID_COLS, h: 3, titleDefault: "Usage overview" },
@@ -10308,7 +10317,7 @@ var init_dashboard_widgets = __esm({
10308
10317
  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) }',
10309
10318
  source: 'Dashboard data source: { type: "folders", folderIds: string[] (1-250) } | { type: "team" } | { type: "workspace" }',
10310
10319
  dateRangePresets: DATE_RANGE_PRESETS,
10311
- 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."
10320
+ sections: "Optional named groups of widgets rendered as tabs/sections (max 12): { id: kebab-case string, title: string (<=24), icon: string, widgetIds: string[] (<=24) }. icon: " + SECTION_ICON_DESCRIPTION + " 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."
10312
10321
  };
10313
10322
  DESIGN_RULES = [
10314
10323
  "Lead with a narrative widget: on a new dashboard, make it the first widget of the first section \u2014 it is the headline insight.",
@@ -10543,7 +10552,7 @@ function register18(server, client) {
10543
10552
  registerSpeakTool(
10544
10553
  server,
10545
10554
  "create_dashboard",
10546
- `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. Creating a dashboard does not share it publicly; only share_dashboard creates a public link. If settings.feedback.sheetWebhookUrl is set, each Feedback submission made on the shared dashboard is posted to that external Google Apps Script URL. Viewer settings (the settings input): ` + SETTINGS_RULES,
10555
+ `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. Creating a dashboard does not share it publicly; only share_dashboard creates a public link. If settings.feedback.sheetWebhookUrl is set, each Feedback submission made on the shared dashboard is posted to that external Google Apps Script URL. ` + SHARED_DASHBOARD_CACHE_NOTE + " Viewer settings (the settings input): " + SETTINGS_RULES,
10547
10556
  {
10548
10557
  title: import_zod20.z.string().min(1).max(60).describe("Dashboard name, max 60 chars (the only required field)"),
10549
10558
  ...specFields,
@@ -10584,7 +10593,7 @@ function register18(server, client) {
10584
10593
  registerSpeakTool(
10585
10594
  server,
10586
10595
  "update_dashboard",
10587
- "Update a dashboard. Two modes. (1) Metadata-only: pass just icon/assignTo/filters/isDefault/settings, with no spec fields and no revision. (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. If settings.feedback.sheetWebhookUrl is set, each Feedback submission made on the shared dashboard is posted to that external Google Apps Script URL. Viewer settings (the settings input): " + SETTINGS_RULES,
10596
+ "Update a dashboard. Two modes. (1) Metadata-only: pass just icon/assignTo/filters/isDefault/settings, with no spec fields and no revision. (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. If settings.feedback.sheetWebhookUrl is set, each Feedback submission made on the shared dashboard is posted to that external Google Apps Script URL. " + SHARED_DASHBOARD_CACHE_NOTE + " Viewer settings (the settings input): " + SETTINGS_RULES,
10588
10597
  {
10589
10598
  dashboardId: import_zod20.z.string().min(1).describe("Dashboard business id"),
10590
10599
  title: import_zod20.z.string().min(1).max(60).optional().describe("Dashboard name \u2014 required (with revision) when updating the spec"),
@@ -10759,7 +10768,7 @@ var init_dashboards = __esm({
10759
10768
  init_client();
10760
10769
  init_dashboard_widgets();
10761
10770
  MAX_DASHBOARD_SOURCE_FOLDERS = 250;
10762
- 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.";
10771
+ FILTER_LIST_DESCRIPTION = 'Fixed pre-filter applied to every widget on the dashboard (not a filter bar viewers can change). filters.filterList is an array of { fieldName: field id, fieldOperator: "include", fieldValue: string[] (1 or more), fieldCondition? }; a media file shows only when that field holds one of the values. Shared links apply include filters only. Other keys pass through but only filterList is enforced.';
10763
10772
  widgetInputSchema = import_zod20.z.object({
10764
10773
  type: import_zod20.z.enum(WIDGET_TYPES).describe(
10765
10774
  "Widget type: narrative | stat-cards | metric-chart | table | comparison | field-distribution | sentiment-trend | themes | people | team-activity | notes | chat-history"
@@ -10786,7 +10795,7 @@ var init_dashboards = __esm({
10786
10795
  sectionInputSchema = import_zod20.z.object({
10787
10796
  id: import_zod20.z.string().min(1).max(64).describe("Section id (kebab-case)"),
10788
10797
  title: import_zod20.z.string().min(1).max(24).describe("Section title, max 24 chars"),
10789
- icon: import_zod20.z.string().min(1).max(40).describe('Kebab-case lucide icon name, e.g. "dollar-sign"'),
10798
+ icon: import_zod20.z.string().min(1).max(40).describe(SECTION_ICON_DESCRIPTION),
10790
10799
  widgetIds: import_zod20.z.array(import_zod20.z.string().max(64)).max(24).describe("Widget ids in this section \u2014 must match explicit `id`s set on widgets[]")
10791
10800
  });
10792
10801
  sourceInputSchema = import_zod20.z.object({
@@ -10800,7 +10809,7 @@ var init_dashboards = __esm({
10800
10809
  dateRangeInputSchema = import_zod20.z.object({
10801
10810
  preset: import_zod20.z.enum(DATE_RANGE_PRESETS).describe("One of: last7days | last30days | last3months | yearToDate | allTime")
10802
10811
  }).describe("Date range \u2014 strict preset only, no free-form start/end dates");
10803
- settingsFieldIds = import_zod20.z.array(import_zod20.z.string());
10812
+ settingsFieldIds = import_zod20.z.array(fieldIdSchema);
10804
10813
  SETTINGS_RULES = "Do not pass settings unless the user explicitly asks to change this dashboard's viewer settings. Saving fields, feedback or fieldEdits moves that dashboard onto the settings flow immediately: its media pages use these groups and this Feedback setup from then on. Each section (fields, feedback, fieldEdits, labels, comments) replaces that whole section when sent; a section left out keeps its saved value. Call get_dashboard first and resend every key of the section you change; a key left out resets to its default. Get field ids from list_fields. Ids that are not the company's fields are dropped when saving and returned in droppedFieldIds. When feedback.isEnabled is true, pass a non-empty feedback.fieldIds (score fields) rather than leaving it empty. Only set feedback.sheetWebhookUrl when the user gives the Apps Script URL. fieldEdits.fieldIds may list only fields that have allowed values (the server rejects any other field with a 400) and that the dashboard's media pages show; pass an empty fieldIds to turn field editing off. Labels and comments on the shared link are off until the user asks to turn them on. Mode 'apply' (labels) or 'reply' (comments) lets a link viewer write as one of the dashboard's feedback submitter names (feedback.submitters, even while feedback itself is off), or as another typed name only when feedback.allowOtherSubmitter is true. Anyone holding the share link can pick any of those names, because the link has no sign-in (an accepted risk; every entry is marked as made via this dashboard), so confirm the names with the user before saving a write mode. With no submitter names nobody can write. Label groups that are not active refuse the whole save with a 400 rather than being dropped.";
10805
10814
  dashboardSettingsSchema = import_zod20.z.object({
10806
10815
  fields: import_zod20.z.object({
@@ -10874,7 +10883,16 @@ var init_dashboards = __esm({
10874
10883
  metadataFields = {
10875
10884
  icon: import_zod20.z.string().max(200).optional().describe("Icon identifier"),
10876
10885
  assignTo: import_zod20.z.array(import_zod20.z.string()).max(100).optional().describe('User ids, or group ids in the "<groupId> (G)" convention, to share view access with'),
10877
- filters: import_zod20.z.record(import_zod20.z.unknown()).optional().describe(FILTER_LIST_DESCRIPTION),
10886
+ filters: import_zod20.z.object({
10887
+ filterList: import_zod20.z.array(
10888
+ import_zod20.z.object({
10889
+ fieldName: fieldIdSchema,
10890
+ fieldOperator: import_zod20.z.literal(FilterOperator.INCLUDE),
10891
+ fieldValue: import_zod20.z.array(import_zod20.z.string().min(1).max(500)).min(1),
10892
+ fieldCondition: import_zod20.z.string().max(50).optional()
10893
+ })
10894
+ ).optional()
10895
+ }).passthrough().optional().describe(FILTER_LIST_DESCRIPTION),
10878
10896
  isDefault: import_zod20.z.boolean().optional().describe("Make this the owner's default dashboard. Setting true clears the default flag on the owner's other dashboards"),
10879
10897
  settings: dashboardSettingsSchema.optional()
10880
10898
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@speakai/mcp-server",
3
- "version": "1.34.0",
3
+ "version": "1.34.1",
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://docs.speakai.co/mcp",