server.py

"""
RCM Billing MCP — Lite (Free)
==============================
Free denial decoding tool for medical billers using Claude.

2 tools:
  decode_denial      — Decode any CARC + RARC + group code from an 835/ERA
  get_pos_description — Look up Place of Service code meaning + billing notes

No subscription required. For the full 10-tool workflow suite
(claim validation, LCD coverage, NPI lookup, timely filing,
modifier analysis, and appeal letter generation), see:
  RCM Billing MCP — Full Suite ($29/mo)

Deploy: Railway (Dockerfile included)
Auth:   No auth required on the lite server
"""

import json
import os
import re
import sqlite3
import datetime
from typing import Optional

from fastmcp import FastMCP

mcp = FastMCP(
    name="RCMBillingMCP-Lite",
    instructions=(
        "Free medical billing denial decoder. Use decode_denial to instantly "
        "translate any CARC/RARC code from an 835 ERA into plain English with "
        "root cause and next action. Use get_pos_description to look up Place "
        "of Service codes. For the full 10-tool billing workflow suite including "
        "claim validation, LCD coverage, NPI lookup, timely filing, and appeal "
        "letter generation, upgrade to RCM Billing MCP Full Suite."
    ),
)

DB_PATH = os.environ.get("RCM_DB_PATH", "rcm_lite.db")

# ---------------------------------------------------------------------------
# Database init
# ---------------------------------------------------------------------------
def init_db():
    con = sqlite3.connect(DB_PATH)
    cur = con.cursor()

    # CARC codes
    cur.execute("""
        CREATE TABLE IF NOT EXISTS carc_codes (
            code TEXT PRIMARY KEY,
            description TEXT,
            notes TEXT,
            last_updated TEXT
        )
    """)

    # RARC codes
    cur.execute("""
        CREATE TABLE IF NOT EXISTS rarc_codes (
            code TEXT PRIMARY KEY,
            description TEXT,
            notes TEXT,
            last_updated TEXT
        )
    """)

    _seed_carc_codes(cur)
    _seed_rarc_codes(cur)
    con.commit()
    con.close()
    print(f"RCM DB initialized at {DB_PATH}")


