diff --git a/app/en/resources/integrations/_meta.tsx b/app/en/resources/integrations/_meta.tsx index 9c0691602..872659842 100644 --- a/app/en/resources/integrations/_meta.tsx +++ b/app/en/resources/integrations/_meta.tsx @@ -42,6 +42,9 @@ const meta: MetaRecord = { "customer-support": { title: "Customer Support", }, + hospitality: { + title: "Retail & Hospitality", + }, "-- Submit your Server": { type: "separator", title: "Submit your server", diff --git a/app/en/resources/integrations/hospitality/_meta.tsx b/app/en/resources/integrations/hospitality/_meta.tsx new file mode 100644 index 000000000..0367ed23d --- /dev/null +++ b/app/en/resources/integrations/hospitality/_meta.tsx @@ -0,0 +1,9 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "toast-api": { + title: "Toast POS API", + }, +}; + +export default meta; diff --git a/app/en/resources/integrations/hospitality/toast-api/page.mdx b/app/en/resources/integrations/hospitality/toast-api/page.mdx new file mode 100644 index 000000000..14b157e83 --- /dev/null +++ b/app/en/resources/integrations/hospitality/toast-api/page.mdx @@ -0,0 +1,492 @@ +# ToastApi + +import StarterToolInfo from "@/app/_components/starter-tool-info"; +import ToolInfo from "@/app/_components/tool-info"; +import TableOfContents from "@/app/_components/table-of-contents"; +import ToolFooter from "@/app/_components/tool-footer"; +import { Callout } from "nextra/components"; + + + + + +The ToastApi MCP Server provides a comprehensive suite of tools for managing restaurant operations through the Toast POS platform. Users can efficiently perform actions such as: + +- **Orders**: Create, retrieve, void orders, and manage discounts +- **Menus**: Access menu configurations, items, and pricing +- **Kitchen**: Manage prep stations and kitchen display configurations +- **Labor**: Handle employee data, shifts, jobs, and time entries +- **Inventory**: Track and update stock levels for menu items +- **Cash Management**: View cash drawer entries and bank deposits +- **Restaurants**: Access restaurant configurations and management groups + +This server is designed to streamline restaurant management and enable AI-powered automation of hospitality operations. + +## Authentication + +The Arcade Toast API MCP Server requires credentials from the [Toast Developer Portal](https://doc.toasttab.com/doc/devguide/authentication.html). Toast uses a **client credentials** OAuth2 flow. Authentication is handled automatically - you just need to provide your client credentials. + +### Required Secrets + +| Secret | Description | +|--------|-------------| +| `TOAST_CLIENT_ID` | Your Toast API client identifier | +| `TOAST_CLIENT_SECRET` | Your Toast API client secret | + + + Bearer tokens are fetched automatically for each API request using your client credentials. + You don't need to manage token expiration or refresh - it's handled for you! + + +### How to Obtain Your Credentials + +1. **Apply for Toast API Access** + - Visit the [Toast Developer Portal](https://pos.toasttab.com/developers) + - Submit an integration request for API access + - Toast will review and approve your application + +2. **Receive API Credentials** + - Once approved, you'll receive your `clientId` and `clientSecret` + - These credentials identify your integration to Toast + - Configure them as `TOAST_CLIENT_ID` and `TOAST_CLIENT_SECRET` secrets in Arcade + +3. **Restaurant External ID** + - Most API calls require a `restaurant_external_id` parameter + - This is the Toast GUID for the specific restaurant location + - Obtain this from your Toast account or via `get_restaurants_in_group` + + + Toast API access requires approval from Toast and is typically available to + registered Toast partners and integrators. Contact Toast directly for access. + + +For more details, see the [Toast API Authentication Guide](https://doc.toasttab.com/doc/devguide/authentication.html). + +## Toast API Scope Coverage + +This toolkit supports the following Toast API scopes: + +| Scope | Supported | Tools | +|-------|-----------|-------| +| `cash_management:read` | Yes | `get_cash_entries`, `get_cash_deposits` | +| `configuration:read` | Yes | `get_restaurant_info`, `get_restaurants_in_group` | +| `menus:read` | Yes | `get_menus`, `get_menu_metadata` | +| `restaurant_availability:read` | Yes | `get_online_ordering_availability` | +| `orders:read` / `orders:write` | Yes | `get_order`, `get_orders_bulk`, `create_order`, `void_order` | +| `kitchen:read` | Yes | `get_prep_stations`, `get_prep_station` | +| `labor:read` | Yes | `get_employees`, `get_employee`, `get_shifts`, `get_jobs`, `get_time_entries` | +| `stock:read` / `stock:write` | Yes | `get_inventory`, `update_inventory` | +| `loyalty:read` | Not supported | See note below | + + + **Loyalty API Limitation**: The `loyalty:read` scope is not currently supported. The Toast Loyalty Integration API is a **webhook-based** system where Toast sends loyalty transaction events to your endpoint - it is not a read API that can be called to retrieve loyalty data. If you need loyalty functionality, contact Toast directly about their loyalty data access options. + + +## Available Tools + + + + + If you need to perform an action that's not listed here, you can [get in touch + with us](mailto:contact@arcade.dev) to request a new tool, or [create your own + tools](/guides/create-tools/tool-basics/build-mcp-server). + + +## ToastApi.get_order + +Retrieve detailed information about a single order from Toast POS. + +Returns comprehensive order data including checks, items, payments, and other order details for a specific order identified by its GUID. + +**Parameters** + +- **order_guid** (`string`, required): The unique Toast platform identifier (GUID) for the order. +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_orders_bulk + +Retrieve multiple orders from Toast POS in bulk. + +Returns an array of orders based on filter criteria such as business date, time range, or modification date. Useful for syncing order data or generating reports. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **business_date** (`string`, optional): Business date in YYYYMMDD format. +- **start_date** (`string`, optional): Start of date/time range in ISO 8601 format. +- **end_date** (`string`, optional): End of date/time range in ISO 8601 format. +- **page_token** (`string`, optional): Pagination token from previous response. +- **page_size** (`integer`, optional): Number of orders per page (max 100). + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.create_order + +Create a new order in Toast POS. + +Submits a new order to the Toast platform. The order can include checks, menu items, modifiers, and other order details. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **order_data** (`object`, required): Order data including checks, entityType, and other properties. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.void_order + +Void an existing order in Toast POS. + +Marks an order as voided, which cancels the order and removes it from active operations. The order record is retained for reporting purposes. + +**Parameters** + +- **order_guid** (`string`, required): The unique Toast platform identifier (GUID) for the order to void. +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_applicable_discounts + +Retrieve discounts that can be applied to an order. + +Returns a list of discounts that are eligible to be applied to a given order or check based on the current order state and restaurant configuration. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **discount_request** (`object`, required): Order context for determining applicable discounts. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_prep_stations + +Retrieve all prep stations configured for a restaurant. + +Returns the configuration for every prep station (kitchen printer or KDS device location) that has been created for the specified restaurant. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **page_token** (`string`, optional): Pagination token from previous response. +- **last_modified** (`string`, optional): Filter by modification date (ISO 8601). + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_prep_station + +Retrieve configuration for a single prep station. + +Returns detailed configuration for a specific prep station (kitchen printer or KDS device location) identified by its GUID. + +**Parameters** + +- **prep_station_guid** (`string`, required): The unique Toast platform identifier (GUID) for the prep station. +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_menus + +Retrieve all menus for a restaurant. + +Returns a fully resolved set of menus for the specified restaurant location, including menu groups, menu items, modifiers, and pricing information. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **last_modified** (`string`, optional): Return only menus modified after this timestamp. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_menu_metadata + +Retrieve the last modified timestamp for restaurant menus. + +Returns metadata about when the menus were last updated. Useful for determining if menu data needs to be refreshed without fetching the full menu payload. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_restaurant_info + +Retrieve detailed configuration information for a restaurant. + +Returns comprehensive restaurant data including name, location, hours, schedules, delivery settings, online ordering configuration, and prep times. + +**Parameters** + +- **restaurant_guid** (`string`, required): The Toast GUID of the restaurant. +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **include_archived** (`boolean`, optional): Include archived restaurants. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_restaurants_in_group + +Retrieve all restaurants in a management group. + +Returns an array of restaurant identifiers for all restaurants that belong to a specified restaurant management group. + +**Parameters** + +- **management_group_guid** (`string`, required): The GUID of the restaurant management group. +- **restaurant_external_id** (`string`, required): The Toast GUID of one restaurant in the management group. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_employees + +Retrieve all employees for a restaurant. + +Returns a list of all employees configured at the restaurant, including their basic information, job assignments, and wage settings. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_employee + +Retrieve detailed information about a single employee. + +Returns comprehensive details about a specific employee including their personal information, job assignments, and wage configurations. + +**Parameters** + +- **employee_id** (`string`, required): The unique Toast identifier for the employee. +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_shifts + +Retrieve scheduled shifts for a restaurant. + +Returns shift data for employees at the restaurant, filtered by date range. Useful for scheduling and labor management. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **start_date** (`string`, optional): Filter shifts starting on or after this date (YYYY-MM-DD). +- **end_date** (`string`, optional): Filter shifts ending on or before this date (YYYY-MM-DD). + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_jobs + +Retrieve all job types configured for a restaurant. + +Returns a list of job roles defined for the restaurant, such as Server, Cook, Manager, etc. These jobs are used to define employee positions and wages. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_time_entries + +Retrieve time entries (clock-in/clock-out records) for a restaurant. + +Returns time tracking records for employees, useful for payroll processing and labor cost analysis. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **start_date** (`string`, optional): Filter entries starting on or after this date (YYYY-MM-DD). +- **end_date** (`string`, optional): Filter entries ending on or before this date (YYYY-MM-DD). + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_inventory + +Retrieve inventory status for menu items at a restaurant. + +Returns the current inventory status for menu items, including quantity on hand and whether items are marked as out of stock. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **status** (`string`, optional): Filter by status: `IN_STOCK`, `OUT_OF_STOCK`, or `QUANTITY`. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.update_inventory + +Update inventory status for menu items at a restaurant. + +Allows you to update the stock status or quantity for one or more menu items. Useful for marking items as out of stock or adjusting quantity levels. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **inventory_updates** (`array`, required): Array of inventory update objects with `menuItemGuid` and `status`. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_online_ordering_availability + +Retrieve online ordering availability for a restaurant. + +Returns information about whether a restaurant is currently accepting online orders, including hours and any temporary closures or busy periods. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_cash_entries + +Retrieve cash entries for a restaurant on a specific business date. + +Returns information about cash added to or removed from cash drawers, including cash-in, cash-out, pay-outs, tip-outs, no-sale events, and drawer close-out records. Each entry includes the amount, reason, type, and associated employees. + +Cash entry types include: +- `CASH_IN`: Cash added to drawer +- `CASH_OUT`: Cash removed and stored elsewhere +- `PAY_OUT`: Cash removed for restaurant expenses +- `TIP_OUT`: Cash removed to distribute tips +- `NO_SALE`: Drawer opened with no cash change +- `CLOSE_OUT_EXACT/OVERAGE/SHORTAGE`: Drawer closing records + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **business_date** (`string`, required): The business date in YYYYMMDD format (e.g., 20240115). + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + +--- + +## ToastApi.get_cash_deposits + +Retrieve cash deposits for a restaurant on a specific business date. + +Returns information about cash removed from the restaurant to be deposited at a bank or other financial institution. Each deposit record includes the amount, date, and the employee who created it. + +**Parameters** + +- **restaurant_external_id** (`string`, required): The Toast platform GUID for the restaurant. +- **business_date** (`string`, required): The business date in YYYYMMDD format (e.g., 20240115). + +**Secrets** + +This tool requires the following secrets: `TOAST_CLIENT_ID`, `TOAST_CLIENT_SECRET`. + + diff --git a/public/llms.txt b/public/llms.txt index cc5933c33..031417959 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,4 +1,4 @@ - + # Arcade @@ -229,6 +229,7 @@ Arcade delivers three core capabilities: Deploy agents even your security team w - [Teams Reference](https://docs.arcade.dev/en/resources/integrations/social-communication/teams/reference.md): The Teams Reference documentation provides a comprehensive list of enumerations related to matching types and team membership within the Teams MCP Server. Users can learn about different match criteria, such as exact and partial matches, as well as the types of team memberships available. This - [The Arcade Registry](https://docs.arcade.dev/en/guides/create-tools/contribute/registry-early-access.md): The Arcade Registry documentation provides an overview of a platform designed for tool developers to share and monetize their integrations for agentic applications. It explains how the registry collects real-time usage metrics and feedback to enhance tool effectiveness, while inviting users to participate in the early - [TicktickApi](https://docs.arcade.dev/en/resources/integrations/productivity/ticktick-api.md): The TicktickApi documentation provides a set of tools for developers to manage tasks and projects within the Ticktick platform using OAuth2 authentication. Users can learn how to create, update, delete, and retrieve tasks and projects through various API endpoints, enabling seamless +- [ToastApi](https://docs.arcade.dev/en/resources/integrations/hospitality/toast-api.md): The ToastApi documentation provides tools for integrating with the Toast POS API, enabling users to manage various restaurant operations such as orders, menus, kitchen configurations, labor, inventory, and cash management. It outlines the authentication process, including obtaining API credentials and managing - [Tool error handling](https://docs.arcade.dev/en/guides/tool-calling/error-handling.md): This documentation page provides guidance on effectively handling errors when using tools with Arcade's Tool Development Kit (TDK). It outlines the error handling philosophy, describes various error types, and offers best practices for implementing robust error management in applications. Users will learn how - [Tools](https://docs.arcade.dev/en/resources/tools.md): This documentation page provides an overview of Arcade's ecosystem of AI tools, enabling users to explore a catalog of pre-built integrations, create custom tools, and contribute to the community. It outlines the benefits of using Arcade tools, including built-in authentication and universal - [TrelloApi](https://docs.arcade.dev/en/resources/integrations/productivity/trello-api.md): The TrelloApi documentation provides users with a comprehensive set of tools for interacting with the Trello API, enabling efficient management of boards, cards, lists, and members. It outlines various functionalities, such as fetching and updating actions, retrieving board details,