# 🏕️ Basecamp MCP Server

A professional **Model Context Protocol (MCP)** server that provides complete programmatic access to **Basecamp 4 API**. Perfect for AI agents, workflow automation, and custom integrations.

## 🚀 NEW in v7.5.0: Claude.ai Compatible!

**The most comprehensive AND most compatible Basecamp MCP server available!**

### What's New in v7.5:
- ✅ **Full Claude.ai compatibility** - Works perfectly in Claude web interface
- ✅ **Latest MCP protocol** - Supports 2025-06-18 specification
- ✅ **Session management** - Proper connection tracking for modern clients
- ✅ **Auto-discovery** - MCP config endpoint for automatic setup
- ✅ **Simplified authentication** - No KV storage, just OAuth + environment variables
- ✅ **55+ specialized tools** - Complete Basecamp API coverage

**🔥 Upgrade from v6.0?** See [UPGRADE-TO-V75.md](./UPGRADE-TO-V75.md) for migration guide.

✅ **8 Project Management** tools - Complete project lifecycle management  
✅ **11 Todo Management** tools - Advanced task automation with auto-lookup  
✅ **6 Communication** tools - Messages and discussions  
✅ **6 Documents & Files** tools - Content management and file handling  
✅ **4 Team Management** tools - Access control and permissions  
✅ **3 Campfire Chat** tools - Real-time communication  
✅ **3 Schedule Management** tools - Calendar and events  
✅ **4 Card Tables** tools - Kanban workflows  
✅ **5 Comments System** tools - Universal collaboration  
✅ **4 Webhooks** tools - Real-time notifications  
✅ **2 Search & Analytics** tools - Data insights  
🆕 **3 Enhanced Features** - Auto-lookup, URL parsing, OAuth flow  

**Enhanced Features:**
- **Auto-lookup functionality** - No more 404 errors! Automatically finds resource IDs
- **OAuth 2.0 integration** - Complete authentication flow with setup UI
- **Multiple authentication methods** - Bearer token, arguments, environment variables
- **Production-ready deployment** - Cloudflare Workers optimized

