Metadata-Version: 2.4
Name: fresh-wbr-mcp
Version: 0.2.0
Summary: Dynamic WBR (Weekly Business Review) report generator MCP server. Queries AWS Athena, auto-discovers metrics, and renders beautiful HTML/PDF reports.
Author-email: mondalbh <mondalbh@amazon.com>
License: MIT
Project-URL: Homepage, https://github.com/mondalbh/fresh-wbr-mcp
Project-URL: Repository, https://github.com/mondalbh/fresh-wbr-mcp
Keywords: mcp,wbr,athena,report,weekly-business-review,analytics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: weasyprint>=60.0
Dynamic: license-file

# Fresh WBR MCP

Dynamic **Weekly Business Review (WBR)** dashboard generator, deployed as an MCP server. Queries AWS Athena, auto-discovers metrics across multiple reporting lenses, and renders a full-featured interactive HTML dashboard.

## Features

- **Multi-lens dashboard** — Overall, Channel, City, GL, Fresh Express views in one report
- **Auto-discovering** — new metrics and segments appear automatically from data
- **Interactive** — collapsible sections, lens filtering, metric focus, theme switcher
- **Real per-segment data** — each city/channel/GL shows actual values from Athena
- **Tamper protection** — DOM mutation observer prevents client-side value editing
- **Key Movements** — auto-generated insights from data
- **Top/Bottom Movers** — highlights best and worst performing metrics
- **No credentials in code** — uses ambient AWS credentials via CLI

## Quick Start (uvx)

```bash
export WBR_ATHENA_DATABASE=your_database
export WBR_ATHENA_VIEW=your_wbr_view
export WBR_ATHENA_OUTPUT_LOCATION=s3://your-athena-results-bucket/
export WBR_ATHENA_REGION=us-east-1

uvx fresh-wbr-mcp
```

## MCP Configuration

```json
{
  "mcpServers": {
    "fresh-wbr": {
      "command": "uvx",
      "args": ["fresh-wbr-mcp"],
      "env": {
        "WBR_ATHENA_DATABASE": "your_database",
        "WBR_ATHENA_VIEW": "your_wbr_view",
        "WBR_ATHENA_OUTPUT_LOCATION": "s3://your-bucket/athena-results/",
        "WBR_ATHENA_REGION": "us-east-1"
      }
    }
  }
}
```

## Tools

### `generate_wbr`

Generate the full leadership WBR dashboard.

```
generate_wbr()
generate_wbr(output_path="my_report.html")
```

## Dashboard Features

| Feature | Description |
|---------|-------------|
| Reporting Lens | Filter by: All, Overall, Channel, City, GL, Seller, Fresh Express |
| Metric Sections | Growth & Demand, Conversion & Basket, Availability & Selection, Price Competitiveness |
| Collapse/Expand | Collapse lenses, lens values, or metric sections independently |
| Theme Switcher | Dark mode (default) or Soft Light mode |
| Top/Bottom Movers | Auto-detected from WoW changes |
| Key Movements | AI-generated insights from metric trends |
| Data Quality | Alerts for missing goals, new/unmapped metrics |
| Export | PDF/Print, Excel download, Copy table |
| Refresh | Smooth animated page refresh |
| Tamper Protection | DOM observer prevents inspect-element value editing |

## Expected Data Schema

Your Athena view must have these columns:

| Column | Type | Description |
|--------|------|-------------|
| `level` | string | Hierarchy level (01_Fresh, 02_Channel, 04_City, 06_GL) |
| `level_value` | string | Segment name (city/channel/GL name) |
| `metric` | string | Metric name |
| `uom` | string | Unit of measure |
| `metric_type_num_topic` | number | Sort order |
| `time_period` | string | "Week" or "Month" |
| `time_period_val` | string | Period label (26-W-20, 26-M-06) |
| `time_period_sort` | number | Sortable period (202620) |
| `actual_topic` | number | Actual value |
| `goal_topic` | number | Goal value |
| `vs_goal_topic` | number | Variance vs goal (%) |
| `vs_last_period_topic` | number | Variance vs prior period (%) |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `WBR_ATHENA_DATABASE` | ✅ | Athena database name |
| `WBR_ATHENA_VIEW` | ✅ | Table/view to query |
| `WBR_ATHENA_OUTPUT_LOCATION` | ✅ | S3 path for query results |
| `WBR_ATHENA_REGION` | ❌ | AWS region (default: us-east-1) |

## Project Structure

```
fresh_wbr_mcp/
├── __init__.py
├── __main__.py          # MCP server entry point
├── data_fetcher.py      # Athena query builder
├── processor.py         # Data → dashboard format
├── renderer.py          # Injects data into template
├── server.py            # Core generation logic
└── templates/
    └── wbr_leadership.html  # Full dashboard template
```

## License

MIT

## Credits

Created by @mondalbh • Owned by CoBRA BIE Team
