grain: AI-optimize MCP action set

components/grain/actions/download-recording/download-recording.mjs

@@ -0,0 +1,64 @@
+import fs from "fs";
+import grain from "../../grain.app.mjs";
+
+const EXTENSION_BY_CONTENT_TYPE = {
+  "video/mp4": "mp4",
+  "video/quicktime": "mov",
+  "audio/mpeg": "mp3",
+  "audio/mp4": "m4a",
+};
+const DEFAULT_EXTENSION = "mp4";
+
+export default {
+  key: "grain-download-recording",
+  name: "Download Recording",
+  description: "Downloads a Grain recording's media file (video or audio) and writes it to File Stash, returning `filePath`, `filename`, and `contentType`."
+    + " Only recordings with processed media have a downloadable file — check `media_type` (`video` or `audio`, not `transcript`) from **List Recordings** or **Get Recording** first."
+    + " Use **Get Transcript** instead if you only need the spoken content, not the media file itself."
+    + " Example: `recordingId: \"8a089fcb-0961-4393-8da2-f0db5f8cfd79\"` downloads the file and returns `{\"filePath\": \"/tmp/grain-recording-8a089fcb-....mp4\", \"filename\": \"grain-recording-8a089fcb-....mp4\", \"contentType\": \"video/mp4\"}`."
+    + " [See the documentation](https://developers.grain.com/#download-recording)",
+  version: "0.0.1",
+  ai: "optimized",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    grain,
+    recordingId: {
+      propDefinition: [
+        grain,
+        "recordingId",
+      ],
+    },
+    syncDir: {
+      type: "dir",
+      accessMode: "write",
+      sync: true,
+    },
+  },
+  async run({ $ }) {
+    const response = await this.grain.downloadRecording({
+      $,
+      recordingId: this.recordingId,
+      responseType: "arraybuffer",
+      returnFullResponse: true,
+    });
+
+    const contentType = response.headers["content-type"];
+    const extension = EXTENSION_BY_CONTENT_TYPE[contentType] ?? DEFAULT_EXTENSION;
+    const filename = `grain-recording-${this.recordingId}.${extension}`;
+    const filePath = `${process.env.STASH_DIR || "/tmp"}/${filename}`;
+
+    fs.writeFileSync(filePath, Buffer.from(response.data));
+
+    $.export("$summary", `Downloaded recording ${this.recordingId} (${filename})`);
+    return {
+      filePath,
+      filename,
+      contentType,
+    };
+  },
+};

components/grain/actions/get-recording/get-recording.mjs