[![Deploy to Cloudflare Workers](https://img.shields.io/badge/Deploy%20to-Cloudflare%20Workers-orange)](https://workers.cloudflare.com/)
[![MCP Protocol](https://img.shields.io/badge/MCP-2025--06--18-blue)](https://modelcontextprotocol.io/)
[![Version](https://img.shields.io/badge/version-7.5.0-brightgreen)](https://github.com/QusaiiSaleem/basecamp-mcp-server/releases)
[![Claude.ai Compatible](https://img.shields.io/badge/Claude.ai-Compatible-blueviolet)](https://claude.ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

### 🛠️ Complete Tool Coverage (59 Tools)
- **Project Management** (8 tools): Full CRUD operations, archiving, construction
- **Todo Management** (11 tools): Lists, items, assignments, completion, positioning
- **Communication** (6 tools): Messages, replies, discussions, archiving
- **Documents & Files** (6 tools): Create, edit, upload, manage attachments
- **Team Management** (4 tools): Add/remove people, permissions, access control
- **Comments & Collaboration** (5 tools): Universal commenting system across all content
- **Campfire Chat** (3 tools): Real-time chat messages and history
- **Schedule Management** (3 tools): Events, milestones, calendar entries
- **Card Tables** (4 tools): Kanban boards, cards, columns, positioning
- **Webhooks** (4 tools): Real-time notifications and event subscriptions
- **Search & Analytics** (2 tools): Content search and activity tracking

### 🔐 Authentication & Security
- **OAuth 2.0** complete authentication flow with setup UI
- **Multi-authentication support** with token priorities:
  1. `access_token` in arguments (highest priority)
  2. `Authorization: Bearer TOKEN` header
  3. `BASECAMP_ACCESS_TOKEN` environment variable (fallback)
- **Individual user tokens** while sharing infrastructure
- **Secure token handling** with proper validation
- **Simplified deployment** - No KV storage required (v7.5+)

### 🚀 Production Ready
- **Edge deployment** on Cloudflare Workers
- **Global CDN** with sub-100ms response times worldwide
- **Automatic scaling** handles any traffic volume
- **Rate limiting** compliance with Basecamp API limits
- **Comprehensive error handling** with meaningful messages
- **Auto-lookup functionality** prevents 404 errors

## 🚀 Quick Start

### 1. Deploy to Cloudflare Workers

```bash
# Clone the repository
git clone https://github.com/QusaiiSaleem/basecamp-mcp-server.git
cd basecamp-mcp-server

# Install dependencies
npm install

# Configure your environment
cp wrangler.toml.example wrangler.toml
# Edit wrangler.toml with your account ID

# Deploy to Cloudflare Workers
npm run deploy
```

### 2. Set Up Basecamp OAuth Integration

1. **Create Integration**: Visit [Basecamp Integrations](https://launchpad.37signals.com/integrations)
2. **Configure Settings**:
   - **Application Name**: "Your Basecamp MCP Server"
   - **Redirect URI**: `https://your-worker.workers.dev/auth/callback`
   - **Client Type**: Web Application

3. **Set Environment Variables**:
```bash
echo "your_client_id" | wrangler secret put BASECAMP_CLIENT_ID
echo "your_client_secret" | wrangler secret put BASECAMP_CLIENT_SECRET
echo "your_account_id" | wrangler secret put BASECAMP_ACCOUNT_ID
```

### 3. Get Your Access Token

Visit `https://your-worker.workers.dev/setup` and follow the OAuth flow to get your access token.

## 🌐 Claude.ai Integration

**NEW in v7.5**: Direct integration with Claude.ai web interface!

### Quick Setup

1. **Visit Claude.ai**: Go to [claude.ai](https://claude.ai)
2. **Open Settings**: Click Settings → Connectors
3. **Add Remote MCP Server**:
   - **Name**: `Basecamp MCP`
   - **URL**: `https://your-worker.workers.dev`
   - **Authentication**: `Bearer YOUR_ACCESS_TOKEN`
4. **Enable Toggle**: Turn on the connector ✅
5. **Verify Tools**: All 55 tools should appear in your conversation

### Full Setup Guide

For detailed step-by-step instructions including screenshots and troubleshooting, see:
- **[CLAUDE-AI-SETUP.md](./CLAUDE-AI-SETUP.md)** - Complete integration guide

### Test Your Connection

In Claude.ai, try these commands:
```
"List all my Basecamp projects"
"Show me my current todo assignments"
"Create a new message in Project X"
```

### Compatibility Matrix

| Client | v6.0 | v7.5 |
|--------|------|------|
| Claude.ai | ⚠️ Limited | ✅ Full |
| Claude Desktop | ✅ Works | ✅ Works |
| Smithery Playground | ⚠️ Limited | ✅ Full |
| RelevanceAI | ✅ Works | ✅ Works |
| n8n | ✅ Works | ✅ Works |
| Make.com | ✅ Works | ✅ Works |

## 🔧 Usage Examples

### With RelevanceAI

1. **Agent Settings** → **MCP Server** → **Add remote MCP tools**
2. **Server URL**: `https://your-worker.workers.dev`  
3. **Authentication**: `Bearer your_access_token_here`

### With Claude Desktop

Add to your MCP configuration (`~/.claude/mcp_servers.json`):

```json
{
  "basecamp": {
    "command": "node",
    "args": ["path/to/mcp-server"],
    "env": {
      "BASECAMP_ACCESS_TOKEN": "your_token_here",
      "BASECAMP_ACCOUNT_ID": "your_account_id"
    }
  }
}
```

### Direct API Usage

```javascript
// Enhanced auto-lookup - no more resource ID hunting!
{
  "tool": "get_todo_lists",
  "arguments": {
    "project_id": "123456"  // That's it! Auto-finds todoset ID
  }
}

// Create todos with full assignment control
{
  "tool": "create_todo",
  "arguments": {
    "project_id": "123456",
    "todolist_id": "789012",
    "content": "Complete project setup",
    "due_on": "2024-12-31",
    "assignee_ids": [1001, 1002]
  }
}

// Universal commenting system
{
  "tool": "add_comment_to_recording",
  "arguments": {
    "project_id": "123456",
    "recording_id": "789012",  // Works with any content type
    "content": "Great progress on this item!"
  }
}

// Smart URL parsing
{
  "tool": "parse_basecamp_url",
  "arguments": {
    "url": "https://3.basecamp.com/999999/buckets/123456/todolists/789012"
  }
}
```

## 📚 Complete Tool Reference

### 📋 Project Management (8 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_projects` | List all accessible projects | - |
| `create_project` | Create new project | `name`, `description` |
| `get_project` | Get project details | `project_id` |
| `update_project` | Update project info | `project_id`, `name`, `description` |
| `archive_project` | Archive project | `project_id` |
| `unarchive_project` | Unarchive project | `project_id` |
| `get_project_construction` | Get project tools/features | `project_id` |
| `parse_basecamp_url` | Parse any Basecamp URL | `url` |

### ✅ Todo Management (11 tools)  
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_todo_lists` 🚀 | Get todo lists (AUTO-LOOKUP) | `project_id` |
| `create_todo_list` 🚀 | Create todo list (AUTO-LOOKUP) | `project_id`, `name` |
| `get_todos` | Get todos from list | `project_id`, `todolist_id` |
| `get_all_project_todos` 🆕 | Get ALL project todos | `project_id` |
| `create_todo` | Create new todo | `project_id`, `todolist_id`, `content` |
| `update_todo` | Update todo details | `project_id`, `todo_id`, `content` |
| `complete_todo` | Mark todo complete | `project_id`, `todo_id` |
| `uncomplete_todo` | Mark todo incomplete | `project_id`, `todo_id` |
| `get_my_assignments` | Get current user assignments | - |
| `get_user_assignments` | Get user's assignments | `user_id` |
| `reposition_todo` | Change todo position | `project_id`, `todo_id`, `position` |

### 💬 Communication (6 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_message_board` 🚀 | Get message board (AUTO-LOOKUP) | `project_id` |
| `get_messages` 🚀 | Get messages (AUTO-LOOKUP) | `project_id` |
| `create_message` 🚀 | Create message (AUTO-LOOKUP) | `project_id`, `subject`, `content` |
| `update_message` | Edit message | `project_id`, `message_id`, `content` |
| `get_message` | Get specific message | `project_id`, `message_id` |
| `archive_message` | Archive message | `project_id`, `message_id` |

### 📄 Documents & Files (6 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_documents` 🚀 | List documents (AUTO-LOOKUP) | `project_id` |
| `create_document` 🚀 | Create document (AUTO-LOOKUP) | `project_id`, `title`, `content` |
| `update_document` | Edit document | `project_id`, `document_id`, `content` |
| `get_document` | Get specific document | `project_id`, `document_id` |
| `upload_attachment` | Upload file | `file_data`, `filename`, `content_type` |
| `get_uploads` | List project uploads | `project_id` |

### 👥 Team & People (4 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_people` | Get project team | `project_id` |
| `get_all_people` | Get all account people | - |
| `add_person_to_project` | Grant project access | `project_id`, `person_ids[]` |
| `remove_person_from_project` | Revoke project access | `project_id`, `person_ids[]` |

### 💭 Comments & Collaboration (5 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `add_comment_to_recording` | Universal comment tool | `project_id`, `recording_id`, `content` |
| `add_comment_to_todo` | Comment on todo | `project_id`, `todo_id`, `content` |
| `add_comment_to_message` | Reply to message | `project_id`, `message_id`, `content` |
| `add_comment_to_document` | Comment on document | `project_id`, `document_id`, `content` |
| `add_comment_to_card` | Comment on card | `project_id`, `card_id`, `content` |

### 💬 Campfire Chat (3 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_campfire` | Get project chat | `project_id` |
| `get_campfire_lines` | Get chat messages | `project_id`, `campfire_id` |
| `post_campfire_message` | Post chat message | `project_id`, `campfire_id`, `content` |

### 📅 Schedule Management (3 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_schedule` 🚀 | Get schedule (AUTO-LOOKUP) | `project_id` |
| `get_schedule_entries` | Get schedule events | `project_id` |
| `create_schedule_entry` | Create new event | `project_id`, `summary`, `starts_at` |

### 🎫 Card Tables (4 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_card_table` | Get Kanban board | `project_id` |
| `get_cards` | Get cards from table | `project_id`, `card_table_id` |
| `create_card` | Create new card | `project_id`, `card_table_id`, `title` |
| `update_card` | Update existing card | `project_id`, `card_id`, `title` |

### 🔗 Webhooks (4 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_webhooks` | List all webhooks | - |
| `create_webhook` | Create webhook | `payload_url`, `types[]` |
| `update_webhook` | Update webhook | `webhook_id`, `payload_url` |
| `delete_webhook` | Delete webhook | `webhook_id` |

### 🔍 Search & Analytics (2 tools)
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `search` | Search content | `query`, `project_id` (optional) |
| `get_events` | Get activity/events | `project_id` (optional) |

## 🔍 Smart Features

### 🧠 Auto-Lookup Intelligence
The server automatically finds required resource IDs, eliminating 404 errors:

```javascript
// Before: Complex resource ID hunting
{
  "tool": "get_todo_lists",
  "arguments": {
    "project_id": "123456",
    "todoset_id": "789012"  // ← Hard to find manually
  }
}

// After: Simple auto-lookup
{
  "tool": "get_todo_lists", 
  "arguments": {
    "project_id": "123456"  // ← Auto-finds todoset ID
  }
}
```

### 📈 URL Intelligence
Parse any Basecamp URL to extract project and resource information:

```javascript
// Input: https://3.basecamp.com/999999/buckets/123456/todolists/789012
// Output: 
{
  "account_id": "999999",
  "project_id": "123456", 
  "resource_type": "todolists",
  "resource_id": "789012",
  "suggested_tools": ["get_todos", "create_todo"]
}
```

### 🔄 Multi-Authentication Support
Flexible authentication with priority order:

1. **Arguments**: `access_token` parameter (highest priority)
2. **Headers**: `Authorization: Bearer TOKEN` 
3. **Environment**: `BASECAMP_ACCESS_TOKEN` (fallback)

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `BASECAMP_ACCOUNT_ID` | Your Basecamp account ID | ✅ |
| `BASECAMP_CLIENT_ID` | OAuth client ID | ✅ (for OAuth) |
| `BASECAMP_CLIENT_SECRET` | OAuth client secret | ✅ (for OAuth) |
| `BASECAMP_ACCESS_TOKEN` | Fallback access token | ⚠️ (optional) |

### wrangler.toml Example

```toml
name = "my-basecamp-mcp-server"
main = "index.ts"
compatibility_date = "2024-08-05"

[vars]
BASECAMP_ACCOUNT_ID = "999999999"

# Note: v7.5 no longer requires KV namespace binding
# All authentication is handled via environment variables
```

## 🔒 Security Best Practices

### Authentication Security
- **Individual Tokens**: Each user maintains their own OAuth token
- **Secure Headers**: All requests use proper authorization headers
- **Token Validation**: Automatic token validation and error handling
- **Environment Isolation**: Production secrets separate from code

### API Security  
- **Rate Limiting**: Automatic compliance with Basecamp API limits
- **Request Validation**: Input sanitization and type checking
- **Error Handling**: Secure error messages without data leaks
- **CORS Configuration**: Proper cross-origin resource sharing

## 🚀 Deployment Options

### Cloudflare Workers (Recommended)
- **Global Edge Network**: Sub-100ms response times worldwide
- **Automatic Scaling**: Handle unlimited traffic
- **Built-in Security**: DDoS protection, WAF, SSL
- **Cost Effective**: Pay per request, no idle costs

### Alternative Platforms
- **Vercel Functions**: Serverless deployment
- **AWS Lambda**: Enterprise-grade infrastructure  
- **Google Cloud Functions**: Google ecosystem integration
- **Azure Functions**: Microsoft ecosystem integration

### Self-Hosted Options
- **Node.js Server**: Traditional server deployment
- **Docker Container**: Containerized deployment
- **Kubernetes**: Container orchestration

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### Development Setup

```bash
# Clone the repository
git clone https://github.com/QusaiiSaleem/basecamp-mcp-server.git
cd basecamp-mcp-server

# Install dependencies
npm install

# Set up environment
cp wrangler.toml.example wrangler.toml

# Start development server
npm run dev
```

### Adding New Tools

1. **Define Tool Schema**: Add tool definition to `getAllBasecampTools()`
2. **Implement Handler**: Add case to `callBasecampTool()` switch statement
3. **Test Implementation**: Verify with Basecamp API endpoints
4. **Update Documentation**: Add to README tool reference
5. **Submit Pull Request**: Include tests and examples

## 📊 Performance & Monitoring

### Performance Metrics
- **Response Time**: Average <100ms globally
- **Availability**: 99.9% uptime SLA
- **Throughput**: 10,000+ requests per second capability
- **Error Rate**: <0.1% error rate

### Monitoring Features
- **Cloudflare Analytics**: Request metrics and performance
- **Custom Logging**: Detailed operation tracking
- **Error Reporting**: Automated error notifications  
- **Health Checks**: Continuous availability monitoring

## ❓ Troubleshooting

### Common Issues

#### Authentication Errors
```
Error: Authentication required
```
**Solution**: Ensure your access token is valid. Visit `/setup` for OAuth flow.

#### Configuration Missing
```
Error: BASECAMP_ACCESS_TOKEN not configured
```
**Solution**: Set up OAuth credentials or provide token in request headers.

#### Auto-lookup Failures
```
Error: Todo lists are not enabled for this project
```
**Solution**: Enable todo lists in your Basecamp project settings.

### Getting Help
- **GitHub Issues**: Report bugs and request features
- **Discussions**: Community support and questions
- **Documentation**: Comprehensive guides and examples

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🏆 Acknowledgments

- **Basecamp Team**: For providing an excellent API
- **MCP Community**: For the Model Context Protocol standard
- **Cloudflare**: For the edge computing platform
- **Contributors**: Thank you to all contributors!

## 📋 Version History

- **v7.5.0** (2025-09-30): Claude.ai compatibility + protocol updates - [CHANGELOG.md](./CHANGELOG.md)
- **v6.0.0** (2024-12-15): Complete 59-tool implementation
- **v5.0.0** (2024-10-01): Initial public release

## 🔗 Links

- **🏠 Homepage**: [GitHub Repository](https://github.com/QusaiiSaleem/basecamp-mcp-server)
- **📖 Documentation**: [Complete API Reference](#-complete-tool-reference)
- **🚀 Upgrade Guide**: [UPGRADE-TO-V75.md](./UPGRADE-TO-V75.md)
- **📝 Changelog**: [CHANGELOG.md](./CHANGELOG.md)
- **🤖 Claude.ai Setup**: [CLAUDE-AI-SETUP.md](./CLAUDE-AI-SETUP.md)
- **🐛 Issues**: [Bug Reports](https://github.com/QusaiiSaleem/basecamp-mcp-server/issues)
- **💬 Discussions**: [Community Forum](https://github.com/QusaiiSaleem/basecamp-mcp-server/discussions)
- **🏕️ Basecamp API**: [Official Documentation](https://github.com/basecamp/bc3-api)
- **🤖 MCP Protocol**: [Specification](https://modelcontextprotocol.io/)

---

**Transform your Basecamp workflow with complete API automation! 🚀**

**Now with full Claude.ai compatibility in v7.5!** ✨

[![Deploy Now](https://img.shields.io/badge/Deploy%20Now-Cloudflare%20Workers-orange?style=for-the-badge)](https://workers.cloudflare.com/)