m3tam3re/basecamp-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Update .gitignore to include Composio integration files and modify README for clarity and setup instructions

Browse Source
This commit is contained in:
George Antonopoulos
2025-06-02 17:19:35 +01:00
parent c9d4165584
commit 9bb32c5697
2 changed files with 59 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.gitignore vendored
View File

@@ -49,4 +49,9 @@ icons/
.idea/ .idea/
.vscode/ .vscode/
*.swp *.swp
*.swo *.swo
# Composio integration files
composio_client_example.py
*composio*
.composio/

258
README.md
View File

@@ -1,244 +1,92 @@
# Basecamp MCP Integration # Basecamp MCP Integration
This project provides a MCP (Magic Copy Paste) integration for Basecamp 3, allowing Cursor to interact with Basecamp directly through the MCP protocol. This project provides a MCP (Model Context Protocol) integration for Basecamp 3, allowing Cursor to interact with Basecamp directly through the MCP protocol.
## Architecture ## Quick Setup for Cursor
The project consists of the following components:
1. **OAuth App** (`oauth_app.py`) - A Flask application that handles the OAuth 2.0 flow with Basecamp.
2. **Token Storage** (`token_storage.py`) - A module for securely storing OAuth tokens.
3. **MCP Server** (`mcp_server.py`) - A Flask server that implements the MCP protocol for Basecamp.
4. **Basecamp Client** (`basecamp_client.py`) - A client library for interacting with the Basecamp API.
5. **Basecamp OAuth** (`basecamp_oauth.py`) - A utility for handling OAuth authentication with Basecamp.
6. **Search Utilities** (`search_utils.py`) - Utilities for searching Basecamp resources.
## Setup
### Prerequisites ### Prerequisites
- Python 3.7+ - Python 3.7+
- A Basecamp 3 account - A Basecamp 3 account
- A Basecamp OAuth application (create one at https://launchpad.37signals.com/integrations) - A Basecamp OAuth application (create one at https://launchpad.37signals.com/integrations)
### Installation ### Step-by-Step Instructions
1. Clone this repository: 1. **Clone and setup the project:**
``` ```bash
git clone <repository-url> git clone <repository-url>
cd basecamp-mcp cd basecamp-mcp
```
2. Create and activate a virtual environment:
```
python -m venv venv python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate source venv/bin/activate # On Windows: venv\Scripts\activate
``` pip install --upgrade pip
3. Install dependencies:
```
pip install -r requirements.txt pip install -r requirements.txt
``` ```
4. Create a `.env` file with the following variables: 2. **Create your `.env` file with your Basecamp OAuth credentials:**
``` ```
BASECAMP_CLIENT_ID=your_client_id BASECAMP_CLIENT_ID=your_client_id_here
BASECAMP_CLIENT_SECRET=your_client_secret BASECAMP_CLIENT_SECRET=your_client_secret_here
BASECAMP_REDIRECT_URI=http://localhost:8000/auth/callback BASECAMP_REDIRECT_URI=http://localhost:8000/auth/callback
BASECAMP_ACCOUNT_ID=your_account_id_here
USER_AGENT="Your App Name (your@email.com)" USER_AGENT="Your App Name (your@email.com)"
BASECAMP_ACCOUNT_ID=your_account_id FLASK_SECRET_KEY=any_random_string_here
FLASK_SECRET_KEY=random_secret_key MCP_API_KEY=any_random_string_here
MCP_API_KEY=your_api_key
COMPOSIO_API_KEY=your_composio_api_key
``` ```
## Usage 3. **Authenticate with Basecamp:**
```bash
### Starting the Servers
1. Start the OAuth app:
```
python oauth_app.py python oauth_app.py
``` ```
- Visit http://localhost:8000 in your browser
- Click "Log in with Basecamp" and complete the OAuth flow
- Keep the OAuth app running in the background
2. Start the MCP server: 4. **Generate Cursor configuration:**
``` ```bash
python mcp_server.py python generate_cursor_config.py
``` ```
This will automatically create the Cursor MCP configuration file in the correct location.
### OAuth Authentication 5. **Restart Cursor** to load the new MCP configuration.
1. Visit http://localhost:8000/ in your browser 6. **Test the integration** by using the Basecamp MCP tools in Cursor!
2. Click "Log in with Basecamp"
3. Follow the OAuth flow to authorize the application
4. The token will be stored securely in the token storage
### Using with Cursor ## Available MCP Tools
1. In Cursor, add the MCP server URL: http://localhost:5001 Once configured, you can use these tools in Cursor:
2. Interact with Basecamp through the Cursor interface
3. The MCP server will use the stored OAuth token to authenticate with Basecamp
### Authentication Flow - **Get Projects**: List all your Basecamp projects
- **Get Project**: Get details for a specific project
When using the MCP server with Cursor, the authentication flow is as follows: - **Get Todo Lists**: Get todo lists for a project
- **Get Todos**: Get todos from a todo list
1. Cursor makes a request to the MCP server - **Search Basecamp**: Search across projects, todos, and messages
2. The MCP server checks if OAuth authentication has been completed - **Get Comments**: Get comments for any Basecamp item
3. If not, it returns an error with instructions to authenticate - **Get Campfire Lines**: Get recent messages from project chat rooms
4. You authenticate using the OAuth app at http://localhost:8000/
5. After authentication, Cursor can make requests to the MCP server
### MCP Server API
The MCP server has two main methods for interacting with Basecamp:
**Preferred Method: Connection-based Approach**
This approach is recommended as it provides better error handling and state management:
1. Initiate a connection:
```
POST /initiate_connection
{
"auth_mode": "oauth"
}
```
2. Use the returned connection ID to make tool calls:
```
POST /tool/<connection_id>
{
"action": "get_projects"
}
```
If OAuth authentication hasn't been completed, the MCP server will return an error with instructions to authenticate.
**Alternative Method: Direct Action**
For simple requests, you can use the action endpoint:
```
POST /mcp/action
{
"action": "get_projects"
}
```
This method also checks for OAuth authentication and returns appropriate error messages if needed.
## Token Management
- Tokens are stored in `oauth_tokens.json`
- The token will be refreshed automatically when it expires
- You can view token info at http://localhost:8000/token/info
- You can logout and clear the token at http://localhost:8000/logout
## Troubleshooting ## Troubleshooting
- **Token Issues**: If you encounter authentication errors, try logging out and logging in again through the OAuth app ### Authentication Issues
- **MCP Connection Issues**: Make sure both the OAuth app and MCP server are running - Make sure the OAuth app is running: `python oauth_app.py`
- **API Errors**: Check the logs in `oauth_app.log` and `mcp_server.log` for detailed error messages - Visit http://localhost:8000 and re-authenticate if needed
- Check that your `.env` file has the correct credentials
## Security Considerations ### Cursor Connection Issues
- Restart Cursor after running `generate_cursor_config.py`
- Check that the generated configuration includes your `BASECAMP_ACCOUNT_ID`
- Make sure your virtual environment is activated when running the OAuth app
- This implementation uses file-based token storage, which is suitable for development but not for production ### Finding Your Account ID
- In a production environment, use a database or secure key management service for token storage If you don't know your Basecamp account ID:
- Always use HTTPS in production and implement proper authentication for the API endpoints 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 ## License
This project is licensed under the MIT License - see the LICENSE file for details. This project is licensed under the MIT License.
## 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 Composio Integration
Added support for [Composio](https://composio.dev/) 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:
- 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
- Standardized tool naming and parameter formats to work with Composio's MCP specifications
- A standalone example client for testing and demonstrating the integration
## Using with Composio
### Prerequisites
1. Create a Composio account at [https://app.composio.dev](https://app.composio.dev)
2. Obtain a Composio API key from your Composio dashboard
3. Add your API key to your `.env` file:
```
COMPOSIO_API_KEY=your_composio_api_key
```
### Setting Up Composio Integration
1. Make sure you have authenticated with Basecamp using the OAuth app (http://localhost:8000/)
2. Run the MCP server with the Composio integration enabled:
```
python mcp_server.py
```
3. In your Composio dashboard, add a new custom integration:
- Integration URL: `http://localhost:5001/composio/schema`
- Authentication: OAuth (managed by our implementation)
4. 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
### Example Composio Client
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
Run the example with:
```
python composio_client_example.py
```
### Testing the Integration
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:
```bash
# 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": {}}'
```
For more detailed documentation on Composio integration, refer to the [official Composio documentation](https://docs.composio.dev).