Metadata-Version: 2.4
Name: merchwatch-mcp
Version: 1.0.0
Summary: MerchWatch MCP Extension — Merchant performance monitoring tools for Goose (disputes, refunds, chargebacks, linkage)
Project-URL: Homepage, https://github.com/sherryxu-7889/MerchWatch_mcp
Project-URL: Repository, https://github.com/sherryxu-7889/MerchWatch_mcp
Project-URL: Issues, https://github.com/sherryxu-7889/MerchWatch_mcp/issues
Author-email: Sherry Xu <sherryxu@squareup.com>
License: MIT
Keywords: afterpay,disputes,goose,mcp,merchant,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# MerchWatch MCP Extension

A Goose MCP extension for monitoring merchant performance — disputes, refunds,
chargebacks, open cases, dispute reason analysis, and merchant linkage.

## Quick Start — Add to Your Goose

### Option 1: Add via Goose Settings UI (Recommended)

1. Open **Goose Desktop** → **Settings** → **Extensions**
2. Click **"Add custom extension"**
3. Fill in:
   - **Type:** Standard I/O
   - **ID:** `merchwatch`
   - **Name:** `MerchWatch`
   - **Description:** `Merchant performance monitoring - disputes, refunds, chargebacks, linkage`
   - **Command:** `uv`
   - **Arguments:** `run --directory /path/to/MerchWatch_mcp merchwatch-mcp`
     _(replace `/path/to/MerchWatch_mcp` with your actual clone path)_
4. Click **Save** → toggle **Enabled**

### Option 2: Edit Config File Directly

Add this block to `~/.config/goose/config.yaml` under `extensions:`:

```yaml
  merchwatch:
    enabled: true
    type: stdio
    name: MerchWatch
    description: Merchant performance monitoring - dispute ratios, open cases, reason analysis, and merchant linkage
    cmd: uv
    args:
      - run
      - --directory
      - /path/to/MerchWatch_mcp    # ← Change to your clone location
      - merchwatch-mcp
    envs: {}
    env_keys: []
    timeout: 300
```

Then restart Goose.

## Installation

### Prerequisites

