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:

   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
   BASECAMP_CLIENT_SECRET=your_client_secret
   BASECAMP_REDIRECT_URI=http://localhost:8000/auth/callback
   USER_AGENT="Your App Name (your@email.com)"
   BASECAMP_ACCOUNT_ID=your_account_id
   FLASK_SECRET_KEY=random_secret_key
   

3. Authenticate with Basecamp:

   python oauth_app.py
   

   Visit http://localhost:8000 and complete the OAuth flow.

4. Generate and install Cursor configuration:

   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

# 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

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"

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

{
    "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, 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)

Token Management

• Tokens are stored securely in oauth_tokens.json
• Tokens refresh automatically when they expire
• View token info at http://localhost:8000/token/info
• Clear tokens at http://localhost:8000/logout

Security Notes

• File-based token storage is suitable for development
• Use a database or secure key management in production
• Always use HTTPS in production environments

License

MIT License - see LICENSE file for details.

Recent Changes

March 9, 2024 - Improved MCP Server Functionality

• Added standardized error and success response handling with new mcp_response helper function
• Fixed API endpoint issues for Basecamp Campfire (chat) functionality:
  • Updated the URL format for retrieving campfires from projects/{project_id}/campfire.json to buckets/{project_id}/chats.json
  • Added support for retrieving campfire chat lines
• Enhanced search capabilities to include campfire lines content
• Improved error handling and response formatting across all action handlers
• Fixed CORS support by adding the Flask-CORS package

These changes ensure more reliable and consistent responses from the MCP server, particularly for Campfire chat functionality.

March 9, 2024 - Added Local Testing

Added comprehensive test suite for reliable local deployment:

• Unit tests for all MCP endpoints
• Authentication guard testing
• Easy verification with pytest -q

TODO: Composio Integration

Note: The following Composio integration is planned for future implementation but not currently functional.

TODO: March 9, 2024 - Added Composio Integration

TODO: Add support for Composio integration, allowing the Basecamp MCP server to be used with Composio for AI-powered workflows. This integration follows the Model Context Protocol (MCP) standards and includes:

• TODO: New endpoints for Composio compatibility:

  • /composio/schema - Returns the schema of available tools in Composio-compatible format
  • /composio/tool - Handles Composio tool calls with standardized parameters
  • /composio/check_auth - Checks authentication status for Composio requests

• TODO: Standardized tool naming and parameter formats to work with Composio's MCP specifications

• TODO: A standalone example client for testing and demonstrating the integration

TODO: Using with Composio

TODO: Prerequisites

1. TODO: Create a Composio account at https://app.composio.dev
2. TODO: Obtain a Composio API key from your Composio dashboard
3. TODO: Add your API key to your .env file:

   COMPOSIO_API_KEY=your_composio_api_key
   

TODO: Setting Up Composio Integration

1. TODO: Make sure you have authenticated with Basecamp using the OAuth app (http://localhost:8000/)

2. TODO: Run the MCP server with the Composio integration enabled:

   python mcp_server.py
   

3. TODO: In your Composio dashboard, add a new custom integration:

   • Integration URL: http://localhost:5001/composio/schema
   • Authentication: OAuth (managed by our implementation)

4. TODO: You can now use Composio to connect to your Basecamp account through the MCP server:

   • Composio will discover available tools via the schema endpoint
   • Tool executions will be handled by the /composio/tool endpoint
   • Authentication status is checked via the /composio/check_auth endpoint

TODO: Example Composio Client

TODO: We provide a simple client example in composio_client_example.py that demonstrates how to:

1. Check authentication status
2. Retrieve the tool schema
3. Execute various Basecamp operations through the Composio integration

TODO: Run the example with:

python composio_client_example.py

TODO: Testing the Integration

TODO: To test the integration without connecting to Composio:

1. Run the MCP server:

   python mcp_server.py
   

2. Use curl to test the endpoints directly:

   # Check authentication status
   curl http://localhost:5001/composio/check_auth
   
   # Get the schema
   curl http://localhost:5001/composio/schema
   
   # Execute a tool (get projects)
   curl -X POST http://localhost:5001/composio/tool \
     -H "Content-Type: application/json" \
     -d '{"tool": "GET_PROJECTS", "params": {}}'
   

TODO: For more detailed documentation on Composio integration, refer to the official Composio documentation.

Quick Setup for Cursor

Step-by-Step Instructions

1. Clone and setup the project:

   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:

   BASECAMP_CLIENT_ID=your_client_id
   BASECAMP_CLIENT_SECRET=your_client_secret
   BASECAMP_REDIRECT_URI=http://localhost:8000/auth/callback
   USER_AGENT="Your App Name (your@email.com)"
   BASECAMP_ACCOUNT_ID=your_account_id
   FLASK_SECRET_KEY=random_secret_key
   

3. Authenticate with Basecamp:

   python oauth_app.py
   

   Then visit http://localhost:8000 and complete the OAuth flow.

4. Generate and install Cursor configuration:

   python generate_cursor_config.py
   

   This script will:

   • Generate the correct MCP configuration with full paths
   • Automatically detect your virtual environment
   • Update your Cursor configuration file
   • Provide next steps

5. Test the CLI server:

   python -m pytest tests/test_cli_server.py -v
   

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

7. Verify in Cursor:

   • Go to Cursor Settings → MCP
   • You should see "basecamp" with a green checkmark
   • It should show available tools like "get_projects", "search_basecamp", etc.

Critical Configuration Requirements

Based on the Cursor community forum, the following are essential for MCP servers to work properly:

1. Full executable paths (not just "python")
2. Proper environment variables (PYTHONPATH, VIRTUAL_ENV)
3. Correct working directory (cwd)
4. MCP protocol compliance (handling 'initialized' notifications)

Manual Configuration (if needed)

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

On macOS/Linux: ~/.cursor/mcp.json
On Windows: %APPDATA%\Cursor\mcp.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"
            }
        }
    }
}

Troubleshooting

• Yellow indicator (not green): Check that the full Python path is correct and virtual environment exists
• "No tools available": Make sure you completed OAuth authentication first (python oauth_app.py)
• "Tool not found" errors: Restart Cursor completely and check mcp_cli_server.log for errors
• Server not starting: Verify all paths in the configuration are absolute and correct
• Can't find mcp.json: Run python generate_cursor_config.py to create it automatically

Testing Without Cursor

You can test the MCP server directly:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python mcp_server_cli.py

What Fixed the Yellow/Green Issue

The key fixes that resolve the "yellow indicator" and "tool not found" issues mentioned in the Cursor forums:

1. Full Python executable path instead of just "python"
2. Environment variables for PYTHONPATH and VIRTUAL_ENV
3. Proper MCP protocol handling including the 'initialized' notification
4. Absolute paths for all configuration values