# ---------------------------------------------------------------------------
# Seed data — CARC codes (X12, refreshed 3x/year)
# ---------------------------------------------------------------------------
def _seed_carc_codes(cur):
    cur.execute("SELECT COUNT(*) FROM carc_codes")
    if cur.fetchone()[0] > 0:
        return

    # Core high-frequency CARC codes (Jan 2026 X12 release)
    # Full ~250-code list — most impactful codes for daily RCM work
    carc_data = [
        ("1",  "Deductible Amount", "Patient responsibility — post to patient balance"),
        ("2",  "Coinsurance Amount", "Patient responsibility — post to patient balance"),
        ("3",  "Co-payment Amount", "Patient responsibility — post to patient balance"),
        ("4",  "The service is inconsistent with the modifier used", "Coding error — modifier does not apply to this CPT. Review modifier rules."),
        ("5",  "The procedure code/bill type is inconsistent with the place of service", "Coding error — POS mismatch. Verify POS code against service type."),
        ("6",  "The procedure/revenue code is inconsistent with the patient's age", "Clinical edit — age restriction on this code. Verify patient DOB and code selection."),
        ("7",  "The procedure/revenue code is inconsistent with the patient's gender", "Clinical edit — gender restriction. Verify patient gender and code selection."),
        ("8",  "The procedure code is inconsistent with the provider type/specialty (taxonomy)", "Taxonomy mismatch — provider specialty does not support this CPT. Verify NPI taxonomy."),
        ("9",  "The diagnosis is inconsistent with the patient's age", "Clinical edit — diagnosis not appropriate for patient age."),
        ("10", "The diagnosis is inconsistent with the patient's gender", "Clinical edit — diagnosis not appropriate for patient gender."),
        ("11", "The diagnosis is inconsistent with the procedure", "Medical necessity — ICD-10 does not support this CPT. Review LCD and recode."),
        ("12", "The diagnosis is inconsistent with the provider type", "Provider type does not typically treat this diagnosis."),
        ("13", "The date of death precedes the date of service", "Eligibility/data error — verify patient information."),
        ("14", "The date of birth follows the date of service", "Eligibility/data error — verify patient DOB."),
        ("15", "The authorization number is missing, invalid, or does not apply to the billed services or provider", "Auth error — obtain correct auth number. Verify auth covers this CPT and provider."),
        ("16", "Claim/service lacks information or has submission/billing error(s)", "Missing info — check remit for specific RARC codes indicating what's missing."),
        ("17", "Requested information was not provided or was insufficient/incomplete", "Additional documentation required — submit records."),
        ("18", "Exact duplicate claim/service", "Duplicate — verify claim was not already paid. If rebilling, use corrected claim frequency code 7."),
        ("19", "Claim denied because this is a work-related injury/illness and thus the liability of the Worker's Compensation Carrier", "COB — bill Workers' Comp first."),
        ("20", "Claim denied because this injury/illness is covered by the liability carrier", "COB — bill liability carrier first."),
        ("21", "Claim denied because this injury/illness is the liability of the no-fault carrier", "COB — bill no-fault carrier first."),
        ("22", "This care may be covered by another payer per coordination of benefits", "COB — verify primary insurance and bill correctly."),
        ("23", "The impact of prior payer(s) adjudication including payments and/or adjustments", "Secondary claim — include primary EOB with corrected secondary claim."),
        ("24", "Charges are covered under a capitation agreement/managed care plan", "Capitated service — not separately billable under this plan."),
        ("25", "Payment denied. Your Stop loss deductible has not been met", "Stop loss threshold — patient responsibility until deductible met."),
        ("26", "Expenses incurred prior to coverage", "Eligibility — service predates coverage effective date. Verify eligibility by DOS."),
        ("27", "Expenses incurred after coverage terminated", "Eligibility — service after termination date. Verify eligibility by DOS."),
        ("29", "The time limit for filing has expired", "Timely filing — check appeal rights. Gather proof of timely submission if available."),
        ("31", "Claim denied as patient cannot be identified as our insured", "Eligibility — verify member ID, DOB, plan. May need to rebill with corrected demographics."),
        ("32", "Our records indicate that this dependent is not an eligible dependent as defined", "Eligibility — dependent not covered. Verify plan terms."),
        ("33", "Insured has no dependent coverage", "Eligibility — dependent not covered under this plan."),
        ("35", "Lifetime benefit maximum has been reached", "Plan limit exhausted — write off per contract or bill patient if allowed."),
        ("36", "Balance does not exceed co-payment amount", "Zero-pay — co-pay equals or exceeds allowed amount. Post co-pay."),
        ("38", "Services not provided or authorized by designated (gatekeeper) primary care provider", "Referral required — obtain referral from PCP. May need to appeal if referral was obtained."),
        ("39", "Services denied at the time authorization/pre-certification was requested", "Auth denied — appeal or obtain medical records supporting medical necessity."),
        ("40", "Charges do not meet qualifications for emergent/urgent care", "EM denial — appeal with clinical documentation supporting emergency level."),
        ("45", "Charge exceeds fee schedule/maximum allowable or contracted/legislated fee arrangement", "Contractual — write off per contract. Do not bill patient for excess."),
        ("49", "These are non-covered services because this is a routine exam or screening procedure done in conjunction with a routine exam", "Non-covered — routine/screening not covered. Review plan benefits or rebill with correct diagnosis."),
        ("50", "These are non-covered services because this is not deemed a 'medical necessity' by the payer", "Medical necessity denial — appeal with clinical documentation and LCD criteria."),
        ("51", "These are non-covered services because this is a pre-existing condition", "Pre-existing — review plan terms. ACA plans cannot deny for pre-existing for individual market."),
        ("55", "Claim/service denied because procedure/treatment is deemed experimental/investigational by the payer", "Experimental — appeal with peer-reviewed literature supporting established use."),
        ("56", "Reason code was incorrectly applied", "Payer error — call payer to request correction."),
        ("57", "Revenue code billed is not correct for the type of bill", "Facility billing error — correct revenue code and rebill."),
        ("58", "Treatment was deemed by the payer to have been rendered in an inappropriate or invalid place of service", "POS denial — appeal or rebill with correct POS supported by documentation."),
        ("59", "Processed based on multiple or concurrent procedure rules", "NCCI edit or multiple procedure reduction — review modifier 51 or 59 usage."),
        ("60", "Charges for outpatient services are not covered when performed within a period of time prior to or after inpatient services", "Bundled into inpatient stay — 3-day payment window rule likely applies."),
        ("61", "Penalty for failure to obtain second surgical opinion", "Plan requirement — review plan terms. May be appealable."),
        ("66", "Blood Deductible", "Patient responsibility — blood deductible applies."),
        ("69", "Day outlier amount", "Inpatient DRG outlier — informational."),
        ("70", "Cost outlier — Adjustment to compensate for additional costs", "Inpatient outlier — informational."),
        ("74", "Duplicate of a claim processed, or to be processed, as a crossover claim", "Crossover duplicate — Medicare/Medicaid crossover handled automatically."),
        ("75", "Claim/service denied because procedure/treatment is deemed experimental/investigational or inconsistent with accepted medical practice", "Experimental/not medically accepted — strong appeal with clinical evidence required."),
        ("76", "Duplicate of a claim that has been processed or will be processed during the review process", "Under review duplicate — call payer to check status."),
        ("78", "Non-covered days/Room and Board does not meet payer criteria", "Inpatient criteria — appeal with clinical necessity documentation."),
        ("85", "Patient Interest Adjustment (Use Only Group Code PR)", "Interest payment to patient — informational."),
        ("87", "Transfer amount", "Transfer adjustment — informational."),
        ("89", "Professional fees are not covered when billed as institutional charges", "Billing type error — professional services must be billed on CMS-1500, not UB-04."),
        ("90", "Ingredient cost adjustment", "Pharmacy — drug cost adjustment."),
        ("91", "Dispensing fee adjustment", "Pharmacy — dispensing fee adjusted."),
        ("94", "Processed in Excess of charges", "Payer error — call payer."),
        ("96", "Non-covered charge(s)", "Non-covered service — review plan benefits. Write off or bill patient per contract."),
        ("97", "The benefit for this service is included in the payment/allowance for another service/procedure that has already been adjudicated", "Bundling — this CPT is bundled into another already paid. Review NCCI edits."),
        ("100", "Payment made to patient/insured/responsible party", "Payment issued to patient — collect from patient or request redirection."),
        ("101", "Predetermination: anticipated payment upon completion of treatment plan", "Predetermination — informational."),
        ("102", "Major Medical Adjustment", "Informational — coordination with major medical."),
        ("103", "Provider promotional discount", "Discount applied per agreement."),
        ("104", "Managed care withholding", "Withheld per managed care contract — informational."),
        ("107", "The related or qualifying claim/service was not identified on this claim", "Missing reference — include original claim number for corrected/related claims."),
        ("109", "Claim/service not covered by this payer/contractor. You must send the claim/service to the correct payer/contractor", "Wrong payer — verify insurance and resubmit to correct payer."),
        ("110", "Billing date predates service date", "Billing error — correct claim dates."),
        ("111", "Not covered unless the provider accepts assignment", "Assignment required — verify provider participation status."),
        ("114", "Procedure/product not approved by the Food and Drug Administration", "FDA approval issue — verify device/drug approval status."),
        ("115", "Procedure postponed, canceled, or delayed", "Service not rendered as scheduled."),
        ("119", "Benefit maximum for this time period or occurrence has been reached", "Benefit limit — verify plan limits. May be patient responsibility."),
        ("121", "Indemnification adjustment — Provider liability in network/out of network adjustment", "Network adjustment — informational."),
        ("122", "Psychiatric reduction", "Mental health benefit limit or reduction applied."),
        ("125", "Submission/billing error(s). At least one Remark Code must be provided", "Billing error — check RARC codes on this claim for specifics."),
        ("129", "Prior processing information appears incorrect. At least one Remark Code must be provided", "Prior claim data error — check RARC for details."),
        ("131", "Claim specific negotiated discount", "Contracted discount — informational."),
        ("132", "Prearranged demonstration project adjustment", "Demo project — informational."),
        ("133", "The disposition of the claim/service is pending further review", "Pending — follow up with payer after 30 days."),
        ("134", "Technical fees removed from charges", "Technical component removed — verify correct billing split."),
        ("135", "Interim bills cannot be processed", "Facility billing — submit final bill only."),
        ("136", "Failure to follow prior payer's coverage determination", "COB error — follow primary payer adjudication."),
        ("137", "Regulatory Surcharges, Assessments, Allowances or Health Related Taxes", "Regulatory adjustment — informational."),
        ("138", "Appeal procedures not followed or time limits not met", "Appeal process error — review payer appeal requirements."),
        ("139", "Contracted funding agreement — Subscriber is employed by the provider of services", "Self-insured employee plan — special rules apply."),
        ("140", "Patient/Insured health identification number and name do not match", "Demographics mismatch — verify member ID and name spelling."),
        ("141", "Claim spans eligible and ineligible periods of coverage", "Eligibility overlap — split claim by coverage period."),
        ("142", "Monthly Medicaid patient liability amount", "Medicaid spend-down — patient owes monthly liability."),
        ("143", "Portion of payment deferred", "Partial payment — remainder pending."),
        ("144", "Incentive adjustment, e.g. preferred product/service", "Incentive — informational."),
        ("146", "Diagnosis was invalid for the date(s) of service reported", "ICD-10 invalid for DOS — check fiscal year applicability (Oct 1 each year)."),
        ("147", "Provider contracted/negotiated rate expired or not on file", "Contract issue — verify provider contract is current with payer."),
        ("148", "Information from another provider was not provided or was insufficient/incomplete", "Missing consult/referral records — obtain and submit."),
        ("149", "Lifetime benefit maximum has been reached for this service/benefit category", "Category-specific limit exhausted."),
        ("150", "Payer deems the information submitted does not support this level of service", "Level-of-service denial — appeal with full documentation supporting code level."),
        ("151", "Payment adjusted because the payer deems the information submitted does not support this many/frequency of services", "Frequency denial — appeal with clinical necessity for frequency billed."),
        ("152", "Payer deems the information submitted does not support this length of service", "Duration denial — appeal with clinical documentation."),
        ("153", "Payer deems the information submitted does not support this dosage", "Dosage denial — appeal with clinical documentation."),
        ("154", "Payer deems the information submitted does not support this day's supply", "Days supply — appeal with clinical documentation."),
        ("155", "Patient refused the service/procedure", "Patient refusal — document in chart."),
        ("157", "Service/procedure was provided as a result of an act of war", "War-related — special billing rules."),
        ("158", "Service/procedure was provided outside of the United States", "Foreign service — verify plan coverage for international care."),
        ("159", "Service/procedure was provided as a result of terrorism", "Terrorism-related — special billing rules."),
        ("160", "Injury/illness was the result of an activity that is a benefit exclusion", "Exclusion — review plan terms."),
        ("161", "Provider performance bonus", "Bonus payment — informational."),
        ("163", "Attachment/other documentation referenced on the claim was not received", "Missing attachment — resubmit with required documentation."),
        ("164", "Attachment/other documentation referenced on the claim was not received in a timely fashion", "Late attachment — resubmit with documentation."),
        ("165", "Referral absent or exceeded", "Referral issue — obtain valid referral or appeal."),
        ("166", "These services were submitted after this plan's responsibility for Medicare crossover services ended", "Crossover timing — informational."),
        ("167", "This (these) diagnosis(es) is (are) not covered", "Diagnosis not covered — review plan exclusions."),
        ("168", "Service(s) have been considered under the patient's medical or dental benefits", "Dual benefit — coordinated under separate benefit."),
        ("169", "Claim/service denied. Performed by a provider who is not identified as a treating provider for this patient", "Treating provider mismatch — verify provider relationship."),
        ("170", "Payment is denied when performed/billed by this type of provider in this type of facility", "Provider/facility type restriction — verify billing rules for this combination."),
        ("171", "Payment is denied for out-of-network providers", "Out-of-network — patient may owe full charges. Verify network status."),
        ("172", "Claim/service denied. Provider was not eligible to perform the service billed", "Provider eligibility — verify licensure and enrollment."),
        ("173", "No authorization obtained for emergent admission to an out-of-network hospital", "Emergency out-of-network — appeal with emergency documentation."),
        ("174", "Service was not prescribed by a physician", "Physician order required — obtain and resubmit."),
        ("175", "Potential fraud, abuse, or misrepresentation — claim investigation", "Investigation — cooperate with payer review."),
        ("176", "Services not related to the primary diagnosis", "Diagnosis linkage — verify ICD-10 codes support all services billed."),
        ("177", "Patient has not met the required eligibility requirements", "Eligibility — verify enrollment and coverage criteria."),
        ("178", "Patient has not met the required spend-down requirements", "Medicaid spend-down — patient must meet liability first."),
        ("179", "Patient has not met the required waiting requirements", "Waiting period — coverage not yet effective."),
        ("180", "Patient has not met the required residency requirements", "Residency requirement — verify plan eligibility rules."),
        ("181", "Procedure code was incorrect. This payment reflects the correct code", "Payer downcoded — appeal with documentation supporting original code level."),
        ("182", "Procedure modifier was incorrect. This payment reflects the correct modifier(s)", "Modifier correction by payer — review and appeal if incorrect."),
        ("183", "The referring provider is not eligible to refer the service billed", "Referral provider issue — verify referring provider enrollment."),
        ("184", "The prescribing/ordering provider is not eligible to prescribe/order the service billed", "Ordering provider issue — verify ordering provider enrollment and prescribing authority."),
        ("185", "Claim/service denied because a non-covered service is bundled with a covered service", "Bundling — separate covered and non-covered services on claim."),
        ("186", "Level of care change adjustment", "Level of care — informational."),
        ("187", "Consumer Spending Account payments (includes but is not limited to: FSA, HRA, HSA, HRA, MSA, HIA)", "Consumer account payment — patient may have FSA/HSA funds."),
        ("188", "This product/procedure is only covered when used according to FDA recommendations", "FDA usage — verify on-label use or appeal with literature."),
        ("189", "Not a work-related injury/illness, thus not the liability of the workers' compensation carrier", "Not WC — bill primary health insurance."),
        ("190", "Payment is included in the allowance for a Skilled Nursing Facility (SNF) stay", "SNF consolidated billing — separately billed service is included in SNF per diem."),
        ("192", "Non standard adjustment code from paper remittance", "Paper remit legacy code — contact payer for details."),
        ("193", "Original payment decision is being maintained. Upon review, it was determined that this claim was processed correctly", "Appeal upheld — consider further levels of appeal or write off."),
        ("194", "Anesthesia performed by the operating physician, the assistant surgeon or the attending physician", "Anesthesia billing rule — separate anesthesia claim not allowed."),
        ("195", "Refund issued to an erroneous priority payer for this claim/service", "Refund — informational."),
        ("197", "Precertification/authorization/notification absent", "Prior auth missing — obtain auth and rebill or appeal if emergent."),
        ("198", "Precertification/authorization exceeded", "Auth exceeded — obtain additional auth or appeal."),
        ("199", "Revenue code and Procedure code do not match", "Facility billing — revenue code must match procedure code."),
        ("200", "Expenses incurred during lapse in coverage", "Coverage lapse — verify continuous eligibility."),
        ("201", "Workers' Compensation case settled. Patient is responsible for amount billed", "WC settlement — bill patient or write off."),
        ("202", "Non-covered personal comfort or convenience services", "Non-covered — write off. Do not bill patient for comfort items if prohibited."),
        ("203", "Discontinued or reduced service", "Service reduction — informational."),
        ("204", "This service/equipment/drug is not covered under the patient's current benefit plan", "Non-covered — verify plan benefits. May bill patient with ABN if Medicare."),
        ("205", "Pharmacy discount card processing fee", "Discount card fee — informational."),
        ("206", "National Drug Codes (NDC) not eligible for rebate; not covered", "NDC not covered — verify formulary."),
        ("207", "Health care benefit manager has advised the claimant regarding coordination of benefits and that a secondary refund is owed", "COB refund request — coordinate with other payer."),
    ]

    cur.executemany(
        "INSERT OR IGNORE INTO carc_codes (code, description, notes) VALUES (?, ?, ?)",
        carc_data
    )
    print(f"Seeded {len(carc_data)} CARC codes")


