🪄 Wand: Magical Multi-Agent MCP Platform

"Where AI automation meets enchantment" ✨

A spellbinding Model Context Protocol (MCP) implementation with comprehensive integrations, providing 50+ powerful magical integrations for AI development workflows. Supports Claude Desktop, Claude Code, and other MCP-compatible clients through mystical stdio and HTTP transports.

    🔮 Cast 50+ integration spells across all platforms 🔮
         ⚡ Enhanced error handling with native preservation ⚡
              ✨ Production-ready enchantments ✨

🚀 Magical Status

• Protocol Version: MCP 2025-06-18 (backward compatible)
• Primary Transport: stdio (via ./add_to_claude.sh)
• Integrations Available: 50+ comprehensive integrations
• Client Integration: Claude Desktop ✅ | Claude Code ✅ | Custom clients ✅
• Error Handling: Enhanced with native error preservation

✨ Enchanted Features

🪄 Comprehensive Integration Arsenal (50+ Integrations)

• 🎥 Media & Content: Video, Audio, Images, OCR, QR codes
• 🤖 AI & ML: OpenAI, Anthropic, Cohere, Hugging Face, Local models
• 💬 Communication: Discord, Telegram, Microsoft Teams, Email, Calendar
• ☁️ Cloud & Storage: Google Drive, S3, Dropbox, OneDrive
• 🛠️ DevOps: Docker, Kubernetes, Terraform, Monitoring
• 💼 Business: CRM, Payments, Project Management, HR tools
• 🔐 Security & Identity: Enterprise IAM, ServiceNow, SailPoint, Britive, Vault

🏗️ Enhanced Error Response Architecture

• Native Error Preservation: Complete exception details without abstraction
• Configuration Validation: Initialization failures properly propagated
• Exception Categorization: Timeout, authentication, connection, and generic errors
• Structured Logging: System warnings with comprehensive context
• Rate Limiting Control: Configurable per integration (disabled by default)

🌐 Multiple Mystical Transports

• HTTP API: Full MCP 2025-06-18 implementation with SSE support
• stdio: Direct process communication for local clients
• Session Management: Secure session handling with cleanup

🚀 Quick Spell Casting

Prerequisites

• Python 3.10 or higher (required for MCP support)
• pip (Python package manager)
• git
• Virtual environment support (venv)

1. Setup & Installation

# Clone and setup
git clone <repository-url>
cd wand

# Set up Python virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Installation Options

Choose the installation that fits your needs:

Basic Installation (Recommended)

# Core server with essential integrations (Slack, GitHub, Docker, AWS)
pip install -r requirements-base.txt

Installation with Audio/Multimedia Support

# Includes PyAudio, OpenCV, Whisper, etc.
# Note: Requires system audio libraries
pip install -r requirements-base.txt -r requirements-audio.txt

Installation with AI/ML Support

# Includes OpenAI, Anthropic, HuggingFace, etc.
# Note: Large download size due to PyTorch and transformers
pip install -r requirements-base.txt -r requirements-ai.txt

Complete Installation (All Features)

# Includes everything - all 55+ integrations
pip install -r requirements-all.txt

Using pip extras (Alternative)

# Install from source with optional dependencies
pip install -e .  # Basic installation
pip install -e ".[audio]"  # With audio support
pip install -e ".[ai]"  # With AI/ML support
pip install -e ".[all]"  # Everything

Environment Configuration

# Configure environment variables
cp .env.example .env
# Edit .env and configure:
# - OLLAMA_BASE_URL - Your Ollama server URL (default: http://localhost:11434)
# - API keys for any integrations you want to use
# - Database connection string if using PostgreSQL

# Configure Wand
cp config.sample.json config.json
# Edit config.json to match your setup. Replace placeholder paths:
# - {WAND_PATH} - The absolute path to your wand installation
# - {WORKSPACE_PATH} - Your workspace directory

2. Add to Claude Desktop (Recommended) 🪄

# One-command setup - adds Wand to Claude Desktop
./add_to_claude.sh

# ✅ Successfully added Wand MCP server to Claude Desktop!
# 📝 Next steps: Restart Claude Desktop to load the server

