@cliwant/mcp-sam-gov 1.12.0 → 1.13.0

package/src/server.ts

@@ -52,6 +52,8 @@ import * as arcgisHub from "./arcgis-hub.js";
 import * as opengov from "./opengov.js";
 import * as bonfire from "./bonfire.js";
 import * as arcgisFeature from "./arcgis-feature.js";
+import * as tableau from "./tableau.js";
+import * as openCheckbook from "./open-checkbook.js";
 import * as govinfo from "./govinfo.js";
 import * as fpds from "./fpds.js";
 import * as nih from "./nih.js";
@@ -106,7 +108,7 @@ import { realpathSync } from "node:fs";
 const SERVER_NAME = "mcp-sam-gov";
 // Kept in lockstep with package.json / manifest.json / server.json.
 // Keep in sync with package.json "version" (asserted at release; see CHANGELOG).
-const SERVER_VERSION = "1.12.0";
+const SERVER_VERSION = "1.13.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -2756,9 +2758,9 @@ const EchoSearchFacilitiesInput = z.object({
 const EchoFacilityReportInput = z.object({
   registryId: z
     .string()
-    .regex(/^[0-9]{9,12}$/)
+    .regex(/^[A-Za-z0-9]{1,20}$/)
     .describe(
-      "The facility's FRS RegistryID (from echo_search_facilities rows' RegistryID) — an all-digit id, 9–12 digits (e.g. '110059768461'). A bad/unknown id ⇒ not_found (never a fabricated report).",
+      "The facility's RegistryID exactly as returned in echo_search_facilities rows — usually a 12-digit FRS id (e.g. '110059768461'), but ECHO also returns state/program ids (e.g. 'DCR000509282') and short ids (e.g. '9434'), which the report accepts. 1–20 letters/digits. A bad/unknown id ⇒ not_found (never a fabricated report).",
     ),
 });
 
