us-gov-open-data-mcp 1.0.0

package/dist/sdk/cms.js

@@ -0,0 +1,227 @@
+/**
+ * CMS SDK — typed API client for Centers for Medicare & Medicaid Services provider data.
+ *
+ * Standalone — no MCP server required. Usage:
+ *
+ *   import { searchDatasets, queryDataset } from "us-gov-open-data/sdk/cms";
+ *
+ * No API key required.
+ * Docs: https://data.cms.gov/provider-data/
+ */
+import { createClient } from "../client.js";
+// ─── Client ──────────────────────────────────────────────────────────
+const api = createClient({
+    baseUrl: "https://data.cms.gov/provider-data/api/1",
+    name: "cms",
+    rateLimit: { perSecond: 5, burst: 10 },
+    cacheTtlMs: 24 * 60 * 60 * 1000, // 24 hours — provider data updates monthly/quarterly
+});
+// ─── Dataset Catalog ─────────────────────────────────────────────────
+// Key CMS Provider Data datasets with their identifiers (short IDs).
+// Use searchDatasets to discover more.
+export const DATASETS = {
+    hospital_info: {
+        id: "xubh-q36u",
+        name: "Hospital General Information",
+        description: "All Medicare-certified hospitals: name, address, phone, type, ownership, star ratings, emergency services",
+        theme: "Hospitals",
+    },
+    nursing_home_info: {
+        id: "4pq5-n9py",
+        name: "Nursing Home Provider Information",
+        description: "All nursing homes: beds, quality ratings, staffing, penalties, five-star ratings",
+        theme: "Nursing homes",
+    },
+    home_health_info: {
+        id: "6jpm-sxkc",
+        name: "Home Health Agency Information",
+        description: "Medicare-registered home health agencies: addresses, quality ratings",
+        theme: "Home health services",
+    },
+    hospice_info: {
+        id: "yc9t-dgbk",
+        name: "Hospice General Information",
+        description: "Medicare-certified hospice providers: addresses, phone numbers",
+        theme: "Hospice care",
+    },
+    dialysis_info: {
+        id: "23ew-n7w9",
+        name: "Dialysis Facility Information",
+        description: "Dialysis facilities: addresses, services, quality of care measures",
+        theme: "Dialysis facilities",
+    },
+    hospital_mortality: {
+        id: "ynj2-r877",
+        name: "Complications and Deaths - Hospital",
+        description: "Hospital-level mortality rates, hip/knee complications, patient safety indicators",
+        theme: "Hospitals",
+    },
+    hospital_readmissions: {
+        id: "9n3s-kdb3",
+        name: "Hospital Readmissions Reduction Program",
+        description: "Excess readmission ratios and payment reductions for hospitals",
+        theme: "Hospitals",
+    },
+    hospital_infections: {
+        id: "77hc-ibv8",
+        name: "Healthcare Associated Infections - Hospital",
+        description: "HAI measures: CLABSI, CAUTI, SSI, MRSA, C.difficile rates by hospital",
+        theme: "Hospitals",
+    },
+    hospital_timely_care: {
+        id: "yv7e-xc69",
+        name: "Timely and Effective Care - Hospital",
+        description: "ED wait times, heart attack/stroke care, preventive care, immunization measures",
+        theme: "Hospitals",
+    },
+    hospital_spending: {
+        id: "rrqw-56er",
+        name: "Medicare Spending Per Beneficiary - Hospital",
+        description: "Medicare spending per episode of care compared to national average",
+        theme: "Hospitals",
+    },
+    hospital_patient_survey: {
+        id: "dgck-syfz",
+        name: "Patient Survey (HCAHPS) - Hospital",
+        description: "HCAHPS patient experience scores: communication, responsiveness, cleanliness, recommendations",
+        theme: "Hospitals",
+    },
+    nursing_home_health_citations: {
+        id: "r5ix-sfxw",
+        name: "Nursing Home Health Deficiencies",
+        description: "Health inspection citations in the last 3 years: tag codes, scope/severity, correction dates",
+        theme: "Nursing homes",
+    },
+    nursing_home_quality: {
+        id: "djen-97ju",
+        name: "Nursing Home Quality Measures (MDS)",
+        description: "Quality measures from the Minimum Data Set: falls, pressure ulcers, pain, UTIs, restraints",
+        theme: "Nursing homes",
+    },
+};
+// ─── Helpers ─────────────────────────────────────────────────────────
+function extractDistributionId(detail) {
+    // Find the first CSV distribution
+    if (detail.distribution?.length) {
+        return detail.distribution[0].identifier ?? null;
+    }
+    return null;
+}
+function simplifyDataset(raw) {
+    const keywords = Array.isArray(raw.keyword)
+        ? raw.keyword.map((k) => (typeof k === "string" ? k : k?.data ?? "")).filter(Boolean)
+        : [];
+    const themes = Array.isArray(raw.theme)
+        ? raw.theme.map((t) => (typeof t === "string" ? t : t?.data ?? "")).filter(Boolean)
+        : [];
+    return {
+        identifier: raw.identifier ?? "",
+        title: raw.title ?? "",
+        description: raw.description ?? "",
+        modified: raw.modified ?? undefined,
+        theme: themes.length ? themes : undefined,
+        keyword: keywords.length ? keywords : undefined,
+    };
+}
+// ─── Public API ──────────────────────────────────────────────────────
+/**
+ * Search CMS Provider Data catalog by keyword.
+ */
+export async function searchDatasets(keyword) {
+    const res = (await api.get("/metastore/schemas/dataset/items", {
+        "show-reference-ids": "",
+    }));
+    if (!Array.isArray(res))
+        return [];
+    // Client-side keyword filter (DKAN API returns all items)
+    const kw = keyword.toLowerCase();
+    const matches = res.filter((item) => {
+        const title = (item.title ?? "").toLowerCase();
+        const desc = (item.description ?? "").toLowerCase();
+        const keywords = Array.isArray(item.keyword)
+            ? item.keyword.map((k) => (typeof k === "string" ? k : k?.data ?? "").toLowerCase())
+            : [];
+        return title.includes(kw) || desc.includes(kw) || keywords.some((k) => k.includes(kw));
+    });
+    return matches.slice(0, 25).map(simplifyDataset);
+}
+/**
+ * Get details for a specific CMS dataset by identifier.
+ */
+export async function getDatasetDetails(datasetId) {
+    try {
+        const res = (await api.get(`/metastore/schemas/dataset/items/${datasetId}`, {
+            "show-reference-ids": "",
+        }));
+        if (!res || !res.identifier)
+            return null;
+        const distributions = Array.isArray(res.distribution)
+            ? res.distribution.map((d) => ({
+                identifier: d?.identifier ?? d?.data?.identifier ?? "",
+                downloadURL: d?.data?.downloadURL ?? d?.downloadURL ?? "",
+                mediaType: d?.data?.mediaType ?? d?.mediaType ?? "",
+            }))
+            : [];
+        return {
+            identifier: res.identifier,
+            title: res.title ?? "",
+            description: res.description ?? "",
+            modified: res.modified ?? undefined,
+            distribution: distributions,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Query data from a CMS dataset. The SDK resolves the distribution UUID
+ * automatically from the dataset identifier.
+ */
+export async function queryDataset(opts) {
+    // Look up the dataset key in our catalog
+    const catalogEntry = Object.values(DATASETS).find((d) => d.id === opts.datasetId);
+    const datasetId = catalogEntry?.id ?? opts.datasetId;
+    // Get dataset details to find the distribution UUID
+    const detail = await getDatasetDetails(datasetId);
+    if (!detail) {
+        return { results: [], count: 0 };
+    }
+    const distId = extractDistributionId(detail);
+    if (!distId) {
+        return { results: [], count: 0 };
+    }
+    // Query the DKAN datastore
+    const params = {
+        limit: String(opts.limit ?? 50),
+        offset: String(opts.offset ?? 0),
+    };
+    // Add conditions
+    if (opts.conditions) {
+        opts.conditions.forEach((cond, i) => {
+            params[`conditions[${i}][property]`] = cond.property;
+            params[`conditions[${i}][value]`] = cond.value;
+            if (cond.operator)
+                params[`conditions[${i}][operator]`] = cond.operator;
+        });
+    }
+    const res = (await api.get(`/datastore/query/${distId}/0`, params));
+    const results = Array.isArray(res?.results) ? res.results : [];
+    const count = typeof res?.count === "number" ? res.count : results.length;
+    return { results, count, limit: opts.limit ?? 50, offset: opts.offset ?? 0 };
+}
+/**
+ * Query a dataset using its short key from the DATASETS catalog.
+ */
+export async function queryByKey(key, conditions, limit, offset) {
+    const entry = DATASETS[key];
+    if (!entry) {
+        return { results: [], count: 0 };
+    }
+    return queryDataset({ datasetId: entry.id, conditions, limit, offset });
+}
+/** Clear the CMS SDK cache. */
+export function clearCache() {
+    api.clearCache();
+}
+//# sourceMappingURL=cms.js.map

package/dist/sdk/cms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms.js","sourceRoot":"","sources":["../../src/sdk/cms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,wEAAwE;AAExE,MAAM,GAAG,GAAG,YAAY,CAAC;IACvB,OAAO,EAAE,0CAA0C;IACnD,IAAI,EAAE,KAAK;IACX,SAAS,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;IACtC,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,qDAAqD;CACvF,CAAC,CAAC;AAoCH,wEAAwE;AACxE,qEAAqE;AACrE,uCAAuC;AAEvC,MAAM,CAAC,MAAM,QAAQ,GAAqF;IACxG,aAAa,EAAE;QACb,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,8BAA8B;QACpC,WAAW,EAAE,2GAA2G;QACxH,KAAK,EAAE,WAAW;KACnB;IACD,iBAAiB,EAAE;QACjB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,mCAAmC;QACzC,WAAW,EAAE,kFAAkF;QAC/F,KAAK,EAAE,eAAe;KACvB;IACD,gBAAgB,EAAE;QAChB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,gCAAgC;QACtC,WAAW,EAAE,sEAAsE;QACnF,KAAK,EAAE,sBAAsB;KAC9B;IACD,YAAY,EAAE;QACZ,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,6BAA6B;QACnC,WAAW,EAAE,gEAAgE;QAC7E,KAAK,EAAE,cAAc;KACtB;IACD,aAAa,EAAE;QACb,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,+BAA+B;QACrC,WAAW,EAAE,oEAAoE;QACjF,KAAK,EAAE,qBAAqB;KAC7B;IACD,kBAAkB,EAAE;QAClB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,qCAAqC;QAC3C,WAAW,EAAE,mFAAmF;QAChG,KAAK,EAAE,WAAW;KACnB;IACD,qBAAqB,EAAE;QACrB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,yCAAyC;QAC/C,WAAW,EAAE,gEAAgE;QAC7E,KAAK,EAAE,WAAW;KACnB;IACD,mBAAmB,EAAE;QACnB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,6CAA6C;QACnD,WAAW,EAAE,uEAAuE;QACpF,KAAK,EAAE,WAAW;KACnB;IACD,oBAAoB,EAAE;QACpB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,sCAAsC;QAC5C,WAAW,EAAE,iFAAiF;QAC9F,KAAK,EAAE,WAAW;KACnB;IACD,iBAAiB,EAAE;QACjB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,8CAA8C;QACpD,WAAW,EAAE,oEAAoE;QACjF,KAAK,EAAE,WAAW;KACnB;IACD,uBAAuB,EAAE;QACvB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,oCAAoC;QAC1C,WAAW,EAAE,+FAA+F;QAC5G,KAAK,EAAE,WAAW;KACnB;IACD,6BAA6B,EAAE;QAC7B,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,kCAAkC;QACxC,WAAW,EAAE,8FAA8F;QAC3G,KAAK,EAAE,eAAe;KACvB;IACD,oBAAoB,EAAE;QACpB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,qCAAqC;QAC3C,WAAW,EAAE,4FAA4F;QACzG,KAAK,EAAE,eAAe;KACvB;CACF,CAAC;AAEF,wEAAwE;AAExE,SAAS,qBAAqB,CAAC,MAAwB;IACrD,kCAAkC;IAClC,IAAI,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC;IACnD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,eAAe,CAAC,GAA4B;IACnD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QACzC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QAC1F,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;QACrC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QACxF,CAAC,CAAC,EAAE,CAAC;IACP,OAAO;QACL,UAAU,EAAG,GAAG,CAAC,UAAqB,IAAI,EAAE;QAC5C,KAAK,EAAG,GAAG,CAAC,KAAgB,IAAI,EAAE;QAClC,WAAW,EAAG,GAAG,CAAC,WAAsB,IAAI,EAAE;QAC9C,QAAQ,EAAG,GAAG,CAAC,QAAmB,IAAI,SAAS;QAC/C,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACzC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;KAChD,CAAC;AACJ,CAAC;AAED,wEAAwE;AAExE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe;IAClD,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,kCAAkC,EAAE;QAC7D,oBAAoB,EAAE,EAAE;KACzB,CAAC,CAA8B,CAAC;IAEjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,0DAA0D;IAC1D,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAClC,MAAM,KAAK,GAAG,CAAE,IAAI,CAAC,KAAgB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3D,MAAM,IAAI,GAAG,CAAE,IAAI,CAAC,WAAsB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAChE,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;YAC1C,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;YACzF,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IACjG,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAiB;IACvD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,oCAAoC,SAAS,EAAE,EAAE;YAC1E,oBAAoB,EAAE,EAAE;SACzB,CAAC,CAA4B,CAAC;QAC/B,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAEzC,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;YACnD,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;gBAChC,UAAU,EAAE,CAAC,EAAE,UAAU,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,IAAI,EAAE;gBACtD,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,IAAI,CAAC,EAAE,WAAW,IAAI,EAAE;gBACzD,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,IAAI,CAAC,EAAE,SAAS,IAAI,EAAE;aACpD,CAAC,CAAC;YACL,CAAC,CAAC,EAAE,CAAC;QAEP,OAAO;YACL,UAAU,EAAE,GAAG,CAAC,UAAoB;YACpC,KAAK,EAAG,GAAG,CAAC,KAAgB,IAAI,EAAE;YAClC,WAAW,EAAG,GAAG,CAAC,WAAsB,IAAI,EAAE;YAC9C,QAAQ,EAAG,GAAG,CAAC,QAAmB,IAAI,SAAS;YAC/C,YAAY,EAAE,aAAa;SAC5B,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAKlC;IACC,yCAAyC;IACzC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC;IAClF,MAAM,SAAS,GAAG,YAAY,EAAE,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC;IAErD,oDAAoD;IACpD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACnC,CAAC;IAED,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAa,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACnC,CAAC;IAED,2BAA2B;IAC3B,MAAM,MAAM,GAA2B;QACrC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;KACjC,CAAC;IAEF,iBAAiB;IACjB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YAClC,MAAM,CAAC,cAAc,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YACrD,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;YAC/C,IAAI,IAAI,CAAC,QAAQ;gBAAE,MAAM,CAAC,cAAc,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC1E,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,oBAAoB,MAAM,IAAI,EAAE,MAAM,CAAC,CAA4B,CAAC;IAC/F,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,OAAqC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9F,MAAM,KAAK,GAAG,OAAO,GAAG,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IAE1E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;AAC/E,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAW,EACX,UAA0E,EAC1E,KAAc,EACd,MAAe;IAEf,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACnC,CAAC;IACD,OAAO,YAAY,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,UAAU;IACxB,GAAG,CAAC,UAAU,EAAE,CAAC;AACnB,CAAC"}

package/dist/sdk/college-scorecard.d.ts

@@ -0,0 +1,63 @@
+/**
+ * College Scorecard SDK — typed API client for the U.S. Department of Education College Scorecard API.
+ *
+ * API docs: https://collegescorecard.ed.gov/data/documentation/
+ * GitHub: https://github.com/RTICWDT/open-data-maker/blob/master/API.md
+ * Requires DATA_GOV_API_KEY (same key used for FBI/GovInfo — get one at https://api.data.gov/signup).
+ *
+ * Usage:
+ *   import { searchSchools, getSchoolById } from "us-gov-open-data-mcp/sdk/college-scorecard";
+ *   const results = await searchSchools({ name: "MIT", fields: POPULAR_FIELDS });
+ */
+export interface ScorecardResponse {
+    metadata: {
+        page: number;
+        total: number;
+        per_page: number;
+    };
+    results: ScorecardSchool[];
+}
+export interface ScorecardSchool {
+    id?: number;
+    [key: string]: unknown;
+}
+/** Commonly requested fields for College Scorecard queries. */
+export declare const POPULAR_FIELDS: string;
+/** School ownership types */
+export declare const OWNERSHIP: Record<number, string>;
+/** Predominant degree types */
+export declare const DEGREE_TYPES: Record<number, string>;
+/** State FIPS to abbreviation for filtering */
+export declare const STATE_FIPS: Record<string, number>;
+/** Search for schools by name, state, or other criteria. */
+export declare function searchSchools(opts: {
+    name?: string;
+    state?: string;
+    ownership?: number;
+    degreePredominant?: number;
+    fields?: string;
+    perPage?: number;
+    page?: number;
+    sort?: string;
+}): Promise<ScorecardResponse>;
+/** Get a specific school by its College Scorecard ID. */
+export declare function getSchoolById(id: number, fields?: string): Promise<ScorecardResponse>;
+/** Search for schools with custom field filters and ranges. */
+export declare function querySchools(params: Record<string, string | number | undefined>): Promise<ScorecardResponse>;
+/** Get the most expensive schools. */
+export declare function getMostExpensive(opts?: {
+    ownership?: number;
+    perPage?: number;
+}): Promise<ScorecardResponse>;
+/** Get schools with the highest earnings after graduation. */
+export declare function getHighestEarners(opts?: {
+    ownership?: number;
+    perPage?: number;
+}): Promise<ScorecardResponse>;
+/** Get schools with the highest completion (graduation) rates. */
+export declare function getHighestGraduationRates(opts?: {
+    state?: string;
+    perPage?: number;
+}): Promise<ScorecardResponse>;
+export declare function clearCache(): void;
+//# sourceMappingURL=college-scorecard.d.ts.map

package/dist/sdk/college-scorecard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"college-scorecard.d.ts","sourceRoot":"","sources":["../../src/sdk/college-scorecard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAeH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID,+DAA+D;AAC/D,eAAO,MAAM,cAAc,QAqBhB,CAAC;AAEZ,6BAA6B;AAC7B,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI5C,CAAC;AAEF,+BAA+B;AAC/B,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAM/C,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO7C,CAAC;AAIF,4DAA4D;AAC5D,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAa7B;AAED,yDAAyD;AACzD,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAK3F;AAED,+DAA+D;AAC/D,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAIlH;AAED,sCAAsC;AACtC,wBAAsB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CACtC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAO7B;AAED,8DAA8D;AAC9D,wBAAsB,iBAAiB,CAAC,IAAI,CAAC,EAAE;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CACtC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAO7B;AAED,kEAAkE;AAClE,wBAAsB,yBAAyB,CAAC,IAAI,CAAC,EAAE;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAO7B;AAED,wBAAgB,UAAU,IAAI,IAAI,CAAsB"}

package/dist/sdk/college-scorecard.js

@@ -0,0 +1,131 @@
+/**
+ * College Scorecard SDK — typed API client for the U.S. Department of Education College Scorecard API.
+ *
+ * API docs: https://collegescorecard.ed.gov/data/documentation/
+ * GitHub: https://github.com/RTICWDT/open-data-maker/blob/master/API.md
+ * Requires DATA_GOV_API_KEY (same key used for FBI/GovInfo — get one at https://api.data.gov/signup).
+ *
+ * Usage:
+ *   import { searchSchools, getSchoolById } from "us-gov-open-data-mcp/sdk/college-scorecard";
+ *   const results = await searchSchools({ name: "MIT", fields: POPULAR_FIELDS });
+ */
+import { createClient } from "../client.js";
+const api = createClient({
+    baseUrl: "https://api.data.gov/ed/collegescorecard/v1",
+    name: "college-scorecard",
+    auth: { type: "query", key: "api_key", envVar: "DATA_GOV_API_KEY" },
+    rateLimit: { perSecond: 5, burst: 15 },
+    cacheTtlMs: 24 * 60 * 60 * 1000, // 24 hours — data updates annually
+    timeoutMs: 30_000,
+});
+// ─── Reference Data ──────────────────────────────────────────────────
+/** Commonly requested fields for College Scorecard queries. */
+export const POPULAR_FIELDS = [
+    "id",
+    "school.name",
+    "school.state",
+    "school.city",
+    "school.school_url",
+    "school.ownership", // 1=public, 2=private nonprofit, 3=private for-profit
+    "school.degrees_awarded.predominant", // 1=certificate, 2=associate, 3=bachelor's, 4=graduate
+    "latest.admissions.admission_rate.overall",
+    "latest.student.size",
+    "latest.cost.tuition.in_state",
+    "latest.cost.tuition.out_of_state",
+    "latest.cost.avg_net_price.overall",
+    "latest.aid.median_debt.completers.overall",
+    "latest.aid.pell_grant_rate",
+    "latest.completion.rate_suppressed.overall",
+    "latest.earnings.10_yrs_after_entry.median",
+    "latest.earnings.6_yrs_after_entry.median",
+    "latest.student.demographics.race_ethnicity.white",
+    "latest.student.demographics.race_ethnicity.black",
+    "latest.student.demographics.race_ethnicity.hispanic",
+].join(",");
+/** School ownership types */
+export const OWNERSHIP = {
+    1: "Public",
+    2: "Private nonprofit",
+    3: "Private for-profit",
+};
+/** Predominant degree types */
+export const DEGREE_TYPES = {
+    0: "Not classified",
+    1: "Certificate",
+    2: "Associate",
+    3: "Bachelor's",
+    4: "Graduate",
+};
+/** State FIPS to abbreviation for filtering */
+export const STATE_FIPS = {
+    AL: 1, AK: 2, AZ: 4, AR: 5, CA: 6, CO: 8, CT: 9, DE: 10, DC: 11, FL: 12,
+    GA: 13, HI: 15, ID: 16, IL: 17, IN: 18, IA: 19, KS: 20, KY: 21, LA: 22,
+    ME: 23, MD: 24, MA: 25, MI: 26, MN: 27, MS: 28, MO: 29, MT: 30, NE: 31,
+    NV: 32, NH: 33, NJ: 34, NM: 35, NY: 36, NC: 37, ND: 38, OH: 39, OK: 40,
+    OR: 41, PA: 42, RI: 44, SC: 45, SD: 46, TN: 47, TX: 48, UT: 49, VT: 50,
+    VA: 51, WA: 53, WV: 54, WI: 55, WY: 56,
+};
+// ─── Public API ──────────────────────────────────────────────────────
+/** Search for schools by name, state, or other criteria. */
+export async function searchSchools(opts) {
+    const params = {
+        _fields: opts.fields || POPULAR_FIELDS,
+        per_page: opts.perPage || 20,
+        page: opts.page || 0,
+    };
+    if (opts.name)
+        params["school.name"] = opts.name;
+    if (opts.state)
+        params["school.state"] = opts.state;
+    if (opts.ownership !== undefined)
+        params["school.ownership"] = opts.ownership;
+    if (opts.degreePredominant !== undefined)
+        params["school.degrees_awarded.predominant"] = opts.degreePredominant;
+    if (opts.sort)
+        params.sort = opts.sort;
+    return api.get("/schools.json", params);
+}
+/** Get a specific school by its College Scorecard ID. */
+export async function getSchoolById(id, fields) {
+    return api.get("/schools.json", {
+        id,
+        _fields: fields || POPULAR_FIELDS,
+    });
+}
+/** Search for schools with custom field filters and ranges. */
+export async function querySchools(params) {
+    if (!params._fields)
+        params._fields = POPULAR_FIELDS;
+    if (!params.per_page)
+        params.per_page = 20;
+    return api.get("/schools.json", params);
+}
+/** Get the most expensive schools. */
+export async function getMostExpensive(opts) {
+    return searchSchools({
+        degreePredominant: 3, // bachelor's
+        ownership: opts?.ownership,
+        perPage: opts?.perPage || 20,
+        sort: "latest.cost.tuition.out_of_state:desc",
+    });
+}
+/** Get schools with the highest earnings after graduation. */
+export async function getHighestEarners(opts) {
+    return searchSchools({
+        degreePredominant: 3,
+        ownership: opts?.ownership,
+        perPage: opts?.perPage || 20,
+        sort: "latest.earnings.10_yrs_after_entry.median:desc",
+    });
+}
+/** Get schools with the highest completion (graduation) rates. */
+export async function getHighestGraduationRates(opts) {
+    return searchSchools({
+        degreePredominant: 3,
+        state: opts?.state,
+        perPage: opts?.perPage || 20,
+        sort: "latest.completion.rate_suppressed.overall:desc",
+    });
+}
+export function clearCache() { api.clearCache(); }
+//# sourceMappingURL=college-scorecard.js.map

package/dist/sdk/college-scorecard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"college-scorecard.js","sourceRoot":"","sources":["../../src/sdk/college-scorecard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,GAAG,GAAG,YAAY,CAAC;IACvB,OAAO,EAAE,6CAA6C;IACtD,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE;IACnE,SAAS,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;IACtC,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,mCAAmC;IACpE,SAAS,EAAE,MAAM;CAClB,CAAC,CAAC;AAcH,wEAAwE;AAExE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI;IACJ,aAAa;IACb,cAAc;IACd,aAAa;IACb,mBAAmB;IACnB,kBAAkB,EAAE,sDAAsD;IAC1E,oCAAoC,EAAE,uDAAuD;IAC7F,0CAA0C;IAC1C,qBAAqB;IACrB,8BAA8B;IAC9B,kCAAkC;IAClC,mCAAmC;IACnC,2CAA2C;IAC3C,4BAA4B;IAC5B,2CAA2C;IAC3C,2CAA2C;IAC3C,0CAA0C;IAC1C,kDAAkD;IAClD,kDAAkD;IAClD,qDAAqD;CACtD,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,6BAA6B;AAC7B,MAAM,CAAC,MAAM,SAAS,GAA2B;IAC/C,CAAC,EAAE,QAAQ;IACX,CAAC,EAAE,mBAAmB;IACtB,CAAC,EAAE,oBAAoB;CACxB,CAAC;AAEF,+BAA+B;AAC/B,MAAM,CAAC,MAAM,YAAY,GAA2B;IAClD,CAAC,EAAE,gBAAgB;IACnB,CAAC,EAAE,aAAa;IAChB,CAAC,EAAE,WAAW;IACd,CAAC,EAAE,YAAY;IACf,CAAC,EAAE,UAAU;CACd,CAAC;AAEF,+CAA+C;AAC/C,MAAM,CAAC,MAAM,UAAU,GAA2B;IAChD,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;IACvE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;IACtE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;IACtE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;IACtE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;IACtE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;CACvC,CAAC;AAEF,wEAAwE;AAExE,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IASnC;IACC,MAAM,MAAM,GAAgD;QAC1D,OAAO,EAAE,IAAI,CAAC,MAAM,IAAI,cAAc;QACtC,QAAQ,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE;QAC5B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC;KACrB,CAAC;IACF,IAAI,IAAI,CAAC,IAAI;QAAE,MAAM,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;IACjD,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IACpD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,MAAM,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;IAC9E,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS;QAAE,MAAM,CAAC,oCAAoC,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC;IAChH,IAAI,IAAI,CAAC,IAAI;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IAEvC,OAAO,GAAG,CAAC,GAAG,CAAoB,eAAe,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAU,EAAE,MAAe;IAC7D,OAAO,GAAG,CAAC,GAAG,CAAoB,eAAe,EAAE;QACjD,EAAE;QACF,OAAO,EAAE,MAAM,IAAI,cAAc;KAClC,CAAC,CAAC;AACL,CAAC;AAED,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAmD;IACpF,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,MAAM,CAAC,OAAO,GAAG,cAAc,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,QAAQ;QAAE,MAAM,CAAC,QAAQ,GAAG,EAAE,CAAC;IAC3C,OAAO,GAAG,CAAC,GAAG,CAAoB,eAAe,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC;AAED,sCAAsC;AACtC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAEtC;IACC,OAAO,aAAa,CAAC;QACnB,iBAAiB,EAAE,CAAC,EAAE,aAAa;QACnC,SAAS,EAAE,IAAI,EAAE,SAAS;QAC1B,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE;QAC5B,IAAI,EAAE,uCAAuC;KAC9C,CAAC,CAAC;AACL,CAAC;AAED,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAEvC;IACC,OAAO,aAAa,CAAC;QACnB,iBAAiB,EAAE,CAAC;QACpB,SAAS,EAAE,IAAI,EAAE,SAAS;QAC1B,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE;QAC5B,IAAI,EAAE,gDAAgD;KACvD,CAAC,CAAC;AACL,CAAC;AAED,kEAAkE;AAClE,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,IAE/C;IACC,OAAO,aAAa,CAAC;QACnB,iBAAiB,EAAE,CAAC;QACpB,KAAK,EAAE,IAAI,EAAE,KAAK;QAClB,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE;QAC5B,IAAI,EAAE,gDAAgD;KACvD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,UAAU,KAAW,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC"}