appiq-solution 1.2.0 → 1.3.1

package/appiq-mcp installer/How-to.md

@@ -0,0 +1,250 @@
+# 📚 AppIQ MCP Installer - Complete How-To Guide
+
+**Everything you need to know about using and customizing the AppIQ MCP Installer**
+
+## 🚀 Getting Started
+
+### Global Installation (Recommended)
+```bash
+# Install once globally:
+npm install -g appiq-mcp-installer
+
+# Then use the short commands:
+appiq-mcp
+mcp-installer
+
+# Or the full command:
+appiq-mcp-installer
+```
+
+## ✨ What Happens When You Start?
+
+1. **🔍 IDE Detection**: The installer automatically searches for:
+   - Claude Desktop
+   - Cursor AI 
+   - Windsurf
+   - VS Code
+   - Trae AI
+
+2. **📊 Status Check**: Shows already installed global MCP servers
+
+3. **🎮 Interactive Selection**:
+   - Choose your IDEs
+   - Decide: Global, Project-specific, or Intelligent recommendations
+   - Select desired MCP servers
+
+4. **⚡ Automatic Installation**: Configures all servers for all chosen IDEs
+
+## 🎯 Recommended Server Selection
+
+### 🌍 Global (for all projects)
+- ✅ **Git MCP Server** - Git integration
+- ✅ **Sequential Thinking** - Structured problem solving  
+- ✅ **Puppeteer** - Browser automation
+- ✅ **Claude Thread Continuity** - Enhanced Claude features
+
+### 📁 Project-specific (only when needed)
+- **Dart MCP** - for Flutter/Dart projects
+- **Firebase MCP** - for Firebase projects
+- **Supabase MCP** - for Supabase projects
+- **Context7** - for documentation
+- **Extended Memory** - for complex AI tasks
+- **Magic MCP** - for UI development
+- **Stripe MCP** - for e-commerce
+
+## 🔧 How to Customize MCP Servers
+
+### Step 1: Edit the Configuration
+1. Open `my_mcps.md` in your editor
+2. Find the `MCP_SERVERS` configuration in the JavaScript code block
+3. Add, remove, or modify server entries
+
+### Step 2: Use the Template
+Copy this template from `my_mcps.md`:
+
+```javascript
+'your-server-key': {
+  name: 'Your Server Name',
+  description: 'Brief description of what this server does',
+  config: {
+    command: 'npx', // or 'uvx', 'python', etc.
+    args: ['-y', 'package-name', '--optional-flags']
+  },
+  env: {
+    'API_KEY': 'your_api_key_here',
+    'OTHER_CONFIG': 'value'
+  }
+}
+```
+
+### Step 3: Choose the Right Section
+- Add to `// 🌍 GLOBAL SERVERS` for tools you use in all projects
+- Add to `// 📁 LOCAL SERVERS` for project-specific tools
+
+### Step 4: Run the Installer
+```bash
+appiq-mcp
+```
+
+## 🔄 How the Smart System Works
+
+### First Run (Global Installation)
+```bash
+appiq-mcp
+# → When choosing "Mixed - intelligent recommendations"
+# → Installs Global servers globally: Git, Sequential Thinking, Puppeteer, Claude Thread Continuity
+# → Installs Local servers project-specifically: Extended Memory, Magic MCP, Firebase, etc.
+```
+
+### Second Run (Project Installation)
+```bash
+cd your-project
+appiq-mcp
+# → Shows: "✅ Git (already globally installed)"
+# → Only installs Local servers for this project
+# → Extended Memory, Magic MCP, Firebase, etc.
+```
+
+### Smart Duplicate Detection
+- **Global installed** → Shows "✅ (already globally installed)" in selection
+- **No duplicates** → Automatic skip of already configured servers
+- **Intelligent recommendations** → Global servers installed globally, Local servers installed locally
+
+## 🔑 After Installation
+
+1. **💻 Restart IDEs** - Important!
+2. **🔧 Set API Keys** (if needed):
+   ```bash
+   # Example for Firebase
+   export SERVICE_ACCOUNT_KEY_PATH="/path/to/key.json"
+   
+   # Example for Supabase  
+   export SUPABASE_ACCESS_TOKEN="your_token"
+   
+   # Example for Magic MCP
+   export MAGIC_API_KEY="your_magic_key"
+   
+   # Example for Stripe
+   export STRIPE_PUBLISHABLE_KEY="pk_test_your_key_here"
+   ```
+3. **🧪 Test**: Open an IDE and test the MCP tools
+
+## 🛠️ Commands
+
+```bash
+# Main installation
+appiq-mcp
+
+# Show all available servers
+appiq-mcp list
+
+# Local test
+node index.js
+```
+
+## 🔧 Configuration Paths
+
+The installer automatically uses the correct paths for each IDE:
+
+### Claude Desktop
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+### Cursor AI
+- **Global**: `~/.cursor/mcp.json`
+- **Project**: `.cursor/mcp.json`
+
+### Windsurf
+- **Global**: `~/.windsurf/mcp.json`
+- **Project**: `.windsurf/mcp.json`
+
+### VS Code
+- **Global**: `~/.vscode/settings.json`
+- **Project**: `.vscode/mcp.json`
+
+### Trae AI
+- **Global**: `~/.trae/mcp.json`
+- **Project**: `.trae/mcp.json`
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**"No IDEs found"**
+- Make sure at least one supported IDE is installed
+- Check if IDE directories exist
+
+**"Installation failed"**
+- Check write permissions for configuration files
+- Make sure Node.js and NPM are up to date
+
+**"Server already installed"**
+- The installer automatically skips already installed servers
+- Use `appiq-mcp-installer list` to see all available servers
+
+## 💡 Pro Tips
+
+### 🌍 Global Servers (🌍 GLOBAL SERVERS section)
+These are in the installer because they're useful everywhere:
+- **Git** - You need git in every project
+- **Sequential Thinking** - Useful for any complex task
+- **Puppeteer** - Web automation has universal applications
+- **Claude Thread Continuity** - Enhanced Claude features for all conversations
+
+### 📁 Local Servers (📁 LOCAL SERVERS section)  
+These are installed per-project because they're specialized:
+- **Firebase/Supabase** - Only needed in backend projects
+- **Dart** - Only for Flutter projects
+- **Stripe** - Only for e-commerce projects
+- **Context7** - Only when you need live docs
+- **Extended Memory** - For complex AI tasks
+- **Magic MCP** - For UI development work
+
+### General Tips
+- 🎯 Choose "Mixed - intelligent recommendations" for optimal configuration
+- 🔄 When in doubt: Restart IDE solves 90% of all problems
+- ⚙️ Check `my_mcps.md` for the server template
+
+## 🔄 Managing Your Servers
+
+### ➕ Adding a New Server
+1. Find the MCP server package (NPM, PyPI, etc.)
+2. Copy the template from `my_mcps.md`
+3. Fill in the details
+4. Add to the appropriate section in the `MCP_SERVERS` configuration in `my_mcps.md`
+5. Run the installer
+
+### ❌ Removing a Server
+1. Delete the entire server entry from the `MCP_SERVERS` configuration in `my_mcps.md`
+2. The installer will skip it automatically
+
+### 🔄 Updating a Server
+1. Modify the existing entry in `my_mcps.md`
+2. Change `name`, `description`, `config`, or `env` as needed
+3. Run the installer to apply changes
+
+## 🏆 Final Result
+
+After running the installer you will have:
+- ✅ All chosen MCP servers installed
+- ✅ Correct configuration for each IDE
+- ✅ No duplicates
+- ✅ Intelligent placement (global vs. project)
+- ✅ Smart detection for future runs
+
+## 🤝 Contributing
+
+Want to add more MCP servers or suggest improvements?
+
+1. Fork the repository
+2. Create a feature branch  
+3. Add the MCP server to the `MCP_SERVERS` constant in `index.js`
+4. Test the installation
+5. Create a Pull Request
+
+> **💡 Tip:** Use the template in `my_mcps.md` for consistent formatting!
+
+---
+
+**🎉 Now you can get started and customize your MCP setup perfectly!**