def _seed_rarc_codes(cur):
    cur.execute("SELECT COUNT(*) FROM rarc_codes")
    if cur.fetchone()[0] > 0:
        return

    rarc_data = [
        ("M1",  "X-ray not taken within the past 12 months or near enough to the time of treatment", "Documentation — submit x-ray report within timeframe"),
        ("M2",  "Not paid separately when the patient is an inpatient", "Inpatient bundling — service included in DRG"),
        ("M10", "Equipment is the same or similar to equipment already being used", "DME duplicate — document medical necessity for additional equipment"),
        ("M11", "DME, orthotics and prosthetics must be billed to the DME carrier who services the patient's zip code", "Wrong DME carrier — resubmit to correct DME MAC"),
        ("M12", "Diagnostic tests performed by a physician must indicate the name of the referring physician", "Missing referring physician — add referring NPI"),
        ("M13", "Only one initial visit is covered per specialty per medical group", "Frequency limit — only one initial visit allowed"),
        ("M14", "No payment for an office visit that is not medically necessary", "Medical necessity — appeal with documentation"),
        ("M15", "Separately billed services/tests have been bundled as they are considered components of the same procedure, and therefore considered one unit", "Bundling — NCCI edit likely applies"),
        ("M16", "Please see our general exclusion list", "Non-covered — check plan exclusion list"),
        ("M17", "Patient is covered by a managed care plan", "MCO — bill the managed care plan instead"),
        ("M18", "Await the outcome of the patient's appeal before resubmitting", "Pending appeal — do not rebill until appeal resolved"),
        ("M19", "Missing/incomplete/invalid patient identifier", "Demographics — correct patient ID and resubmit"),
        ("M20", "Missing/incomplete/invalid amount billed", "Billing error — correct billed amount"),
        ("M36", "This is a medigap claim", "Medigap crossover — informational"),
        ("M44", "Missing/incomplete/invalid condition code", "UB condition code missing — add correct condition code"),
        ("M47", "Missing/incomplete/invalid claim number of the original claim", "Original claim number needed — add on corrected claim"),
        ("M49", "Missing/incomplete/invalid rendering provider", "Missing rendering NPI — add rendering provider info"),
        ("M51", "Missing/incomplete/invalid procedure code(s)", "Procedure code error — correct and resubmit"),
        ("M52", "Missing/incomplete/invalid date(s) of service", "Date error — correct service dates"),
        ("M53", "Missing/incomplete/invalid days or units of service", "Units missing — add correct units"),
        ("M54", "Missing/incomplete/invalid total charges", "Charge error — correct total charges"),
        ("M55", "Missing/incomplete/invalid place of service", "POS missing — add correct POS code"),
        ("M56", "Missing/incomplete/invalid national provider identifier", "NPI missing — add billing/rendering NPI"),
        ("M57", "Missing/incomplete/invalid subscriber information", "Subscriber info — correct member demographics"),
        ("M58", "Missing/incomplete/invalid referring provider", "Referring provider missing — add referring NPI"),
        ("M59", "Missing/incomplete/invalid diagnosis code(s)", "ICD-10 missing — add correct diagnosis codes"),
        ("M60", "Missing Certificate of Medical Necessity", "CMN required — obtain and resubmit"),
        ("M61", "Missing/incomplete/invalid treatment authorization code", "Auth code missing — obtain auth and resubmit"),
        ("M62", "Missing/incomplete/invalid original claim number", "Corrected claim — add original claim number"),
        ("M76", "Missing/incomplete/invalid diagnosis or condition", "Diagnosis needed — add supporting ICD-10 code"),
        ("M77", "Missing/incomplete/invalid place of service", "POS error — verify and correct"),
        ("M79", "Missing/incomplete/invalid charge", "Charge line error — correct charge amount"),
        ("M80", "Not covered when performed during the same session/date as a previously processed service for the patient", "Same-day bundling — separate dates or use appropriate modifier"),
        ("M81", "You have indicated that this is the initial treatment for this condition. This service is not covered for the first visit", "First visit exclusion — verify plan benefits"),
        ("M86", "Service denied because payment already made for same/similar procedure within set time frame", "Frequency denial — document clinical necessity for repeat service"),
        ("M89", "Not covered when performed on the same day as another procedure", "Same-day restriction — use modifier 59/XU if appropriate"),
        ("MA01", "If you do not agree with what we approved for these services, you may appeal our decision", "Appeal rights notice — Medicare standard language"),
        ("MA02", "If you do not agree with this determination, you may appeal this decision", "Appeal rights notice — Medicare standard language"),
        ("MA04", "Secondary payment cannot be considered without the identity of or payment information from the primary payer", "COB — include primary EOB with secondary claim"),
        ("MA07", "The claim information has also been forwarded to Medicaid for review", "Crossover forwarded — informational"),
        ("MA08", "Claim information forwarded as required by regulation", "Forwarded — informational"),
        ("MA09", "Claim submitted as unassigned but NPI indicates provider is participating", "Assignment issue — verify provider's participation status"),
        ("MA10", "Your claims should be submitted to the proper Medicare Administrative Contractor (MAC)", "Wrong MAC — resubmit to correct Medicare contractor for this jurisdiction"),
        ("MA12", "You have not established that you have the right to appeal on behalf of the patient", "Appeal authorization — include patient authorization to appeal"),
        ("MA13", "Only one initial visit is covered per specialty per medical group", "Initial visit limit — informational"),
        ("MA14", "Coinsurance and deductible were applied to the allowable amount of the higher priced procedure", "Higher priced procedure rule applied — informational"),
        ("MA15", "Payment has been adjusted because a member of a group practice referred and/or ordered this service", "Group practice referral rule — informational"),
        ("MA16", "The patient is a Medicare Advantage enrollee; however, a separate remittance will be issued by the applicable Medicare Advantage plan", "Medicare Advantage — bill MA plan directly"),
        ("MA17", "We are the primary payer, but this patient also has a secondary plan", "Secondary payer exists — submit to secondary after Medicare"),
        ("MA18", "The claim information is also being forwarded to the patient's supplemental insurer", "Supplemental forwarded — informational"),
        ("MA19", "Provider level adjustments have been made", "Provider adjustment — informational"),
        ("MA20", "Informational remittance associated with a Medicare demonstration", "Demo project — informational"),
        ("MA25", "The information provided does not support the need for this item or service as furnished", "Medical necessity — appeal with clinical documentation"),
        ("MA27", "Missing/incomplete/invalid entitlement number or name shown on the claim", "Medicare ID error — correct patient Medicare number"),
        ("MA28", "Receipt of a claim/letter has been acknowledged. A formal response will follow", "Acknowledged — await payer response"),
        ("MA30", "Missing/incomplete/invalid type of bill", "UB type of bill — correct TOB and resubmit"),
        ("MA36", "Missing/incomplete/invalid patient name", "Patient name error — correct and resubmit"),
        ("MA37", "Missing/incomplete/invalid date of birth", "DOB error — correct and resubmit"),
        ("MA40", "Claim submitted to the wrong Medicare contractor", "Wrong MAC — see MA10"),
        ("MA41", "Receiving provider information (name, address, NPI) is not consistent with claim information", "Receiving provider mismatch — verify facility NPI"),
        ("MA42", "Unable to process. A corrected/replacement or voided claim has already been received", "Duplicate corrected claim — verify claim status before resubmitting"),
        ("MA43", "Missing/incomplete/invalid Condition Code 20 — the number of patients in the sample for ESRD claims", "ESRD claim — add condition code 20"),
        ("MA44", "Missing/incomplete/invalid condition code", "Condition code — add required condition code for claim type"),
        ("MA46", "The new information has been considered; however, our original determination is confirmed", "Appeal denial upheld — consider QIC or ALJ appeal"),
        ("MA47", "Our records show the patient was in a skilled nursing facility (SNF) or Medicare covered nursing home stay at the time these services were rendered", "SNF consolidated billing — cannot bill separately during SNF stay"),
        ("MA50", "Missing/incomplete/invalid Investigational Device Exemption number or Clinical Trial Registry number", "IDE/CTN number required — add for investigational device claims"),
        ("MA53", "Missing/incomplete/invalid occurrence code(s)", "UB occurrence code missing — add required occurrence code"),
        ("MA55", "Not covered as a railroad retirement beneficiary", "Railroad retirement — bill Railroad Retirement Board"),
        ("MA57", "Patient must use the mail order provider indicated in their plan enrollment", "Mail order required — redirect to plan's mail order pharmacy"),
        ("MA59", "Additional Payment/Reduction Request was processed as a Change of Bill type", "TOB change — informational"),
        ("MA60", "Missing/incomplete/invalid patient relationship to insured", "Relationship code — add correct patient relationship to subscriber"),
        ("MA61", "Missing/incomplete/invalid social security number or health identification claim number", "SSN/HICN error — correct identifier"),
        ("MA62", "Alert: This claim may be for a patient who is potentially eligible for Medicaid", "Medicaid eligibility — verify and bill Medicaid if appropriate"),
        ("MA63", "Missing/incomplete/invalid principal diagnosis", "Principal diagnosis — add/correct principal ICD-10"),
        ("MA64", "Our records indicate that the patient is enrolled in a Medicare Advantage Plan", "MA plan — bill MA plan, not Medicare fee-for-service"),
        ("MA65", "Missing/incomplete/invalid admitting diagnosis", "Admitting diagnosis — add admitting ICD-10 for inpatient"),
        ("MA67", "Missing/incomplete/invalid operating physician information", "Surgeon NPI — add operating physician NPI for surgical claim"),
        ("MA68", "Missing/incomplete/invalid referring/ordering provider", "Referring provider — add referring/ordering NPI"),
        ("MA69", "Missing/incomplete/invalid treatment authorization codes", "Auth code — see MA61"),
        ("MA71", "Missing/incomplete/invalid diagnosis related group", "DRG missing — add assigned DRG for inpatient claim"),
        ("MA73", "Informational, applies to New Technology APC payments only", "New Technology APC — informational"),
        ("MA75", "Missing/incomplete/invalid plan information for other insurance", "COB info — add other insurance plan details"),
        ("MA76", "Missing/incomplete/invalid diagnosis or condition", "Diagnosis — add required diagnosis codes"),
        ("MA79", "Billed in excess of interim rate", "Interim billing limit — adjust charge"),
        ("MA80", "Not covered when the beneficiary performs the service", "Self-administered exclusion — informational"),
        ("MA81", "Missing/incomplete/invalid admit date", "Admission date — add hospital admission date"),
        ("MA83", "Did not indicate whether Medicare is primary or secondary payer", "MSP indicator missing — add Medicare secondary payer information"),
        ("MA84", "Patient identified as participating in the Kidney Disease Education program, but transaction does not contain a valid code", "KDE code error — add correct KDE code"),
        ("MA88", "Missing/incomplete/invalid insured's address and/or Community Plan ID", "Address missing — add subscriber address"),
        ("MA89", "Not covered when the patient refuses to use the provider designated by the plan", "Provider choice — plan-directed care requirement"),
        ("MA90", "Missing/incomplete/invalid employee identification number or state agency number", "Employer/state ID — add required identifier"),
        ("MA91", "Alert: This request has been tested successfully", "Test transaction — informational"),
        ("MA93", "Non-PIP (Personal Injury Protection) claim", "Auto insurance — bill PIP if applicable"),
        ("MA94", "Did not enter the narrative description of the unspecified code", "Narrative required — add description for unlisted/unspecified code"),
        ("MA96", "Claim rejected. Coded as a Medicare Managed Care Demonstration but patient is not enrolled in a Medicare managed care plan", "MCO mismatch — bill correct payer"),
        ("MA97", "Missing/incomplete/invalid Medicare Managed Care Demonstration contract number", "MCO contract — add contract number"),
        ("MA99", "Missing/incomplete/invalid Ambulance drop-off address", "Ambulance — add destination address"),
        ("N1",  "Alert: You may appeal this decision", "Appeal rights — standard notice"),
        ("N2",  "Invalid combination of UPIN and provider name", "UPIN error — use NPI instead of UPIN"),
        ("N3",  "Missing/incomplete/invalid prior authorization number", "Auth number — obtain auth and add to claim"),
        ("N4",  "Alert: The meal was not provided by a Medicare-certified provider", "Meal services — provider must be Medicare-certified"),
        ("N5",  "Incomplete/invalid tax ID number (EIN)", "Tax ID error — correct EIN on claim"),
        ("N6",  "Alert: This payment reflects the correct code for the service(s) provided", "Downcoded — payer corrected code; appeal if original code was correct"),
        ("N7",  "Alert: Processing of this claim/service has been delayed", "Delay notice — follow up after 30 days"),
        ("N10", "Payment based on the information provided at the time the service/item was ordered/authorized", "Auth-based payment — informational"),
        ("N11", "Denial reversed per Medical Review", "Denial overturned — informational"),
        ("N15", "Services for a newborn must be billed separately", "Newborn billing — bill newborn separately with own demographics"),
        ("N19", "Procedure code incidental to primary procedure", "Incidental procedure — included in primary procedure payment"),
        ("N20", "Service not payable to the referring/ordering provider", "Referring provider cannot bill this service — verify billing rules"),
        ("N22", "Alert: This procedure is not payable unless non-elective medical circumstances require that it be performed in the inpatient setting", "Inpatient only — IPO procedure; must be inpatient"),
        ("N25", "This company has been contracted by your benefit plan to provide benefits and process your claims", "Plan contractor — informational"),
        ("N26", "Missing itemized bill/statement", "Itemized bill required — attach and resubmit"),
        ("N27", "Missing/incomplete/invalid treatment number", "Treatment number — add serial treatment number"),
        ("N28", "Consent form for nonemergency treatment required", "Consent form — obtain and submit"),
        ("N29", "Missing documentation/orders/notes/summary/report/chart", "Clinical records required — attach and resubmit"),
        ("N30", "Missing/incomplete/invalid invoice or statement", "Invoice missing — attach and resubmit"),
        ("N31", "Missing/incomplete/invalid prescription", "Prescription required — obtain and submit"),
        ("N32", "Missing/incomplete/invalid purchase/rental agreement", "DME purchase agreement — attach and resubmit"),
        ("N33", "Missing/incomplete/invalid referral number", "Referral number — obtain referral and add number"),
        ("N34", "Missing/incomplete/invalid demonstration log", "Demo log — attach and resubmit"),
        ("N35", "Missing/incomplete/invalid laboratory report", "Lab report — attach and resubmit"),
        ("N36", "Missing/incomplete/invalid x-ray or other imaging documentation", "Imaging report — attach and resubmit"),
        ("N37", "Missing/incomplete/invalid pathology report", "Path report — attach and resubmit"),
        ("N38", "Missing/incomplete/invalid treatment plan", "Treatment plan — attach and resubmit"),
        ("N39", "Missing/incomplete/invalid patient medical record for this service", "Medical records — attach and resubmit"),
        ("N40", "Missing/incomplete/invalid radiology film(s)", "Radiology films — submit with claim"),
        ("N43", "Missing/incomplete/invalid accident information", "Accident info — add accident details for injury claim"),
        ("N45", "Payment based on authorized amount", "Auth-limited payment — informational"),
        ("N47", "Claim submitted in error; this is a not-for-profit plan", "Wrong payer type — verify and resubmit"),
        ("N49", "Court ordered coverage information needs to be verified", "Court order — contact plan for verification"),
        ("N50", "Missing/incomplete/invalid discharge information", "Discharge info — add discharge status code"),
        ("N56", "Procedure code billed is not correct/valid for the services billed or the date of service billed", "Invalid code for DOS — check code effective dates"),
        ("N57", "Missing/incomplete/invalid referring provider primary identifier", "Referring NPI — add correct referring provider NPI"),
        ("N58", "Missing/incomplete/invalid charge for administrative cost", "Admin fee — add charge amount"),
        ("N59", "Please refer to your provider manual for specific information about this service", "See provider manual — contact payer for details"),
        ("N61", "Consult plan benefit documents/guidelines for information about restrictions for this service", "Benefits restriction — review plan documents"),
        ("N62", "Dates of service span multiple rate periods. Resubmit separate claims", "Rate period change — split claim by rate period dates"),
        ("N63", "Rebill services on separate claims", "Split required — rebill on separate claim"),
        ("N65", "Procedure code or procedure rate count cannot be determined, or was not on file, for the date(s) of service/provider/supplier/patient type combination billed", "Reimbursement data missing — verify code is on fee schedule for DOS"),
        ("N67", "Professional provider services not covered when the technical component of a global service is billed by the facility", "TC/26 split — verify correct component billing"),
        ("N68", "Prior payment being cancelled as adjustments were made to a prior claim", "Prior payment cancelled — informational"),
        ("N69", "PPS (Prospective Payment System) code changed by claims processing system", "PPS recode — informational"),
        ("N70", "Consolidated billing and payment applies", "Consolidated billing — service included in consolidated payment"),
        ("N71", "Your unassigned claim for a drug or biological, clinical diagnostic laboratory services or ambulance service was processed as an assigned claim", "Assignment applied — informational"),
        ("N72", "PPS (Prospective Payment System) claim contains charge in excess of limit", "PPS charge limit — correct charge"),
        ("N74", "Resubmit with multiple claims, each claim covering services provided in only one calendar month", "Monthly split — submit separate claim per calendar month"),
        ("N75", "Missing/incomplete/invalid tooth number/letter", "Dental — add tooth identifier"),
        ("N76", "Missing/incomplete/invalid number of riders", "Rider count — add required information"),
        ("N77", "Missing/incomplete/invalid designated facility primary identifier", "Facility NPI — add facility NPI"),
        ("N78", "The non-covered days/room and board charges are at a higher level than covered days/room and board charges", "Room rate error — correct room and board charges"),
        ("N79", "Service billed is not compatible with patient location information", "Location mismatch — verify POS and patient location"),
        ("N80", "Missing/incomplete/invalid prenatal screening information", "Prenatal info — add required screening data"),
        ("N82", "Provider must accept insurance payment as payment in full when a supplemental plan pays benefits", "Assignment required — accept insurance payment as full payment"),
        ("N83", "No appeal right. Adjudicator made no discretionary decision to deny, reduce, or terminate", "No appeal right — informational"),
        ("N84", "Alert: Further installation payments cannot be made until you provide the information requested", "Missing info for installment — provide requested documentation"),
        ("N85", "Alert: Services spans multiple rate/fee schedule periods and was split accordingly", "Rate period split — informational"),
        ("N87", "Currently in a Global Surgery Period", "Global period — service included in global surgical package"),
        ("N88", "Your claim was registered on the following date(s)", "Registration date — informational"),
        ("N89", "Alert: This claim is being processed under a special payment arrangement", "Special payment arrangement — informational"),
        ("N90", "Comprehensive Error Rate Testing (CERT) Additional Documentation Request", "CERT audit — submit requested documentation"),
        ("N91", "Services not covered when the patient is in a Medicare-covered skilled nursing facility (SNF) stay", "SNF consolidated billing — same as MA47"),
        ("N92", "This facility is not certified for the service billed", "Facility certification — verify facility is certified for this service type"),
        ("N93", "A separate claim must be submitted for each place of service. Only one place of service is allowed per claim", "POS per claim — split by place of service"),
        ("N94", "Claim/service denied because a more specific diagnosis code is required", "ICD-10 specificity — recode with more specific ICD-10 code"),
        ("N95", "This provider type/provider specialty may not bill this service", "Provider type restriction — see CARC 8"),
        ("N96", "Patient must be reimbursed for charges", "Patient reimbursement required — forward payment to patient"),
        ("N97", "The administration of the contrast agent is not separately payable", "Contrast bundled — included in imaging code"),
        ("N98", "A separate claim must be submitted for each date of service", "DOS split — submit one claim per date of service"),
        ("N99", "Missing/incomplete/invalid Universal Product Number/Serial Number", "UPN required — add device identifier"),
        ("N100", "Missing/incomplete/invalid Bill Type", "TOB error — add/correct type of bill"),
        ("N101", "Bill Type not appropriate for services billed", "TOB mismatch — correct type of bill"),
        ("N102", "Missing/incomplete/invalid Patient Reason for Visit", "Reason for visit — add for ER claim"),
        ("N103", "Records indicate this patient was a prisoner or in custody of a Federal, State, or local authority when the service was rendered", "Prisoner — verify payer liability"),
        ("N104", "The service is not covered when the onset/first treatment date is not within the plan year", "Onset date issue — verify and correct onset date"),
        ("N105", "This is a medigap plan that is not qualified for direct billing", "Non-qualifying Medigap — informational"),
    ]

    cur.executemany(
        "INSERT OR IGNORE INTO rarc_codes (code, description, notes) VALUES (?, ?, ?)",
        rarc_data
    )
    print(f"Seeded {len(rarc_data)} RARC codes")


