Customize: Platform-specific README, tools, and docs

.env.example

@@ -1,2 +1,3 @@
 # Gusto API Credentials
-GUSTO_API_KEY=your-api-key-here
+# Get your OAuth token from: https://dev.gusto.com/
+GUSTO_ACCESS_TOKEN=your-oauth-access-token-here

README.md

@@ -4,38 +4,47 @@
 
 ---
 
-# 🚀 Gusto MCP Server — 2026 Complete Version
+# 💼 Gusto MCP Server — HR & Payroll Intelligence
 
 ## 💡 What This Unlocks
 
-**This MCP server gives AI direct access to your entire Gusto workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
+**This MCP server gives AI direct access to your Gusto HR and payroll data.** Stop manually exporting spreadsheets or hunting through dashboards. Ask Claude questions in plain English, and get instant answers.
 
-### 🎯 Gusto-Native Power Moves
+### 🎯 Gusto-Specific Power Moves
 
-The AI can directly control your Gusto account with natural language:
+| Use Case | What It Does | Tools Used |
+|----------|-------------|-----------|
+| **Headcount reporting** | Get current employee list with salaries, departments, roles | `list_employees`, `get_employee` |
+| **Payroll reconciliation** | Pull processed payrolls for a date range, verify amounts | `list_payrolls`, `get_payroll` |
+| **Contractor audit** | List all 1099 contractors and YTD payments | `list_contractors` |
+| **Benefits enrollment check** | See who's enrolled in health, 401k, etc. | `list_benefits`, `list_employees` |
+| **Company info export** | Get all company details, locations, tax IDs | `get_company` |
 
-- **Smart automation** — Complex workflows in plain English
+### 🔗 The Real Power: Natural Language HR Queries
-- **Data intelligence** — Query, analyze, and export your Gusto data
-- **Rapid operations** — Bulk actions that would take hours manually
-- **Cross-platform integration** — Combine Gusto with other tools seamlessly
 
-### 🔗 The Real Power: Combining Tools
+Instead of logging into Gusto and clicking around:
 
-AI can chain multiple Gusto operations together:
+- *"Show me all employees hired in the last 6 months"*
-
+- *"What's our total payroll for Q4 2024?"*
-- Query data → Filter results → Generate reports
+- *"List all contractors with payments over $10k this year"*
-- Search records → Update fields → Notify team
+- *"Who's enrolled in our health insurance plan?"*
-- Analyze metrics → Create tasks → Schedule follow-ups
+- *"Get company details including all locations"*
 
 ## 📦 What's Inside
 
-**91 API tools** covering the entire Gusto platform (HR & Payroll).
+**7 HR-focused API tools** covering Gusto's core people operations:
 
-All with proper error handling, automatic authentication, and TypeScript types.
+- **Employees:** `list_employees`, `get_employee` — Staff directory, salaries, departments
+- **Payroll:** `list_payrolls`, `get_payroll` — Pay runs, gross/net amounts, taxes
+- **Contractors:** `list_contractors` — 1099 contractors and payments
+- **Company:** `get_company` — Organization details, locations, settings
+- **Benefits:** `list_benefits` — Health insurance, 401k, other benefits
+
+All with OAuth2 bearer token 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 +54,116 @@ All with proper error handling, automatic authentication, and TypeScript types.
    npm run build
    ```
 
-2. **Get your Gusto API credentials** (see Authentication section below)
+2. **Get your Gusto OAuth token:**
+   - Log into [Gusto Developer Portal](https://dev.gusto.com/)
+   - Create a new application
+   - Complete the OAuth flow to get an **access token**
+   - **Note:** Gusto uses OAuth2, so you'll need to implement a refresh flow for production use
 
 3. **Configure Claude Desktop:**
    
-   On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
-   
+   **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-   On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
    ```json
    {
      "mcpServers": {
        "gusto": {
          "command": "node",
-         "args": ["/ABSOLUTE/PATH/TO/gusto-mcp/dist/index.js"],
+         "args": ["/ABSOLUTE/PATH/TO/gusto-mcp-2026-complete/dist/index.js"],
          "env": {
-           "GUSTO_API_KEY": "your-api-key-here"
+           "GUSTO_ACCESS_TOKEN": "your-oauth-access-token"
          }
        }
      }
    }
    ```
 
-4. **Restart Claude Desktop**
+4. **Restart Claude Desktop** — you'll see 7 Gusto tools appear in the MCP section
 
-### Option 2: Deploy to Railway
+### Option 2: Local Development
-
-[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/gusto-mcp)
-
-1. Click the button above
-2. Set your Gusto API credentials in Railway dashboard
-3. Use the Railway URL as your MCP server endpoint
-
-### Option 3: Docker
 
 ```bash
