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.
2025-07-27 20:18:03 +01:00
parent 1cb7b4423b
commit ee3f31fcd2
2 changed files with 228 additions and 9 deletions
--- 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 <repository-url>
+   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
 {
--- a/generate_claude_desktop_config.py
+++ 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()