added webhook and indexing

Author: aline-pereira

grain/README.md

@@ -13,6 +13,7 @@ The Grain MCP provides seamless integration with [Grain](https://grain.com), all
 - 📊 **Rich Metadata**: Access titles, dates, durations, participants, and summaries
 - 🎯 **Filter by Status**: View only ready recordings or check processing status
 - 📅 **Date Range Filtering**: Find meetings within specific time periods
+- 🔔 **Real-time Webhooks**: Receive automatic notifications when recordings are created, updated, or processed
 
 ## Authentication
 
@@ -121,6 +122,31 @@ Each recording object includes:
 }
 ```
 
+## Webhooks
+
+This MCP automatically sets up webhooks with Grain to receive real-time notifications about your recordings. When you install or configure this MCP, it will:
+
+1. **Automatically create webhooks** pointing to the Deco Mesh
+2. **Listen for events** such as:
+   - `recording.created` - When a new recording starts
+   - `recording.updated` - When recording metadata changes
+   - `recording.processed` - When transcription and AI processing completes
+
+3. **Process events** through the `eventHandler` where you can add custom logic
+
+### How Webhooks Work
+
+```
+Grain Event → Grain API → Mesh → Your MCP → Custom Logic
+```
+
+The webhook URL is automatically constructed as:
+```
+${meshUrl}/events/grain_recording?sub=${connectionId}
+```
+
+This ensures events are routed to your specific MCP instance.
+
 ## Use Cases
 
 ### Meeting Analytics
@@ -138,6 +164,9 @@ Identify meetings that require follow-up based on participants, topics, or actio
 ### Team Insights
 Track team collaboration by analyzing who attends which meetings and how often different people interact.
 
+### Real-time Notifications
+Get instant alerts when new recordings are ready, enabling immediate action on important meetings.
+
 ## API Reference
 
 The Grain API uses the following structure:

grain/app.json

@@ -7,6 +7,16 @@
   },
   "description": "Grain App Connection - Access and manage your meeting recordings",
   "icon": "https://grain.com/favicon.ico",
-  "unlisted": false
+  "unlisted": false,
+  "bindings": [
+    {
+      "type": "mcp",
+      "name": "DATABASE",
+      "app_name": "@deco/postgres"
+    }
+  ]
 }
 
+
+
+

grain/server/constants.ts

@@ -1,17 +1,18 @@
 /**
- * Grain API constants and configuration
  * API Documentation: https://developers.grain.com/
- *
- * IMPORTANT: Grain API uses GET with query parameters!
- * Correct endpoint: /_/public-api/recordings (ONE underscore, no /v2)
  */
-
 export const GRAIN_BASE_URL = "https://api.grain.com";
-export const GRAIN_LIST_RECORDINGS_ENDPOINT = "/_/public-api/recordings"; // GET method!
-export const GRAIN_RECORDING_ENDPOINT = "/_/public-api/recordings"; // GET method
+export const GRAIN_LIST_RECORDINGS_ENDPOINT = "/_/public-api/recordings";
+export const GRAIN_RECORDING_ENDPOINT = "/_/public-api/recordings";
 export const GRAIN_TRANSCRIPT_ENDPOINT =
   "/_/public-api/recordings/:id/transcript";
 
-// Default pagination
+// Webhook endpoints (API v2)
+export const GRAIN_CREATE_WEBHOOK_ENDPOINT = "/_/public-api/v2/hooks/create";
+export const GRAIN_LIST_WEBHOOKS_ENDPOINT = "/_/public-api/v2/hooks";
+export const GRAIN_DELETE_WEBHOOK_ENDPOINT = "/_/public-api/v2/hooks";
+
+export const GRAIN_API_VERSION = "2025-10-31";
+
 export const DEFAULT_PAGE_SIZE = 50;
 export const MAX_PAGE_SIZE = 100;

grain/server/lib/grain-client.ts

@@ -7,12 +7,18 @@ import {
   GRAIN_BASE_URL,
   GRAIN_LIST_RECORDINGS_ENDPOINT,
   GRAIN_RECORDING_ENDPOINT,
+  GRAIN_CREATE_WEBHOOK_ENDPOINT,
+  GRAIN_LIST_WEBHOOKS_ENDPOINT,
+  GRAIN_DELETE_WEBHOOK_ENDPOINT,
+  GRAIN_API_VERSION,
 } from "../constants.ts";
 import type {
   ListRecordingsParams,
   ListRecordingsResponse,
-  Recording,
   RecordingDetails,
+  WebhookConfig,
+  CreateWebhookResponse,
+  ListWebhooksResponse,
 } from "./types.ts";
 
 export interface GrainClientConfig {
@@ -30,13 +36,20 @@ export class GrainClient {
 
   /**
    * Build headers for API requests
+   * Note: API v2 requires the Public-Api-Version header
    */
-  private getHeaders(): Record<string, string> {
-    return {
+  private getHeaders(includeApiVersion = false): Record<string, string> {
+    const headers: Record<string, string> = {
       Authorization: `Bearer ${this.apiKey}`,
       "Content-Type": "application/json",
       Accept: "application/json",
     };
+
+    if (includeApiVersion) {
+      headers["Public-Api-Version"] = GRAIN_API_VERSION;
+    }
+
+    return headers;
   }
 
   /**
@@ -147,4 +160,74 @@ export class GrainClient {
       search: query,
     });
   }
+
+  /**
+   * Create a webhook to receive real-time notifications from Grain
+   * API v2 endpoint: POST /_/public-api/v2/hooks/create
+   *
+   * Note: Grain performs a reachability test on the provided URL.
+   * The endpoint MUST respond with a 2xx status for the hook to be created.
+   *
+   * @param config - Webhook configuration with hook_url and optional filter/include
+   * @returns Created webhook details
+   */
+  async createWebhook(config: WebhookConfig): Promise<CreateWebhookResponse> {
+    const response = await fetch(
+      `${this.baseUrl}${GRAIN_CREATE_WEBHOOK_ENDPOINT}`,
+      {
+        method: "POST",
+        headers: this.getHeaders(true),
+        body: JSON.stringify(config),
+      },
+    );
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      throw new Error(`Grain API error (${response.status}): ${errorText}`);
+    }
+
+    return (await response.json()) as CreateWebhookResponse;
+  }
+
+  /**
+   * List all webhooks configured for this account
+   * API v2 endpoint: POST /_/public-api/v2/hooks (yes, it's POST not GET!)
+   * @returns List of webhooks
+   */
+  async listWebhooks(): Promise<ListWebhooksResponse> {
+    const response = await fetch(
+      `${this.baseUrl}${GRAIN_LIST_WEBHOOKS_ENDPOINT}`,
+      {
+        method: "POST", // Grain API v2 uses POST for listing hooks
+        headers: this.getHeaders(true),
+      },
+    );
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      throw new Error(`Grain API error (${response.status}): ${errorText}`);
+    }
+
+    return (await response.json()) as ListWebhooksResponse;
+  }
+
+  /**
+   * Delete a webhook by its ID
+   * API v2 endpoint: DELETE /_/public-api/v2/hooks/{id}
+   * @param webhookId - The ID of the webhook to delete
+   */
+  async deleteWebhook(webhookId: string): Promise<void> {
+    const response = await fetch(
+      `${this.baseUrl}${GRAIN_DELETE_WEBHOOK_ENDPOINT}/${webhookId}`,
+      {
+        method: "DELETE",
+        headers: this.getHeaders(true),
+      },
+    );
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      throw new Error(`Grain API error (${response.status}): ${errorText}`);
+    }
+  }
 }