Manual Claude Desktop Setup

If you prefer manual setup or the script doesn't work:

1. Open Claude Desktop Settings
2. Navigate to MCP Servers
3. Add a new server with these details:
   • Name: wand
   • Command: /path/to/wand/venv/bin/python
   • Arguments: /path/to/wand/wand.py

Troubleshooting Claude Integration

• Ensure you're in the Wand directory when running ./add_to_claude.sh
• Make sure the virtual environment is set up: python -m venv venv && source venv/bin/activate && pip install -e .
• Restart Claude Desktop after adding the server
• Check Claude Desktop logs for connection errors
• Verify the Python path and script path are correct

3. Alternative: Manual HTTP Server Setup

# Start HTTP server
python wand.py http

# Add HTTP MCP server to Claude
claude mcp add wand-http --transport http http://localhost:8001/mcp

4. Test Your Magic ✨

After restarting Claude Desktop, test the installation:

# Test imports
./venv/bin/python -c "from integrations.ai_ml.ollama import OllamaIntegration; print('✓ Installation successful')"

# Start the Wand server
./venv/bin/python wand.py stdio

Then test the integration:

• Ask Claude: "Use Wand to check the system status"
• Try: "Use Wand to list the available integrations"
• Or: "Show me what Wand tools are available"

Troubleshooting Installation

Module Import Errors

• Ensure virtual environment is activated
• Reinstall requirements: pip install -r requirements.txt

Ollama Connection Issues

• Verify Ollama is running: curl http://localhost:11434/api/tags
• Check OLLAMA_BASE_URL in your .env file

Claude Desktop Integration

• Check logs in the logs/ directory
• Ensure paths in Claude configuration are absolute, not relative
• Restart Claude Desktop after configuration changes

✨ Why the Script Setup is Magical

The ./add_to_claude.sh script provides the best experience because it:

🎯 Optimal Integration Benefits

• Direct stdio communication (faster than HTTP)
• Extended timeouts (handles long-running operations)
• Automatic path detection (no manual configuration)
• Enhanced error handling with detailed diagnostics
• All 50+ integrations ready to use immediately

🔍 What the Script Does

1. Detects your Python environment automatically
2. Configures the MCP server with proper paths
3. Adds Wand to Claude Desktop configuration
4. Enables all integrations with enhanced error reporting
5. Provides clear next steps

🔧 Extended Timeout Configuration

For long-running magical operations (AI training, large deployments, etc.), configure extended timeouts:

File: /Users/david/wand/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "43200000",
    "BASH_MAX_TIMEOUT_MS": "43200000",
    "MCP_TIMEOUT": "43200000",
    "MCP_TOOL_TIMEOUT": "43200000"
  },
  "permissions": {
    "allow": [
      "mcp__wand__*"
    ]
  }
}

Key Timeout Settings:

• 43200000ms = 12 hours (for extensive magical operations)
• MCP_TIMEOUT: Overall MCP session timeout
• MCP_TOOL_TIMEOUT: Individual spell execution timeout
• BASH timeouts: Command execution limits

📋 Complete stdio Configuration

The working Claude Code configuration (~/.claude.json):

{
  "mcpServers": {
    "wand": {
      "command": [
        "/path/to/wand/venv/bin/python",
        "/path/to/wand/wand.py",
        "stdio"
      ],
      "args": [],
      "env": {}
    }
  }
}

🎭 stdio vs HTTP Comparison

Feature	stdio Mode	HTTP Mode
Performance	🚀 Fastest	⚡ Fast
Timeouts	🕐 12+ hours	⏰ 10 minutes
Setup	🔌 One command	🌐 Server + client
Reliability	💎 Highest	🛡️ High
Use Case	🪄 Heavy automation	🎯 Quick tasks

📚 Magical Grimoires

Document	Description
📖 Enchanted Documentation Index	Complete magical grimoire directory with navigation
🚀 Quick Start	5-minute setup guide
🔌 Claude Code Integration	Complete integration guide
📊 API Spellbook	All 69 magical tools and enchanted endpoints
🏗️ Architecture	Complete system design and components
🚀 Deployment	Production deployment guide
🎨 Wand UI Integration	Magical dashboard and enchanted management APIs

