aidevops 2.52.1 → 2.53.2

package/.agent/aidevops/extension.md

@@ -1,311 +0,0 @@
----
-description: Guidelines for extending the framework
-mode: subagent
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: false
-  glob: true
-  grep: true
-  webfetch: false
-  task: true
----
-
-# Framework Extension Guidelines
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **New service steps**: Research -> Helper script -> Config template -> Documentation -> Update framework files
-- **Helper location**: `.agent/scripts/[service-name]-helper.sh`
-- **Config template**: `configs/[service-name]-config.json.txt`
-- **Documentation**: `.agent/[service-name].md`
-- **Required functions**: check_dependencies, load_config, get_account_config, api_request, list_accounts, show_help, main
-- **Security checklist**: Token validation, input sanitization, no credential exposure, rate limiting, confirmation prompts
-- **Testing**: Functional, integration, and security testing required
-- **Update files**: .gitignore, README.md, AGENTS.md, recommendations-opinionated.md, setup-wizard-helper.sh
-<!-- AI-CONTEXT-END -->
-
-## Extension Principles
-
-### Core Principles
-
-- **Consistency**: Follow established patterns and conventions
-- **Security**: Implement security measures from the start
-- **Documentation**: Comprehensive documentation for all additions
-- **Testing**: Thorough testing before integration
-- **Maintainability**: Code that is easy to understand and maintain
-
-### Quality Standards
-
-- **Code review**: All additions must pass code review
-- **Security review**: Security implications must be assessed
-- **Documentation review**: Documentation must be complete and accurate
-- **Integration testing**: Must integrate properly with existing services
-- **User experience**: Must maintain or improve user experience
-
-## Adding New Service Providers
-
-### Step 1: Research & Planning
-
-```bash
-# Research checklist:
-□ Service has public API with documentation
-□ API supports required operations (list, create, update, delete)
-□ Authentication method is supported (token, OAuth, etc.)
-□ Rate limits and usage policies are acceptable
-□ Service has MCP server available or can be created
-□ Service fits into existing framework categories
-```
-
-### Step 2: Create Helper Script
-
-```bash
-# File: .agent/scripts/[service-name]-helper.sh
-#!/bin/bash
-
-# [Service Name] Helper Script
-# [Brief description of service and capabilities]
-
-# Standard header (copy from existing script)
-GREEN='\033[0;32m'
-BLUE='\033[0;34m'
-YELLOW='\033[1;33m'
-RED='\033[0;31m'
-NC='\033[0m'
-
-print_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
-print_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
-print_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
-print_error() { echo -e "${RED}[ERROR]${NC} $1"; }
-
-CONFIG_FILE="../configs/[service-name]-config.json"
-
-# Required functions (implement all):
-check_dependencies() { ... }
-load_config() { ... }
-get_account_config() { ... }
-api_request() { ... }
-list_accounts() { ... }
-show_help() { ... }
-main() { ... }
-
-# Service-specific functions
-[service_specific_functions]() { ... }
-
-main "$@"
-```
-
-### Step 3: Create Configuration Template
-
-```bash
-# File: configs/[service-name]-config.json.txt
-{
-  "accounts": {
-    "personal": {
-      "api_token": "YOUR_[SERVICE]_API_TOKEN_HERE",
-      "base_url": "https://api.[service].com",
-      "description": "Personal [service] account",
-      "username": "your-username"
-    },
-    "work": {
-      "api_token": "YOUR_WORK_[SERVICE]_API_TOKEN_HERE",
-      "base_url": "https://api.[service].com",
-      "description": "Work [service] account",
-      "username": "work-username"
-    }
-  },
-  "default_settings": {
-    "timeout": 30,
-    "rate_limit": 60,
-    "retry_attempts": 3,
-    "page_size": 50
-  },
-  "mcp_servers": {
-    "[service]": {
-      "enabled": true,
-      "port": 30XX,
-      "host": "localhost",
-      "auth_required": true
-    }
-  },
-  "features": {
-    "bulk_operations": true,
-    "webhooks": false,
-    "real_time_updates": true
-  }
-}
-```
-
-### Step 4: Create Comprehensive Documentation
-
-```bash
-# File: .agent/[SERVICE-NAME].md
-# [Service Name] Guide
-
-## 🏢 **Provider Overview**
-### **[Service] Characteristics:**
-- **Service Type**: [Description]
-- **Strengths**: [Key benefits and features]
-- **API Support**: [API capabilities and limitations]
-- **MCP Integration**: [MCP server availability]
-- **Use Case**: [Primary use cases and scenarios]
-
-## 🔧 **Configuration**
-[Detailed setup instructions]
-
-## 🚀 **Usage Examples**
-[Real command examples with expected output]
-
-## 🛡️ **Security Best Practices**
-[Service-specific security guidelines]
-
-## 📊 **MCP Integration**
-[MCP server setup and capabilities]
-
-## 🔍 **Troubleshooting**
-[Common issues and solutions]
-
-## 📚 **Best Practices**
-[Service-specific best practices]
-
-## 🎯 **AI Assistant Integration**
-[AI automation capabilities and patterns]
-```
-
-### Step 5: Update Framework Files
-
-```bash
-# Update .gitignore
-echo "configs/[service-name]-config.json" >> .gitignore
-
-# Update README.md
-# - Add to service list
-# - Add to helper scripts list
-# - Add to file structure
-# - Add to documentation list
-
-# Update AGENTS.md
-# - Add to appropriate service category
-# - Update service count
-
-# Update .agent/recommendations-opinionated.md
-# - Add to appropriate category with description
-
-# Update .agent/scripts/setup-wizard-helper.sh
-# - Add to service recommendations logic
-# - Add to API keys guide
-# - Add to configuration generation
-```
-
-## Security Implementation
-
-### Required Security Features
-
-```bash
-# All new services must implement:
-1. API token validation before use
-2. Input validation and sanitization
-3. Secure error messages (no credential exposure)
-4. Rate limiting awareness and backoff
-5. Confirmation prompts for destructive operations
-6. Audit logging for important operations
-7. Encrypted credential storage
-8. Secure temporary file handling
-```
-
-### Security Testing Checklist
-
-```bash
-□ No credentials exposed in logs or output
-□ All inputs properly validated
-□ Error messages don't reveal sensitive information
-□ Destructive operations require confirmation
-□ API rate limits are respected
-□ Temporary files are cleaned up
-□ File permissions are properly set
-□ Configuration files are gitignored
-```
-
-## Testing Requirements
-
-### Functional Testing
-
-```bash
-# Test all major functions:
-□ Configuration loading and validation
-□ API connectivity and authentication
-□ List operations (accounts, resources)
-□ Create operations (if applicable)
-□ Update operations (if applicable)
-□ Delete operations (if applicable)
-□ Error handling and recovery
-□ Help and documentation
-```
-
-### Integration Testing
-
-```bash
-# Test framework integration:
-□ Helper script follows naming conventions
-□ Configuration follows standard structure
-□ Documentation follows standard format
-□ MCP server integration (if applicable)
-□ Setup wizard integration
-□ Cross-service workflows (if applicable)
-```
-
-### Security Testing
-
-```bash
-# Security validation:
-□ No credential exposure in any output
-□ Proper input validation
-□ Secure error handling
-□ File permission verification
-□ Configuration security
-□ API security best practices
-```
-
-## Maintenance Guidelines
-
-### Ongoing Maintenance
-
-- **API updates**: Monitor service API changes and update accordingly
-- **Security updates**: Regular security reviews and updates
-- **Documentation updates**: Keep documentation current with service changes
-- **Performance optimization**: Monitor and optimize performance
-- **User feedback**: Incorporate user feedback and feature requests
-
-### Version Management
-
-- **Semantic versioning**: Use semantic versioning for major changes
-- **Backward compatibility**: Maintain backward compatibility when possible
-- **Migration guides**: Provide migration guides for breaking changes
-- **Deprecation notices**: Provide adequate notice for deprecated features
-- **Change logs**: Maintain detailed change logs
-
-## Quality Assurance
-
-### Code Quality Standards
-
-- **Consistent formatting**: Follow established code formatting
-- **Clear naming**: Use descriptive function and variable names
-- **Comprehensive comments**: Comment complex logic and decisions
-- **Error handling**: Implement robust error handling
-- **Performance**: Optimize for performance and resource usage
-
-### Documentation Quality
-
-- **Completeness**: Cover all features and capabilities
-- **Accuracy**: Ensure all examples and instructions work
-- **Clarity**: Write clear, understandable documentation
-- **Examples**: Provide real, working examples
-- **Troubleshooting**: Include common issues and solutions
-
-  task: true
----
-
-**Following these guidelines ensures new services integrate seamlessly with the framework while maintaining security, quality, and consistency standards.**