-docker build -t gusto-mcp .
+cp .env.example .env
-docker run -p 3000:3000 \
+# Edit .env with your Gusto OAuth token
-  -e GUSTO_API_KEY=your-key \
+npm run dev
-  gusto-mcp
 ```
 
 ## 🔐 Authentication
 
-See the official [Gusto API documentation](https://docs.gusto.com) for authentication details.
+Gusto uses **OAuth2** for authentication:
 
-The MCP server handles token refresh automatically.
+1. Go to [Gusto Developer Portal](https://dev.gusto.com/)
+2. Create a new **Partner Application**
+3. Configure OAuth redirect URIs
+4. Use the OAuth flow to obtain an **access token**
+5. Set `GUSTO_ACCESS_TOKEN` in your environment
+
+**Required Scopes:**
+- `employees:read`
+- `payrolls:read`
+- `contractors:read`
+- `company:read`
+- `benefits:read`
+
+**API Docs:** [https://docs.gusto.com/](https://docs.gusto.com/)
+
+**⚠️ Token Expiration:** Access tokens expire after a certain period. For production, implement token refresh using Gusto's OAuth refresh flow.
 
 ## 🎯 Example Prompts
 
-Once connected to Claude, you can use natural language. Examples:
+Once connected to Claude:
 
-- *"Show me recent activity in Gusto"*
+**Employee Management:**
-- *"Create a new record with these details..."*
+- *"List all employees in the Engineering department"*
-- *"Export all data from last month"*
+- *"Show me details for employee ID abc123"*
-- *"Update the status of X to Y"*
+- *"Who are our newest hires?"*
-- *"Generate a report of..."*
+
+**Payroll Analysis:**
+- *"Pull all processed payrolls from January 2025"*
+- *"Show me payroll details for ID xyz789"*
+- *"What's our average gross payroll per run?"*
+
+**Contractor Management:**
+- *"List all contractors"*
+- *"Which contractors have YTD payments over $50k?"*
+
+**Company & Benefits:**
+- *"Get our company information"*
+- *"What benefits do we offer?"*
+- *"How many employees are enrolled in 401k?"*
 
 ## 🛠️ Development
 
 ### Prerequisites
 - Node.js 18+
 - npm or yarn
-- Gusto account with API access
+- Gusto account with API access (requires partner application setup)
 
-### Setup
+### Local Setup
 
 ```bash
 git clone https://github.com/BusyBee3333/Gusto-MCP-2026-Complete.git
 cd gusto-mcp-2026-complete
 npm install
 cp .env.example .env
-# Edit .env with your Gusto credentials
+# Edit .env with your OAuth token
 npm run build
 npm start
 ```
 
+### Project Structure
+
+```
+gusto-mcp-2026-complete/
+├── src/
+│   └── index.ts          # Main MCP server + Gusto API client
+├── dist/                 # Compiled JavaScript (npm run build)
+├── package.json
+├── tsconfig.json
+└── .env.example
+```
+
 ### Testing
 
 ```bash
@@ -131,31 +174,43 @@ npm run test:coverage     # Coverage report
 
 ## 🐛 Troubleshooting
 
-### "Authentication failed"
+### "Gusto API error: 401 Unauthorized"
-- Verify your API credentials are correct
+- Your access token is invalid or expired
-- Check that your API key hasn't been revoked
+- Generate a new token through the OAuth flow
-- Ensure you have the necessary permissions
+- Verify you've set `GUSTO_ACCESS_TOKEN` correctly
+
+### "Gusto API error: 403 Forbidden"
+- Your OAuth application doesn't have the required scopes
+- Check your app's permissions in the Gusto Developer Portal
 
 ### "Tools not appearing in Claude"
-- Restart Claude Desktop after updating config
+- Restart Claude Desktop after updating `claude_desktop_config.json`
-- Check that the path in `claude_desktop_config.json` is absolute
+- Verify the path is **absolute** (no `~` or relative paths)
-- Verify the build completed successfully (`dist/index.js` exists)
+- Check that `npm run build` completed successfully
+- Look for the `dist/index.js` file
+
+### "company_id required"
+- Most Gusto API calls require a `company_id` parameter
+- Get your company ID via the `get_company()` tool first
+- Or find it in your Gusto dashboard URL
 
 ## 📖 Resources
 
-- [Gusto API Documentation](https://docs.gusto.com)
+- [Gusto API Documentation](https://docs.gusto.com/)
+- [Gusto Developer Portal](https://dev.gusto.com/)
+- [OAuth 2.0 Guide](https://docs.gusto.com/embedded-payroll/docs/oauth)
 - [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 Gusto API endpoints:
 
 1. Fork the repo
-2. Create a feature branch (`git checkout -b feature/amazing-tool`)
+2. Add tool definitions to `src/index.ts` (tools array)
-3. Commit your changes (`git commit -m 'Add amazing tool'`)
+3. Implement handlers in `handleTool()` function
-4. Push to the branch (`git push origin feature/amazing-tool`)
+4. Update README with new capabilities
-5. Open a Pull Request
+5. Submit a PR
 
 ## 📄 License
 
@@ -163,10 +218,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 (Toast, 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).

package.json

@@ -1,10 +1,10 @@
 {
   "name": "gusto-mcp-server",
   "version": "1.0.0",
-  "description": "MCP server for Gusto API - 2026 Complete Version",
+  "description": "MCP server for Gusto - HR and payroll with 7 AI-ready tools",
   "type": "module",
   "main": "dist/index.js",
-  "author": "MCPEngine <hello@mcpengage.com>",
+  "author": "MCPEngage <hello@mcpengage.com>",
   "license": "MIT",
   "repository": {
     "type": "git",