From 31a22d7350aff596d378ec474f95901b8ee1c579 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:57:03 -0500 Subject: [PATCH] Customize: Platform-specific README, tools, and docs --- .env.example | 5 +- README.md | 181 +++++++++++++++++++++++++++++++++------------------ package.json | 4 +- 3 files changed, 122 insertions(+), 68 deletions(-) diff --git a/.env.example b/.env.example index c9fda2b..d68f234 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,5 @@ # Toast API Credentials -TOAST_API_KEY=your-api-key-here +# Get these from: https://dev.toasttab.com/ +TOAST_CLIENT_ID=your-client-id-here +TOAST_CLIENT_SECRET=your-client-secret-here +TOAST_RESTAURANT_GUID=your-restaurant-guid-here diff --git a/README.md b/README.md index f720429..81f37fc 100644 --- a/README.md +++ b/README.md @@ -4,38 +4,46 @@ --- -# 🚀 Toast MCP Server — 2026 Complete Version +# 🍞 Toast MCP Server — Restaurant Operations on Autopilot ## 💡 What This Unlocks -**This MCP server gives AI direct access to your entire Toast workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your Toast POS system.** Stop manually pulling reports, updating menu items, or tracking labor costs. Just tell Claude what you need, and it happens. -### 🎯 Toast-Native Power Moves +### 🎯 Toast-Specific Power Moves -The AI can directly control your Toast account with natural language: +| Use Case | What It Does | Tools Used | +|----------|-------------|-----------| +| **"86" items instantly** | Mark menu items out of stock across all terminals | `list_menu_items`, `update_menu_item` | +| **Daily sales reconciliation** | Pull all orders + payments for a business day | `list_orders`, `get_order`, `list_checks` | +| **Labor cost analysis** | Compare actual hours worked vs. scheduled shifts | `list_employees`, `get_labor` | +| **Order investigation** | Find specific orders by time/amount, void if needed | `list_orders`, `get_order`, `void_check` | +| **Menu sync verification** | Audit menu items against your master menu list | `list_menu_items` | -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Toast data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Toast with other tools seamlessly +### 🔗 The Real Power: Natural Language Restaurant Ops -### 🔗 The Real Power: Combining Tools +Instead of clicking through Toast dashboards: -AI can chain multiple Toast operations together: - -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- *"Show me all orders from last night's dinner rush (5-9pm)"* +- *"Mark the grilled salmon as 86'd"* +- *"What's our total labor cost for this week?"* +- *"Find the order with the $127 total from yesterday"* +- *"Void check #4521 — customer never showed up"* ## 📦 What's Inside -**93 API tools** covering the entire Toast platform (Restaurant & POS). +**8 restaurant-focused API tools** covering Toast's core POS functionality: -All with proper error handling, automatic authentication, and TypeScript types. +- **Orders:** `list_orders`, `get_order` — Sales data, items, modifiers, payments +- **Checks:** `list_checks`, `void_check` — Tab management and corrections +- **Menu:** `list_menu_items`, `update_menu_item` — Inventory & 86'd items +- **Labor:** `list_employees`, `get_labor` — Staff scheduling & time tracking + +All with automatic OAuth2 authentication, proper error handling, and TypeScript types. ## 🚀 Quick Start -### Option 1: Claude Desktop (Local) +### Option 1: Claude Desktop (Recommended) 1. **Clone and build:** ```bash @@ -45,82 +53,115 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Toast API credentials** (see Authentication section below) +2. **Get your Toast API credentials:** + - Log into [Toast Developer Portal](https://dev.toasttab.com/) + - Create a new integration (Restaurant Management API) + - Save your **Client ID**, **Client Secret**, and **Restaurant GUID** 3. **Configure Claude Desktop:** - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - - On Windows: `%APPDATA%\Claude\claude_desktop_config.json` + **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` + **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "toast": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/toast-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/toast-mcp-2026-complete/dist/index.js"], "env": { - "TOAST_API_KEY": "your-api-key-here" + "TOAST_CLIENT_ID": "your-client-id", + "TOAST_CLIENT_SECRET": "your-client-secret", + "TOAST_RESTAURANT_GUID": "your-restaurant-guid" } } } } ``` -4. **Restart Claude Desktop** +4. **Restart Claude Desktop** — you'll see 8 Toast tools appear in the MCP section -### Option 2: Deploy to Railway - -[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/toast-mcp) - -1. Click the button above -2. Set your Toast API credentials in Railway dashboard -3. Use the Railway URL as your MCP server endpoint - -### Option 3: Docker +### Option 2: Local Development ```bash -docker build -t toast-mcp . -docker run -p 3000:3000 \ - -e TOAST_API_KEY=your-key \ - toast-mcp +cp .env.example .env +# Edit .env with your Toast credentials +npm run dev ``` ## 🔐 Authentication -See the official [Toast API documentation](https://docs.toast.com) for authentication details. +Toast uses **OAuth2 Client Credentials** flow: -The MCP server handles token refresh automatically. +1. Go to [Toast Developer Portal](https://dev.toasttab.com/) +2. Navigate to **Integrations** → **Create Integration** +3. Select **Restaurant Management API** scope +4. Copy your **Client ID** and **Client Secret** +5. Find your **Restaurant GUID** in Toast Web (Settings → Restaurant Info) + +**Required Scopes:** +- Orders (read) +- Menus (read/write) +- Labor (read) + +**API Docs:** [https://doc.toasttab.com/doc/devguide/apiOverview.html](https://doc.toasttab.com/doc/devguide/apiOverview.html) + +The MCP server automatically handles token refresh (tokens expire after 1 hour). ## 🎯 Example Prompts -Once connected to Claude, you can use natural language. Examples: +Once connected to Claude: -- *"Show me recent activity in Toast"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +**Sales & Orders:** +- *"Pull all orders from yesterday between 6-9pm"* +- *"Show me order abc123 with full details"* +- *"What were our top-selling items last week?"* + +**Menu Management:** +- *"List all menu items with prices"* +- *"Mark the ribeye steak as out of stock"* +- *"What items are currently 86'd?"* + +**Labor & Staffing:** +- *"Show me all employees"* +- *"Get labor data for last Monday-Friday"* +- *"Calculate total hours worked by employee X"* + +**Check Operations:** +- *"List all open checks right now"* +- *"Void check #4521 with reason 'customer no-show'"* ## 🛠️ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Toast account with API access +- Toast account with API access (paid plan required) -### Setup +### Local Setup ```bash git clone https://github.com/BusyBee3333/Toast-MCP-2026-Complete.git cd toast-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your Toast credentials +# Edit .env with your credentials npm run build npm start ``` +### Project Structure + +``` +toast-mcp-2026-complete/ +├── src/ +│ └── index.ts # Main MCP server + Toast API client +├── dist/ # Compiled JavaScript (npm run build) +├── package.json +├── tsconfig.json +└── .env.example +``` + ### Testing ```bash @@ -131,31 +172,41 @@ npm run test:coverage # Coverage report ## 🐛 Troubleshooting -### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +### "Toast auth error: 401" +- Verify your Client ID and Client Secret are correct +- Check that your integration has the required scopes enabled +- Ensure your Restaurant GUID matches your actual restaurant + +### "Toast API error: 403 Forbidden" +- Your API credentials don't have the necessary permissions +- Check your integration's scope settings in the Toast Developer Portal ### "Tools not appearing in Claude" -- Restart Claude Desktop after updating config -- Check that the path in `claude_desktop_config.json` is absolute -- Verify the build completed successfully (`dist/index.js` exists) +- Restart Claude Desktop after updating `claude_desktop_config.json` +- Verify the path is **absolute** (no `~` or relative paths) +- Check that `npm run build` completed successfully +- Look for the `dist/index.js` file + +### "Toast-Restaurant-External-ID header required" +- Make sure `TOAST_RESTAURANT_GUID` is set in your environment +- This is different from your Client ID — find it in Toast Web settings ## 📖 Resources -- [Toast API Documentation](https://docs.toast.com) +- [Toast API Documentation](https://doc.toasttab.com/doc/devguide/apiOverview.html) +- [Toast Developer Portal](https://dev.toasttab.com/) - [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- [Claude Desktop Setup](https://claude.ai/desktop) ## 🤝 Contributing -Contributions are welcome! Please: +Contributions welcome! To add new Toast API endpoints: 1. Fork the repo -2. Create a feature branch (`git checkout -b feature/amazing-tool`) -3. Commit your changes (`git commit -m 'Add amazing tool'`) -4. Push to the branch (`git push origin feature/amazing-tool`) -5. Open a Pull Request +2. Add tool definitions to `src/index.ts` (tools array) +3. Implement handlers in `handleTool()` function +4. Update README with new capabilities +5. Submit a PR ## 📄 License @@ -163,10 +214,10 @@ MIT License - see [LICENSE](LICENSE) for details ## 🙏 Credits -Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software. +Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software. -Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms. +**Want more MCP servers?** Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms (Gusto, Calendly, Stripe, QuickBooks, and more). --- -**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine). +**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage). diff --git a/package.json b/package.json index 755e000..a0a522d 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,10 @@ { "name": "toast-mcp-server", "version": "1.0.0", - "description": "MCP server for Toast API - 2026 Complete Version", + "description": "MCP server for Toast POS - Restaurant operations with 8 AI-ready tools", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",