# ---------------------------------------------------------------------------
# POS codes (embedded static)
# ---------------------------------------------------------------------------
POS_CODES = {
    "01": ("Pharmacy", "A facility or location where drugs and other medically related items and services are sold, dispensed, or otherwise provided directly to patients."),
    "02": ("Telehealth Provided Other than in Patient's Home", "The location where health services and health related services are provided or received through a telecommunication system."),
    "03": ("School", "A facility whose primary purpose is education."),
    "04": ("Homeless Shelter", "A facility or location whose primary purpose is to provide temporary housing to homeless individuals."),
    "05": ("Indian Health Service Free-standing Facility", "IHS facility."),
    "06": ("Indian Health Service Provider-based Facility", "IHS provider-based facility."),
    "07": ("Tribal 638 Free-Standing Facility", "Tribal 638 facility."),
    "08": ("Tribal 638 Provider-Based Facility", "Tribal 638 provider-based facility."),
    "09": ("Prison/Correctional Facility", "A prison, jail, reformatory, work farm, detention center, or any other similar facility maintained by either Federal, State or local authorities."),
    "10": ("Telehealth Provided in Patient's Home", "Telehealth in patient's home. Note: Required for many Medicare telehealth services post-2020."),
    "11": ("Office", "Location other than a hospital, SNF, military treatment facility, community health center, State or local public health clinic, or intermediate care facility, where the health professional routinely provides health examinations, diagnosis, and treatment of illness or injury."),
    "12": ("Home", "Location, other than a hospital or other facility, where the patient receives care in a private residence."),
    "13": ("Assisted Living Facility", "Congregate residential facility with self-contained living units providing assessment of each resident's needs and on-site support 24 hours a day."),
    "14": ("Group Home", "A residence, with shared living areas, where clients receive supervision and other services."),
    "15": ("Mobile Unit", "A facility/unit that moves from place-to-place equipped to provide preventive, screening, diagnostic, and/or treatment services."),
    "16": ("Temporary Lodging", "A short term accommodation such as a hotel, camp ground, hostel, cruise ship or resort where the patient receives care."),
    "17": ("Walk-in Retail Health Clinic", "A walk-in health clinic, other than an office, urgent care facility, pharmacy, or independent clinic and not described by any other POS code."),
    "18": ("Place of Employment-Worksite", "A location, not described by any other POS code, owned or operated by a public or private entity where the patient is employed."),
    "19": ("Off Campus-Outpatient Hospital", "A portion of an off-campus hospital provider-based department."),
    "20": ("Urgent Care Facility", "Location, distinct from a hospital emergency room, an office, or a clinic, whose purpose is to diagnose and treat illness or injury for unscheduled, ambulatory patients seeking immediate medical attention."),
    "21": ("Inpatient Hospital", "A facility, other than psychiatric, which primarily provides diagnostic, therapeutic, and rehabilitation services by, or under, the supervision of physicians."),
    "22": ("On Campus-Outpatient Hospital", "A portion of a hospital's main campus which provides diagnostic, therapeutic, and rehabilitation services to sick or injured persons."),
    "23": ("Emergency Room – Hospital", "A portion of a hospital where emergency diagnosis and treatment of illness or injury is provided."),
    "24": ("Ambulatory Surgical Center", "A freestanding facility, other than a physician's office, where surgical and diagnostic services are provided on an ambulatory basis."),
    "25": ("Birthing Center", "A facility, other than a hospital's maternity facilities or a physician's office, which provides a setting for labor, delivery, and immediate postpartum care."),
    "26": ("Military Treatment Facility", "A medical facility operated by one or more of the Uniformed Services. MTF also refers to certain former U.S. Public Health Service (USPHS) facilities now designated as Federally Qualified Health Centers (FQHC)."),
    "31": ("Skilled Nursing Facility", "A facility which primarily provides inpatient skilled nursing care and related services to patients who require medical, nursing, or rehabilitative services."),
    "32": ("Nursing Facility", "A facility which primarily provides to residents skilled nursing care and related services for the rehabilitation of injured, disabled, or sick persons."),
    "33": ("Custodial Care Facility", "A facility which provides room, board and other personal assistance services, generally on a long-term basis."),
    "34": ("Hospice", "A facility, other than a patient's home, in which palliative and supportive care for terminally ill patients and their families are provided."),
    "41": ("Ambulance – Land", "A land vehicle specifically designed, equipped and staffed for lifesaving and transporting the sick or injured."),
    "42": ("Ambulance – Air or Water", "An air or water vehicle specifically designed, equipped and staffed for lifesaving and transporting the sick or injured."),
    "49": ("Independent Clinic", "A location, not part of a hospital and not described by any other POS code, that is organized and operated to provide preventive, diagnostic, therapeutic, rehabilitative, or palliative services to outpatients only."),
    "50": ("Federally Qualified Health Center", "A facility located in a medically underserved area that provides Medicare beneficiaries preventive primary medical care under the general direction of a physician."),
    "51": ("Inpatient Psychiatric Facility", "A facility that provides inpatient psychiatric services for the diagnosis and treatment of mental illness on a 24-hour basis."),
    "52": ("Psychiatric Facility Partial Hospitalization", "A facility for the diagnosis and treatment of mental illness that provides a planned therapeutic program for patients who do not require full time hospitalization."),
    "53": ("Community Mental Health Center", "A facility that provides the following services: outpatient services, 24-hour a day emergency care services, day treatment."),
    "54": ("Intermediate Care Facility/Individuals with Intellectual Disabilities", "A facility which primarily provides health-related care and services above the level of custodial care to intellectually disabled individuals."),
    "55": ("Residential Substance Abuse Treatment Facility", "A facility which provides treatment for substance (alcohol and drug) abuse to live-in residents who do not require acute medical care."),
    "56": ("Psychiatric Residential Treatment Center", "A facility or distinct part of a facility for psychiatric care which provides a total 24-hour therapeutically planned and professionally staffed group living and learning environment."),
    "57": ("Non-residential Substance Abuse Treatment Facility", "A location which provides treatment for substance (alcohol and drug) abuse on an ambulatory basis."),
    "58": ("Non-residential Opioid Treatment Facility", "A location that provides treatment for opioid use disorder on an ambulatory basis."),
    "60": ("Mass Immunization Center", "A location where providers administer pneumococcal pneumonia and influenza virus vaccinations and submit these services as electronic media claims."),
    "61": ("Comprehensive Inpatient Rehabilitation Facility", "A facility that provides comprehensive rehabilitation services under the supervision of a physician."),
    "62": ("Comprehensive Outpatient Rehabilitation Facility", "A facility that provides comprehensive rehabilitation services under the supervision of a physician to outpatients."),
    "65": ("End-Stage Renal Disease Treatment Facility", "A facility other than a hospital, which provides dialysis treatment, maintenance, and/or training to patients or caregivers on an ambulatory or home-care basis."),
    "71": ("Public Health Clinic", "A facility maintained by either State or local health departments that provides ambulatory primary medical care."),
    "72": ("Rural Health Clinic", "A certified facility which is located in a rural medically underserved area that provides ambulatory primary medical care under the general direction of a physician."),
    "81": ("Independent Laboratory", "A laboratory certified to perform diagnostic and/or clinical tests independent of an institution or a physician's office."),
    "99": ("Other Place of Service", "Other place of service not identified above."),
}

# ---------------------------------------------------------------------------
# MAC jurisdiction map: state → MAC code
# ---------------------------------------------------------------------------
MAC_JURISDICTION = {
    "CT": "JK", "ME": "JK", "MA": "JK", "NH": "JK", "NY": "JK", "RI": "JK", "VT": "JK",
    "DC": "JL", "DE": "JL", "MD": "JL", "NJ": "JL", "PA": "JL",
    "VA": "JM", "WV": "JM",
    "NC": "JM", "SC": "JM",
    "CO": "J5", "TX": "J5", "OK": "J5", "NM": "J5",
    "AK": "J2", "AZ": "J2", "ID": "J2", "MT": "J2", "ND": "J2", "OR": "J2", "SD": "J2", "UT": "J2", "WA": "J2", "WY": "J2",
    "CA": "JE",
    "HI": "JE", "NV": "JE",
    "AL": "JH", "GA": "JH", "TN": "JH",
    "FL": "JN",
    "IL": "J6", "MN": "J6", "WI": "J6",
    "KS": "J6", "NE": "J6", "IA": "J6", "MO": "J6",
    "IN": "J8", "MI": "J8", "OH": "J8", "KY": "J8",
    "AR": "J7", "LA": "J7", "MS": "J7",
}

# ---------------------------------------------------------------------------
# Timely filing limits (days from DOS)
# ---------------------------------------------------------------------------
TIMELY_FILING = {
    "medicare": {"initial": 365, "corrected": 365, "appeal": 120, "note": "12 months from DOS (CMS IOM Pub 100-04, Ch 1, §70)"},
    "medicaid": {
        "AL": 365, "AK": 365, "AZ": 365, "AR": 365, "CA": 365,
        "CO": 365, "CT": 365, "DE": 365, "FL": 365, "GA": 365,
        "HI": 365, "ID": 365, "IL": 180, "IN": 365, "IA": 365,
        "KS": 365, "KY": 365, "LA": 365, "ME": 365, "MD": 365,
        "MA": 365, "MI": 365, "MN": 365, "MS": 365, "MO": 365,
        "MT": 365, "NE": 365, "NV": 365, "NH": 365, "NJ": 365,
        "NM": 365, "NY": 90,  "NC": 365, "ND": 365, "OH": 365,
        "OK": 365, "OR": 365, "PA": 180, "RI": 365, "SC": 365,
        "SD": 365, "TN": 365, "TX": 95,  "UT": 365, "VT": 365,
        "VA": 365, "WA": 365, "WV": 365, "WI": 365, "WY": 365,
        "DC": 365,
        "_default": 365,
        "_note": "State-specific limits — always verify with state Medicaid portal",
    },
    "commercial": {
        "UHC": 90, "UNITEDHEALTHCARE": 90,
        "BCBS": 180, "BLUECROSS": 180, "BLUESHIELD": 180,
        "AETNA": 180,
        "CIGNA": 180,
        "HUMANA": 180,
        "ANTHEM": 180,
        "CENTENE": 180,
        "MOLINA": 180,
        "WELLCARE": 180,
        "KAISER": 180,
        "MAGELLAN": 180,
        "TRICARE": 365,
        "CHAMPVA": 365,
        "RAILROAD": 365,
        "_default": 180,
        "_note": "Commercial limits are contractual — always verify with provider manual. Corrected claims typically 90 days from original EOB.",
    },
}

# ---------------------------------------------------------------------------
# NCCI edit curated subset — top denied CPT pairs
# (modifier indicator: 0=never, 1=allowed with modifier, 9=not applicable)
# ---------------------------------------------------------------------------
NCCI_EDITS = {
    # E&M with procedures same day — modifier 25 required
    ("99213", "93000"): {"indicator": 1, "note": "Use modifier 25 on E&M when ECG performed same day"},
    ("99214", "93000"): {"indicator": 1, "note": "Use modifier 25 on E&M when ECG performed same day"},
    ("99213", "96372"): {"indicator": 1, "note": "Use modifier 25 on E&M when injection administered same day"},
    ("99214", "96372"): {"indicator": 1, "note": "Use modifier 25 on E&M when injection administered same day"},
    ("99213", "20610"): {"indicator": 1, "note": "Use modifier 25 on E&M when joint injection performed same day"},
    ("99214", "20610"): {"indicator": 1, "note": "Use modifier 25 on E&M when joint injection performed same day"},
    # Surgical bundles
    ("27447", "27370"): {"indicator": 0, "note": "Total knee replacement includes knee arthrography — not separately billable"},
    ("27130", "27250"): {"indicator": 0, "note": "Total hip arthroplasty includes closed treatment of hip dislocation"},
    ("43239", "43235"): {"indicator": 0, "note": "EGD with biopsy includes diagnostic EGD"},
    ("43239", "43200"): {"indicator": 0, "note": "EGD with biopsy includes diagnostic EGD"},
    ("45385", "45378"): {"indicator": 0, "note": "Colonoscopy with polypectomy includes diagnostic colonoscopy"},
    ("45380", "45378"): {"indicator": 0, "note": "Colonoscopy with biopsy includes diagnostic colonoscopy"},
    # Radiology
    ("71046", "71045"): {"indicator": 0, "note": "2-view chest x-ray includes 1-view — bill 71046 only"},
    ("72148", "72141"): {"indicator": 0, "note": "MRI lumbar with and without contrast includes without only"},
    # Lab panels
    ("80053", "82040"): {"indicator": 0, "note": "CMP includes albumin — do not bill separately"},
    ("80053", "82374"): {"indicator": 0, "note": "CMP includes CO2 — do not bill separately"},
    ("80053", "82435"): {"indicator": 0, "note": "CMP includes chloride — do not bill separately"},
    ("80053", "82565"): {"indicator": 0, "note": "CMP includes creatinine — do not bill separately"},
    ("80048", "82040"): {"indicator": 0, "note": "BMP includes albumin — do not bill separately"},
    # Evaluation and management
    ("99213", "99212"): {"indicator": 0, "note": "Cannot bill two E&M codes same day same provider"},
    ("99214", "99213"): {"indicator": 0, "note": "Cannot bill two E&M codes same day same provider"},
    ("99215", "99214"): {"indicator": 0, "note": "Cannot bill two E&M codes same day same provider"},
    # Anesthesia
    ("01402", "27447"): {"indicator": 0, "note": "Anesthesia for total knee — bill 01402, not surgical code for anesthesia"},
    # Wound care
    ("97597", "97596"): {"indicator": 0, "note": "Active wound care includes debridement prep"},
    # Injections
    ("96413", "96415"): {"indicator": 1, "note": "Initial infusion (96413) and additional hour (96415) — bill with correct units"},
    ("96360", "96361"): {"indicator": 1, "note": "Initial hydration (96360) and additional hour (96361)"},
}

# Modifier rules: which modifiers are valid for which code types
MODIFIER_RULES = {
    "25": {"applies_to": "E&M", "description": "Significant, separately identifiable E&M service on same day as procedure", "common_error": "Do not use on procedure codes — only on E&M (9920x, 9921x) codes"},
    "26": {"applies_to": "Diagnostic", "description": "Professional component of global service", "common_error": "Cannot use with codes that are already professional component only"},
    "TC": {"applies_to": "Diagnostic", "description": "Technical component of global service", "common_error": "Cannot use with codes that are already technical component only"},
    "59": {"applies_to": "Procedure", "description": "Distinct procedural service — bypass NCCI edit", "common_error": "Should be replaced by XE, XS, XP, or XU when possible (more specific)"},
    "XE": {"applies_to": "Procedure", "description": "Separate encounter — distinct encounter or visit"},
    "XS": {"applies_to": "Procedure", "description": "Separate structure — distinct body part/organ system"},
    "XP": {"applies_to": "Procedure", "description": "Separate practitioner — distinct practitioner performed the service"},
    "XU": {"applies_to": "Procedure", "description": "Unusual non-overlapping service — service does not overlap usual components"},
    "51": {"applies_to": "Procedure", "description": "Multiple procedures — second and subsequent procedures at same session", "common_error": "Do not use on add-on codes (marked with +) or modifier 51 exempt codes"},
    "52": {"applies_to": "Procedure", "description": "Reduced services — service partially reduced"},
    "53": {"applies_to": "Procedure", "description": "Discontinued procedure — procedure discontinued after start"},
    "54": {"applies_to": "Surgical", "description": "Surgical care only — surgeon performs surgery but not pre/post care"},
    "55": {"applies_to": "Surgical", "description": "Postoperative management only"},
    "56": {"applies_to": "Surgical", "description": "Preoperative management only"},
    "57": {"applies_to": "E&M", "description": "Decision for surgery — E&M on same day as major surgery (90-day global)"},
    "58": {"applies_to": "Surgical", "description": "Staged or related procedure during postoperative period"},
    "59": {"applies_to": "Procedure", "description": "Distinct procedural service"},
    "62": {"applies_to": "Surgical", "description": "Two surgeons — co-surgeons each bill with modifier 62"},
    "63": {"applies_to": "Neonatal", "description": "Procedure performed on infant less than 4 kg"},
    "76": {"applies_to": "Procedure", "description": "Repeat procedure by same physician"},
    "77": {"applies_to": "Procedure", "description": "Repeat procedure by another physician"},
    "78": {"applies_to": "Surgical", "description": "Unplanned return to OR during postoperative period"},
    "79": {"applies_to": "Surgical", "description": "Unrelated procedure during postoperative period"},
    "80": {"applies_to": "Surgical", "description": "Assistant surgeon"},
    "81": {"applies_to": "Surgical", "description": "Minimum assistant surgeon"},
    "82": {"applies_to": "Surgical", "description": "Assistant surgeon when qualified resident not available"},
    "AS": {"applies_to": "Surgical", "description": "PA, NP, or CNS services for assistant at surgery"},
    "GT": {"applies_to": "Telehealth", "description": "Via interactive audio and video telecommunications systems (legacy; now use POS 02 or 10 for Medicare)"},
    "95": {"applies_to": "Telehealth", "description": "Synchronous telemedicine service rendered via real-time interactive audio and video"},
    "GQ": {"applies_to": "Telehealth", "description": "Via asynchronous telecommunications system"},
    "GX": {"applies_to": "ABN", "description": "Notice of liability issued, voluntary under payer policy"},
    "GY": {"applies_to": "Non-covered", "description": "Item or service statutorily excluded or does not meet definition"},
    "GZ": {"applies_to": "Non-covered", "description": "Item or service expected to be denied as not reasonable and necessary"},
    "GA": {"applies_to": "ABN", "description": "Waiver of liability statement issued as required by payer policy"},
    "KX": {"applies_to": "Medicare", "description": "Requirements specified in the medical policy have been met"},
    "NU": {"applies_to": "DME", "description": "New equipment"},
    "RR": {"applies_to": "DME", "description": "Rental"},
    "UE": {"applies_to": "DME", "description": "Used durable medical equipment"},
    "LT": {"applies_to": "Bilateral", "description": "Left side"},
    "RT": {"applies_to": "Bilateral", "description": "Right side"},
    "50": {"applies_to": "Bilateral", "description": "Bilateral procedure — bill once with modifier 50"},
    "E1": {"applies_to": "Eyelid", "description": "Upper left eyelid"},
    "E2": {"applies_to": "Eyelid", "description": "Lower left eyelid"},
    "E3": {"applies_to": "Eyelid", "description": "Upper right eyelid"},
    "E4": {"applies_to": "Eyelid", "description": "Lower right eyelid"},
    "F1": {"applies_to": "Finger", "description": "Left hand, second digit"},
    "F2": {"applies_to": "Finger", "description": "Left hand, third digit"},
    "F3": {"applies_to": "Finger", "description": "Left hand, fourth digit"},
    "F4": {"applies_to": "Finger", "description": "Left hand, fifth digit"},
    "F5": {"applies_to": "Finger", "description": "Right hand, thumb"},
    "F6": {"applies_to": "Finger", "description": "Right hand, second digit"},
    "F7": {"applies_to": "Finger", "description": "Right hand, third digit"},
    "F8": {"applies_to": "Finger", "description": "Right hand, fourth digit"},
    "F9": {"applies_to": "Finger", "description": "Right hand, fifth digit"},
    "FA": {"applies_to": "Finger", "description": "Left hand, thumb"},
    "QX": {"applies_to": "CRNA", "description": "CRNA service with medical direction by a physician"},
    "QY": {"applies_to": "CRNA", "description": "Medical direction of one CRNA by an anesthesiologist"},
    "QZ": {"applies_to": "CRNA", "description": "CRNA service without medical direction by a physician"},
    "AA": {"applies_to": "Anesthesia", "description": "Anesthesia services performed personally by anesthesiologist"},
    "AD": {"applies_to": "Anesthesia", "description": "Medical supervision by physician: more than four concurrent anesthesia procedures"},
    "QK": {"applies_to": "Anesthesia", "description": "Medical direction of two, three, or four concurrent anesthesia procedures"},
    "22": {"applies_to": "Procedure", "description": "Increased procedural services — when work required exceeds usual; requires documentation"},
}

# ---------------------------------------------------------------------------
# Denial action playbook: CARC → recommended actions
# ---------------------------------------------------------------------------
DENIAL_ACTION_PLAYBOOK = {
    "4":   {"action": "CORRECT_AND_REBILL", "steps": ["Identify correct modifier for this CPT", "Remove incorrect modifier", "Resubmit corrected claim"], "appeal_basis": "Modifier correction"},
    "5":   {"action": "CORRECT_AND_REBILL", "steps": ["Verify POS code matches location of service", "Correct POS on claim", "Resubmit"], "appeal_basis": "POS correction"},
    "11":  {"action": "APPEAL_OR_RECODE", "steps": ["Review LCD for this CPT", "Verify ICD-10 is on covered diagnosis list", "If correct code: gather documentation and appeal", "If wrong code: recode and resubmit"], "appeal_basis": "Medical necessity with supporting clinical documentation"},
    "15":  {"action": "CORRECT_AND_REBILL", "steps": ["Obtain correct authorization number", "Verify auth covers this CPT code and provider", "Resubmit with correct auth number"], "appeal_basis": "Auth correction"},
    "16":  {"action": "CORRECT_AND_REBILL", "steps": ["Review RARC codes on this claim for specific missing info", "Correct identified errors", "Resubmit"], "appeal_basis": "Corrected billing information"},
    "18":  {"action": "INVESTIGATE", "steps": ["Pull original claim from PM system", "Verify original was paid or denied", "If duplicate in error: submit corrected claim with frequency code 7", "If legitimate duplicate: write off"], "appeal_basis": "Proof of separate/distinct service"},
    "22":  {"action": "CORRECT_AND_REBILL", "steps": ["Identify primary payer from eligibility", "Bill primary first", "Submit secondary with primary EOB"], "appeal_basis": "COB coordination"},
    "29":  {"action": "APPEAL_WITH_PROOF", "steps": ["Gather proof of timely submission (clearinghouse report, certified mail receipt)", "If proof exists: appeal with documentation", "If truly late: evaluate write-off vs. appeal on extenuating circumstances"], "appeal_basis": "Proof of timely filing or extenuating circumstances"},
    "45":  {"action": "WRITE_OFF", "steps": ["Verify amount is contractual adjustment per contract", "Post contractual write-off", "Do not bill patient for this amount"], "appeal_basis": "N/A — contractual adjustment"},
    "50":  {"action": "APPEAL", "steps": ["Pull LCD for this CPT and jurisdiction", "Verify ICD-10 meets coverage criteria", "Gather supporting documentation (chart notes, labs, imaging)", "Write appeal letter citing LCD criteria met", "Submit with medical records"], "appeal_basis": "Clinical documentation supporting medical necessity per LCD criteria"},
    "55":  {"action": "APPEAL", "steps": ["Gather peer-reviewed literature supporting established use", "Obtain letter of medical necessity from treating physician", "Submit appeal with evidence-based support"], "appeal_basis": "Peer-reviewed evidence supporting established (non-experimental) use"},
    "58":  {"action": "APPEAL_OR_RECODE", "steps": ["Verify POS was appropriate for service rendered", "If appropriate: appeal with documentation", "If incorrect: correct POS and resubmit"], "appeal_basis": "Documentation supporting appropriateness of place of service"},
    "59":  {"action": "REVIEW_NCCI", "steps": ["Check NCCI edit for these procedure codes", "If modifier indicator = 1: add appropriate modifier (59/X modifier)", "If indicator = 0: review for bundling; remove component code"], "appeal_basis": "Distinct procedural service with appropriate modifier"},
    "96":  {"action": "WRITE_OFF_OR_PATIENT_BILL", "steps": ["Verify service is truly non-covered", "If covered service billed incorrectly: recode and resubmit", "If non-covered: check if ABN on file", "If ABN on file: bill patient", "If no ABN: write off"], "appeal_basis": "Recode to covered service if applicable"},
    "97":  {"action": "REVIEW_BUNDLING", "steps": ["Identify which code bundled this service", "Verify bundling is correct per NCCI", "If incorrect bundling: appeal with NCCI reference", "If correct bundling: write off"], "appeal_basis": "NCCI unbundling with appropriate modifier"},
    "109": {"action": "REROUTE", "steps": ["Verify correct payer for this patient and DOS", "Re-verify eligibility", "Resubmit to correct payer"], "appeal_basis": "N/A — wrong payer"},
    "150": {"action": "APPEAL", "steps": ["Pull documentation supporting level of service billed", "Ensure MDM or time documentation is complete", "Submit appeal with full chart note"], "appeal_basis": "Documentation supporting level of service billed"},
    "197": {"action": "OBTAIN_AUTH_OR_APPEAL", "steps": ["Check if auth was obtained before service", "If auth obtained: appeal with auth number and approval documentation", "If no auth: evaluate retro-auth request with payer", "If emergent: appeal with emergency documentation"], "appeal_basis": "Authorization documentation or emergency/urgent care exception"},
    "_default": {"action": "INVESTIGATE", "steps": ["Look up CARC description", "Review RARC codes for additional specificity", "Determine root cause (eligibility/coding/auth/coverage)", "Select appropriate action based on root cause"], "appeal_basis": "Varies by root cause"},
}

# ---------------------------------------------------------------------------
# Async cache helpers
# ---------------------------------------------------------------------------
@mcp.tool()
def decode_denial(
    carc_code: str,
    rarc_code: Optional[str] = None,
    group_code: Optional[str] = None,
) -> dict:
    """
    Decode any CARC + RARC + group code combination from an 835/ERA remittance.
    Returns plain-English translation, root cause category, and suggested next action.
    This tool is FREE — no subscription required.

    Args:
        carc_code: Claim Adjustment Reason Code (e.g. "4", "CO-4", "97")
        rarc_code: Remittance Advice Remark Code (e.g. "N30", "MA01") — optional
        group_code: Adjustment group code (CO, PR, OA, PI, CR) — optional
    """
    # Normalize CARC — strip group prefix if included (e.g. "CO-4" → "4")
    carc_clean = re.sub(r'^(CO|PR|OA|PI|CR)-?', '', carc_code.strip().upper())

    con = sqlite3.connect(DB_PATH)
    cur = con.cursor()

    # Look up CARC
    cur.execute("SELECT description, notes FROM carc_codes WHERE code = ?", (carc_clean,))
    carc_row = cur.fetchone()

    # Look up RARC
    rarc_result = None
    if rarc_code:
        rarc_clean = rarc_code.strip().upper()
        cur.execute("SELECT description, notes FROM rarc_codes WHERE code = ?", (rarc_clean,))
        rarc_row = cur.fetchone()
        if rarc_row:
            rarc_result = {"code": rarc_clean, "description": rarc_row[0], "action_note": rarc_row[1]}
        else:
            rarc_result = {"code": rarc_clean, "description": "RARC code not found in local database — check x12.org for current codes", "action_note": None}

    con.close()

    # Group code meanings
    group_meanings = {
        "CO": "Contractual Obligation — amount not billable to patient per contract",
        "PR": "Patient Responsibility — patient owes this amount",
        "OA": "Other Adjustment — neither contractual nor patient responsibility",
        "PI": "Payer Initiated — payer-initiated reduction not related to patient liability",
        "CR": "Correction and Reversals — adjustment to correct prior payment",
    }

    # Root cause categories
    root_cause_map = {
        "4": "coding_error", "5": "coding_error", "8": "coding_error",
        "11": "medical_necessity", "50": "medical_necessity", "55": "medical_necessity", "150": "medical_necessity",
        "15": "authorization", "197": "authorization", "198": "authorization",
        "18": "duplicate", "76": "duplicate",
        "22": "eligibility_cob", "27": "eligibility", "26": "eligibility", "31": "eligibility",
        "29": "timely_filing",
        "45": "contractual", "96": "non_covered",
        "97": "bundling", "59": "ncci_edit",
    }

    root_cause = root_cause_map.get(carc_clean, "review_required")

    if carc_row:
        result = {
            "carc_code": carc_clean,
            "carc_description": carc_row[0],
            "plain_english": carc_row[1],
            "root_cause_category": root_cause,
            "group_code": group_code.upper() if group_code else None,
            "group_code_meaning": group_meanings.get(group_code.upper(), "Unknown group code") if group_code else None,
            "rarc": rarc_result,
            "suggested_next_action": DENIAL_ACTION_PLAYBOOK.get(carc_clean, DENIAL_ACTION_PLAYBOOK["_default"])["action"],
        }
    else:
        result = {
            "carc_code": carc_clean,
            "carc_description": f"CARC code {carc_clean} not found in local database",
            "plain_english": "Check x12.org/codes/claim-adjustment-reason-codes for current code definitions",
            "root_cause_category": "unknown",
            "group_code": group_code,
            "group_code_meaning": group_meanings.get(group_code.upper(), None) if group_code else None,
            "rarc": rarc_result,
            "suggested_next_action": "INVESTIGATE",
        }

    return result


# ---------------------------------------------------------------------------
# TOOL 2: get_pos_description — FREE TIER
# ---------------------------------------------------------------------------
@mcp.tool()
def get_pos_description(pos_code: str) -> dict:
    """
    Look up Place of Service code description and billing implications.
    This tool is FREE — no subscription required.

    Args:
        pos_code: Two-digit POS code (e.g. "11", "22", "23")
    """
    code = pos_code.strip().zfill(2)
    if code in POS_CODES:
        name, description = POS_CODES[code]
        billing_notes = {
            "11": "Standard office setting. Non-facility RVU rates apply for most services. Most common POS for outpatient professional billing.",
            "12": "Home visit. Non-facility RVU rates. Verify home visit codes (99341-99350).",
            "21": "Inpatient hospital. Facility rates apply. Professional services billed separately on CMS-1500. 3-day payment window rule applies.",
            "22": "Outpatient hospital (on-campus). Hospital bills on UB-04; professional services on CMS-1500 with POS 22.",
            "23": "Emergency room. Higher RVU rates may apply. Emergency modifier usage rules apply.",
            "24": "ASC. Facility bills ASC-specific payment rates. Professional services billed separately.",
            "31": "Skilled nursing facility. Consolidated billing applies — most Part B services bundled into SNF per diem. Check consolidated billing exclusion list.",
            "32": "Nursing facility. Some services bundled. Verify what can be billed separately.",
        }.get(code, "Standard billing rules apply for this POS.")

        return {
            "pos_code": code,
            "name": name,
            "description": description,
            "billing_notes": billing_notes,
            "reimbursement_type": "facility_rate" if code in ["21","22","23","24","31","32","61","62"] else "non_facility_rate",
        }
    else:
        return {
            "pos_code": code,
            "name": "Unknown POS code",
            "description": f"POS code {code} not found. Check cms.gov for current POS code list.",
            "billing_notes": None,
            "reimbursement_type": None,
        }


# ---------------------------------------------------------------------------
# TOOL 3: lookup_icd10 — PRO TIER
# ---------------------------------------------------------------------------

# ---------------------------------------------------------------------------
# Startup — init DB at module load time, before any tool calls
# ---------------------------------------------------------------------------
init_db()

if __name__ == "__main__":
    port = int(os.environ.get("PORT", 8001))
    mcp.run(transport="streamable-http", host="0.0.0.0", port=port)