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

refactor: Remove deprecated files and clean up codebase

Browse Source 
This commit deletes obsolete files related to the Basecamp MCP integration, including:
- `basecamp_client.py`
- `basecamp_oauth.py`
- `composio_client_example.py`
- `composio_integration.py`
- `mcp_integration.py`
- `setup.sh`
- `start_basecamp_mcp.sh`

Additionally, a new file `mcp_server_cli.py` is introduced to streamline the MCP server functionality. The README has been updated to reflect these changes and provide clearer setup instructions.

This cleanup aims to enhance maintainability and focus on the core components of the integration.
This commit is contained in:
George Antonopoulos
2025-06-02 17:11:39 +01:00
parent b0deac4d87
commit b3a6efc5d7
16 changed files with 1050 additions and 2732 deletions
Download Patch File Download Diff File Expand all files Collapse all files

379
README.md
View File

@@ -1,46 +1,28 @@
# 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
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
## Quick Setup for Cursor
### Prerequisites
- Python 3.7+
- A Basecamp 3 account
- A Basecamp 3 account
- 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>
cd basecamp-mcp
```
2. Create and activate a virtual environment:
```
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```
pip install --upgrade pip
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_SECRET=your_client_secret
@@ -48,110 +30,129 @@ The project consists of the following components:
USER_AGENT="Your App Name (your@email.com)"
BASECAMP_ACCOUNT_ID=your_account_id
FLASK_SECRET_KEY=random_secret_key
MCP_API_KEY=your_api_key
COMPOSIO_API_KEY=your_composio_api_key
```
## Usage
### Starting the Servers
1. Start the OAuth app:
```
3. **Authenticate with Basecamp:**
```bash
python oauth_app.py
```
Visit http://localhost:8000 and complete the OAuth flow.
2. Start the MCP server:
```
python mcp_server.py
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
### OAuth Authentication
5. **Restart Cursor completely** (quit and reopen, not just reload)
1. Visit http://localhost:8000/ in your browser
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
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.
### Using with Cursor
### Test Your Setup
1. In Cursor, add the MCP server URL: `http://localhost:5001/mcp/stream`
- **Note:** This URL points to the new Server-Sent Events (SSE) endpoint. Cursor may prefer this for real-time updates and for features like `ListOfferings` that stream data.
- If you encounter issues, Cursor might alternatively try to use the base URL (`http://localhost:5001`) to first query `/mcp/info` (to discover available actions and endpoints) and then connect to the appropriate endpoint as indicated there.
2. Interact with Basecamp through the Cursor interface.
3. The MCP server will use the stored OAuth token to authenticate with Basecamp.
```bash
# Quick test the MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python mcp_server_cli.py
### Authentication Flow
When using the MCP server with Cursor, the authentication flow is as follows:
1. Cursor makes a request to the MCP server
2. The MCP server checks if OAuth authentication has been completed
3. If not, it returns an error with instructions to authenticate
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"
}
# Run automated tests
python -m pytest tests/ -v
```
This method also checks for OAuth authentication and returns appropriate error messages if needed.
## Available MCP Tools
## Token Management
Once configured, you can use these tools in Cursor:
- 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
- `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
- **Token Issues**: If you encounter authentication errors, try logging out and logging in again through the OAuth app
- **MCP Connection Issues**: Make sure both the OAuth app and MCP server are running
- **API Errors**: Check the logs in `oauth_app.log` and `mcp_server.log` for detailed error messages
### Common Issues
## Security Considerations
- **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
- This implementation uses file-based token storage, which is suitable for development but not for production
- In a production environment, use a database or secure key management service for token storage
- Always use HTTPS in production and implement proper authentication for the API endpoints
### 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)
## 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
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License - see LICENSE file for details.
## Recent Changes
@@ -167,62 +168,73 @@ This project is licensed under the MIT License - see the LICENSE file for detail
These changes ensure more reliable and consistent responses from the MCP server, particularly for Campfire chat functionality.
### March 9, 2024 - Added Composio Integration
### March 9, 2024 - Added Local Testing
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:
Added comprehensive test suite for reliable local deployment:
- Unit tests for all MCP endpoints
- Authentication guard testing
- Easy verification with `pytest -q`
- New endpoints for Composio compatibility:
## 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](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:
- 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
- Standardized tool naming and parameter formats to work with Composio's MCP specifications
- A standalone example client for testing and demonstrating the integration
- 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
## Using with Composio
### TODO: Using with Composio
### Prerequisites
### TODO: 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:
1. TODO: Create a Composio account at [https://app.composio.dev](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
```
### Setting Up Composio Integration
### TODO: 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:
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. In your Composio dashboard, add a new custom integration:
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. You can now use Composio to connect to your Basecamp account through the MCP server:
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
### Example Composio Client
### TODO: Example Composio Client
We provide a simple client example in `composio_client_example.py` that demonstrates how to:
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
Run the example with:
TODO: Run the example with:
```
python composio_client_example.py
```
### Testing the Integration
### TODO: Testing the Integration
To test the integration without connecting to Composio:
TODO: To test the integration without connecting to Composio:
1. Run the MCP server:
```
@@ -243,4 +255,115 @@ To test the integration without connecting to Composio:
-d '{"tool": "GET_PROJECTS", "params": {}}'
```
For more detailed documentation on Composio integration, refer to the [official Composio documentation](https://docs.composio.dev).
TODO: For more detailed documentation on Composio integration, refer to the [official Composio documentation](https://docs.composio.dev).
## Quick Setup for Cursor
### 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:**
```
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:**
```bash
python oauth_app.py
```
Then 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
- Update your Cursor configuration file
- Provide next steps
5. **Test the CLI server:**
```bash
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](https://forum.cursor.com/t/mcp-servers-no-tools-found/49094), 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`
```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:
```bash
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](https://forum.cursor.com/t/mcp-tools-enabled-in-settings-but-cursor-not-detecting-tools/96663):
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