airbyte_ops_mcp.mcp.devin_reminders

  1# Copyright (c) 2025 Airbyte, Inc., all rights reserved.
  2"""MCP tools for scheduling and cancelling Devin agent reminders.
  3
  4This module exposes reminder scheduling and cancellation as MCP tools for AI agents.
  5It is a thin wrapper around the core dispatch functions in the devin_reminders module.
  6
  7## MCP reference
  8
  9.. include:: ../../../docs/mcp-generated/devin_reminders.md
 10    :start-line: 2
 11"""
 12
 13from __future__ import annotations
 14
 15__all__: list[str] = []
 16
 17from typing import Annotated
 18
 19from fastmcp import FastMCP
 20from fastmcp_extensions import mcp_tool, register_mcp_tools
 21from pydantic import BaseModel, Field
 22
 23from airbyte_ops_mcp.devin_reminders import dispatch_cancel_reminder, dispatch_reminder
 24
 25
 26class SetDevinReminderResponse(BaseModel):
 27    """Response from the set_devin_reminder tool."""
 28
 29    success: bool = Field(description="Whether the workflow was triggered successfully")
 30    message: str = Field(description="Human-readable status message")
 31    workflow_url: str | None = Field(
 32        default=None,
 33        description="URL to view the GitHub Actions workflow file",
 34    )
 35    run_id: int | None = Field(
 36        default=None,
 37        description="GitHub Actions workflow run ID",
 38    )
 39    run_url: str | None = Field(
 40        default=None,
 41        description="Direct URL to the GitHub Actions workflow run",
 42    )
 43
 44
 45@mcp_tool(
 46    read_only=False,
 47    idempotent=False,
 48    open_world=True,
 49)
 50def set_devin_reminder(
 51    reminder_message: Annotated[
 52        str,
 53        "The reminder message to deliver. Should clearly describe what "
 54        "you need to be reminded about.",
 55    ],
 56    agent_session_url: Annotated[
 57        str,
 58        "Your Devin session URL so the reminder can be injected back into "
 59        "your session. Use the session URL from your system prompt.",
 60    ],
 61    delay_minutes: Annotated[
 62        int | None,
 63        "Number of minutes until the reminder fires. Must be a positive "
 64        "multiple of 30, up to 10080 (7 days). Examples: 30, 60, 120, 1440. "
 65        "Mutually exclusive with remind_at_local_time.",
 66    ] = None,
 67    remind_at_local_time: Annotated[
 68        str | None,
 69        "Date-time in local time when the reminder should fire. "
 70        "At Airbyte, local time is always Pacific (America/Los_Angeles). "
 71        "Accepts '2026-04-02 09:00' (24-hour), "
 72        "'2026-04-02 9:00 AM' (12-hour), or ISO-like 'YYYY-MM-DDTHH:MM'. "
 73        "Must be in the future and within 7 days. "
 74        "Mutually exclusive with delay_minutes. "
 75        "PREFERRED — use this instead of delay_minutes to avoid "
 76        "timezone-conversion errors.",
 77    ] = None,
 78    slack_users_cc: Annotated[
 79        str | None,
 80        "Optional comma-delimited list of Slack user tags to CC on the "
 81        "reminder notification. Example: '<@U12345>, <@U67890>'.",
 82    ] = None,
 83) -> SetDevinReminderResponse:
 84    """Schedule a reminder that fires at a specified time or after a delay.
 85
 86    Creates a reminder that will be delivered back to your Devin session
 87    and posted to the #devin-reminders Slack channel when the time arrives.
 88    Reminders are checked every 30 minutes via a cron schedule.
 89
 90    Exactly one of `delay_minutes` or `remind_at_local_time` must be provided.
 91    Prefer `remind_at_local_time` (Pacific local time) over `delay_minutes`
 92    to avoid timezone-conversion mistakes — unless the user explicitly
 93    asks for a reminder in N minutes.
 94
 95    The reminder is stored as a GitHub Actions artifact and processed by
 96    the devin-reminders-action. When the reminder is due, it injects a
 97    message into the originating Devin session and sends a Slack notification.
 98
 99    Use this tool when you need to schedule a follow-up action, check on
100    a long-running process, or remind yourself about a task.
101    """
102    try:
103        result = dispatch_reminder(
104            delay_minutes=delay_minutes,
105            remind_at_local_time=remind_at_local_time,
106            reminder_message=reminder_message,
107            agent_session_url=agent_session_url,
108            slack_users_cc=slack_users_cc,
109        )
110    except ValueError as e:
111        return SetDevinReminderResponse(
112            success=False,
113            message=f"Invalid input: {e}",
114        )
115
116    if remind_at_local_time:
117        time_desc = f"at {remind_at_local_time} Pacific"
118    else:
119        time_desc = f"in {delay_minutes} minutes"
120
121    view_url = result.run_url or result.workflow_url
122    return SetDevinReminderResponse(
123        success=True,
124        message=(
125            f"Reminder scheduled to fire {time_desc}. "
126            f"View progress at: {view_url}\n\n"
127            f"To cancel pending reminders for this session, use the "
128            f"`cancel_devin_reminder` tool."
129        ),
130        workflow_url=result.workflow_url,
131        run_id=result.run_id,
132        run_url=result.run_url,
133    )
134
135
136class CancelDevinReminderResponse(BaseModel):
137    """Response from the cancel_devin_reminder tool."""
138
139    success: bool = Field(
140        description="Whether the cancel workflow was triggered successfully"
141    )
142    message: str = Field(description="Human-readable status message")
143    workflow_url: str | None = Field(
144        default=None,
145        description="URL to view the GitHub Actions workflow file",
146    )
147    run_id: int | None = Field(
148        default=None,
149        description="GitHub Actions workflow run ID",
150    )
151    run_url: str | None = Field(
152        default=None,
153        description="Direct URL to the GitHub Actions workflow run",
154    )
155
156
157@mcp_tool(
158    read_only=False,
159    idempotent=False,
160    open_world=True,
161)
162def cancel_devin_reminder(
163    agent_session_url: Annotated[
164        str,
165        "Your Devin session URL. Use the session URL from your system prompt. "
166        "Required together with cancel_guids.",
167    ],
168    cancel_guids: Annotated[
169        list[str],
170        "List of reminder GUIDs to cancel. You can get GUIDs from "
171        "the reminder creation response or from the reminders list.",
172    ],
173) -> CancelDevinReminderResponse:
174    """Cancel pending Devin reminders by session URL and specific GUIDs.
175
176    Removes matching reminders so they will not fire. Use this when instructed
177    to stop reminders, or when a reminder is no longer needed.
178
179    Both agent_session_url and cancel_guids are required. Only reminders
180    matching the session URL AND present in the GUID list are cancelled.
181    """
182    try:
183        result = dispatch_cancel_reminder(
184            agent_session_url=agent_session_url,
185            cancel_guids=cancel_guids,
186        )
187    except ValueError as e:
188        return CancelDevinReminderResponse(
189            success=False,
190            message=f"Invalid input: {e}",
191        )
192
193    view_url = result.run_url or result.workflow_url
194    guid_list = ", ".join(cancel_guids)
195    return CancelDevinReminderResponse(
196        success=True,
197        message=(
198            f"Cancel workflow triggered for GUIDs [{guid_list}] "
199            f"in session {agent_session_url}. View progress at: {view_url}"
200        ),
201        workflow_url=result.workflow_url,
202        run_id=result.run_id,
203        run_url=result.run_url,
204    )
205
206
207def register_devin_reminder_tools(app: FastMCP) -> None:
208    """Register Devin reminder tools with the FastMCP app."""
209    register_mcp_tools(app, mcp_module=__name__)