jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/servers/basecamp/README.md

267 lines
8.0 KiB
Markdown
Raw Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink