merchwatch-mcp 1.0.0

MerchWatch MCP Extension — Merchant performance monitoring tools for Goose (disputes, refunds, chargebacks, linkage)

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::

  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 — 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

# 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