From 832784cddcb5cdcc1ed033ba917c62b6c7a4c2a0 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:59:56 -0500 Subject: [PATCH] Customize: Wrike-specific README, tools, and docs (8 tools, work management workflows, MCPEngage branding) --- .env.example | 3 +- README.md | 211 +++++++++++++++++++++++++++++++++++++++------------ package.json | 2 +- 3 files changed, 165 insertions(+), 51 deletions(-) diff --git a/.env.example b/.env.example index 41c060f..043742f 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,3 @@ # Wrike API Credentials -WRIKE_API_KEY=your-api-key-here +# Get access token from: Wrike Settings β†’ Apps & Integrations β†’ API β†’ Create Token +WRIKE_ACCESS_TOKEN=your_access_token_here diff --git a/README.md b/README.md index c056300..b4b2f36 100644 --- a/README.md +++ b/README.md @@ -8,30 +8,63 @@ ## πŸ’‘ What This Unlocks -**This MCP server gives AI direct access to your entire Wrike workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your entire Wrike workspace.** Instead of navigating folders, projects, and tasks manually, you just *tell* Claude what you needβ€”and it executes instantly across your enterprise work management platform. -### 🎯 Wrike-Native Power Moves +### 🎯 Wrike-Specific Power Moves -The AI can directly control your Wrike account with natural language: +The AI can directly control your Wrike workspace with natural language. Here are **5 real workflows** using the actual tools in this MCP server: -- **Smart automation** β€” Complex workflows in plain English -- **Data intelligence** β€” Query, analyze, and export your Wrike data -- **Rapid operations** β€” Bulk actions that would take hours manually -- **Cross-platform integration** β€” Combine Wrike with other tools seamlessly +1. **πŸ“Š Project Portfolio Health Check** + - AI uses `list_projects` β†’ `list_tasks` (per project) β†’ analyzes status distribution and completion rates + - Identifies at-risk projects (high % of Deferred/Cancelled tasks, overdue tasks piling up) + - *"Show me all active projects, calculate task completion rates, and flag any with 20%+ deferred tasks or overdue work"* -### πŸ”— The Real Power: Combining Tools +2. **πŸ”₯ Priority Escalation Workflow** + - AI calls `list_tasks` with status filters to find urgent work + - Uses `update_task` to escalate importance (High β†’ Critical) and adjust due dates + - Calls `add_comment` to notify stakeholders of priority shifts + - *"Find all High importance tasks due in next 3 days, escalate to Critical, push due dates by 1 day, and comment to notify project leads"* -AI can chain multiple Wrike operations together: +3. **πŸ‘₯ Resource Allocation Intelligence** + - AI uses `list_users` to get team roster β†’ `list_tasks` filtered by assignee (responsibles) + - Calculates workload distribution, identifies over-allocated team members + - *"Show me task counts per team member for active projects, flag anyone with 15+ active tasks, and suggest redistribution"* -- Query data β†’ Filter results β†’ Generate reports -- Search records β†’ Update fields β†’ Notify team -- Analyze metrics β†’ Create tasks β†’ Schedule follow-ups +4. **πŸ—‚οΈ Folder Structure Audit** + - AI chains `list_folders` β†’ `list_folders` (recursively for subfolders) β†’ `list_tasks` (per folder) + - Maps entire workspace hierarchy, identifies empty folders or orphaned tasks + - *"Audit my folder structure: show folder tree, task counts in each, and flag any folders with 0 tasks or 100+ tasks"* + +5. **πŸ“… Sprint Planning & Assignment** + - AI uses `list_tasks` (filtered by project/folder) to pull backlog + - Calls `create_task` in batch to set up sprint tasks with due dates and assignees + - Uses `update_task` to bulk-assign tasks based on team capacity from `list_users` + - *"Pull backlog from 'Product Dev' folder, create 10 sprint tasks with names from list, assign round-robin to dev team, due dates staggered over 2 weeks"* + +### πŸ”— The Real Power: Chaining Operations + +AI doesn't just execute single commandsβ€”it orchestrates **multi-step workflows**: + +- **Cross-Project Reporting** β†’ `list_projects` β†’ `list_tasks` (per project, status filters) β†’ Generate burndown charts +- **Task Migration** β†’ `list_tasks` (source folder) β†’ `create_task` (destination folder) β†’ `update_task` (archive source) +- **Team Rebalancing** β†’ `list_users` β†’ `list_tasks` (per user) β†’ `update_task` (reassign overloaded users) β†’ `add_comment` (notify) ## πŸ“¦ What's Inside -**84 API tools** covering the entire Wrike platform (Project Management). +**8 production-ready Wrike API tools** covering core work management operations: -All with proper error handling, automatic authentication, and TypeScript types. +| Tool | Purpose | +|------|---------| +| `list_tasks` | Query tasks with filters (folder, status, limit) | +| `get_task` | Fetch detailed task info (including custom fields) | +| `create_task` | Create new tasks with metadata (title, desc, status, importance, dates, responsibles) | +| `update_task` | Update existing tasks (title, desc, status, importance, dates, add/remove responsibles) | +| `list_folders` | List folders (can filter by parent folder for hierarchy) | +| `list_projects` | List all projects (projects are folders with project=true flag) | +| `add_comment` | Add comments to tasks (supports markdown) | +| `list_users` | List all users/contacts in your Wrike workspace | + +All tools include proper error handling, automatic authentication (OAuth Bearer tokens), and full TypeScript types. ## πŸš€ Quick Start @@ -45,7 +78,20 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Wrike API credentials** (see Authentication section below) +2. **Get your Wrike Access Token:** + + Wrike uses **OAuth 2.0** (or permanent access tokens for apps): + + - **For personal use (easiest):** + 1. Go to your Wrike account β†’ **Settings** β†’ **Apps & Integrations** + 2. Click **API** tab β†’ **Create Token** + 3. Set a name (e.g., "MCPEngage MCP Server") and select scopes (`wsReadWrite` for full access) + 4. Copy the **Permanent Access Token** (starts with Bearer token format, very long string) + + - **For OAuth apps (advanced):** + - Follow [Wrike OAuth Guide](https://developers.wrike.com/oauth-20-authorization/) to create an app + - Use authorization code flow to get refresh/access tokens + - This MCP server expects a direct access token in `WRIKE_ACCESS_TOKEN` 3. **Configure Claude Desktop:** @@ -58,23 +104,23 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "wrike": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/wrike-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/wrike-mcp-2026-complete/dist/index.js"], "env": { - "WRIKE_API_KEY": "your-api-key-here" + "WRIKE_ACCESS_TOKEN": "your_long_access_token_here" } } } } ``` -4. **Restart Claude Desktop** +4. **Restart Claude Desktop** β€” the πŸ”Œ icon should show "wrike" connected ### Option 2: Deploy to Railway [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/wrike-mcp) 1. Click the button above -2. Set your Wrike API credentials in Railway dashboard +2. Set `WRIKE_ACCESS_TOKEN` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -82,25 +128,48 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t wrike-mcp . docker run -p 3000:3000 \ - -e WRIKE_API_KEY=your-key \ + -e WRIKE_ACCESS_TOKEN=your_token \ wrike-mcp ``` ## πŸ” Authentication -See the official [Wrike API documentation](https://docs.wrike.com) for authentication details. +**Wrike uses OAuth 2.0 Bearer tokens** for API authentication. -The MCP server handles token refresh automatically. +- **Permanent Access Tokens:** Easiest for personal/internal use (create in Wrike Settings β†’ API) +- **OAuth Apps:** For public integrations (requires authorization flow, refresh tokens) +- **Scopes:** `wsReadWrite` grants full read/write access to workspace +- **Security:** Tokens are sensitiveβ€”store securely, never commit to version control -## 🎯 Example Prompts +πŸ“– **Official docs:** [Wrike API Authentication](https://developers.wrike.com/api/v4/authentication/) -Once connected to Claude, you can use natural language. Examples: +The MCP server automatically includes `Authorization: Bearer ` headers on all requests. -- *"Show me recent activity in Wrike"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +## 🎯 Example Prompts for Work Management + +Once connected to Claude, use these natural language prompts: + +**Project & Task Management:** +- *"Show me all active projects, list task counts in each, and identify projects with 0 tasks or 50+ tasks"* +- *"Get all tasks in project IEABCDEF123, filter by status Active, and show me which are overdue"* +- *"Create 5 tasks in folder IEABCDEF456: 'Requirements doc', 'Design review', 'Implementation', 'QA testing', 'Deployment'"* + +**Task Operations:** +- *"Update task IEABCDEF789 to status 'Completed', set importance to Normal, and add a comment 'Finished ahead of schedule'"* +- *"Find all tasks with status Deferred in the Engineering folder, change status to Active, and set due dates to next Friday"* + +**Team & Resource Management:** +- *"List all users in my Wrike workspace and show me their contact info"* +- *"Show me all tasks assigned to user IEABCDEF123, group by project, and calculate total active task count"* +- *"Find tasks assigned to Sarah (user ID IEABCDEF456) that are overdue, reassign to Tom (IEABCDEF789), and add comment explaining why"* + +**Workspace Intelligence:** +- *"Audit my folder structure: list all folders, subfolders, and task countsβ€”flag any folders with 100+ tasks as needing reorganization"* +- *"Pull all tasks created in last 7 days across my workspace, group by folder, and summarize what's being worked on"* + +**Reporting & Analytics:** +- *"Get all tasks from Q1 projects with status Completed or Cancelled, calculate completion rate, and identify which projects shipped on time"* +- *"Show me all Critical importance tasks across my workspace with due dates in next 48 hoursβ€”highlight any blockers"* ## πŸ› οΈ Development @@ -116,7 +185,7 @@ git clone https://github.com/BusyBee3333/Wrike-MCP-2026-Complete.git cd wrike-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your Wrike credentials +# Edit .env with your Wrike access token npm run build npm start ``` @@ -129,44 +198,88 @@ npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` +### Project Structure + +``` +wrike-mcp-2026-complete/ +β”œβ”€β”€ src/ +β”‚ └── index.ts # Main MCP server + Wrike API client +β”œβ”€β”€ dist/ # Compiled JavaScript (after build) +β”œβ”€β”€ package.json +β”œβ”€β”€ tsconfig.json +└── .env.example +``` + ## πŸ› 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" or 401/403 errors +- Verify your access token is correctly set in `WRIKE_ACCESS_TOKEN` +- Check token hasn't expired (permanent tokens don't expire unless revoked) +- Ensure token has `wsReadWrite` scope (or appropriate permissions) +- Verify token in Wrike Settings β†’ Apps & Integrations β†’ API + +### "Folder not found" or "Task not found" +- Wrike IDs are case-sensitive and start with `IE` followed by alphanumeric +- Use `list_folders` or `list_projects` to get exact IDs +- Some folders/tasks may be in archived spacesβ€”check workspace settings ### "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) +- Verify path in `claude_desktop_config.json` is **absolute** +- Check `dist/index.js` exists after `npm run build` +- View logs: macOS `~/Library/Logs/Claude/mcp*.log` + +### Rate limits +- Wrike API limits: Varies by plan (free: 100 req/min, paid: higher) +- The MCP server doesn't implement rate limiting yetβ€”add delays for bulk operations +- Check rate limit headers in responses if hitting limits + +### Date format issues +- Wrike expects dates in **YYYY-MM-DD** format for `start_date` and `due_date` +- Timestamps are returned as ISO 8601 strings +- Custom date fields may have different formatsβ€”check API docs ## πŸ“– Resources -- [Wrike API Documentation](https://docs.wrike.com) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- **[Wrike API v4 Documentation](https://developers.wrike.com/api/v4/)** β€” Official REST API reference +- **[Wrike API Getting Started](https://developers.wrike.com/getting-started/)** β€” Quickstart guide +- **[Wrike OAuth 2.0 Guide](https://developers.wrike.com/oauth-20-authorization/)** β€” OAuth setup +- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** β€” How MCP servers work +- **[Claude Desktop Documentation](https://claude.ai/desktop)** β€” Configure AI integrations ## 🀝 Contributing -Contributions are welcome! Please: +Contributions are welcome! Missing a Wrike feature? Want to add custom fields, timelog, or dependency management? Open a PR. -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 +**How to contribute:** + +1. Fork this repo +2. Create a feature branch (`git checkout -b feature/add-custom-fields`) +3. Add your tool definition in `src/index.ts` (follow existing patterns) +4. Test locally with Claude Desktop +5. Commit your changes (`git commit -m 'Add custom fields support'`) +6. Push to your fork (`git push origin feature/add-custom-fields`) +7. Open a Pull Request with details ## πŸ“„ License -MIT License - see [LICENSE](LICENSE) for details +MIT License - see [LICENSE](LICENSE) for details. + +You're free to use, modify, and distribute this MCP server for personal or commercial projects. ## πŸ™ 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. +This server is part of the **MCPEngage 2026 Complete Series**, providing production-ready MCP servers for 30+ business platforms. + +**Want more?** Check out our full catalog: +- [Asana MCP Server](https://github.com/BusyBee3333/Asana-MCP-2026-Complete) β€” Project management +- [ClickUp MCP Server](https://github.com/BusyBee3333/ClickUp-MCP-2026-Complete) β€” All-in-one PM +- [Jira MCP Server](https://github.com/BusyBee3333/Jira-MCP-2026-Complete) β€” Issue tracking +- [Trello MCP Server](https://github.com/BusyBee3333/Trello-MCP-2026-Complete) β€” Kanban boards +- ...and 26 more at [mcpengage.com](https://mcpengage.com) --- -**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) (invite on mcpengine.pages.dev). diff --git a/package.json b/package.json index a25c37e..d1118b6 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Wrike API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",