🪄 Available Magical Integrations (50+ Total)

🎥 Media & Content Creation

• FFmpeg - Video processing and conversion
• OpenCV - Computer vision and image processing
• YouTube - Video upload and management
• Twitch - Streaming platform integration
• Audio - Audio processing and manipulation
• Whisper - Speech-to-text transcription
• ElevenLabs - Text-to-speech synthesis
• Image - Image generation and editing
• OCR - Optical character recognition
• QR - QR code generation and reading
• Chart - Data visualization and charting

🤖 AI & Machine Learning

• OpenAI - GPT models and API integration
• Anthropic - Claude model integration
• Cohere - Language model services
• Hugging Face - Model hub and transformers
• Replicate - Cloud AI model hosting
• Stability AI - Image generation models
• Ollama - Local language model management
• DeepL - Advanced translation services

💬 Communication & Social

• Discord - Bot integration and messaging
• Telegram - Bot and messaging automation
• Microsoft Teams - Webhook messaging and notifications
• Email - SMTP/IMAP email management
• Calendar - Calendar integration and scheduling

☁️ Cloud Storage & File Management

• Google Drive - File storage and sharing
• Dropbox - Cloud file synchronization
• OneDrive - Microsoft cloud storage
• S3 - Amazon S3 object storage
• FTP - File transfer protocol operations

📚 Documentation & Knowledge

• Notion - Knowledge management integration
• Confluence - Team wiki and documentation
• GitBook - Documentation platform
• Markdown - Markdown processing and conversion
• PDF - PDF generation and manipulation

🛠️ DevOps & Infrastructure

• Docker - Container management
• Kubernetes - Container orchestration
• Terraform - Infrastructure as code
• Prometheus - Monitoring and metrics
• Datadog - Application monitoring
• Sentry - Error tracking and monitoring

🔍 Testing & Automation

• Selenium - Web browser automation
• Playwright - Modern web testing
• Postman - API testing and development

💼 Business & CRM

• Salesforce - CRM and sales automation
• HubSpot - Marketing and sales platform
• Pipedrive - Sales pipeline management
• Stripe - Payment processing

📋 Project Management

• Jira - Issue tracking and project management
• Asana - Team task management
• Trello - Kanban board management
• Linear - Modern issue tracking
• Monday.com - Work operating system

👥 HR & Productivity

• Workday - Human capital management
• BambooHR - HR information system
• Toggl - Time tracking
• Harvest - Time tracking and invoicing

🔐 Security & Identity

• ServiceNow - IT Service Management and ITSM
• SailPoint - Identity Security Cloud and governance
• Microsoft Entra - Azure AD identity management
• Britive - Privileged access management (PAM)
• Vault - Secret management
• 1Password - Password management
• Okta - Identity and access management
• Auth0 - Authentication as a service
• Veracode - Application security testing
• Snyk - Vulnerability management
• SonarQube - Code quality and security

🎮 Entertainment & Gaming

• Spotify - Music streaming integration
• Podcast - Podcast management and processing
• Steam - Gaming platform integration

🏢 Enterprise Integration Spotlight

Wand now includes comprehensive enterprise identity management and communication tools:

🔐 Identity & Access Management

• servicenow - Create incidents, manage users, query ITSM records
• sailpoint - Identity governance, access requests, certification campaigns
• entra - Azure AD user/group management, role assignments
• britive - Just-in-time privileged access, secret checkout

💬 Enterprise Communication

• teams - Send messages, cards, and notifications via webhooks

Example Usage:

# Create ServiceNow incident
servicenow(operation="create_incident",
          short_description="Server outage",
          priority="1")

# Request SailPoint access
sailpoint(operation="request_access",
          identity_id="user123",
          access_profile_ids=["admin_profile"])

# Send Teams notification
teams(operation="send_notification",
      title="Deployment Complete",
      message="v2.1.0 deployed successfully",
      status="success")

