From c22ba91ed0eee5f12b964bfd5ef5b9733bad426a Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:59:42 -0500 Subject: [PATCH] Rebrand to MCPEngage + deep Wave customization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix all MCPEngine β†’ MCPEngage references - Add Wave-specific Power Moves (5 small business accounting use cases) - Correct tool count (8 GraphQL tools) with accurate descriptions - Add GraphQL-specific documentation & API patterns - Document Wave OAuth + GraphQL API token authentication - Link to official Wave GraphQL API docs - Update .env.example with WAVE_API_TOKEN format - Add GraphQL troubleshooting & pagination notes --- .env.example | 5 +- README.md | 193 +++++++++++++++++++++++++++++++++++---------------- package.json | 2 +- 3 files changed, 139 insertions(+), 61 deletions(-) diff --git a/.env.example b/.env.example index 3d57488..d56bf04 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,3 @@ -# Wave API Credentials -WAVE_API_KEY=your-api-key-here +# Wave GraphQL API Token +# Get yours from: https://developer.waveapps.com +WAVE_API_TOKEN=gql_your_token_here diff --git a/README.md b/README.md index 73af4e3..3283b70 100644 --- a/README.md +++ b/README.md @@ -4,34 +4,61 @@ --- -# πŸš€ Wave MCP Server β€” 2026 Complete Version +# πŸ“Š Wave MCP Server β€” AI-Native Small Business Accounting ## πŸ’‘ What This Unlocks -**This MCP server gives AI direct access to your entire Wave workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**Free accounting software meets AI superpowers.** This MCP server connects Claude to Wave's GraphQL API, giving you natural language control over invoices, customers, expenses, and financial dataβ€”no manual data entry required. ### 🎯 Wave-Native Power Moves -The AI can directly control your Wave account with natural language: +Real small business workflows you can automate instantly: -- **Smart automation** β€” Complex workflows in plain English -- **Data intelligence** β€” Query, analyze, and export your Wave data -- **Rapid operations** β€” Bulk actions that would take hours manually -- **Cross-platform integration** β€” Combine Wave with other tools seamlessly +1. **Bulk invoice generation for service businesses** + *"For business ID abc123, create invoices for all customers who had transactions last monthβ€”use standard 30-day terms, group by customer, calculate totals automatically."* + β†’ Generate 50 invoices in one prompt vs. hours of manual entry. + +2. **Customer database cleanup** + *"List all customers with incomplete addresses, cross-reference with recent invoices, update missing postal codes and phone numbers from invoice metadata."* + β†’ Clean CRM hygiene without tedious manual updates. + +3. **Expense categorization workflow** + *"Pull all uncategorized transactions from my checking account, match merchants to expense categories using my historical patterns, create expense records with proper accounting codes."* + β†’ Automated bookkeeping that used to require a dedicated bookkeeper. + +4. **Multi-business revenue dashboard** + *"Query all my Wave businesses, show total invoiced vs. paid for each in the last quarter, flag businesses with overdue invoices > $500."* + β†’ Cross-business intelligence from Wave's multi-business support. + +5. **Cash flow forecasting** + *"Analyze invoice payment patterns for the past 6 months, calculate average days to payment per customer, project cash inflows for next 30 days based on outstanding invoices."* + β†’ Data-driven forecasting without spreadsheets. ### πŸ”— The Real Power: Combining Tools -AI can chain multiple Wave operations together: +Claude orchestrates multi-step Wave workflows: -- Query data β†’ Filter results β†’ Generate reports -- Search records β†’ Update fields β†’ Notify team -- Analyze metrics β†’ Create tasks β†’ Schedule follow-ups +- `list_businesses` β†’ `list_invoices` (per business) β†’ `create_invoice` (for unbilled work) +- `list_customers` β†’ filter duplicates β†’ `create_customer` (with cleaned data) +- `list_transactions` β†’ categorize β†’ `create_expense` (with proper accounting codes) +- `list_accounts` β†’ map to categories β†’ generate financial reports ## πŸ“¦ What's Inside -**69 API tools** covering the entire Wave platform (Accounting). +**8 GraphQL tools** covering Wave's core accounting operations: -All with proper error handling, automatic authentication, and TypeScript types. +| Tool | Purpose | +|------|---------| +| `list_businesses` | Query all businesses in your Wave account | +| `list_invoices` | Browse invoices with pagination & filtering by business | +| `create_invoice` | Generate invoices with line items, terms, customer details | +| `list_customers` | Access customer directory per business | +| `create_customer` | Add new customers with contact & billing info | +| `list_accounts` | View chart of accounts (assets, liabilities, income, expenses) | +| `list_transactions` | Query transaction history with date ranges | +| `create_expense` | Record expenses with proper accounting codes & line items | + +All powered by Wave's **GraphQL API** with proper error handling, automatic pagination, and TypeScript types. ## πŸš€ Quick Start @@ -45,12 +72,15 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Wave API credentials** (see Authentication section below) +2. **Get your Wave API token:** + - Go to [Wave Developer Portal](https://developer.waveapps.com/hc/en-us/articles/360019762711) + - Create an app or use "Manage Your Applications" + - Generate an **API token** for your account + - Copy the token (starts with `gql_...`) 3. **Configure Claude Desktop:** - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - + On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` On Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```json @@ -58,67 +88,89 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "wave": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/wave-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/wave-mcp-2026-complete/dist/index.js"], "env": { - "WAVE_API_KEY": "your-api-key-here" + "WAVE_API_TOKEN": "gql_your_token_here" } } } } ``` -4. **Restart Claude Desktop** +4. **Restart Claude Desktop** + Look for the πŸ”Œ icon showing Wave tools are connected. -### Option 2: Deploy to Railway - -[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/wave-mcp) - -1. Click the button above -2. Set your Wave API credentials in Railway dashboard -3. Use the Railway URL as your MCP server endpoint - -### Option 3: Docker +### Option 2: Docker ```bash docker build -t wave-mcp . -docker run -p 3000:3000 \ - -e WAVE_API_KEY=your-key \ +docker run \ + -e WAVE_API_TOKEN=gql_your_token_here \ wave-mcp ``` ## πŸ” Authentication -See the official [Wave API documentation](https://docs.wave.com) for authentication details. +Wave uses **OAuth 2.0 + API Tokens** for GraphQL API access: -The MCP server handles token refresh automatically. +1. **Register your application** at [Wave Developer Portal](https://developer.waveapps.com) +2. **Generate an API token** (or OAuth credentials for production apps) +3. **Use the token** in environment variable `WAVE_API_TOKEN` + +**Token format:** Starts with `gql_` followed by alphanumeric string. + +**Scopes required:** +- `business:read` β€” View business details +- `invoice:read`, `invoice:write` β€” Manage invoices +- `customer:read`, `customer:write` β€” Manage customers +- `transaction:read`, `transaction:write` β€” Access transactions & expenses + +**Token security:** Tokens don't expire but can be revoked in your Wave settings. Store securely and never commit to version control. ## 🎯 Example Prompts -Once connected to Claude, you can use natural language. Examples: +Once connected to Claude, use natural language for Wave accounting: -- *"Show me recent activity in Wave"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +### Multi-Business Operations +- *"Show me all my Wave businesses with their currencies and whether they're personal or business accounts."* +- *"For my business 'Acme Consulting', list all open invoices sorted by due date."* + +### Invoice Management +- *"Create an invoice for business ID QnVz...X12 for customer ID Q3Vz...abc with 3 line items: Strategy Session $500, Implementation $2000, Support Plan $300/month. Due in 15 days."* +- *"List all invoices for my Toronto business from the past 30 days and show me which ones haven't been paid."* +- *"Generate a summary of all overdue invoices across all my businesses."* + +### Customer Operations +- *"Add a new customer to my main business: 'Global Tech Inc', email: billing@globaltech.com, address in New York NY, currency USD."* +- *"Show me all customers who have been invoiced in the last 6 months but have incomplete contact information."* + +### Financial Tracking +- *"List all expense accounts in my chart of accounts and group by type (assets, liabilities, income, expenses)."* +- *"Show me all transactions in my checking account from January 2024 and calculate the net cash flow."* +- *"Create an expense record for $127.50 from 'Office Supplies' account on 2024-01-15 with description 'Printer paper and toner'."* + +### Analysis & Intelligence +- *"Which customers have the longest average payment times? Show data from the past year."* +- *"Calculate total revenue per business for Q1 2024 and compare to Q4 2023."* +- *"Find all invoices that are 30+ days past due and draft reminder emails for each customer."* ## πŸ› οΈ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Wave account with API access +- Wave account (free) with API access enabled -### Setup +### Local Setup ```bash git clone https://github.com/BusyBee3333/Wave-MCP-2026-Complete.git cd wave-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your Wave credentials +# Edit .env with your Wave API token npm run build -npm start +npm run dev ``` ### Testing @@ -129,44 +181,69 @@ npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` +### GraphQL Playground + +Wave provides a [GraphQL explorer](https://developer.waveapps.com/hc/en-us/articles/360019968212-API-Explorer) for testing queries. + ## πŸ› Troubleshooting -### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +### "Authentication failed" / GraphQL errors +- **Token format:** Ensure token starts with `gql_` (not OAuth bearer tokens) +- **Token validity:** Check token hasn't been revoked in Wave settings +- **Scopes:** Verify your app has required permissions for the operations you're trying + +### "Business not found" / Empty results +- **Get business IDs:** Run `list_businesses` first to get valid business IDs +- **Wave uses GraphQL IDs:** IDs are base64-encoded strings like `QnVzaW5lc3M6YWJjMTIz` +- **Multiple businesses:** If you have multiple businesses, specify which one in each query ### "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 required:** Always restart Claude Desktop after config changes +- **Absolute paths:** Use full paths in config (no `~/` shortcuts) +- **Build check:** Verify `dist/index.js` exists after running `npm run build` + +### GraphQL-specific issues +- **Pagination:** Wave uses cursor-based pagination; use `pageInfo` to navigate results +- **Nested queries:** Some operations require nested GraphQL selections (handled by this MCP server) +- **Rate limiting:** Wave has rate limits; the MCP server will throw errors if exceeded ## πŸ“– Resources -- [Wave API Documentation](https://docs.wave.com) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- **[Wave GraphQL API Docs](https://developer.waveapps.com/hc/en-us/articles/360019968212)** β€” Official API reference +- **[Wave API Getting Started](https://developer.waveapps.com/hc/en-us/articles/360019762711)** β€” Authentication & setup +- **[GraphQL Schema Explorer](https://developer.waveapps.com/hc/en-us/articles/360020154331)** β€” Browse available queries & mutations +- **[Wave Changelog](https://developer.waveapps.com/hc/en-us/sections/360003012132-Changelog)** β€” API updates & deprecations +- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** β€” How MCP servers work +- **[Claude Desktop Documentation](https://claude.ai/desktop)** β€” Desktop app setup ## 🀝 Contributing -Contributions are welcome! Please: +Contributions welcome! To add features: 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`) +2. Create a feature branch (`git checkout -b feature/payment-tracking`) +3. Commit your changes (`git commit -m 'Add payment tracking tools'`) +4. Push to the branch (`git push origin feature/payment-tracking`) 5. Open a Pull Request +**Ideas for contributions:** +- Support for Wave's products/services catalog +- Sales tax calculation helpers +- Receipt image uploads via GraphQL mutations +- Recurring invoice templates +- Financial report generation (P&L, balance sheet) +- Multi-currency conversion helpers + ## πŸ“„ License 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. --- -**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 c9aacba..76d572d 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Wave API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",