Mambo by Othocs - MCP Server

🎭 Mambo

AI-driven UX audit agent that detects conversion-killing issues traditional tools miss

Mambo is an MCP server for Mistral's Le Chat that uses AI to analyze websites and identify subtle UX/design issues that hurt conversion rates. Unlike traditional tools like Lighthouse that focus on technical metrics, Mambo understands user psychology and business impact.

🎯 What Mambo Does

UX Issues: Poor CTA visibility, confusing navigation, bad form design
Conversion Blockers: Missing trust signals, unclear pricing, checkout friction
Accessibility: WCAG violations, keyboard navigation issues
Performance: Layout shifts, slow loading that impacts user experience
Visual Design: Poor contrast, hierarchy problems, readability issues

🚀 Quick Start

Prerequisites

Python 3.10+
uv package manager (install guide)
Mistral API key (get one here)

Installation

Clone and setup the project:

git clone <your-repo-url>
cd Mambo
uv sync

Install Playwright browsers:

uv run python scripts/setup_playwright.py

Set your Mistral API key:

export MISTRAL_API_KEY="your-api-key-here"

Running Mambo

Start the FastMCP server:

uv run python src/mambo/server/fastmcp_server.py

🔧 Configuration for Le Chat

Add Mambo to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mambo": {
      "command": "uv",
      "args": ["run", "python", "src/mambo/server/fastmcp_server.py"],
      "cwd": "/path/to/your/Mambo/project",
      "env": {
        "MISTRAL_API_KEY": "your-actual-mistral-api-key-here"
      }
    }
  }
}

⚠️ Important: You must include the env section with your Mistral API key, as MCP servers run in isolated environments and don't inherit shell environment variables.

📖 Usage

Once configured, you can use Mambo in Le Chat:

Basic Audit

Audit this website for UX issues: https://example.com

Mobile Audit

Run a mobile audit on https://shop.com/checkout

Quick Check

Do a quick UX check on https://landing-page.com

🛠️ Available Tools

Tool	Description	Parameters
`audit_url`	Comprehensive UX audit	`url`, `device` (desktop/mobile/tablet), `wait_until`
`quick_audit`	Fast audit focusing on critical issues	`url`
`get_artifact`	Retrieve screenshots or DOM snapshots	`artifact_id`

📊 Sample Report

{
  "success": true,
  "quick_stats": {
    "score": 62,
    "critical_issues": 2,
    "high_issues": 4,
    "total_issues": 12
  },
  "top_issues": [
    {
      "title": "CTA contrast too low",
      "severity": "high",
      "category": "ux",
      "why_it_hurts": "Primary action is hard to perceive; users may miss next step"
    }
  ],
  "summary": "Found 6 conversion-impacting issues. Primary CTA has poor contrast and sticky header overlaps form fields on mobile."
}

🏗️ Architecture

Le Chat → Mambo MCP Server → Mistral AI ↘
                           ↗              → Analysis
                    Playwright → Browser

Mistral AI: Intelligent analysis and decision making
Playwright: Browser automation and data collection
FastMCP: Simple MCP server implementation
Le Chat: User interface and conversation

🛣️ Roadmap

v1.0 (Current)

✅ Single page audits
✅ Mobile/desktop analysis
✅ AI-powered issue detection
✅ FastMCP integration

v2.0 (Planned)

🔄 User flow analysis (multi-step journeys)
🔄 A/B test recommendations
🔄 Competitive analysis
🔄 Integration with analytics tools

🧪 Development

Project Structure

Mambo/
├── src/mambo/
│   ├── agent/              # Core AI agent logic
│   ├── models/             # Pydantic schemas  
│   ├── server/             # MCP server
│   └── analyzers/          # Analysis modules
├── scripts/                # Setup scripts
└── tests/                  # Test suite

Running Tests

uv run pytest

Code Quality

uv run ruff check --fix    # Linting
uv run ruff format         # Formatting

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run quality checks: uv run ruff check && uv run pytest
Commit using conventional commits: git commit -m "feat: add amazing feature"
Push and create a Pull Request

📝 License

This project is licensed under the MIT License - see the file for details.

🙋‍♀️ Support

🐛 Bug reports: GitHub Issues
💬 Questions: GitHub Discussions
📧 Email: your-email@example.com

Built with ❤️ for better web experiences