carrier-accounting-mcp: Instructions file for Claude Code

Carrier Accounting MCP — Claude Code Context

CRITICAL DATA PROTECTION RULES

NEVER delete, truncate, drop, or overwrite customer data. This includes:

• Supabase: synced_policies (316K+), synced_clients (15K+), carrier_transactions, carrier_runs, carrier_learned_mappings, organizations, users, subscriptions
• BigQuery: Any tables in the data-lake-412218 project
• No DELETE, TRUNCATE, DROP TABLE, or .delete() bulk operations
• Use soft deletes only. When in doubt, ASK first.

---

Project Overview

This is an Insurance Carrier Accounting MCP Server for Snellings Walters Insurance. It automates the full carrier statement lifecycle:

1. Ingest carrier PDFs and Excel bordereaux files
2. Browse carrier portals to download statements
3. Normalize and validate transactions against the BigQuery data lake
4. Post approved entries to Applied Epic via the SDK
5. Provide a daily accuracy dashboard for the accounting team

Architecture

Carrier PDFs/Excel/Portals
         ↓
[MCP: Ingestion Layer]       — pdfplumber, pandas, playwright
         ↓
[MCP: Normalization Layer]   — Claude LLM maps raw → canonical schema
         ↓
[MCP: Validation Layer]      — BigQuery: match policies, check duplicates
         ↓
[Confidence Scoring]         — ≥95% auto-queue, <95% human review queue
         ↓
[Staging / Trial Mode]       — Shadow writes to BQ, NOT Epic
         ↓ (approved)
[MCP: Epic Write Layer]      — Applied Epic SDK posts entries
         ↓
[Audit Trail in Data Lake]   — Full lineage: source file → Epic entry ID
         ↓
[Daily Monitoring Dashboard] — Streamlit + BigQuery

Repository Structure

carrier-accounting-mcp/
├── CLAUDE.md                          ← YOU ARE HERE
├── README.md
├── requirements.txt
├── pyproject.toml
├── .env.example
├── mcp_server/
│   ├── server.py                      ← Main MCP server entrypoint
│   ├── config.py                      ← All configuration
│   ├── tools/
│   │   ├── ingestion.py               ← PDF/Excel parsing tools
│   │   ├── normalization.py           ← LLM normalization tools
│   │   ├── validation.py              ← BigQuery validation tools
│   │   ├── staging.py                 ← Trial/shadow mode tools
│   │   ├── epic_writer.py             ← Applied Epic SDK write tools
│   │   ├── monitoring.py              ← Daily metrics & exception queue
│   │   └── browser.py                 ← Playwright carrier portal tools
│   ├── schemas/
│   │   ├── canonical.py               ← Canonical transaction dataclass
│   │   └── carrier_schemas/           ← Per-carrier field mappings
│   └── services/
│       ├── bigquery_client.py         ← BQ connection + query helpers
│       ├── epic_sdk_client.py         ← Applied Epic SDK wrapper
│       └── confidence_scorer.py       ← Confidence scoring logic
├── data_lake/
│   ├── schemas/
│   │   ├── staging_tables.sql         ← BQ staging + shadow table DDL
│   │   └── audit_tables.sql           ← Audit trail DDL
│   └── queries/
│       ├── validate_policy.sql
│       ├── check_duplicate.sql
│       └── daily_metrics.sql
├── dashboard/
│   └── daily_monitoring.py            ← Streamlit daily scorecard
├── carrier_configs/
│   ├── README.md
│   └── carrier_template.yaml          ← Template for onboarding new carriers
├── tests/
│   ├── test_ingestion.py
│   ├── test_normalization.py
│   └── test_validation.py
└── docs/
    ├── architecture.md
    ├── adding_carriers.md
    ├── trial_run_guide.md
    └── epic_sdk_setup.md