# Basecamp MCP Server

A comprehensive Model Context Protocol (MCP) server for Basecamp 4 API integration.

## Features

- **Complete API Coverage**: 50+ tools covering all major Basecamp 4 API endpoints
- **Rich UI Components**: 18 React MCP apps for visualizing and managing Basecamp data
- **Robust Client**: OAuth2 authentication, automatic pagination, and comprehensive error handling
- **Type-Safe**: Full TypeScript implementation with detailed type definitions

## Installation

```bash
npm install
npm run build
```

## Configuration

Set the following environment variables:

```bash
export BASECAMP_ACCOUNT_ID="your-account-id"
export BASECAMP_ACCESS_TOKEN="your-oauth-token"
export BASECAMP_USER_AGENT="YourApp (your-email@example.com)"  # Optional
```

### Getting Your Credentials

1. **Account ID**: Found in your Basecamp URL: `https://3.basecamp.com/{ACCOUNT_ID}/`
2. **Access Token**: Create an OAuth2 application at https://launchpad.37signals.com/integrations
   - Follow Basecamp's OAuth flow to get an access token
   - Scopes required: Full access to projects, todos, messages, etc.

## Usage

### As MCP Server

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "basecamp": {
      "command": "node",
      "args": ["/path/to/basecamp-mcp/dist/main.js"],
      "env": {
        "BASECAMP_ACCOUNT_ID": "your-account-id",
        "BASECAMP_ACCESS_TOKEN": "your-token"
      }
    }
  }
}
```

### Standalone

```bash
npm start
```

## Available Tools (50+)

### Projects (7 tools)
- `basecamp_projects_list` - List all projects
- `basecamp_project_get` - Get project details
- `basecamp_project_create` - Create new project
- `basecamp_project_update` - Update project
- `basecamp_project_archive` - Archive project
- `basecamp_project_trash` - Move project to trash
- `basecamp_project_tools_list` - List project tools (dock)

### Todolists (5 tools)
- `basecamp_todolists_list` - List todolists in project
- `basecamp_todolist_get` - Get todolist details
- `basecamp_todolist_create` - Create new todolist
- `basecamp_todolist_update` - Update todolist
- `basecamp_todolist_reorder` - Reorder todolists

### Todos (8 tools)
- `basecamp_todos_list` - List todos in todolist
- `basecamp_todo_get` - Get todo details
- `basecamp_todo_create` - Create new todo
- `basecamp_todo_update` - Update todo
- `basecamp_todo_complete` - Mark todo as complete
- `basecamp_todo_uncomplete` - Mark todo as incomplete
- `basecamp_todos_reorder` - Reorder todos

### Messages (5 tools)
- `basecamp_messages_list` - List messages on message board
- `basecamp_message_get` - Get message details
- `basecamp_message_create` - Create new message
- `basecamp_message_update` - Update message
- `basecamp_message_trash` - Move message to trash

### Comments (4 tools)
- `basecamp_comments_list` - List comments on recording
- `basecamp_comment_get` - Get comment details
- `basecamp_comment_create` - Create new comment
- `basecamp_comment_update` - Update comment

### Campfire (2 tools)
- `basecamp_campfire_lines_list` - List recent chat messages
- `basecamp_campfire_line_create` - Send chat message

### Schedules (5 tools)
- `basecamp_schedules_list` - List schedules in project
- `basecamp_schedule_entries_list` - List schedule entries
- `basecamp_schedule_entry_get` - Get entry details
- `basecamp_schedule_entry_create` - Create new schedule entry
- `basecamp_schedule_entry_update` - Update schedule entry

### Documents (4 tools)
- `basecamp_documents_list` - List documents in vault
- `basecamp_document_get` - Get document details
- `basecamp_document_create` - Create new document
- `basecamp_document_update` - Update document

### Uploads (3 tools)
- `basecamp_uploads_list` - List uploaded files
- `basecamp_upload_get` - Get upload details
- `basecamp_upload_create` - Upload file

### People (6 tools)
- `basecamp_people_list` - List all people in account
- `basecamp_person_get` - Get person details
- `basecamp_project_people_list` - List people in project
- `basecamp_project_person_add` - Add person to project
- `basecamp_project_person_remove` - Remove person from project
- `basecamp_profile_get` - Get current user profile

### Questionnaires (4 tools)
- `basecamp_questionnaires_list` - List automatic check-ins
- `basecamp_questionnaire_get` - Get questionnaire details
- `basecamp_questions_list` - List questions in questionnaire
- `basecamp_answers_list` - List answers to question

### Webhooks (4 tools)
- `basecamp_webhooks_list` - List all webhooks
- `basecamp_webhook_create` - Create new webhook
- `basecamp_webhook_update` - Update webhook
- `basecamp_webhook_delete` - Delete webhook

### Recordings (5 tools)
- `basecamp_recordings_list` - List all recordings (generic content)
- `basecamp_recording_get` - Get recording details
- `basecamp_recording_archive` - Archive recording
- `basecamp_recording_unarchive` - Unarchive recording
- `basecamp_recording_trash` - Move recording to trash

## MCP Apps (18 React Components)

### Project Management
- **project-dashboard** - Overview of all projects with filtering
- **project-detail** - Detailed single project view with dock
- **project-grid** - Grid view of all projects

### Task Management
- **todo-board** - Kanban-style todo board
- **todo-detail** - Detailed todo view with comments

### Communication
- **message-board** - Message board posts list
- **message-detail** - Single message with comments
- **campfire-chat** - Real-time team chat interface

### Planning
- **schedule-calendar** - Calendar view of schedule entries
- **project-timeline** - Gantt-style timeline

### Content
- **document-browser** - Browse and manage documents
- **file-manager** - File upload management

### People
- **people-directory** - Team member directory

### Check-ins
- **checkin-dashboard** - Automatic check-in overview
- **checkin-responses** - View responses to check-ins

### Insights
- **activity-feed** - Recent project activity
- **search-results** - Global search interface
- **hill-chart** - Visual progress tracking

## Architecture

```
src/
├── clients/
│   └── basecamp.ts          # API client with OAuth2 & pagination
├── tools/
│   ├── projects-tools.ts    # Project management tools
│   ├── todolists-tools.ts   # Todolist tools
│   ├── todos-tools.ts       # Todo tools
│   ├── messages-tools.ts    # Message board tools
│   ├── comments-tools.ts    # Comment tools
│   ├── campfires-tools.ts   # Chat tools
│   ├── schedules-tools.ts   # Schedule tools
│   ├── documents-tools.ts   # Document tools
│   ├── uploads-tools.ts     # File upload tools
│   ├── people-tools.ts      # People management tools
│   ├── questionnaires-tools.ts # Check-in tools
│   ├── webhooks-tools.ts    # Webhook tools
│   └── recordings-tools.ts  # Generic recordings tools
├── types/
│   └── index.ts             # TypeScript type definitions
├── ui/
│   └── react-app/
│       ├── index.tsx        # App registry
│       └── apps/            # 18 React MCP apps
├── server.ts                # MCP server implementation
└── main.ts                  # Entry point
```

## API Reference

### Basecamp 4 API

- Base URL: `https://3.basecampapi.com/{account_id}/`
- Authentication: OAuth2 Bearer token
- Rate limiting: Respected via standard headers
- User-Agent: Required for all requests

### Error Handling

The client handles common errors:
- 401: Invalid/expired token
- 403: Permission denied
- 404: Resource not found
- 429: Rate limit exceeded
- 500-503: Server errors

## Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run dev
```

## License

MIT

## Contributing

Contributions welcome! Please ensure:
- All tools have proper input validation
- TypeScript types are comprehensive
- Error handling is consistent
- MCP apps are self-contained

## Links

- [Basecamp API Documentation](https://github.com/basecamp/bc3-api)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCPEngine Repository](https://github.com/BusyBee3333/mcpengine)