diff --git a/.env.example b/.env.example index f8f1558..18ea5c0 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,12 @@ # Basecamp API Credentials -BASECAMP_API_KEY=your-api-key-here +# Get these from: https://launchpad.37signals.com/integrations + +# OAuth 2.0 Access Token (get via OAuth flow) +BASECAMP_ACCESS_TOKEN=your-oauth-token-here + +# Your Account ID (from URL: https://3.basecamp.com/{ACCOUNT_ID}/) +BASECAMP_ACCOUNT_ID=your-account-id-here + +# User-Agent identifier (required by Basecamp API) +# Format: "AppName (contact@email.com)" +BASECAMP_APP_IDENTITY="MCPServer (mcp@example.com)" diff --git a/README.md b/README.md index a439a94..65946b1 100644 --- a/README.md +++ b/README.md @@ -4,32 +4,39 @@ --- -# 🚀 Basecamp MCP Server — 2026 Complete Version +# 📊 Basecamp MCP Server — 2026 Complete Version ## 💡 What This Unlocks -**This MCP server gives AI direct access to your entire Basecamp workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your Basecamp workspace.** Instead of manually clicking through projects and to-dos, you just *tell* the AI what you need. -### 🎯 Basecamp-Native Power Moves +### 🎯 Team Collaboration Power Moves The AI can directly control your Basecamp account with natural language: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Basecamp data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Basecamp with other tools seamlessly +1. **Project Intelligence** — "Show me all active projects" or "Get full details on the Q1 Launch project including tools and team" +2. **Smart Task Management** — "List all incomplete to-dos in the Engineering project" or "Create 5 new tasks for the design sprint with due dates" +3. **Instant Updates** — "Post a message to the Marketing project board about today's campaign results" +4. **Team Coordination** — "List all team members in the Q2 Planning project" or "Show me who's assigned to incomplete tasks" +5. **Bulk Operations** — "Mark all overdue to-dos as complete" or "Create to-dos from a list of requirements" ### 🔗 The Real Power: Combining Tools AI can chain multiple Basecamp operations together: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query projects → List to-dos → Identify blockers → Post status update +- Pull team members → Check task assignments → Balance workload +- Analyze completed tasks → Generate progress report → Share with stakeholders +- Create to-dos from meeting notes → Assign team members → Set deadlines ## 📦 What's Inside -**52 API tools** covering the entire Basecamp platform (Project Management). +**8 powerful API tools** covering core Basecamp operations: + +- **Projects**: `list_projects`, `get_project` +- **To-Dos**: `list_todos`, `create_todo`, `complete_todo` +- **Messages**: `list_messages`, `create_message` +- **People**: `list_people` All with proper error handling, automatic authentication, and TypeScript types. @@ -45,7 +52,11 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Basecamp API credentials** (see Authentication section below) +2. **Get your Basecamp API credentials:** + - Go to [Basecamp Launchpad](https://launchpad.37signals.com/integrations) + - Create a new OAuth 2.0 app (or use existing) + - Complete the OAuth flow to get an access token + - Find your Account ID in your Basecamp URL: `https://3.basecamp.com/{ACCOUNT_ID}/` 3. **Configure Claude Desktop:** @@ -58,9 +69,11 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "basecamp": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/basecamp-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/basecamp-mcp-2026-complete/dist/index.js"], "env": { - "BASECAMP_API_KEY": "your-api-key-here" + "BASECAMP_ACCESS_TOKEN": "your-oauth-token-here", + "BASECAMP_ACCOUNT_ID": "your-account-id-here", + "BASECAMP_APP_IDENTITY": "YourAppName (contact@yourdomain.com)" } } } @@ -74,7 +87,7 @@ All with proper error handling, automatic authentication, and TypeScript types. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/basecamp-mcp) 1. Click the button above -2. Set your Basecamp API credentials in Railway dashboard +2. Set `BASECAMP_ACCESS_TOKEN`, `BASECAMP_ACCOUNT_ID`, and `BASECAMP_APP_IDENTITY` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -82,32 +95,70 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t basecamp-mcp . docker run -p 3000:3000 \ - -e BASECAMP_API_KEY=your-key \ + -e BASECAMP_ACCESS_TOKEN=your-token \ + -e BASECAMP_ACCOUNT_ID=your-account-id \ + -e BASECAMP_APP_IDENTITY="MyApp (me@example.com)" \ basecamp-mcp ``` ## 🔐 Authentication -See the official [Basecamp API documentation](https://docs.basecamp.com) for authentication details. +Basecamp uses **OAuth 2.0** authentication with account-specific access tokens. -The MCP server handles token refresh automatically. +**Required credentials:** +- `BASECAMP_ACCESS_TOKEN` — OAuth 2.0 access token from Basecamp Launchpad +- `BASECAMP_ACCOUNT_ID` — Your account ID (from URL: `https://3.basecamp.com/{ACCOUNT_ID}/`) +- `BASECAMP_APP_IDENTITY` — User-Agent identifier: `"AppName (contact@email.com)"` (required by Basecamp API) -## 🎯 Example Prompts +**Setting up OAuth 2.0:** +1. Visit [Basecamp Launchpad](https://launchpad.37signals.com/integrations) +2. Register your application +3. Complete the OAuth flow to get an access token +4. Store the token securely (it doesn't expire but can be revoked) -Once connected to Claude, you can use natural language. Examples: +**Official docs:** [Basecamp 4 API Authentication](https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md) -- *"Show me recent activity in Basecamp"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +The MCP server handles API routing and authentication headers automatically. + +## 🎯 Example Prompts for Claude + +Once connected, you can use natural language to manage your projects: + +**Project Management:** +- *"Show me all active projects"* +- *"Get details for the Q1 Launch project including all tools and team members"* +- *"List archived projects from last year"* + +**Task Management:** +- *"Show me all incomplete to-dos in the Engineering project"* +- *"Create a new to-do: 'Review design mockups' in the Design to-do list, assign to Sarah, due Friday"* +- *"Mark to-do #12345 as complete"* +- *"List all overdue tasks across all projects"* + +**Team Communication:** +- *"Post a message to the Marketing project board: 'Campaign launched successfully, tracking metrics'"* +- *"List recent messages in the Product Development project"* +- *"Create an announcement about tomorrow's team meeting"* + +**Team Coordination:** +- *"Show me all people in the Q2 Planning project"* +- *"List all team members across the account"* +- *"Find who's assigned to incomplete tasks in Engineering"* + +**Bulk Operations:** +- *"Create 10 to-dos from this requirements list and assign them to different team members"* +- *"Generate a project status report by pulling all completed tasks from last week"* + +**Combined Operations:** +- *"Check all projects → identify incomplete to-dos → post a summary message to each project"* +- *"Pull team members → analyze task distribution → suggest workload rebalancing"* ## 🛠️ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Basecamp account with API access +- Basecamp 4 account with API access ### Setup @@ -132,9 +183,18 @@ 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 +- Verify your OAuth access token is valid +- Check that your Account ID matches your Basecamp URL +- Ensure your token hasn't been revoked (check Launchpad) + +### "Missing User-Agent" +- Basecamp requires a `User-Agent` header in format: `"AppName (contact@email.com)"` +- Set `BASECAMP_APP_IDENTITY` environment variable with your app details + +### "Project/To-Do list not found" +- Use `list_projects` to get valid project IDs +- Use `get_project` to find to-do list IDs in the project's "dock" +- IDs are numeric; ensure you're passing numbers, not strings ### "Tools not appearing in Claude" - Restart Claude Desktop after updating config @@ -143,7 +203,9 @@ npm run test:coverage # Coverage report ## 📖 Resources -- [Basecamp API Documentation](https://docs.basecamp.com) +- [Basecamp 4 API Documentation](https://github.com/basecamp/bc3-api) +- [Basecamp Launchpad (OAuth Setup)](https://launchpad.37signals.com/integrations) +- [Authentication Guide](https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,10 +225,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. --- -**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 63d6ff7..68916b5 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Basecamp API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",