fix(mcp): replace compare_payers with compare_practice_to_community + add .env.example

.env.example

@@ -1,2 +1,14 @@
-UPSTREAM_API_KEY=dev_your_key_here
-UPSTREAM_BASE_URL=https://api.upstream.cx
+# Upstream MCP — environment configuration template.
+# Copy to `.env` and fill in real values. Never commit `.env`.
+
+# Required: your Upstream API key (free tier available at upstream.cx/developers).
+# Format: lz_live_... or lz_test_... — generated at app.upstream.cx/settings/api-keys
+UPSTREAM_API_KEY=
+
+# Optional: override the API base URL. Default is https://api.upstream.cx.
+# Set this when developing against a local Django dev server (http://localhost:8000)
+# or against a Vercel preview.
+# UPSTREAM_API_BASE_URL=https://api.upstream.cx
+
+# Optional: per-request timeout in milliseconds. Default 30000 (30s).
+# UPSTREAM_REQUEST_TIMEOUT_MS=30000

README.md

@@ -103,7 +103,7 @@ Free API key (500 calls per month, no credit card): [upstream.cx/developers/keys
 | Tool | Tier | What it does |
 |---|---|---|
 | `get_payer_scorecard` | `[Paid]` | A to F grade and denial rate for a payer by specialty. Includes top denial codes, payment timing percentiles, and historical appeal success rates. |
-| `compare_payers` | `[Paid]` | Side by side comparison of two payers on denial rates, payment timing, and appeal success. |
+| `compare_practice_to_community` | `[Free, lead-capture]` | Compare your practice's payer-specific metrics (denial rate, days-to-pay, appeal win rate) against the Upstream network aggregate for that payer + specialty. Requires email — saved as a lead. Returns delta metrics + risk-adjusted CTA. |
 | `check_payer_behavior` | `[Paid]` | Behavioral risk score and cluster classification (Aggressive Denier, Slow Payer, Prompt Payer, Underpayer). Includes recent policy changes and the specific dates of detection. |
 
 ### Reimbursement

src/index.ts

@@ -13,7 +13,7 @@ import { lookupDenialCode } from './tools/lookup_denial_code.js';
 import { lookupFeeSchedule } from './tools/lookup_fee_schedule.js';
 import { scanClaim } from './tools/scan_claim.js';
 import { getPayerScorecard } from './tools/get_payer_scorecard.js';
-import { comparePayers } from './tools/compare_payers.js';
+import { comparePracticeToCommunity } from './tools/compare_practice_to_community.js';
 import { checkPayerBehavior } from './tools/check_payer_behavior.js';
 import { getIndustrySignals } from './tools/get_industry_signals.js';
 import { checkPriorAuthReadiness } from './tools/check_prior_auth_readiness.js';
@@ -27,7 +27,7 @@ const tools = [
   lookupFeeSchedule,
   scanClaim,
   getPayerScorecard,
-  comparePayers,
+  comparePracticeToCommunity,
   checkPayerBehavior,
   getIndustrySignals,
   checkPriorAuthReadiness,

src/tools/compare_practice_to_community.ts

@@ -0,0 +1,52 @@
+import { UpstreamAPIClient } from '../client.js';
+
+export const comparePracticeToCommunity = {
+  name: 'compare_practice_to_community',
+  description:
+    "Compare your practice's payer-specific metrics (denial rate, days-to-pay, appeal " +
+    'win rate) against the Upstream network aggregate for that payer + specialty. ' +
+    'Lead-capture endpoint — requires email. Returns delta metrics and a risk-adjusted CTA.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      email: {
+        type: 'string',
+        description: 'Work email — saved as a lead and returned with results',
+      },
+      payer: {
+        type: 'string',
+        description: 'Payer name to compare against (e.g. "UnitedHealthcare", "Aetna")',
+      },
+      specialty: {
+        type: 'string',
+        description: 'Specialty for the community aggregate (e.g. "ABA", "PT/OT", "dental")',
+      },
+      your_denial_rate: {
+        type: 'number',
+        description: 'Your practice denial rate as a decimal (e.g. 0.18 = 18%)',
+      },
+      your_days_to_pay: {
+        type: 'number',
+        description: 'Average days from claim submission to payment for your practice',
+      },
+      your_appeal_win_rate: {
+        type: 'number',
+        description: 'Your appeal win rate as a decimal (e.g. 0.62 = 62%)',
+      },
+    },
+    required: ['email', 'payer', 'specialty'],
+  },
+  async execute(
+    client: UpstreamAPIClient,
+    args: {
+      email: string;
+      payer: string;
+      specialty: string;
+      your_denial_rate?: number;
+      your_days_to_pay?: number;
+      your_appeal_win_rate?: number;
+    },
+  ) {
+    return client.post('/api/v1/public/payer-scorecard/compare/', args);
+  },
+};