@@ -3042,7 +3044,7 @@ const OpengovSearchSolicitationsInput = z.object({
 // ─── Bonfire (Euna) — keyless per-org open-opportunity RSS (SLED bids) ─
 // SLED bid campaign. Thousands of US state/local govs on Bonfire expose a keyless
 // RSS of open opportunities at {org}.bonfirehub.com/opportunities/rss. Ships a
-// curated 187-org seed directory. Fixed-suffix SSRF. org = charclass slug.
+// curated 186-org seed directory. Fixed-suffix SSRF. org = charclass slug.
 const BonfireListOrganizationsInput = z.object({
   state: z.string().length(2).optional().describe("2-letter US state filter (client-side), e.g. 'TX', 'CA'. Optional."),
   query: z.string().min(1).max(120).optional().describe("Case-insensitive name substring filter (client-side), e.g. 'county', 'ISD'. Optional."),
@@ -3061,6 +3063,34 @@ const BonfireSearchOpportunitiesInput = z.object({
   offset: z.number().int().min(0).default(0).describe("0-based offset; page with _meta.pagination.nextOffset. totalAvailable = the exact open-opportunity count."),
 });
 
+// ─── Socrata Open Expenditures checkbook (curated portal allowlist — SLED) ─
+// Row-level vendor-payment search over the keyless /api/checkbook_data.json
+// app-proxy (the underlying SODA dataset is login-gated — never touched).
+const OpenCheckbookSearchInput = z.object({
+  portal: z
+    .enum(openCheckbook.OPEN_CHECKBOOK_PORTALS.map((p) => p.key) as [string, ...string[]])
+    .describe("The curated Open-Checkbook portal (SSRF allowlist enum). 'sd' = State of South Dakota Open Checkbook (~740,980 vendor payments, ~$8.41B, ~3 most-recent fiscal years)."),
+  year: z.string().min(1).max(40).optional().describe("Fiscal-year filter (EXACT match), e.g. '2025'. Default 'All Years' = the exposed ~3-year window (NOT full history)."),
+  vendor: z.string().min(1).max(200).optional().describe("Vendor name filter (EXACT match, e.g. 'US BANK NA' → 917). A partial/misspelled value returns an honest count:0."),
+  org: z.string().min(1).max(200).optional().describe("Department filter (org1, EXACT match, e.g. 'TRANSPORTATION' → 109,887)."),
+  expenseCategory: z.string().min(1).max(200).optional().describe("Expense-category filter (EXACT match, e.g. 'CONTRACTUAL SERVICES')."),
+  sortBy: z.enum(["amount", "payment_date", "vendor", "org1", "expense_category"]).optional().describe("Sort field. Pair with sortOrder."),
+  sortOrder: z.enum(["asc", "desc"]).optional().describe("Sort direction (default desc when sortBy is set)."),
+  limit: z.number().int().min(1).max(1000).default(25).describe("Rows per page, 1..1000, default 25."),
+  offset: z.number().int().min(0).default(0).describe("0-based offset (snapped to a page×limit boundary; the served offset is disclosed). totalAvailable = the real match count, NOT a page length."),
+});
+
+// ─── Tableau Server Guest view CSV (curated view allowlist — SLED transparency) ─
+// Fetch a Guest-enabled Tableau Server WORKSHEET view's COMPLETE CSV export
+// (keyless) and page over it client-side. `view` is an enum (SSRF core).
+const TableauViewCsvInput = z.object({
+  view: z
+    .enum(tableau.TABLEAU_VIEWS.map((v) => v.key) as [string, ...string[]])
+    .describe("The curated Tableau Server Guest view (SSRF allowlist enum). 'mt_contracts_awarded' = State of Montana (DOA) Contracts Awarded (~4,554 award records: $ Awarded, Award Date, Event Type IFB/RFP, Event# solicitation, Vendor Name, Agency)."),
+  limit: z.number().int().min(1).max(1000).default(50).describe("Rows per page, 1..1000, default 50. The CSV is the complete view export; this pages over it client-side."),
+  offset: z.number().int().min(0).default(0).describe("0-based offset; page with _meta.pagination.nextOffset. totalAvailable = the complete export row count (NOT a page length)."),
+});
+
 // ─── ArcGIS REST feature query (curated service allowlist — SLED bids/GIS) ─
 // Generic ArcGIS FeatureServer/MapServer layer query over a curated allowlist.
 // First payload: DC OCP PASS procurement layers (live solicitations/contracts/PO/
@@ -3068,7 +3098,7 @@ const BonfireSearchOpportunitiesInput = z.object({
 const ArcgisFeatureQueryInput = z.object({
   service: z
     .enum(arcgisFeature.ARCGIS_SERVICES.map((s) => s.key) as [string, ...string[]])
-    .describe("The curated ArcGIS layer (SSRF allowlist enum). DC OCP PASS: 'dc_pass_solicitations' (live solicitations ~25k), 'dc_pass_contracts', 'dc_pass_purchase_orders', 'dc_pass_payments'. Other US local govs: 'asheville_purchase_orders'/'asheville_po_summary' (Asheville NC), 'bellevue_vendor_payments'/'bellevue_awarded_contracts' (Bellevue WA), 'miamidade_purchase_orders_2025'/'miamidade_purchase_orders_2017' (Miami-Dade FL, current/2017), 'suffolk_county_ny_contracts_2018' (Suffolk County NY), 'matsu_borough_ak_checkbook' (Matanuska-Susitna Borough AK), 'lasvegas_checkbook' (Las Vegas NV ~373k), 'baltimore_checkbook' (Baltimore City MD ~367k), 'naperville_vendor_payments' (Naperville IL ~127k), 'worcester_ma_checkbook_fy25' (Worcester MA FY25), 'lasvegas_purchasing_contracts' (Las Vegas NV contract register), 'txdot_construction_projects' (Texas DOT, awarded construction company ~85k), 'akdot_construction_awards'/'akdot_aashtoware_proposals' (Alaska DOT&PF bid awards/proposals), 'iowadot_public_bid_awards' (Iowa DOT public bid), 'okdot_cirb_contract_status' (Oklahoma DOT CIRB contract status), 'topeka_checkbook_aggregate' (Topeka KS checkbook FY2015–2023 ~332k). 23 curated services (state DOT bid/award registers: TX/AK/IA/OK + municipal checkbooks/contracts)."),
+    .describe("The curated ArcGIS layer (SSRF allowlist enum). DC OCP PASS: 'dc_pass_solicitations' (live solicitations ~25k), 'dc_pass_contracts', 'dc_pass_purchase_orders', 'dc_pass_payments'. Other US local govs: 'asheville_purchase_orders'/'asheville_po_summary' (Asheville NC), 'bellevue_vendor_payments'/'bellevue_awarded_contracts' (Bellevue WA), 'miamidade_purchase_orders_2025'/'miamidade_purchase_orders_2017' (Miami-Dade FL, current/2017), 'suffolk_county_ny_contracts_2018' (Suffolk County NY), 'matsu_borough_ak_checkbook' (Matanuska-Susitna Borough AK), 'lasvegas_checkbook' (Las Vegas NV ~373k), 'baltimore_checkbook' (Baltimore City MD ~367k), 'naperville_vendor_payments' (Naperville IL ~127k), 'worcester_ma_checkbook_fy25' (Worcester MA FY25), 'lasvegas_purchasing_contracts' (Las Vegas NV contract register), 'txdot_construction_projects' (Texas DOT, awarded construction company ~85k), 'akdot_construction_awards'/'akdot_aashtoware_proposals' (Alaska DOT&PF bid awards/proposals), 'iowadot_public_bid_awards' (Iowa DOT public bid), 'okdot_cirb_contract_status' (Oklahoma DOT CIRB contract status), 'topeka_checkbook_aggregate' (Topeka KS checkbook FY2015–2023 ~332k), 'nddot_flex_setaside_road'/'nddot_flex_partner_road'/'nddot_flex_setaside_bridge'/'nddot_flex_partner_bridge' (North Dakota DOT federal flex-funding awards to local public agencies — counties/townships/cities, NOT vendor contracts; a proxy because ND's checkbook/procurement portal is not keyless-reachable). 27 curated services (state DOT bid/award registers: TX/AK/IA/OK + ND DOT flex-funding awards + municipal checkbooks/contracts)."),
   where: z
     .string()
     .min(1)
@@ -6089,7 +6119,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "echo_facility_report",
     description:
-      "Fetch the EPA ECHO Detailed Facility Report (DFR) for ONE facility by its FRS RegistryID (keyless) — the per-facility compliance / enforcement / inspection / permit deep-dive for competitor or acquisition-target due diligence. Input `registryId` (all-digit FRS id, 9–12 digits, from echo_search_facilities rows). Returns { registryId, report:{…verbatim compliance/enforcement/permit detail…} } + single-record _meta (complete:true, no pagination). A bad/unknown RegistryID ⇒ not_found (never a fabricated report).",
+      "Fetch the EPA ECHO Detailed Facility Report (DFR) for ONE facility by its FRS RegistryID (keyless) — the per-facility compliance / enforcement / inspection / permit deep-dive for competitor or acquisition-target due diligence. Input `registryId` (the RegistryID exactly as returned by echo_search_facilities rows — usually a 12-digit FRS id, but ECHO also returns state/program ids like 'DCR000509282' and short ids like '9434', all accepted; 1–20 letters/digits). Returns { registryId, report:{…verbatim compliance/enforcement/permit detail…} } + single-record _meta (complete:true, no pagination). A bad/unknown RegistryID ⇒ not_found (never a fabricated report).",
     inputSchema: EchoFacilityReportInput,
     handler: (input) => echo.facilityReport(input),
   }),
@@ -6194,13 +6224,13 @@ export const TOOLS: ToolDef[] = [
   }),
   // ━━━ Bonfire (Euna) — keyless per-org open-opportunity RSS (SLED bids) ━━━
   // SLED bid campaign. Thousands of US state/local govs on Bonfire expose a keyless
-  // RSS of open opportunities. Ships a curated 187-org live-verified seed directory
+  // RSS of open opportunities. Ships a curated 186-org live-verified seed directory
   // (Bonfire's authoritative org API is auth-gated → out of bounds). Fixed-suffix
   // SSRF (.bonfirehub.com). RSS = the complete open set (totalAvailable honest).
   defineTool({
     name: "bonfire_list_organizations",
     description:
-      "List US governments on the Bonfire (Euna) eProcurement platform — the directory for bonfire_search_opportunities (keyless). Bonfire hosts thousands of US state/local governments' open-bid portals, each with a keyless RSS feed. Filter the curated seed by `state` (2-letter) / `query` (case-insensitive name substring); `limit`(1..200)/`offset`. Output: { organizations:[{ org, name, state }] }. Feed a result's `org` to bonfire_search_opportunities. ★HONESTY: this is a CURATED, live-verified SEED of 187 US orgs — Bonfire has NO keyless org-list API (its authoritative directory is auth-gated, out of bounds), and Euna markets up to ~900 US orgs, so the seed is PARTIAL (disclosed in _meta); probe `{slug}.bonfirehub.com/opportunities/rss` to extend. totalAvailable = the exact filtered seed count.",
+      "List US governments on the Bonfire (Euna) eProcurement platform — the directory for bonfire_search_opportunities (keyless). Bonfire hosts thousands of US state/local governments' open-bid portals, each with a keyless RSS feed. Filter the curated seed by `state` (2-letter) / `query` (case-insensitive name substring); `limit`(1..200)/`offset`. Output: { organizations:[{ org, name, state }] }. Feed a result's `org` to bonfire_search_opportunities. ★HONESTY: this is a CURATED, live-verified SEED of 186 US orgs — Bonfire has NO keyless org-list API (its authoritative directory is auth-gated, out of bounds), and Euna markets up to ~900 US orgs, so the seed is PARTIAL (disclosed in _meta); probe `{slug}.bonfirehub.com/opportunities/rss` to extend. totalAvailable = the exact filtered seed count.",
     inputSchema: BonfireListOrganizationsInput,
     handler: (input) => bonfire.listOrganizations(input),
   }),
@@ -6222,6 +6252,28 @@ export const TOOLS: ToolDef[] = [
     inputSchema: ArcgisFeatureQueryInput,
     handler: (input) => arcgisFeature.featureQuery(input),
   }),
+  // ─── Tableau Server Guest view CSV export (curated allowlist) — SLED transparency ─
+  // Many US state/local govs publish contracts/vendor-payment/checkbook data on a
+  // Guest-enabled Tableau Server; a worksheet view exports its full data as CSV at
+  // {host}/t/{site}/views/{wb}/{view}.csv?:embed=y (keyless). First payload: Montana
+  // Contracts Awarded — the ND-sibling in the dark-state closure campaign.
+  defineTool({
+    name: "tableau_view_csv",
+    description:
+      "Fetch a curated US-government **Tableau Server Guest** view's COMPLETE CSV export (keyless) and page over it — a SLED transparency source (many state/local govs publish contracts / vendor-payment / checkbook data on a Guest-enabled Tableau Server; a worksheet view exports as CSV at `{host}/t/{site}/views/{workbook}/{view}.csv?:embed=y`, no login/key/cookie). First payload: `mt_contracts_awarded` = **State of Montana (DOA) Contracts Awarded** (~4,554 award records: '$ Awarded', 'Award Date', 'Event Type' (Invitation For Bid / RFP), 'Event#' solicitation number, 'Vendor Name', 'Agency'). Inputs: `view` (the allowlist ENUM — SSRF core, never a free host), `limit`(1..1000)/`offset`. Returns { view, columns:[…], rows:[{col:value…}] } + honest _meta. HONESTY: the CSV is the COMPLETE view export (Tableau returns ALL summary rows — NO server pagination), so totalAvailable = the true row count (NEVER a page length); limit/offset page it client-side; a round-number total is flagged as a possible Tableau export cap. Values are TRIMMED strings (an empty field ⇒ null, never 0/\"\"); the content is preserved — amounts like \"$5,879,590.00\" are FORMATTED STRINGS, parse client-side. A 429/5xx/404/timeout THROWS; a gated/renamed view (200 sign-in HTML or an empty dashboard-container export) ⇒ schema_drift (a loud failure, NEVER a fake empty); a worksheet with a header but 0 data rows ⇒ honest empty. SSRF: fixed allowlist base + hostname assertion + redirect:error.",
+    inputSchema: TableauViewCsvInput,
+    handler: (input) => tableau.viewCsv(input),
+  }),
+  // ─── Socrata Open Expenditures checkbook (curated portal allowlist) — SLED ─
+  // Row-level vendor payments via the keyless /api/checkbook_data.json app-proxy.
+  // First portal: South Dakota — the LAST dark-state closure (presence → 100%).
+  defineTool({
+    name: "open_checkbook_search",
+    description:
+      "Row-level vendor-payment search over a curated US-government **Socrata Open Expenditures** checkbook portal (keyless) — a SLED spending source. Some govs run Socrata's 'Open Expenditures/Open Checkbook' product, whose public dashboard fronts a keyless app-proxy at `{host}/api/checkbook_data.json`. First portal: `sd` = **State of South Dakota Open Checkbook** (~740,980 vendor-payment rows, ~$8.41B, the ~3 most-recent fiscal years). Inputs: `portal` (allowlist ENUM — SSRF core), `year`/`vendor`/`org`/`expenseCategory` (EXACT-match filters), `sortBy`/`sortOrder`, `limit`(1..1000)/`offset`. Returns { portal, rows:[{vendor, amount, payment_date, org1, expense_category, description, fund, invoice, payment_id}] } + honest _meta. HONESTY: totalAvailable = the API's own `count` (the REAL filtered total — matches the product's totals.json, e.g. 740,980 unfiltered / 109,887 for org=TRANSPORTATION — NEVER a page length); `amount` = number|null (a real $0 is 0, an absent value is null, never a fabricated 0); an EXACT-match filter miss ⇒ honest count:0; a deep offset past the end ⇒ returned:0 with the real count preserved; a 429/5xx/timeout THROWS; a non-`{data:[],count}` body ⇒ schema_drift. ★Only the ~3 most-recent fiscal years are exposed (NOT full history — disclosed). ★The underlying Socrata SODA dataset is login-gated and is NEVER touched — only the public app-proxy the dashboard itself uses. SSRF: fixed allowlist host + assertion + redirect:error.",
+    inputSchema: OpenCheckbookSearchInput,
+    handler: (input) => openCheckbook.openCheckbookSearch(input),
+  }),
   // ━━━ GovInfo (api.govinfo.gov) — the api.data.gov keyed trio's 3rd API (3) ━━━ ADR-0010
   // GPO-authoritative bulk publications (BILLS/PLAW/USCODE/CREC/CFR-FR editions/
   // BUDGET/GAOREPORTS) with PDF/XML/MODS downloads + provenance. 2nd consumer of the
@@ -6823,7 +6875,7 @@ const TOOL_SOURCE_LABELS: Record<string, string> = {
   clinicaltrials: "ClinicalTrials.gov", bls: "BLS", socrata: "Socrata", opengov: "OpenGov",
   nsf: "NSF", nonprofit: "Nonprofit", nhtsa: "NHTSA", gsa: "GSA", grants: "Grants.gov",
   fred: "FRED", fac: "FAC", echo: "EPA ECHO", dol: "DOL", congress: "Congress.gov",
-  ckan: "data.gov", bonfire: "Bonfire", arcgis: "ArcGIS", sba: "SBA", ofac: "OFAC",
+  ckan: "data.gov", bonfire: "Bonfire", arcgis: "ArcGIS", tableau: "Tableau", open: "Open Checkbook", sba: "SBA", ofac: "OFAC",
   nws: "NWS", nppes: "NPPES", nist: "NIST", nih: "NIH", lda: "Senate LDA", hts: "USITC HTS",
   bea: "BEA", cbp: "CBP", cpsc: "CPSC", nvd: "NVD", courtlistener: "CourtListener",
   fpds: "FPDS", gao: "GAO", epa: "EPA", nsn: "NSN",

package/src/tableau.ts

@@ -0,0 +1,159 @@
+/**
+ * tableau.ts — Tableau Server "Guest" view CSV export, a keyless-first SLED
+ * transparency source (loop cycle 75, 2026-07-24 — Montana dark-state closure).
+ *
+ * WHAT IT ADDS: many US state/local governments publish contracts / vendor-payment
+ * / checkbook data on a Guest-enabled Tableau Server. A WORKSHEET view exports its
+ * FULL summary data as CSV at
+ *   `https://{host}/t/{site}/views/{workbook}/{view}.csv?:embed=y`
+ * — anonymous, KEYLESS (no login, key, or session cookie required). This is the
+ * export the public Tableau UI itself offers ("Download ▸ Data"). First payload:
+ * Montana state **Contracts Awarded** (DOA), a live gov-con award register.
+ *
+ * ★ CURATED allowlist (SSRF core): each `base` is a FIXED, live-verified Tableau
+ *   Server view URL (up to the view name; the tool appends `.csv?:embed=y`). The
+ *   `view` enum in server.ts is built FROM the keys (single source of truth), and
+ *   a post-construction hostname assertion (over https) guards the fetch
+ *   (`redirect:"error"`). where/columns cannot alter the host.
+ *
+ * ★ HONESTY PILLARS:
+ *   P1: the CSV is the COMPLETE view export — Tableau returns ALL summary rows in
+ *     the view (there is NO server-side pagination on this endpoint), so
+ *     totalAvailable = the parsed DATA-row count (the true total, NOT a page
+ *     length); limit/offset page over it CLIENT-side. NOTE (disclosed every
+ *     response): a Tableau Server MAY server-cap a very large summary export — the
+ *     seeded views are live-verified COMPLETE (non-round counts), and a round-number
+ *     count is flagged as a possible cap.
+ *   P2: getText THROWS on 429 / 5xx / 404 / timeout — NEVER a fake empty. A view
+ *     that is gated/renamed (a 200 sign-in HTML, or a dashboard-CONTAINER whose CSV
+ *     export is empty) ⇒ schema_drift (a loud, honest failure — NEVER a silent 0).
+ *     A worksheet that legitimately has a header but zero data rows ⇒ honest empty.
+ *   P3: values are TRIMMED strings (surrounding whitespace removed; an empty field
+ *     ⇒ null, never 0 or ""). The value CONTENT is preserved — amounts/dates are
+ *     FORMATTED STRINGS (e.g. "$5,879,590.00"), parse client-side. Header trimmed.
+ *   P4: a 200 body that is not CSV (HTML, or no header row) ⇒ schema_drift.
+ */
+
+import { ToolErrorCarrier } from "./errors.js";
+import { getText, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { parseCsv } from "./gov-domains.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+export { num };
+
+// ─── Curated view allowlist (SSRF core) — LIVE-VERIFIED 2026-07-24 ──
+// Each `base` is the Tableau Server view URL WITHOUT extension; the tool appends
+// `.csv?:embed=y`. All keyless (anonymous, empty-cookie 200 verified).
+export type TableauView = { key: string; base: string; label: string; note: string };
+export const TABLEAU_VIEWS: readonly TableauView[] = [
+  {
+    key: "mt_contracts_awarded",
+    base: "https://tableau-ext.mt.gov/t/DOA/views/ContractsAwarded/ContractsAwarded",
+    label: "Montana DOA — Contracts Awarded",
+    note: "State of Montana contract/solicitation awards (columns: '$ Awarded', 'Award Date', 'Event Title', 'Event Type' (Invitation For Bid / Request for Proposal), 'Event#' (solicitation number), 'Montana Vendor' (Y/N; '?'=unknown), 'Vendor Name', 'Agency'). ~4,554 awards, April 2020–present. ★'$ Awarded' is a FORMATTED STRING (e.g. \" $1,878,796.10 \") — parse client-side. Source: transparency.mt.gov (Tableau Server Guest CSV).",
+  },
+] as const;
+
+const VIEW_BY_KEY: ReadonlyMap<string, TableauView> = new Map(TABLEAU_VIEWS.map((v) => [v.key, v]));
+
+const VALUE_NOTE =
+  "Values are TRIMMED strings (surrounding whitespace removed; an empty field ⇒ null, never 0 or \"\"). The content is preserved — amounts/dates are FORMATTED STRINGS (e.g. \"$5,879,590.00\"), parse client-side.";
+
+/** Build the `.csv?:embed=y` export URL + assert it stays on the allowlisted host. */
+function csvUrl(v: TableauView): string {
+  const url = `${v.base}.csv?:embed=y`;
+  const allowedHost = new URL(v.base).hostname;
+  const built = new URL(url);
+  if (built.hostname !== allowedHost || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Constructed Tableau URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the allowlisted view host ${JSON.stringify(allowedHost)} over https — refusing to fetch (SSRF safety).`,
+      retryable: false,
+      upstreamEndpoint: `tableau:${v.key}`,
+    });
+  }
+  return url;
+}
+
+// ─── Tool: tableau_view_csv ───────────────────────────────────────
+export type TableauViewCsvArgs = { view: string; limit?: number; offset?: number };
+
+/**
+ * Fetch a curated Tableau Server Guest view's COMPLETE CSV export (keyless) and
+ * page over it client-side. `view` is an allowlist enum; `limit`/`offset` page
+ * the parsed rows. Returns { view, columns, rows:[{col:value…}] } + honest _meta
+ * (totalAvailable = the complete row count, NOT a page length).
+ */
+export async function viewCsv(args: TableauViewCsvArgs): Promise<MetaBundle> {
+  const v = VIEW_BY_KEY.get(args.view);
+  if (!v) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Unknown Tableau view ${JSON.stringify(args.view)}. Allowed: ${TABLEAU_VIEWS.map((s) => s.key).join(", ")}.`,
+      retryable: false,
+    });
+  }
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+
+  // ── Fetch the full view CSV. getText THROWS on 429/5xx/404/timeout (P2). ──
+  const url = csvUrl(v);
+  const body = await getText(url, { label: `tableau:${v.key}`, redirect: "error", timeoutMs: 45_000 });
+
+  // P4: a non-CSV body (HTML sign-in / error page) ⇒ schema_drift, never parsed as empty.
+  const text = body.replace(/^/, ""); // strip a leading UTF-8 BOM if present
+  if (text.trim().length === 0 || /^\s*</.test(text)) {
+    throw driftError(
+      `tableau:${v.key}`,
+      "Tableau returned an empty or non-CSV (HTML) body at HTTP 200 — the view may be gated, renamed, or a dashboard container (not a worksheet). Schema drift — refusing to report a fake empty.",
+    );
+  }
+
+  const table = parseCsv(text);
+  // P4: the first row MUST be a header (≥1 named column). No rows ⇒ drift.
+  if (table.length === 0 || !Array.isArray(table[0]) || table[0].length === 0) {
+    throw driftError(`tableau:${v.key}`, "Tableau CSV has no header row — schema drift.");
+  }
+  const header = table[0].map((h) => str(h) ?? "");
+  const dataRows = table.slice(1);
+  const totalAvailable = dataRows.length; // P1: complete view export = true total
+
+  const pageRows = dataRows.slice(offset, offset + limit).map((r) => {
+    const obj: Record<string, string | null> = {};
+    for (let i = 0; i < header.length; i++) obj[header[i] || `col${i}`] = str(r[i]);
+    return obj;
+  });
+  const returned = pageRows.length;
+  const hasMore = offset + returned < totalAvailable;
+  const nextOffset = hasMore ? offset + returned : null;
+
+  // P1 cap disclosure: a suspiciously round total may indicate a server export cap.
+  const roundCap = totalAvailable >= 1000 && totalAvailable % 1000 === 0;
+  const notes: string[] = [
+    `Source: ${v.label} (Tableau Server Guest CSV export, keyless). ${v.note}`,
+    "totalAvailable is the COMPLETE view export row count (Tableau returns all summary rows; there is no server-side pagination) — limit/offset page over the full set client-side.",
+    "Pagination order follows the Tableau view's OWN sort. Each call re-fetches the complete CSV and slices it; if the view lacks a stable sort, offsets across SEPARATE calls could shift — for a consistent snapshot of a large view, fetch it with a single large limit.",
+    VALUE_NOTE,
+    "FRESHNESS is set by the publisher: a Tableau export carries no refresh timestamp, and the view reflects whenever the publisher last refreshed it, which can lag by weeks. Check the newest value in the view's date columns before relying on recency.",
+  ];
+  if (roundCap)
+    notes.push(
+      `NOTE: the row count (${totalAvailable}) is an exact multiple of 1000 — Tableau Server MAY have capped this summary export, so totalAvailable could be a lower bound. Treat with caution.`,
+    );
+
+  return withMeta(
+    { view: v.key, columns: header, rows: pageRows },
+    {
+      source: `${new URL(v.base).hostname} via Tableau Server Guest CSV (keyless)`,
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      filtersApplied: ["view"],
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset, limit, hasMore, nextOffset },
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}