college-roi-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LE TEEN (le-teen.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# college-roi-mcp
+
+MCP server for U.S. college-ROI data: 30-year net present value (NPV) for **500 four-year colleges**, lifetime ROI for **19 major categories + 115 CIP subfields**, per-state **best-value rankings**, and the **out-of-state tuition penalty** ranking.
+
+Wraps the free, keyless [LE TEEN College ROI API](https://le-teen.com/api) (static JSON, CC BY 4.0). No API key, no signup, no rate limits beyond CDN sanity. Data derives from FREOPP program-level ROI estimates, IPEDS institutional data, and BEA price deflators — methodology at [le-teen.com/methodology](https://le-teen.com/methodology). Dataset DOI: [10.5281/zenodo.21351602](https://doi.org/10.5281/zenodo.21351602).
+
+## Install
+
+Requires Node ≥ 18.
+
+**Claude Desktop / Claude Code** (`claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "college-roi": {
+      "command": "npx",
+      "args": ["-y", "college-roi-mcp"]
+    }
+  }
+}
+```
+
+**Claude Code CLI:**
+
+```sh
+claude mcp add college-roi -- npx -y college-roi-mcp
+```
+
+Any other MCP client: run `npx -y college-roi-mcp` over stdio.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `list_majors` | Compact ROI rows for 19 categories / 115 subfields — median & mean lifetime ROI, % never break even, break-even age, AI-exposure band. Filter by kind/parent, sort, limit. |
+| `get_major` | Full record for one major: ROI distribution (p25/median/mean/p75), completion-adjusted & dropout ROI, graduates/programs, AI-exposure detail. |
+| `search_colleges` | Search the 500 positive-NPV-envelope colleges by name/state/control — resident & non-resident 30-yr NPV, cost of attendance, median earnings, break-even age. |
+| `get_college` | Full record for one college, incl. IPEDS unitid and FREOPP coverage. |
+| `best_value_colleges` | Each state's best-value four-years at resident pricing (top 15 per state), or a nationwide top-pick summary. |
+| `out_of_state_penalty` | Public four-years ranked by how much 30-yr NPV a non-resident gives up vs a resident. |
+| `get_api_info` | Metadata for the underlying API: endpoints, license, DOI, attribution. |
+
+All dollar figures are lifetime/30-year totals in USD. List responses are compact projections with `limit` controls so they stay small in agent contexts; detail tools return the full upstream record.
+
+Note the envelope: only colleges that clear a positive-NPV bar appear (500 of ~1,656 U.S. four-years). A school being *absent* is itself a signal.
+
+## Example prompts
+
+- "Is a nursing degree worth it compared to computer science?"
+- "Best-value colleges in Michigan for a resident."
+- "How much does going out-of-state to UVA cost me over 30 years?"
+- "Which majors have the worst odds of ever breaking even?"
+
+## Data freshness & caching
+
+The upstream API is static JSON regenerated with the dataset; this server caches responses in-process for 24 h (matching the API's CDN cache). Nothing is written anywhere; the server is read-only.
+
+## License & attribution
+
+- **Code:** MIT.
+- **Data:** CC BY 4.0 — free to use with attribution. Cite **LE TEEN, le-teen.com** (and FREOPP/IPEDS/BEA as upstream sources).

package/dist/index.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * college-roi-mcp — MCP server over the LE TEEN College ROI API (le-teen.com/api).
+ *
+ * Wraps the free, keyless, CC BY 4.0 static-JSON API: 30-year NPV for 500 U.S.
+ * four-year colleges, lifetime ROI for 19 major categories + 115 CIP subfields,
+ * and the standing rankings. Read-only; no auth; data fetched live and cached
+ * in-process for 24h (matching the API's CDN cache).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_BASE = "https://le-teen.com/api/v1";
+const ATTRIBUTION = "Data: LE TEEN College ROI API (le-teen.com/api), CC BY 4.0. Upstream sources: FREOPP, IPEDS, BEA. DOI: 10.5281/zenodo.21351602";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Fetch + cache
+// ---------------------------------------------------------------------------
+const cache = new Map();
+async function apiGet(path) {
+    const hit = cache.get(path);
+    if (hit && Date.now() - hit.at < CACHE_TTL_MS)
+        return hit.data;
+    const res = await fetch(`${API_BASE}${path}`, {
+        headers: { "user-agent": "college-roi-mcp/1.0 (+https://github.com/thomasthinks/college-roi-mcp)" },
+    });
+    if (res.status === 404) {
+        throw new NotFoundError(path);
+    }
+    if (!res.ok) {
+        throw new Error(`API request failed: ${res.status} ${res.statusText} for ${path}`);
+    }
+    const data = await res.json();
+    cache.set(path, { at: Date.now(), data });
+    return data;
+}
+class NotFoundError extends Error {
+    constructor(path) {
+        super(`Not found: ${path}`);
+    }
+}
+function ok(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 1) }] };
+}
+function err(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/&/g, "and")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({ name: "college-roi-mcp", version: "1.0.0" }, {
+    instructions: "Query U.S. college-ROI data: 30-year net present value (NPV) for 500 four-year colleges, " +
+        "lifetime ROI for 19 bachelor's-degree major categories and 115 CIP subfields, per-state " +
+        "best-value rankings, and the out-of-state tuition penalty ranking. All dollar figures are " +
+        "lifetime/30-year totals in USD. Start with list_majors or search_colleges to find slugs, " +
+        `then get_major / get_college for full detail. ${ATTRIBUTION}`,
+});
+// --- get_api_info -----------------------------------------------------------
+server.registerTool("get_api_info", {
+    title: "About the College ROI API",
+    description: "Metadata for the underlying LE TEEN College ROI API: description, license, attribution, DOI, docs URL, and the list of raw endpoints.",
+    inputSchema: {},
+}, async () => {
+    const idx = await apiGet("/index.json");
+    return ok(idx);
+});
+// --- list_majors -------------------------------------------------------------
+server.registerTool("list_majors", {
+    title: "List majors by lifetime ROI",
+    description: "List bachelor's-degree majors (19 broad categories and/or 115 CIP subfields) with lifetime-ROI stats: " +
+        "median/mean lifetime ROI (USD), % of programs that never break even, median break-even age, and AI-exposure band. " +
+        "Returns compact rows sorted by the chosen field. Use the returned slug with get_major for full detail.",
+    inputSchema: {
+        kind: z.enum(["category", "subfield", "all"]).default("all")
+            .describe("Filter to broad categories (19), CIP subfields (115), or all 134."),
+        parent: z.string().optional()
+            .describe("Only subfields of this category slug, e.g. 'engineering'."),
+        sort_by: z
+            .enum(["median_lifetime_roi_usd", "mean_lifetime_roi_usd", "pct_never_breakeven", "graduates", "name"])
+            .default("median_lifetime_roi_usd")
+            .describe("Sort field. ROI sorts are descending; name ascending."),
+        limit: z.number().int().min(1).max(150).default(50).describe("Max rows returned."),
+    },
+}, async ({ kind, parent, sort_by, limit }) => {
+    const data = await apiGet("/majors.json");
+    let rows = data.majors;
+    if (kind !== "all")
+        rows = rows.filter((m) => m.kind === kind);
+    if (parent) {
+        const p = slugify(parent);
+        rows = rows.filter((m) => m.parent?.slug === p);
+    }
+    rows = [...rows].sort((a, b) => sort_by === "name" ? String(a.name).localeCompare(String(b.name)) : (b[sort_by] ?? -Infinity) - (a[sort_by] ?? -Infinity));
+    const total = rows.length;
+    const majors = rows.slice(0, limit).map((m) => ({
+        slug: m.slug,
+        kind: m.kind,
+        name: m.name,
+        parent: m.parent?.slug ?? null,
+        median_lifetime_roi_usd: m.median_lifetime_roi_usd,
+        mean_lifetime_roi_usd: m.mean_lifetime_roi_usd,
+        pct_never_breakeven: m.pct_never_breakeven,
+        median_breakeven_age: m.median_breakeven_age,
+        graduates: m.graduates,
+        ai_exposure_band: m.ai_exposure?.band ?? null,
+    }));
+    return ok({ total_matching: total, returned: majors.length, majors, attribution: ATTRIBUTION });
+});
+// --- get_major ----------------------------------------------------------------
+server.registerTool("get_major", {
+    title: "Get one major's full ROI detail",
+    description: "Full lifetime-ROI record for one major category or CIP subfield by slug (e.g. 'nursing', 'computer-science', " +
+        "'philosophy-and-religious-studies'): ROI distribution (p25/median/mean/p75), never-break-even %, break-even age, " +
+        "completion-adjusted and dropout ROI, graduates/programs counts, and AI-exposure detail. " +
+        "Accepts a plain name and will slugify it; use list_majors to discover exact slugs.",
+    inputSchema: {
+        slug: z.string().describe("Major slug or name, e.g. 'computer-science' or 'Computer Science'."),
+    },
+}, async ({ slug }) => {
+    const s = slugify(slug);
+    try {
+        return ok({ ...(await apiGet(`/majors/${s}.json`)), attribution: ATTRIBUTION });
+    }
+    catch (e) {
+        if (e instanceof NotFoundError) {
+            const data = await apiGet("/majors.json");
+            const near = data.majors
+                .filter((m) => m.slug.includes(s) || s.includes(m.slug) || m.name.toLowerCase().includes(slug.toLowerCase()))
+                .slice(0, 8)
+                .map((m) => m.slug);
+            return err(`No major with slug '${s}'.${near.length ? ` Did you mean: ${near.join(", ")}` : " Use list_majors to browse slugs."}`);
+        }
+        throw e;
+    }
+});
+// --- search_colleges -----------------------------------------------------------
+server.registerTool("search_colleges", {
+    title: "Search colleges by name/state",
+    description: "Search the 500 largest-coverage U.S. four-year colleges that clear the positive-NPV envelope. " +
+        "Each row: 30-year NPV at resident and non-resident pricing, total cost of attendance, median earnings 10 years " +
+        "after entry, and break-even age. Filter by name substring, state, and control; sorted by resident NPV descending " +
+        "unless overridden. Use the returned slug with get_college.",
+    inputSchema: {
+        query: z.string().optional().describe("Case-insensitive substring of the college name."),
+        state: z.string().length(2).optional().describe("Two-letter state code, e.g. 'MI'."),
+        control: z.enum(["public", "private-nonprofit", "private-forprofit"]).optional(),
+        sort_by: z
+            .enum(["npv_30yr_resident_usd", "npv_30yr_nonresident_usd", "median_earnings_10yr_usd", "total_cost_of_attendance_usd", "name"])
+            .default("npv_30yr_resident_usd"),
+        limit: z.number().int().min(1).max(100).default(25).describe("Max rows returned."),
+    },
+}, async ({ query, state, control, sort_by, limit }) => {
+    const data = await apiGet("/colleges.json");
+    let rows = data.colleges;
+    if (query) {
+        // Token-AND matching so partial names work ("cal poly" matches
+        // "California Polytechnic State University-San Luis Obispo").
+        const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+        rows = rows.filter((c) => {
+            const hay = `${c.name} ${c.city ?? ""}`.toLowerCase();
+            return tokens.every((t) => hay.includes(t));
+        });
+    }
+    if (state)
+        rows = rows.filter((c) => c.state === state.toUpperCase());
+    if (control)
+        rows = rows.filter((c) => c.control === control);
+    rows = [...rows].sort((a, b) => sort_by === "name" ? String(a.name).localeCompare(String(b.name)) : (b[sort_by] ?? -Infinity) - (a[sort_by] ?? -Infinity));
+    const total = rows.length;
+    const colleges = rows.slice(0, limit);
+    return ok({
+        total_matching: total,
+        returned: colleges.length,
+        note: "Only colleges clearing the positive-NPV envelope are listed (500 of ~1,656 four-years). Absence from this list is itself a signal.",
+        colleges,
+        attribution: ATTRIBUTION,
+    });
+});
+// --- get_college -----------------------------------------------------------------
+server.registerTool("get_college", {
+    title: "Get one college's full record",
+    description: "Full record for one college by slug (e.g. 'university-of-michigan-ann-arbor'): 30-year NPV at resident and " +
+        "non-resident pricing, total cost of attendance both ways, median earnings 10 years after entry, break-even age, " +
+        "IPEDS unitid, and FREOPP program coverage. Accepts a plain name and will slugify it; use search_colleges to discover slugs.",
+    inputSchema: {
+        slug: z.string().describe("College slug or name, e.g. 'university-of-michigan-ann-arbor'."),
+    },
+}, async ({ slug }) => {
+    const s = slugify(slug);
+    try {
+        return ok({ ...(await apiGet(`/colleges/${s}.json`)), attribution: ATTRIBUTION });
+    }
+    catch (e) {
+        if (e instanceof NotFoundError) {
+            const data = await apiGet("/colleges.json");
+            const q = slug.toLowerCase();
+            const near = data.colleges
+                .filter((c) => c.slug.includes(s) || c.name.toLowerCase().includes(q))
+                .slice(0, 8)
+                .map((c) => c.slug);
+            return err(`No college with slug '${s}'.${near.length ? ` Did you mean: ${near.join(", ")}` : " Note: only the 500 positive-NPV-envelope colleges are covered; use search_colleges to browse."}`);
+        }
+        throw e;
+    }
+});
+// --- best_value_colleges -----------------------------------------------------------
+server.registerTool("best_value_colleges", {
+    title: "Best-value colleges by state",
+    description: "Each U.S. state's best-value four-year colleges at resident pricing, ranked by 30-year NPV (top 15 per state). " +
+        "Pass a state for its full list; omit it for a nationwide summary (every state's top pick).",
+    inputSchema: {
+        state: z.string().length(2).optional().describe("Two-letter state code, e.g. 'CA'. Omit for all states' #1."),
+    },
+}, async ({ state }) => {
+    const data = await apiGet("/rankings/best-value.json");
+    if (state) {
+        const st = data.states.find((s) => s.state === state.toUpperCase());
+        if (!st)
+            return err(`No ranking for state '${state}'. Use a two-letter USPS code.`);
+        return ok({ ...st, attribution: ATTRIBUTION });
+    }
+    const summary = data.states.map((s) => ({
+        state: s.state,
+        state_name: s.state_name,
+        top_college: s.colleges[0],
+    }));
+    return ok({ title: data.title, states: summary, note: "Pass state for the full top-15 list.", attribution: ATTRIBUTION });
+});
+// --- out_of_state_penalty ------------------------------------------------------------
+server.registerTool("out_of_state_penalty", {
+    title: "Out-of-state tuition penalty ranking",
+    description: "U.S. public four-year colleges ranked by the out-of-state penalty: how much 30-year NPV a non-resident gives up " +
+        "versus a resident at the same school. Includes both NPVs and both tuition figures per row.",
+    inputSchema: {
+        limit: z.number().int().min(1).max(100).default(25).describe("Max rows returned (77 total)."),
+        state: z.string().length(2).optional().describe("Filter to one state's public colleges."),
+    },
+}, async ({ limit, state }) => {
+    const data = await apiGet("/rankings/out-of-state-penalty.json");
+    let rows = data.rankings;
+    if (state)
+        rows = rows.filter((r) => r.state === state.toUpperCase());
+    return ok({
+        title: data.title,
+        total_matching: rows.length,
+        returned: Math.min(rows.length, limit),
+        rankings: rows.slice(0, limit),
+        attribution: ATTRIBUTION,
+    });
+});
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("college-roi-mcp running on stdio");
+}
+main().catch((e) => {
+    console.error("Fatal:", e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "college-roi-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for U.S. college ROI data: 30-year NPV for 500 colleges, lifetime ROI for 134 majors, best-value and out-of-state-penalty rankings. Free, keyless, CC BY 4.0.",
+  "license": "MIT",
+  "mcpName": "io.github.thomasthinks/college-roi-mcp",
+  "type": "module",
+  "bin": {
+    "college-roi-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "college",
+    "roi",
+    "education",
+    "tuition",
+    "npv",
+    "earnings",
+    "dataset"
+  ],
+  "author": "LE TEEN (https://le-teen.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomasthinks/college-roi-mcp.git"
+  },
+  "homepage": "https://le-teen.com/api",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0"
+  }
+}