package/.agent/aidevops/mcp-integrations.md

@@ -1,340 +0,0 @@
----
-description: Advanced MCP integrations for AI DevOps
-mode: subagent
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
----
-
-# Advanced MCP Integrations for AI DevOps
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-**Setup All**: `bash .agent/scripts/setup-mcp-integrations.sh all`
-**Validate**: `bash .agent/scripts/validate-mcp-integrations.sh`
-
-**Browser & Web**:
-- Chrome DevTools MCP: `claude mcp add chrome-devtools npx chrome-devtools-mcp@latest`
-- Playwright MCP: `npm install -g playwright-mcp`
-- Cloudflare Browser Rendering: Server-side scraping
-
-**SEO & Research**:
-- Ahrefs MCP: `AHREFS_API_KEY` required
-- Perplexity MCP: `PERPLEXITY_API_KEY` required
-- Google Search Console: `GOOGLE_APPLICATION_CREDENTIALS` (service account JSON)
-
-**Development**:
-- Next.js DevTools MCP
-- Context7 MCP: Real-time library docs
-- LocalWP MCP: WordPress database access
-
-**Config Location**: `configs/mcp-templates/`
-<!-- AI-CONTEXT-END -->
-
-This document provides comprehensive setup and usage instructions for advanced Model Context Protocol (MCP) integrations that dramatically expand our AI development capabilities.
-
-## 📋 **Available MCP Integrations**
-
-### **🌐 Web & Browser Automation**
-
-- **Chrome DevTools MCP**: Browser automation, debugging, performance analysis
-- **Playwright MCP**: Cross-browser testing and automation
-- **Cloudflare Browser Rendering**: Server-side web scraping and rendering
-
-### **🔍 SEO & Research Tools**
-
-- **Ahrefs MCP**: SEO analysis, backlink research, keyword data
-- **Perplexity MCP**: AI-powered web search and research
-- **Google Search Console MCP**: Search performance data and insights
-
-### **⚡ Development Tools**
-
-- **Next.js DevTools MCP**: Next.js development and debugging assistance
-
-### **📧 CRM & Marketing**
-
-- **FluentCRM MCP**: WordPress CRM with contacts, campaigns, automations, and email marketing
-
-### **📚 Legacy MCP Servers (from MCP-SERVERS.md)**
-
-- **Context7 MCP**: Real-time documentation access for development libraries
-- **LocalWP MCP**: Direct WordPress database access for local development
-
-## 🎯 **Quick Setup Commands**
-
-### **Chrome DevTools MCP**
-
-```bash
-# Add to Claude Desktop
-claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
-
-# Add to VS Code Copilot
-code --add-mcp '{"name":"chrome-devtools","command":"npx","args":["chrome-devtools-mcp@latest"]}'
-
-# Manual configuration
-npx chrome-devtools-mcp@latest --channel=canary --headless=true
-```
-
-### **Playwright MCP**
-
-```bash
-# Install Playwright MCP
-npm install -g playwright-mcp
-playwright-mcp --install-browsers
-
-# Add to MCP client
-claude mcp add playwright npx playwright-mcp@latest
-```
-
-### **Ahrefs MCP**
-
-```bash
-# Get your standard 40-char API key (NOT JWT tokens) from https://ahrefs.com/api
-# Store in ~/.config/aidevops/mcp-env.sh:
-export AHREFS_API_KEY="your_40_char_api_key"
-
-# For Claude Desktop:
-claude mcp add ahrefs npx @ahrefs/mcp@latest
-```
-
-**Important**: The `@ahrefs/mcp` package expects `API_KEY` environment variable, not `AHREFS_API_KEY`.
-
-**For OpenCode** - use bash wrapper pattern (environment blocks don't expand variables):
-
-```json
-{
-  "ahrefs": {
-    "type": "local",
-    "command": ["/bin/bash", "-c", "API_KEY=$AHREFS_API_KEY /opt/homebrew/bin/npx -y @ahrefs/mcp@latest"],
-    "enabled": true
-  }
-}
-```
-
-### **Perplexity MCP**
-
-```bash
-# Setup Perplexity integration
-export PERPLEXITY_API_KEY="your_api_key_here"
-claude mcp add perplexity npx perplexity-mcp@latest
-```
-
-### **Google Search Console MCP**
-
-```bash
-# Setup Google Search Console integration
-export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
-claude mcp add google-search-console npx mcp-server-gsc@latest
-```
-
-### **FluentCRM MCP**
-
-**Note**: The FluentCRM MCP server is not published to npm. It requires cloning and building locally.
-
-```bash
-# 1. Clone and build the MCP server
-mkdir -p ~/.local/share/mcp-servers
-cd ~/.local/share/mcp-servers
-git clone https://github.com/netflyapp/fluentcrm-mcp-server.git
-cd fluentcrm-mcp-server
-npm install
-npm run build
-
-# 2. Store credentials in ~/.config/aidevops/mcp-env.sh:
-export FLUENTCRM_API_URL="https://your-domain.com/wp-json/fluent-crm/v2"
-export FLUENTCRM_API_USERNAME="your_username"
-export FLUENTCRM_API_PASSWORD="your_application_password"
-```
-
-**For OpenCode** - use bash wrapper pattern (disabled globally, enabled per-agent):
-
-```json
-{
-  "fluentcrm": {
-    "type": "local",
-    "command": ["/bin/bash", "-c", "source ~/.config/aidevops/mcp-env.sh && node ~/.local/share/mcp-servers/fluentcrm-mcp-server/dist/fluentcrm-mcp-server.js"],
-    "enabled": false
-  }
-}
-```
-
-**For Claude Desktop**:
-
-```json
-{
-  "mcpServers": {
-    "fluentcrm": {
-      "command": "node",
-      "args": ["~/.local/share/mcp-servers/fluentcrm-mcp-server/dist/fluentcrm-mcp-server.js"],
-      "env": {
-        "FLUENTCRM_API_URL": "https://your-domain.com/wp-json/fluent-crm/v2",
-        "FLUENTCRM_API_USERNAME": "your_username",
-        "FLUENTCRM_API_PASSWORD": "your_application_password"
-      }
-    }
-  }
-}
-```
-
-**Per-Agent Enablement**: The `services/crm/fluentcrm.md` subagent has `fluentcrm_*: true` in its tools section. Main agents (`sales.md`, `marketing.md`) reference this subagent for CRM operations.
-
-**Available Tools**: Contacts, Tags, Lists, Campaigns, Email Templates, Automations, Webhooks, Smart Links, Dashboard Stats.
-
-See `services/crm/fluentcrm.md` for detailed documentation.
-
-## 🔧 **Configuration Examples**
-
-### **Advanced Chrome DevTools Configuration**
-
-```json
-{
-  "mcpServers": {
-    "chrome-devtools": {
-      "command": "npx",
-      "args": [
-        "chrome-devtools-mcp@latest",
-        "--channel=canary",
-        "--headless=true",
-        "--isolated=true",
-        "--viewport=1920x1080",
-        "--logFile=/tmp/chrome-mcp.log"
-      ]
-    }
-  }
-}
-```
-
-### **Cloudflare Browser Rendering Configuration**
-
-```json
-{
-  "mcpServers": {
-    "cloudflare-browser": {
-      "command": "npx",
-      "args": [
-        "cloudflare-browser-rendering-mcp@latest",
-        "--account-id=your_account_id",
-        "--api-token=your_api_token"
-      ]
-    }
-  }
-}
-```
-
-## 📊 **Use Cases & Examples**
-
-### **Web Scraping & Analysis**
-
-- Extract data from websites using Chrome DevTools or Cloudflare Browser Rendering
-- Perform SEO analysis with Ahrefs integration
-- Research topics and gather information with Perplexity
-
-### **Automated Testing**
-
-- Cross-browser testing with Playwright
-- Performance analysis with Chrome DevTools
-- Visual regression testing and debugging
-
-### **Development Assistance**
-
-- Next.js development debugging and optimization
-- Real-time browser inspection and manipulation
-- API testing and validation
-
-## 🔐 **Security & API Keys**
-
-### **Required API Keys**
-
-- **Ahrefs**: Get standard 40-char key from [Ahrefs API Dashboard](https://ahrefs.com/api) (JWT tokens don't work)
-- **Perplexity**: Get from [Perplexity API](https://docs.perplexity.ai/)
-- **Cloudflare**: Account ID and API token from Cloudflare dashboard
-
-### **Environment Variables**
-
-```bash
-# Ahrefs - store as AHREFS_API_KEY, MCP receives it as API_KEY via bash wrapper
-export AHREFS_API_KEY="your_40_char_ahrefs_key"
-export PERPLEXITY_API_KEY="your_perplexity_key"
-export CLOUDFLARE_ACCOUNT_ID="your_account_id"
-export CLOUDFLARE_API_TOKEN="your_api_token"
-```
-
-## 🚀 **Getting Started**
-
-### **Quick Setup (All Integrations)**
-
-```bash
-# Install all MCP integrations
-bash .agent/scripts/setup-mcp-integrations.sh all
-
-# Validate setup
-bash .agent/scripts/validate-mcp-integrations.sh
-```
-
-### **Individual Integration Setup**
-
-```bash
-# Install specific integration
-bash .agent/scripts/setup-mcp-integrations.sh chrome-devtools
-bash .agent/scripts/setup-mcp-integrations.sh playwright
-bash .agent/scripts/setup-mcp-integrations.sh ahrefs
-```
-
-### **Configuration Steps**
-
-1. **Choose your MCP integrations** based on your needs
-2. **Run the setup script** for your selected integrations
-3. **Configure API keys** using the provided templates
-4. **Test integrations** with the validation script
-5. **Start using** advanced AI-assisted development capabilities!
-
-## 🎯 **Real-World Use Cases**
-
-### **Web Development Workflow**
-
-- **Chrome DevTools**: Debug performance issues, analyze Core Web Vitals
-- **Playwright**: Automated cross-browser testing and E2E validation
-- **Next.js DevTools**: Real-time development assistance and optimization
-
-### **SEO & Content Strategy**
-
-- **Ahrefs**: Keyword research, backlink analysis, competitor insights
-- **Perplexity**: AI-powered research and content ideation
-- **Cloudflare Browser Rendering**: Server-side content analysis
-
-### **Quality Assurance**
-
-- **Playwright**: Comprehensive test automation across browsers
-- **Chrome DevTools**: Performance monitoring and debugging
-- **Visual regression testing** with screenshot comparisons
-
-## 📊 **Integration Status Dashboard**
-
-Run the validation script to see your current setup status:
-
-```bash
-bash .agent/scripts/validate-mcp-integrations.sh
-```
-
-Expected output for fully configured setup:
-
-```text
-✅ Overall status: EXCELLENT (100% success rate)
-✅ All MCP integrations are ready to use!
-```
-
-## 📚 **Additional Resources**
-
-- [MCP Integration Setup Script](.agent/scripts/setup-mcp-integrations.sh)
-- [MCP Validation Script](.agent/scripts/validate-mcp-integrations.sh)
-- [MCP Configuration Templates](configs/mcp-templates/)
-- [Chrome DevTools Examples](docs/mcp-examples/chrome-devtools-examples.md)
-- [Playwright Automation Examples](docs/mcp-examples/playwright-automation-examples.md)
-- [Troubleshooting Guide](docs/MCP-TROUBLESHOOTING.md)