Metadata-Version: 2.4
Name: fresh-wbr-mcp
Version: 0.1.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)** report generator, deployed as an MCP server. Queries AWS Athena, auto-discovers metrics, and renders beautiful HTML/PDF reports.

## Features

- **Dynamic columns** — auto-detects latest 5 weeks and trailing 12 months from data
- **Auto-expanding metrics** — new metrics in the data automatically appear in reports
- **Beautiful HTML output** — dark theme, responsive, RAG color indicators
- **Server-side PDF** — tamper-proof PDF generation via WeasyPrint
- **No credentials in code** — uses ambient AWS credentials (AWS CLI)
- **MCP integration** — use from Kiro, Claude Desktop, or any MCP client

## Quick Start (uvx)

```bash
# Set your environment variables
export WBR_ATHENA_DATABASE=my_database
export WBR_ATHENA_VIEW=my_wbr_view
export WBR_ATHENA_OUTPUT_LOCATION=s3://my-bucket/athena-results/
export WBR_ATHENA_REGION=us-east-1

# Run via uvx (no install needed)
uvx fresh-wbr-mcp
```

## MCP Configuration

Add to your MCP client config (e.g., `.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "fresh-wbr": {
      "command": "uvx",
      "args": ["fresh-wbr-mcp"],
      "env": {
        "WBR_ATHENA_DATABASE": "my_database",
        "WBR_ATHENA_VIEW": "my_wbr_view",
        "WBR_ATHENA_OUTPUT_LOCATION": "s3://my-bucket/athena-results/",
        "WBR_ATHENA_REGION": "us-east-1"
      },
      "disabled": false
    }
  }
}
```

## Tools

### `generate_wbr`

Generate a WBR report as HTML.

```
generate_wbr(level="01_Fresh")
generate_wbr(level="02_Category", level_value="grocery")
generate_wbr(level="11_Channel", level_value="Online", metrics="Traffic,GV,Orders")
```

### `generate_wbr_pdf`

Generate a tamper-proof PDF (server-side, not from browser DOM).

```
generate_wbr_pdf(level="01_Fresh")
```

### `list_wbr_levels`

Discover available hierarchy levels in your data.

### `list_wbr_metrics`

List metrics available for a given level.

### `preview_wbr_data`

Preview data without generating a file.

## Expected Data Schema

Your Athena view/table must have these columns:

| Column | Type | Description |
|--------|------|-------------|
| `level` | string | Hierarchy level identifier |
| `level_dim_1` | string | First dimension name |
| `level_value` | string | First dimension value |
| `level_dim_2` | string | Second dimension name |
| `level_value_2` | string | Second dimension value |
| `metric` | string | Metric name |
| `uom` | string | Unit of measure (#, %, ₹, etc.) |
| `metric_type` | string | Metric type |
| `metric_type_num_topic` | number | Sort order for metrics |
| `time_period_type` | string | "1.Weekly" or "2.Monthly" |
| `time_period` | string | "Week" or "Month" |
| `time_period_val` | string | Period label (e.g., "26-W-20", "26-M-06") |
| `time_period_sort` | number | Sortable period number (e.g., 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 (%) |

## Prerequisites

- **AWS CLI** configured with valid credentials
- **Access** to the Athena database specified in env vars
- **Python 3.9+** (for local install) or just `uvx` (for direct run)

## Environment Variables

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

## Local Development

```bash
git clone https://github.com/mondalbh/fresh-wbr-mcp.git
cd fresh-wbr-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## License

MIT
