MCP Client (GitHub Copilot / Claude Desktop / …)
  │  calls tools over MCP stdio transport
  ▼
FastMCP Server
  ├─► ChromaDB  (sentence-transformers embeddings — local, no API key)
  │     semantic search over VISA Dispute Management Guidelines PDF chunks
  └─► SQLite    (SQLAlchemy)
        merchant dispute history warehouse

# 1. Clone
git clone https://github.com/alejamorenovallejo/visa-dispute-advisor.git
cd visa-dispute-advisor

# 2. Install dependencies
uv sync

# 3. Configure paths (defaults work out-of-the-box)
cp .env.example .env

# 4. Place VISA PDF in the data/ folder
# Download from: https://myanmar.visa.com/content/dam/VCOM/global/support-legal/documents/merchants-dispute-management-guidelines.pdf
# Save it as: data/merchants-dispute-management-guidelines.pdf

# 5. Ingest VISA rules into vector store
uv run python -m visa_dispute_advisor.ingest

# 6. Seed demo merchant dispute history
uv run python scripts/seed_merchants.py

# stdio transport — for MCP clients
uv run visa-advisor

# HTTP transport with browser inspector — for development
uv run fastmcp dev src/visa_dispute_advisor/server.py

{
  "servers": {
    "visa-dispute-advisor": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "visa-advisor"],
      "cwd": "${workspaceFolder}"
    }
  }
}

{
  "mcpServers": {
    "visa-dispute-advisor": {
      "command": "uv",
      "args": ["run", "visa-advisor"],
      "cwd": "/absolute/path/to/visa-dispute-advisor"
    }
  }
}

Dispute case:
  Merchant ID: MER-001 (Tech Store Guatemala)
  Cardholder claim: Item not received. Ordered a laptop online on
  2026-03-01, expected delivery 2026-03-10. Tracking shows "delivered"
  but customer denies receiving it. Amount: $450.00.
  Merchant response: Has carrier tracking proof showing delivery to
  the billing address.

Agent calls:
  1. search_visa_rules("customer claims item not received, merchant has tracking proof")
  2. query_warehouse("MER-001")

Recommendation: REJECT DISPUTE (favor merchant)
  Applicable rule: Condition 13.1 — Merchandise/Services Not Received.
  Merchant can provide tracking documentation proving delivery to the
  agreed address. Under Condition 13.1, this constitutes valid compelling
  evidence to dispute the chargeback.

  Merchant risk profile: LOW RISK — 2 of 3 prior disputes resolved in
  merchant's favor. No pattern of fraudulent behavior detected.

  Next steps:
  1. Request signed proof of delivery from carrier.
  2. Submit tracking number and delivery confirmation to acquirer.
  3. If cardholder insists, escalate to Visa arbitration.

uv run ruff check --fix src/
uv run ruff format src/
uv run pytest