@@ -6,8 +6,10 @@ export default {
   description: "Fetches a specific recording by its ID from Grain, returning its metadata (title, times, URL, tags, teams, meeting type)."
     + " Enable the optional include props to add highlights, participants, AI action items, AI summary, calendar event, HubSpot data, or screenshares to the response."
     + " Use **List Recordings** to find recording IDs, and **Get Transcript** to fetch the full transcript."
+    + " Example: `recordingId: \"pppp6666-qq77-rr88-ss99-tttt00000000\"` with `aiSummary: true` returns the recording's metadata plus `{\"ai_summary\": {\"text\": \"...\"}}`."
     + " [See the documentation](https://developers.grain.com/#get-recording)",
-  version: "1.0.0",
+  version: "1.0.1",
+  ai: "optimized",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/grain/actions/get-transcript/get-transcript.mjs

@@ -8,8 +8,10 @@ export default {
     + " The `json` format returns structured segments with speaker, participant ID, start/end times in milliseconds, and text;"
     + " `txt`, `vtt`, and `srt` return plain text or subtitle formats."
     + " Use **List Recordings** to find recording IDs; use **Get Recording** for the recording's metadata instead of its transcript."
+    + " Example: `recordingId: \"pppp6666-qq77-rr88-ss99-tttt00000000\"` with `format: \"txt\"` returns plain text like `\"Speaker 1: Thanks for joining today...\"`."
     + " [See the documentation](https://developers.grain.com/#get-recording-transcript-json)",
-  version: "0.0.1",
+  version: "0.0.2",
+  ai: "optimized",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/grain/actions/list-meeting-types/list-meeting-types.mjs

@@ -0,0 +1,31 @@
+import grain from "../../grain.app.mjs";
+
+export default {
+  key: "grain-list-meeting-types",
+  name: "List Meeting Types",
+  description: "Lists the meeting types configured in your Grain workspace (id, name, scope), where scope is `internal` or `external`."
+    + " Use this to understand how recordings are categorized, or to resolve a meeting type's ID for filtering."
+    + " Example: returns `[{\"id\": \"e8b894a9-7ecf-4330-a282-527c085618fd\", \"name\": \"Sales\", \"scope\": \"external\"}, {\"id\": \"815747d1-9e25-40f6-a3b8-e1908e25151e\", \"name\": \"1:1s\", \"scope\": \"internal\"}]`."
+    + " [See the documentation](https://developers.grain.com/#list-meeting-types)",
+  version: "0.0.1",
+  ai: "optimized",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    grain,
+  },
+  async run({ $ }) {
+    const { meeting_types: meetingTypes } = await this.grain.listMeetingTypes({
+      $,
+    });
+
+    $.export("$summary", `Found ${meetingTypes.length} meeting type${meetingTypes.length === 1
+      ? ""
+      : "s"}`);
+    return meetingTypes;
+  },
+};

components/grain/actions/list-recordings/list-recordings.mjs

@@ -6,8 +6,12 @@ export default {
   description: "Lists Grain recordings, optionally filtered by start datetime range (ISO8601), title search, or participant scope."
     + " Automatically paginates and returns up to Max Results recordings."
     + " Use this to find recording IDs for **Get Recording** and **Get Transcript**."
+    + " Example: `titleSearch: \"Acme\"` returns recordings like"
+    + " `[{\"id\": \"pppp6666-qq77-rr88-ss99-tttt00000000\", \"title\": \"Acme Renewal Call\", \"start_datetime\": \"2026-01-05T15:00:00Z\", \"media_type\": \"video\", ...}]`."
+    + " Pass `fields` to return only the fields you need instead of the full object."
     + " [See the documentation](https://developers.grain.com/#list-recordings)",
-  version: "0.0.1",
+  version: "0.0.2",
+  ai: "optimized",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -52,6 +56,13 @@ export default {
       default: 100,
       min: 1,
     },
+    fields: {
+      type: "string[]",
+      label: "Fields",
+      description: "Only include these fields in each returned recording (e.g. `[\"id\", \"title\", \"start_datetime\"]`)."
+        + " Omit fields to return the full recording object for each result.",
+      optional: true,
+    },
   },
   async run({ $ }) {
     const filter = {
@@ -84,6 +95,15 @@ export default {
     $.export("$summary", `Successfully fetched ${recordings.length} recording${recordings.length === 1
       ? ""
       : "s"}`);
-    return recordings;
+
+    if (!this.fields?.length) {
+      return recordings;
+    }
+    return recordings.map((recording) => Object.fromEntries(
+      this.fields.map((field) => [
+        field,
+        recording[field],
+      ]),
+    ));
   },
 };

components/grain/actions/list-teams/list-teams.mjs

@@ -0,0 +1,31 @@
+import grain from "../../grain.app.mjs";
+
+export default {
+  key: "grain-list-teams",
+  name: "List Teams",
+  description: "Lists the teams in your Grain workspace (id, name)."
+    + " Use this to resolve a team's ID before sharing a recording with it via **Manage Recording Sharing**."
+    + " Example: returns `[{\"id\": \"a414c333-c9fe-4fdc-9131-fb31796699b2\", \"name\": \"Pipedream\"}]`."
+    + " [See the documentation](https://developers.grain.com/#list-teams)",
+  version: "0.0.1",
+  ai: "optimized",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    grain,
+  },
+  async run({ $ }) {
+    const { teams } = await this.grain.listTeams({
+      $,
+    });
+
+    $.export("$summary", `Found ${teams.length} team${teams.length === 1
+      ? ""
+      : "s"}`);
+    return teams;
+  },
+};

components/grain/actions/list-users/list-users.mjs

@@ -0,0 +1,31 @@
+import grain from "../../grain.app.mjs";
+
+export default {
+  key: "grain-list-users",
+  name: "List Users",
+  description: "Lists the users in your Grain workspace (id, name, email)."
+    + " Use this to resolve a user's ID before sharing a recording with them via **Manage Recording Sharing**, or to identify who's who when reviewing recording participants."
+    + " Example: returns `[{\"id\": \"d91b7ed0-a149-425c-9623-0664148e4fc1\", \"name\": \"Danny Archer\", \"email\": \"darcher@pipedream.com\"}]`."
+    + " [See the documentation](https://developers.grain.com/#list-users)",
+  version: "0.0.1",
+  ai: "optimized",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    grain,
+  },
+  async run({ $ }) {
+    const { users } = await this.grain.listUsers({
+      $,
+    });
+
+    $.export("$summary", `Found ${users.length} user${users.length === 1
+      ? ""
+      : "s"}`);
+    return users;
+  },
+};