See Enterprise Integrations Guide for complete setup and usage documentation.

🪄 Magical Server Modes

HTTP Mode (Recommended)

python wand.py http
# Server available at http://localhost:8001/mcp

stdio Mode

python wand.py stdio
# For direct process communication

🏗️ Magical Architecture

• Multi-Agent System: 3 internal agents with load balancing
• Execution Backends: Native, Docker, SSH, Host Agent
• Security: Command validation, path restrictions, resource limits
• Monitoring: Health checks, performance tracking, audit logging

🐳 Docker Support

# Quick start with Docker
docker build -f scripts/Dockerfile -t wand .
docker run -p 8001:8001 wand

🔒 Protective Wards

• OAuth 2.1 authentication with resource indicators
• Command allowlist/blocklist with pattern matching
• Path restrictions and resource limits
• Session management with cleanup
• Comprehensive audit logging

📊 Magical Performance

• Response Time: <200ms average
• Concurrency: 10+ simultaneous sessions
• Memory Usage: <50MB per backend
• Scalability: Horizontal scaling support

🧪 Local CI & Testing

Wand includes a comprehensive local CI system that mirrors the GitHub Actions pipeline, helping you catch issues before pushing code.

Quick Testing

# Run the full CI pipeline (recommended before every commit)
./ci.sh

# Run only enterprise integration tests
./ci.sh --enterprise

# Run with verbose output for detailed logs
./ci.sh --enterprise --verbose

# Setup environment only
./ci.sh --setup

Available Test Modes

• ./ci.sh - Full CI pipeline (setup + all checks + tests)
• ./ci.sh --enterprise - Enterprise integration tests only
• ./ci.sh --basic - Basic tests (no external dependencies)
• ./ci.sh --tests-only - All tests without setup
• ./ci.sh --lint-only - Code linting only
• ./ci.sh --security-only - Security scans only

CI Pipeline Features

• Environment Setup: Automatic virtual environment management
• Dependency Management: Installs required and optional dependencies
• Enterprise Integration Testing: Tests for ServiceNow, SailPoint, Microsoft Entra, Britive, Teams
• Code Quality: Linting (ruff), type checking (mypy), security scanning (bandit, safety)
• Smart Dependencies: Gracefully handles missing optional enterprise packages
• Colored Output: Clear, colored logging for easy reading

Enterprise Integration Tests

The enterprise tests are designed for CI environments:

• With Dependencies: Full integration tests with proper mocking
• Without Dependencies: Tests automatically skip with descriptive messages
• Expected Skips: pysnc (ServiceNow), azure-identity (Entra), britive (PAM)

Before Committing

# Always run CI to catch issues early
./ci.sh

# If enterprise tests fail, investigate with verbose output
./ci.sh --enterprise --verbose

🤝 Join the Magic

Development Workflow

1. Setup: Run ./ci.sh --setup to prepare your environment
2. Development: Use ./ci.sh --tests-only for quick feedback
3. Before committing: Run ./ci.sh to ensure all checks pass
4. Code quality: Use ./ci.sh --lint-only to fix style issues

Contributing Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Set up development environment (./ci.sh --setup)
4. Make your changes and test (./ci.sh)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under a proprietary license - see the LICENSE file for details.

🆘 Magical Support

• 📖 Documentation: Check the docs/ directory for detailed guides
• 🐛 Issues: Report bugs via GitHub Issues
• 💬 Questions: Start a GitHub Discussion
• 🔧 Debug: Enable debug logging with LOG_LEVEL=DEBUG

🚫 AI Training Policy

This repository opts out of AI/ML training. The code and documentation in this repository may not be used for training machine learning models without explicit written permission.

For more details, see:

• DO_NOT_TRAIN.md - Full legal notice
• .ai-training-opt-out - Opt-out marker file
• .noai - Additional opt-out marker
• robots.txt - Crawler directives

---

🪄 May your automation be swift and your magic be strong! ✨ Happy spell casting with Wand!

    🌟 Welcome to the magical realm of automation 🌟
         🔮 Where 50+ integrations await your command 🔮
              ✨ Cast responsibly, automate magically ✨