From ee3f31fcd29f16622da7dff3791d5cff59642082 Mon Sep 17 00:00:00 2001 From: George Antonopoulos Date: Sun, 27 Jul 2025 20:18:03 +0100 Subject: [PATCH] Add generate_claude_desktop_config.py for Claude Desktop integration - Introduce a new script to generate configuration for Claude Desktop based on Basecamp MCP integration. - Update README with setup instructions for Claude Desktop users, including configuration generation steps and troubleshooting tips. - Ensure compatibility with both Cursor and Claude Desktop clients. --- README.md | 100 ++++++++++++++++++++-- generate_claude_desktop_config.py | 137 ++++++++++++++++++++++++++++++ 2 files changed, 228 insertions(+), 9 deletions(-) create mode 100644 generate_claude_desktop_config.py diff --git a/README.md b/README.md index f8225f2..1862174 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,9 @@ This project provides a **FastMCP-powered** integration for Basecamp 3, allowing āœ… **Migration Complete:** Successfully migrated to official Anthropic FastMCP framework with **100% feature parity** (all 46 tools) šŸš€ **Ready for Production:** Full protocol compliance with MCP 2025-06-18 -## Quick Setup for Cursor +## Quick Setup + +This server works with both **Cursor** and **Claude Desktop**. Choose your preferred client: ### Prerequisites @@ -13,7 +15,7 @@ This project provides a **FastMCP-powered** integration for Basecamp 3, allowing - A Basecamp 3 account - A Basecamp OAuth application (create one at https://launchpad.37signals.com/integrations) -### Step-by-Step Instructions +## For Cursor Users ### One-Command Setup @@ -60,7 +62,7 @@ This project provides a **FastMCP-powered** integration for Basecamp 3, allowing ### Test Your Setup ```bash -# Quick test the FastMCP server +# Quick test the FastMCP server (works with both clients) echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}} {"jsonrpc":"2.0","method":"notifications/initialized","params":{}} {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | python basecamp_fastmcp.py @@ -69,6 +71,82 @@ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion": python -m pytest tests/ -v ``` +## For Claude Desktop Users + +Based on the [official MCP quickstart guide](https://modelcontextprotocol.io/quickstart/server), Claude Desktop integration follows these steps: + +### Setup Steps + +1. **Complete the basic setup** (steps 1-3 from Cursor setup above): + ```bash + git clone + cd basecamp-mcp + python setup.py + # Configure .env file with OAuth credentials + python oauth_app.py + ``` + +2. **Generate Claude Desktop configuration:** + ```bash + python generate_claude_desktop_config.py + ``` + +3. **Restart Claude Desktop completely** (quit and reopen the application) + +4. **Verify in Claude Desktop:** + - Look for the "Search and tools" icon (šŸ”) in the chat interface + - You should see "basecamp" listed with all 46 tools available + - Toggle the tools on to enable Basecamp integration + +### Claude Desktop Configuration + +The configuration is automatically created at: +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `~/AppData/Roaming/Claude/claude_desktop_config.json` +- **Linux**: `~/.config/claude-desktop/claude_desktop_config.json` + +Example configuration generated: +```json +{ + "mcpServers": { + "basecamp": { + "command": "/path/to/your/project/venv/bin/python", + "args": ["/path/to/your/project/basecamp_fastmcp.py"], + "env": { + "PYTHONPATH": "/path/to/your/project", + "VIRTUAL_ENV": "/path/to/your/project/venv", + "BASECAMP_ACCOUNT_ID": "your_account_id" + } + } + } +} +``` + +### Usage in Claude Desktop + +Ask Claude things like: +- "What are my current Basecamp projects?" +- "Show me the latest campfire messages from the Technology project" +- "Create a new card in the Development column with title 'Fix login bug'" +- "Get all todo items from the Marketing project" +- "Search for messages containing 'deadline'" + +### Troubleshooting Claude Desktop + +**Check Claude Desktop logs** (following [official debugging guide](https://modelcontextprotocol.io/quickstart/server#troubleshooting)): +```bash +# macOS/Linux - Monitor logs in real-time +tail -n 20 -f ~/Library/Logs/Claude/mcp*.log + +# Check for specific errors +ls ~/Library/Logs/Claude/mcp-server-basecamp.log +``` + +**Common issues:** +- **Tools not appearing**: Verify configuration file syntax and restart Claude Desktop +- **Connection failures**: Check that Python path and script path are absolute paths +- **Authentication errors**: Ensure OAuth flow completed successfully (`oauth_tokens.json` exists) + ## Available MCP Tools Once configured, you can use these tools in Cursor: @@ -139,23 +217,26 @@ Ask Cursor things like: ## Architecture -The project uses the **official Anthropic FastMCP framework** for maximum reliability: +The project uses the **official Anthropic FastMCP framework** for maximum reliability and compatibility: -1. **FastMCP Server** (`basecamp_fastmcp.py`) - Official MCP SDK with 46 tools +1. **FastMCP Server** (`basecamp_fastmcp.py`) - Official MCP SDK with 46 tools, compatible with both Cursor and Claude Desktop 2. **OAuth App** (`oauth_app.py`) - Handles OAuth 2.0 flow with Basecamp 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 6. **Setup Automation** (`setup.py`) - One-command installation +7. **Configuration Generators**: + - `generate_cursor_config.py` - For Cursor IDE integration + - `generate_claude_desktop_config.py` - For Claude Desktop integration ## Troubleshooting -### Common Issues +### Common Issues (Both Clients) - šŸ”“ **Red/Yellow indicator:** Run `python setup.py` to create proper virtual environment - šŸ”“ **"0 tools available":** Virtual environment missing MCP packages - run setup script -- šŸ”“ **"Tool not found" errors:** Restart Cursor completely after configuration changes -- āš ļø **Missing BASECAMP_ACCOUNT_ID:** Add to `.env` file, then re-run `python generate_cursor_config.py` +- šŸ”“ **"Tool not found" errors:** Restart your client (Cursor/Claude Desktop) completely +- āš ļø **Missing BASECAMP_ACCOUNT_ID:** Add to `.env` file, then re-run the config generator ### Quick Fixes @@ -181,7 +262,8 @@ python oauth_app.py ### Manual Configuration (Last Resort) -**Config location:** `~/.cursor/mcp.json` (macOS/Linux) or `%APPDATA%\Cursor\mcp.json` (Windows) +**Cursor config location:** `~/.cursor/mcp.json` (macOS/Linux) or `%APPDATA%\Cursor\mcp.json` (Windows) +**Claude Desktop config location:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ```json { diff --git a/generate_claude_desktop_config.py b/generate_claude_desktop_config.py new file mode 100644 index 0000000..91d542a --- /dev/null +++ b/generate_claude_desktop_config.py @@ -0,0 +1,137 @@ +#!/usr/bin/env python3 +""" +Generate Claude Desktop configuration for Basecamp MCP Integration. +Based on official MCP quickstart guide: https://modelcontextprotocol.io/quickstart/server +""" + +import os +import sys +import json +import platform +from pathlib import Path +from dotenv import load_dotenv + +def get_project_root(): + """Get the absolute path to the project root.""" + return os.path.abspath(os.path.dirname(__file__)) + +def get_python_path(): + """Get the Python executable path from virtual environment.""" + project_root = get_project_root() + + if platform.system() == "Windows": + python_path = os.path.join(project_root, "venv", "Scripts", "python.exe") + else: + python_path = os.path.join(project_root, "venv", "bin", "python") + + # Convert to absolute path + return os.path.abspath(python_path) + +def get_claude_desktop_config_path(): + """Get the Claude Desktop configuration file path.""" + if platform.system() == "Windows": + return os.path.expanduser("~/AppData/Roaming/Claude/claude_desktop_config.json") + elif platform.system() == "Darwin": # macOS + return os.path.expanduser("~/Library/Application Support/Claude/claude_desktop_config.json") + else: # Linux + return os.path.expanduser("~/.config/claude-desktop/claude_desktop_config.json") + +def generate_config(): + """Generate the Claude Desktop configuration for Basecamp MCP server.""" + project_root = get_project_root() + python_path = get_python_path() + script_path = os.path.join(project_root, "basecamp_fastmcp.py") + + # Load .env file to get BASECAMP_ACCOUNT_ID + dotenv_path = os.path.join(project_root, ".env") + load_dotenv(dotenv_path) + basecamp_account_id = os.getenv("BASECAMP_ACCOUNT_ID") + + if not basecamp_account_id: + print("āš ļø Warning: BASECAMP_ACCOUNT_ID not found in .env file") + print(" Add BASECAMP_ACCOUNT_ID to your .env file for proper configuration") + basecamp_account_id = "YOUR_ACCOUNT_ID_HERE" + + # Verify Python executable exists + if not os.path.exists(python_path): + print(f"āŒ Python executable not found at {python_path}") + print(" Run 'python setup.py' first to create the virtual environment") + return False + + # Verify FastMCP server exists + if not os.path.exists(script_path): + print(f"āŒ FastMCP server not found at {script_path}") + return False + + # Create configuration + config = { + "mcpServers": { + "basecamp": { + "command": python_path, + "args": [script_path], + "env": { + "PYTHONPATH": project_root, + "VIRTUAL_ENV": os.path.join(project_root, "venv"), + "BASECAMP_ACCOUNT_ID": basecamp_account_id + } + } + } + } + + config_path = get_claude_desktop_config_path() + config_dir = os.path.dirname(config_path) + + # Create config directory if it doesn't exist + os.makedirs(config_dir, exist_ok=True) + + # Load existing config if it exists + existing_config = {} + if os.path.exists(config_path): + try: + with open(config_path, 'r') as f: + existing_config = json.load(f) + except json.JSONDecodeError: + print(f"āš ļø Warning: Existing config at {config_path} has invalid JSON") + existing_config = {} + + # Merge with existing mcpServers + if "mcpServers" not in existing_config: + existing_config["mcpServers"] = {} + + # Add or update Basecamp server + existing_config["mcpServers"]["basecamp"] = config["mcpServers"]["basecamp"] + + # Write configuration + try: + with open(config_path, 'w') as f: + json.dump(existing_config, f, indent=2) + + print("āœ… Claude Desktop configuration updated successfully!") + print(f"šŸ“ Config file: {config_path}") + print("\nšŸ“‹ Configuration details:") + print(f" ā€¢ Server name: basecamp") + print(f" ā€¢ Python path: {python_path}") + print(f" ā€¢ Server script: {script_path}") + print(f" ā€¢ Account ID: {basecamp_account_id}") + print("\nšŸ”„ Next steps:") + print(" 1. Restart Claude Desktop completely") + print(" 2. Look for the MCP tools icon in Claude Desktop") + print(" 3. Enable Basecamp tools in your conversation") + print("\nšŸ’” Tip: Check ~/Library/Logs/Claude/mcp*.log for troubleshooting") + + return True + + except Exception as e: + print(f"āŒ Error writing configuration: {str(e)}") + return False + +def main(): + """Main function.""" + print("šŸš€ Generating Claude Desktop Configuration for Basecamp MCP") + print("=" * 60) + + if not generate_config(): + sys.exit(1) + +if __name__ == "__main__": + main() \ No newline at end of file