package/appiq-mcp installer/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AppIQ MCP Installer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/appiq-mcp installer/README.md

@@ -0,0 +1,235 @@
+# 🚀 AppIQ MCP Installer
+
+**The intelligent One-Click Installer for all MCP Servers**
+
+Automatic installation and configuration of Model Context Protocol (MCP) servers for:
+- **Claude Desktop** 🤖
+- **Cursor AI** ⚡
+- **Windsurf** 🏄‍♂️
+- **VS Code** 💻
+- **Trae AI** 🎯
+
+## ✨ Features
+
+- 🎯 **Intelligent Recommendations** - Automatic categorization of global vs. project-specific
+- 🔍 **IDE Detection** - Automatically detects installed IDEs
+- 📊 **Duplicate Protection** - Shows already installed servers
+- 🔧 **Smart Configuration** - Correct paths for each IDE
+- 📋 **Comprehensive Server List** - All important MCP servers pre-configured
+- 🌍 **Multi-Platform** - Windows, macOS, Linux support
+
+## 🚀 Installation & Usage
+
+### Global Installation (Recommended)
+```bash
+# Install once globally:
+npm install -g appiq-mcp-installer
+
+# Then use the short commands:
+appiq-mcp
+mcp-installer
+
+# Or the full command:
+appiq-mcp-installer
+```
+
+**🛠️ How it works:**
+1. **First run**: Creates `my_mcps.md` in your current directory
+2. **Edit**: Customize the MCP servers you want to install
+3. **Install**: Run the installer - it reads your configuration automatically
+4. **Validation**: Built-in syntax checking with helpful error messages
+
+## 📋 MCP Server Configuration
+
+The AppIQ MCP Installer comes with a pre-configured set of MCP servers organized into two simple categories:
+
+### 🌍 Global Servers
+Always useful servers that you want available in **all projects**:
+- **Git MCP Server** - Git repository management
+- **Sequential Thinking** - Structured problem solving
+- **Puppeteer** - Browser automation
+- **Claude Thread Continuity** - Enhanced Claude features
+
+### 📁 Local Servers  
+Project-specific servers that you only need in **certain projects**:
+- **Dart MCP Server** - Flutter/Dart development
+- **Firebase MCP** - Firebase services integration
+- **Supabase MCP** - Supabase backend services
+- **Context7** - Live code documentation
+- **Extended Memory** - AI memory enhancement
+- **Magic MCP** - UI builder (like v0)
+- **Stripe MCP** - Payment integration
+
+> **🛠️ Customize Your Setup**: Edit the `MCP_SERVERS` configuration in `my_mcps.md` to add, remove, or modify servers. The installer automatically loads this configuration. See [How-to.md](How-to.md) for complete instructions.
+
+## 🎮 Interactive User Guide
+
+The installer guides you through these steps:
+
+1. **IDE Detection** - Finds all installed supported IDEs
+2. **Already Installed Servers** - Shows globally installed MCP servers
+3. **IDE Selection** - Choose IDEs for installation
+4. **Installation Type** - Global, Project-specific, or Intelligent recommendations
+5. **Server Selection** - Choose desired MCP servers with recommendations
+6. **Installation** - Automatic configuration for all selected IDEs
+
+## 🔧 Configuration Paths
+
+The installer knows the correct paths for each IDE:
+
+### Claude Desktop
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+### Cursor AI
+- **Global**: `~/.cursor/mcp.json`
+- **Project**: `.cursor/mcp.json`
+
+### Windsurf
+- **Global**: `~/.windsurf/mcp.json`
+- **Project**: `.windsurf/mcp.json`
+
+### VS Code
+- **Global**: `~/.vscode/settings.json`
+- **Project**: `.vscode/mcp.json`
+
+### Trae AI
+- **Global**: `~/.trae/mcp.json`
+- **Project**: `.trae/mcp.json`
+
+## 🔑 Environment Variables
+
+Some MCP servers require API keys or configuration:
+
+### Firebase MCP
+```env
+SERVICE_ACCOUNT_KEY_PATH=/path/to/serviceAccountKey.json
+FIREBASE_STORAGE_BUCKET=your-project-id.firebasestorage.app
+```
+
+### Supabase MCP
+```env
+SUPABASE_ACCESS_TOKEN=sbp_v0_your_token_here
+```
+
+### Magic MCP
+```bash
+# API key is passed directly as argument:
+# API_KEY="your_magic_api_key_here"
+```
+
+### Stripe MCP
+```env
+STRIPE_PUBLISHABLE_KEY=pk_test_your_key_here
+```
+
+## 📝 Command Line Options
+
+```bash
+# Install MCP servers (default behavior)
+appiq-mcp
+mcp-installer
+appiq-mcp-installer
+
+# List all available servers
+appiq-mcp list
+mcp-installer list
+appiq-mcp-installer list
+
+# Show help (future)
+appiq-mcp --help
+
+# Uninstall (future)
+appiq-mcp uninstall
+```
+
+## 🔍 Intelligent Installation
+
+The installer uses a simple two-tier system:
+
+### 🌍 Global Installation
+Install once, use everywhere - perfect for universally useful tools:
+- Git, Sequential Thinking, Puppeteer, Claude Thread Continuity
+
+### 📁 Local Installation
+Install only where needed - ideal for project-specific functionality:
+- Dart (Flutter projects), Firebase/Supabase (backend projects), Context7 (documentation), Extended Memory, Magic MCP
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+**"No IDEs found"**
+- Make sure at least one supported IDE is installed
+- Check if IDE directories exist
+
+**"Installation failed"**
+- Check write permissions for configuration files
+- Make sure Node.js and NPM are up to date
+
+**"Server already installed"**
+- The installer automatically skips already installed servers
+- Use `appiq-mcp-installer list` to see all available servers
+
+### After Installation
+
+1. **Restart IDEs** - All IDEs must be restarted
+2. **Configure API Keys** - Set required environment variables
+3. **Test Servers** - Test the MCP tools in your IDE
+
+## ⚙️ Configuration & Customization
+
+Want to add your own MCP servers or modify the existing ones? 
+
+### 🛠️ How It Works
+1. **Edit** `my_mcps.md` → `MCP_SERVERS` configuration  
+2. **Add servers** to `// 🌍 GLOBAL SERVERS` or `// 📁 LOCAL SERVERS` sections
+3. **Remove servers** by deleting their entries
+4. **Run** installer - everything in the configuration gets installed automatically
+5. **Smart detection** - duplicate prevention & intelligent installation
+
+### 🎯 Quick Example
+```javascript
+// Add your own server to the appropriate section
+'my-custom-server': {
+  name: 'My Custom MCP Server',
+  description: 'Does something amazing',
+  config: {
+    command: 'npx',
+    args: ['-y', 'my-package-name']
+  },
+  env: {
+    'MY_API_KEY': 'your_key_here'
+  }
+}
+```
+
+> **📚 Complete Guide**: See [How-to.md](How-to.md) for detailed instructions and [my_mcps.md](my_mcps.md) for the server template.
+
+## 🤝 Contributing
+
+Want to add more MCP servers or suggest improvements?
+
+1. Fork the repository
+2. Create a feature branch  
+3. Add the MCP server to the appropriate section in `my_mcps.md`
+4. Test the installation
+5. Create a Pull Request
+
+> **💡 Tip:** Use the template in [my_mcps.md](my_mcps.md) for consistent formatting!
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🔗 Links
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Desktop](https://claude.ai/desktop)
+- [Cursor AI](https://cursor.sh/)
+- [Windsurf](https://codeium.com/windsurf)
+
+---
+
+**Created with ❤️ for the AI Developer Community**