components/grain/actions/manage-recording-sharing/manage-recording-sharing.mjs

@@ -0,0 +1,83 @@
+import grain from "../../grain.app.mjs";
+
+export default {
+  key: "grain-manage-recording-sharing",
+  name: "Manage Recording Sharing",
+  description: "Shares or unshares a recording with a specific user or team."
+    + " Use **List Recordings** to find the recording's ID, and **List Users** or **List Teams** to resolve the target's ID."
+    + " Set `operation` to `share` to grant access or `unshare` to revoke it, and `targetType` to `user` or `team`."
+    + " Example: `recordingId: \"pppp6666-qq77-rr88-ss99-tttt00000000\", operation: \"share\", targetType: \"user\", targetId: \"d91b7ed0-a149-425c-9623-0664148e4fc1\"` shares the recording with that user and returns `{\"success\": true}`."
+    + " [See the documentation](https://developers.grain.com/#share-recording-to-a-team)",
+  version: "0.0.1",
+  ai: "optimized",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  type: "action",
+  props: {
+    grain,
+    recordingId: {
+      propDefinition: [
+        grain,
+        "recordingId",
+      ],
+    },
+    operation: {
+      type: "string",
+      label: "Operation",
+      description: "Whether to share or unshare the recording.",
+      options: [
+        "share",
+        "unshare",
+      ],
+    },
+    targetType: {
+      type: "string",
+      label: "Target Type",
+      description: "Whether the target is a user or a team.",
+      options: [
+        "user",
+        "team",
+      ],
+    },
+    targetId: {
+      type: "string",
+      label: "Target ID",
+      description: "The ID of the user (from **List Users**) or team (from **List Teams**) to share or unshare the recording with. E.g. `d91b7ed0-a149-425c-9623-0664148e4fc1`.",
+    },
+  },
+  async run({ $ }) {
+    if (this.operation === "share") {
+      await this.grain.shareRecording({
+        $,
+        recordingId: this.recordingId,
+        targetType: this.targetType,
+        data: {
+          [`${this.targetType}_id`]: this.targetId,
+        },
+      });
+    } else {
+      await this.grain.unshareRecording({
+        $,
+        recordingId: this.recordingId,
+        targetType: this.targetType,
+        targetId: this.targetId,
+      });
+    }
+
+    const summary = `${this.operation === "share"
+      ? "Shared"
+      : "Unshared"} recording ${this.recordingId} ${this.operation === "share"
+      ? "with"
+      : "from"} ${this.targetType} ${this.targetId}`;
+    $.export("$summary", summary);
+    return {
+      recordingId: this.recordingId,
+      operation: this.operation,
+      targetType: this.targetType,
+      targetId: this.targetId,
+    };
+  },
+};