- **Python 3.10+**
- **[uv](https://docs.astral.sh/uv/)** — Python package manager
- **Goose Desktop** or **Goose CLI**
- **Snowflake MCP extension** — must be enabled in Goose (MerchWatch generates SQL, Snowflake executes it)
- Appropriate **Snowflake permissions** for the data tables listed below

### Steps

```bash
# 1. Clone the repo
git clone https://github.com/sherryxu-7889/MerchWatch_mcp.git
cd MerchWatch_mcp

# 2. Install dependencies (uv handles this automatically, but to verify)
uv sync

# 3. Add to Goose using one of the options above
#    Make sure to update the --directory path to where you cloned the repo
#    e.g. /Users/yourname/projects/MerchWatch_mcp

# 4. Enable the Snowflake extension in Goose
#    Go to Goose Settings → Extensions → Snowflake → Enable
```

### Verify It Works

After setup, open a new Goose session and try:
> "Show dispute ratio for merchant 12345"

Goose should call the `dispute_ratio` tool, execute the SQL via Snowflake, and present results.

## How It Works

```
User asks about a merchant (e.g. "Show disputes for MID 40457")
        ↓
Goose calls a MerchWatch tool → returns SQL query + presentation instructions
        ↓
Goose executes the SQL via Snowflake MCP extension (snowflake__execute_query)
        ↓
Goose presents results with charts & formatted tables
```

## Overview

MerchWatch provides **11 tools** that generate SQL queries for execution via
Goose's Snowflake MCP extension. It covers the full merchant risk monitoring
workflow:

| # | Tool | Description |
|---|------|-------------|
| 1 | `dispute_ratio` | Dispute ratio trend (dispute amount / GMV by **order date**) |
| 2 | `dispute_events` | Daily dispute count & amount by **event date** |
| 3 | `refund_ratio` | Refund ratio trend (refund amount / GMV by **order date**) |
| 4 | `refund_events` | Daily refund count & amount by **event date** |
| 5 | `chargeback_ratio` | Merch chargeback ratio trend (chargeback amount / GMV by **order date**) |
| 6 | `chargeback_events` | Daily chargeback count & amount by **event date** |
| 7 | `open_cases` | Current open case count & amount (IN_PROGRESS status) |
| 8 | `open_case_reasons` | Categorize **open** disputes by subject keyword analysis (11 categories) |
| 9 | `period_reasons` | Categorize **all** disputes in a date range by subject keyword analysis |
| 10 | `merchant_linkage` | Find linked merchants via 8 sources (website, trading name, company, phone, ABN, address, bank, redirect URL) |
| 11 | `linkage_website` | Find merchants by website domain search (no MID required) |

## Tool Details

### Ratio Tools (dispute_ratio, refund_ratio, chargeback_ratio)

Analyse negative-event amounts against daily GMV, grouped by **ORDER_DATE**
(when the original order was placed).

**Parameters:**
- `merchant_id` (required) — Merchant ID, supports comma-separated for multiple MIDs
- `start_date` (optional) — YYYY-MM-DD, defaults to 60 days ago
- `end_date` (optional) — YYYY-MM-DD, defaults to today

**Returns:** ORDER_DATE, MERCHANT_ID, DAILY_GMV, EVENT_AMT, EVENT_COUNT, RATIO

### Event Tools (dispute_events, refund_events, chargeback_events)

Daily count and amount grouped by **EVENT_DATE** (when the negative event
actually occurred, not when the order was placed).

**Parameters:** Same as ratio tools.

**Returns:** EVENT_DATE, MERCHANT_ID, EVENT_COUNT, EVENT_AMT

### open_cases

Point-in-time snapshot of open dispute cases (IN_PROGRESS status).

**Parameters:**
- `merchant_id` (required)

**Returns:** DISPUTE_RESULT, CUR_INTENT, OPEN_CASE_AMOUNT, OPEN_CASE_COUNT

### open_case_reasons

Categorizes **open** (IN_PROGRESS) dispute cases into 11 categories by
analysing the free-text SUBJECT field with keyword matching:

1. Order/Flight Cancelled
2. Non-Delivery / No Tracking
3. Merchant Unresponsive
4. Payment Error / Double Charge
5. Item Out of Stock
6. Scam / Fraud
7. Refund Not Processed
8. Wrong / Damaged Item
9. Return Not Refunded
10. No Subject Provided
11. Other

**Parameters:**
- `merchant_id` (required)

**Returns:** DISPUTE_CATEGORY, DISPUTE_COUNT, TOTAL_DISPUTE_AMOUNT, SAMPLE_ORDER_IDS, SAMPLE_SUBJECTS

### period_reasons

Same 11-category analysis as `open_case_reasons`, but covers **all** cases
filed within a date range (not just open ones). Uses PAR_PROCESS_DATE for
date filtering.

**Parameters:**
- `merchant_id` (required)
- `start_date` (optional) — YYYY-MM-DD, defaults to 60 days ago
- `end_date` (optional) — YYYY-MM-DD, defaults to today

### merchant_linkage

Multi-step linkage analysis that finds merchants sharing attributes across
**8 data sources**:

| # | Source | Attribute |
|---|--------|-----------|
| 1 | Website Domain | MERCHANT_PRODUCT_DETAILS_WEBSITE_URL |
| 2 | Trading Name | MERCHANT_GENERAL_DETAILS_TRADING_NAME |
| 3 | Company Name | MERCHANT_GENERAL_DETAILS_COMPANY_NAME |
| 4 | Phone (hashed) | MERCHANT_GENERAL_DETAILS_CONTACT_NUMBER |
| 5 | ABN (hashed) | MERCHANT_GENERAL_DETAILS_BUSINESS_NUMBER |
| 6 | Address | ADDRESS1 + POSTCODE |
| 7 | Bank Account | BRANCH_NUMBER + ACCOUNT_NUMBER |
| 8 | Redirect URL | RAW_C_E_ORDER_INITIATED.REDIRECT_CONFIRM_URL |

**Parameters:**
- `merchant_id` (required)
- `website` (optional) — override the merchant's registered website

**Confidence scoring:**
- **High** — 3+ linkage sources matched
- **Medium** — 2 sources matched
- **Low** — 1 source matched

### linkage_website

Website-only search — find all merchants associated with a domain. No MID
required. Searches both registered website URLs and redirect confirm URLs,
and joins DWM_MERCHANT_MASTER_TBL for last order date.

**Parameters:**
- `website` (required) — URL or domain to search

**Returns:** MERCHANT_ID, TRADING_NAME, COMPANY_NAME, WEBSITE_URL, STATUS, LAST_ORDER_DATE, MATCH_SOURCE

## Data Sources

| Table | Used By |
|-------|---------|
| `AP_CUR_BI_G.CURATED_ANALYTICS_GREEN.CUR_C_M_ORDER_MASTER` | Ratio tools (GMV) |
| `AP_CUR_MERRISK_G.CURATED_MERCHANT_RISK_GREEN.CRT_NEGATIVE_EVENT_ORDER` | Ratio + Event tools |
| `AP_CUR_MERRISK_G.CURATED_MERCHANT_RISK_GREEN.MERCHANDISE_DISPUTE_CHARGEBACK_DAILY` | open_cases, open_case_reasons |
| `AP_RAW_GREEN.GREEN.RAW_P_E_DISPUTE_CASE_PROCESS` | open_case_reasons, period_reasons |
| `AP_RAW_GREEN.GREEN.RAW_M_E_MERCHANT` | merchant_linkage, linkage_website |
| `AP_RAW_GREEN.GREEN.RAW_C_E_ORDER_INITIATED` | merchant_linkage (redirect URL), linkage_website |
| `AP_CUR_BI_G.CURATED_ANALYTICS_GREEN.DWM_MERCHANT_MASTER_TBL` | linkage_website (last order date) |

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `uv: command not found` | Install uv: `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Extension not showing in Goose | Check `~/.config/goose/config.yaml` — ensure `enabled: true` and the `--directory` path is correct |
| Tools not appearing | Restart Goose after config changes. Check the extension shows a green dot in Settings. |
| Queries return no data | Ensure the Snowflake extension is enabled and you have permissions for the tables above |
| Timeout errors | Increase `timeout` in config (default 300s). Linkage queries can be slow. |
| `ModuleNotFoundError` | Run `uv sync` in the MerchWatch_mcp directory |

## Contributing

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/my-new-tool`)
3. Commit your changes (`git commit -am 'Add new tool'`)
4. Push to the branch (`git push origin feature/my-new-tool`)
5. Open a Pull Request
