basecamp-mcp-server/README.md

# Basecamp MCP Integration

This project provides a MCP (Model Context Protocol) integration for Basecamp 3, allowing Cursor to interact with Basecamp directly through the MCP protocol.

## Quick Setup for Cursor

### Prerequisites

- Python 3.7+
- A Basecamp 3 account
- A Basecamp OAuth application (create one at https://launchpad.37signals.com/integrations)

### Step-by-Step Instructions

1. **Clone and setup the project:**
   ```bash
   git clone <repository-url>
   cd basecamp-mcp
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install --upgrade pip
   pip install -r requirements.txt
   ```

2. **Create your `.env` file with your Basecamp OAuth credentials:**
   ```
   BASECAMP_CLIENT_ID=your_client_id_here
   BASECAMP_CLIENT_SECRET=your_client_secret_here
   BASECAMP_REDIRECT_URI=http://localhost:8000/auth/callback
   BASECAMP_ACCOUNT_ID=your_account_id_here
   USER_AGENT="Your App Name (your@email.com)"
   FLASK_SECRET_KEY=any_random_string_here
   MCP_API_KEY=any_random_string_here
   ```

3. **Authenticate with Basecamp:**
   ```bash
   python oauth_app.py
   ```
   Visit http://localhost:8000 and complete the OAuth flow.

4. **Generate and install Cursor configuration:**
   ```bash
   python generate_cursor_config.py
   ```

   This script will:
   - Generate the correct MCP configuration with full paths
   - Automatically detect your virtual environment
   - Include the BASECAMP_ACCOUNT_ID environment variable
   - Update your Cursor configuration file automatically

5. **Restart Cursor completely** (quit and reopen, not just reload)

6. **Verify in Cursor:**
   - Go to Cursor Settings → MCP
   - You should see "basecamp" with a **green checkmark**
   - Available tools: "get_projects", "search_basecamp", "get_project", etc.

### Test Your Setup

```bash
# Quick test the MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python mcp_server_cli.py

# Run automated tests
python -m pytest tests/ -v
```

## Available MCP Tools

Once configured, you can use these tools in Cursor:

- `get_projects` - Get all Basecamp projects
- `get_project` - Get details for a specific project
- `get_todolists` - Get todo lists for a project
- `get_todos` - Get todos from a todo list
- `search_basecamp` - Search across projects, todos, and messages
- `get_comments` - Get comments for a Basecamp item
- `get_campfire_lines` - Get recent messages from a Basecamp campfire
- `get_daily_check_ins` - Get project's daily check-in questions
- `get_question_answers` - Get answers to daily check-in questions

### Card Table Tools

- `get_card_table` - Get the card table details for a project
- `get_columns` - Get all columns in a card table
- `get_column` - Get details for a specific column
- `create_column` - Create a new column in a card table
- `update_column` - Update a column title
- `move_column` - Move a column to a new position
- `update_column_color` - Update a column color
- `put_column_on_hold` - Put a column on hold (freeze work)
- `remove_column_hold` - Remove hold from a column (unfreeze work)
- `watch_column` - Subscribe to notifications for changes in a column
- `unwatch_column` - Unsubscribe from notifications for a column
- `get_cards` - Get all cards in a column
- `get_card` - Get details for a specific card
- `create_card` - Create a new card in a column
- `update_card` - Update a card
- `move_card` - Move a card to a new column and/or position

### Example Cursor Usage

Ask Cursor things like:
- "Show me all my Basecamp projects"
- "What todos are in project X?"
- "Search for messages containing 'deadline'"
- "Get details for the Technology project"
- "Show me the card table for project X"
- "Create a new card in the 'In Progress' column"
- "Move this card to the 'Done' column"
- "Update the color of the 'Urgent' column to red"

## Architecture

The project consists of:

1. **OAuth App** (`oauth_app.py`) - Handles OAuth 2.0 flow with Basecamp
2. **MCP Server** (`mcp_server_cli.py`) - Implements MCP protocol for Cursor
3. **Token Storage** (`token_storage.py`) - Securely stores OAuth tokens
4. **Basecamp Client** (`basecamp_client.py`) - Basecamp API client library
5. **Search Utilities** (`search_utils.py`) - Search across Basecamp resources

## Troubleshooting

### Common Issues

- **Yellow indicator (not green):** Check that paths in Cursor config are correct
- **"No tools available":** Make sure you completed OAuth authentication first
- **"Tool not found" errors:** Restart Cursor completely and check `mcp_cli_server.log`
- **Missing BASECAMP_ACCOUNT_ID:** The config generator automatically includes this from your `.env` file

### Configuration Issues

If automatic configuration doesn't work, manually edit your Cursor MCP configuration:

**On macOS/Linux:** `~/.cursor/mcp.json`
**On Windows:** `%APPDATA%\Cursor\mcp.json`

```json
{
    "mcpServers": {
        "basecamp": {
            "command": "/full/path/to/your/project/venv/bin/python",
            "args": ["/full/path/to/your/project/mcp_server_cli.py"],
            "cwd": "/full/path/to/your/project",
            "env": {
                "PYTHONPATH": "/full/path/to/your/project",
                "VIRTUAL_ENV": "/full/path/to/your/project/venv",
                "BASECAMP_ACCOUNT_ID": "your_account_id"
            }
        }
    }
}
```

### Key Requirements

Based on [Cursor community forums](https://forum.cursor.com/t/mcp-servers-no-tools-found/49094), the following are essential:

1. **Full executable paths** (not just "python")
2. **Proper environment variables** (PYTHONPATH, VIRTUAL_ENV, BASECAMP_ACCOUNT_ID)
3. **Correct working directory** (cwd)
4. **MCP protocol compliance** (our server handles this correctly)

## Finding Your Account ID

If you don't know your Basecamp account ID:
1. Log into Basecamp in your browser
2. Look at the URL - it will be like `https://3.basecamp.com/4389629/projects`
3. The number (4389629 in this example) is your account ID

## Security Notes

- Keep your `.env` file secure and never commit it to version control
- The OAuth tokens are stored locally in `oauth_tokens.json`
- This setup is designed for local development use

## License

This project is licensed under the MIT License.