@cyanheads/college-scorecard-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/search-schools.tool.js

@@ -0,0 +1,223 @@
+/**
+ * @fileoverview School search tool. Searches and filters institutions by name, location,
+ * type, size, and acceptance rate range.
+ * @module mcp-server/tools/definitions/search-schools.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { degreeLevelLabel, ownershipLabel } from '../../../mcp-server/format-helpers.js';
+import { getScorecardService } from '../../../services/scorecard/scorecard-service.js';
+export const searchSchoolsTool = tool('scorecard_search_schools', {
+    title: 'Search Schools',
+    description: 'Search and filter U.S. colleges and universities by name, location, type, size, and acceptance rate. Returns a list with core identity and cost metrics for each match. For a full institutional profile use scorecard_get_school; for cross-institution program rankings use scorecard_search_programs. Geographic filtering requires a U.S. zip code and a distance string (e.g. "50mi"). State filter uses two-letter codes (e.g. "WA", "CA"). Ownership: 1=public, 2=private nonprofit, 3=for-profit. Degree level: 0=non-degree, 1=certificate, 2=associate, 3=bachelor, 4=graduate.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        query: z
+            .string()
+            .optional()
+            .describe('School name search — partial or full name; all words must appear.'),
+        state: z
+            .string()
+            .length(2)
+            .optional()
+            .describe('Filter to schools in this state (two-letter code, e.g. "WA").'),
+        ownership: z
+            .number()
+            .int()
+            .min(1)
+            .max(3)
+            .optional()
+            .describe('Control type: 1=public, 2=private nonprofit, 3=private for-profit.'),
+        degree_level: z
+            .number()
+            .int()
+            .min(0)
+            .max(4)
+            .optional()
+            .describe('Predominant degree: 0=non-degree/certificate, 1=certificate, 2=associate, 3=bachelor, 4=graduate.'),
+        size_range: z
+            .object({
+            min: z.number().int().min(0).describe('Minimum enrollment size.'),
+            max: z.number().int().min(0).describe('Maximum enrollment size.'),
+        })
+            .optional()
+            .describe('Undergraduate enrollment size range. Omit for no size filter.'),
+        acceptance_rate_range: z
+            .object({
+            min: z
+                .number()
+                .min(0)
+                .max(1)
+                .describe('Minimum acceptance rate as a decimal (e.g. 0.1 for 10%).'),
+            max: z
+                .number()
+                .min(0)
+                .max(1)
+                .describe('Maximum acceptance rate as a decimal (e.g. 0.9 for 90%).'),
+        })
+            .optional()
+            .describe('Acceptance rate range as decimals (0–1). Omit for no filter.'),
+        zip: z
+            .string()
+            .optional()
+            .describe('U.S. zip code for geographic center. Requires distance to be set.'),
+        distance: z
+            .string()
+            .optional()
+            .describe('Search radius around zip (e.g. "25mi", "50km"). Requires zip to be set.'),
+        cip_code: z
+            .string()
+            .optional()
+            .describe('Filter to schools offering this CIP 4-digit program code (e.g. "11.07"). Use scorecard_lookup_cip to find codes.'),
+        per_page: z.number().int().min(1).max(100).default(20).describe('Results per page (max 100).'),
+        page: z.number().int().min(0).default(0).describe('Zero-indexed page number for pagination.'),
+    }),
+    output: z.object({
+        total: z.number().describe('Total institutions matching the filters (before pagination).'),
+        page: z.number().describe('Current page (zero-indexed).'),
+        per_page: z.number().describe('Results per page used.'),
+        schools: z
+            .array(z
+            .object({
+            id: z.number().describe('Unit ID — use for scorecard_get_school lookups.'),
+            name: z.string().describe('Institution name.'),
+            city: z.string().optional().describe('City.'),
+            state: z.string().optional().describe('State code.'),
+            ownership: z
+                .string()
+                .describe('Control type: Public, Private nonprofit, or For-profit.'),
+            degree_level: z.string().describe('Predominant degree awarded.'),
+            enrollment: z.number().optional().describe('Undergraduate enrollment.'),
+            admission_rate: z
+                .number()
+                .optional()
+                .describe('Overall admission rate (0–1). Null if not reported.'),
+            tuition_in_state: z.number().optional().describe('In-state tuition and fees.'),
+            tuition_out_of_state: z.number().optional().describe('Out-of-state tuition and fees.'),
+            net_price_overall: z
+                .number()
+                .optional()
+                .describe('Average net price (all income levels).'),
+            median_debt: z.number().optional().describe('Median debt at graduation.'),
+            earnings_6yr_median: z
+                .number()
+                .optional()
+                .describe('Median earnings 6 years after entry.'),
+        })
+            .describe('School summary record.'))
+            .describe('Matching institutions.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results exist.'),
+    }),
+    errors: [
+        {
+            reason: 'no_results',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No institutions matched the provided filters.',
+            recovery: 'Broaden the search by removing filters or widening size and acceptance rate ranges.',
+        },
+        {
+            reason: 'api_error',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The College Scorecard API returned an error.',
+            recovery: 'Check SCORECARD_API_KEY validity and retry after a brief delay.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Searching schools', { query: input.query, state: input.state, page: input.page });
+        const service = getScorecardService();
+        const sizeRange = input.size_range?.min != null && input.size_range?.max != null
+            ? [input.size_range.min, input.size_range.max]
+            : undefined;
+        const acceptanceRateRange = input.acceptance_rate_range?.min != null && input.acceptance_rate_range?.max != null
+            ? [input.acceptance_rate_range.min, input.acceptance_rate_range.max]
+            : undefined;
+        const response = await service.searchSchools({
+            ...(input.query && { name: input.query }),
+            ...(input.state && { state: input.state }),
+            ...(input.ownership != null && { ownership: input.ownership }),
+            ...(input.degree_level != null && { degreeLevel: input.degree_level }),
+            ...(sizeRange && { sizeRange }),
+            ...(acceptanceRateRange && { acceptanceRateRange }),
+            ...(input.zip && { zip: input.zip }),
+            ...(input.distance && { distance: input.distance }),
+            ...(input.cip_code && { cipCode: input.cip_code }),
+            perPage: input.per_page,
+            page: input.page,
+        }, ctx);
+        const schools = response.results.map((r) => ({
+            id: r.id ?? 0,
+            name: r['school.name'] ?? 'Unknown',
+            ...(r['school.city'] && { city: r['school.city'] }),
+            ...(r['school.state'] && { state: r['school.state'] }),
+            ownership: ownershipLabel(r['school.ownership']),
+            degree_level: degreeLevelLabel(r['school.degrees_awarded.predominant']),
+            ...(r['latest.student.size'] != null && { enrollment: r['latest.student.size'] }),
+            ...(r['latest.admissions.admission_rate.overall'] != null && {
+                admission_rate: r['latest.admissions.admission_rate.overall'],
+            }),
+            ...(r['latest.cost.tuition.in_state'] != null && {
+                tuition_in_state: r['latest.cost.tuition.in_state'],
+            }),
+            ...(r['latest.cost.tuition.out_of_state'] != null && {
+                tuition_out_of_state: r['latest.cost.tuition.out_of_state'],
+            }),
+            ...(r['latest.cost.avg_net_price.overall'] != null && {
+                net_price_overall: r['latest.cost.avg_net_price.overall'],
+            }),
+            ...(r['latest.aid.median_debt.completers.overall'] != null && {
+                median_debt: r['latest.aid.median_debt.completers.overall'],
+            }),
+            ...(r['latest.earnings.6_yrs_after_entry.median'] != null && {
+                earnings_6yr_median: r['latest.earnings.6_yrs_after_entry.median'],
+            }),
+        }));
+        const notice = schools.length === 0
+            ? `No schools matched the applied filters. Try removing state, size, or acceptance rate filters.`
+            : undefined;
+        ctx.log.info('School search complete', {
+            total: response.metadata.total,
+            returned: schools.length,
+        });
+        return {
+            total: response.metadata.total,
+            page: response.metadata.page,
+            per_page: response.metadata.per_page,
+            schools,
+            ...(notice && { notice }),
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `## School Search Results`,
+            `**Total Matches:** ${result.total} | **Page:** ${result.page} | **Per Page:** ${result.per_page}`,
+        ];
+        if (result.notice)
+            lines.push(`\n> ${result.notice}`);
+        for (const s of result.schools) {
+            lines.push(`\n### ${s.name} (ID: ${s.id})`);
+            const loc = [s.city, s.state].filter(Boolean).join(', ');
+            if (loc)
+                lines.push(`**Location:** ${loc}`);
+            lines.push(`**Type:** ${s.ownership} | **Degree:** ${s.degree_level}`);
+            if (s.enrollment != null)
+                lines.push(`**Enrollment:** ${s.enrollment.toLocaleString()}`);
+            if (s.admission_rate != null)
+                lines.push(`**Acceptance Rate:** ${(s.admission_rate * 100).toFixed(1)}%`);
+            if (s.tuition_in_state != null)
+                lines.push(`**In-State Tuition:** $${s.tuition_in_state.toLocaleString()}`);
+            if (s.tuition_out_of_state != null)
+                lines.push(`**Out-of-State Tuition:** $${s.tuition_out_of_state.toLocaleString()}`);
+            if (s.net_price_overall != null)
+                lines.push(`**Avg Net Price:** $${s.net_price_overall.toLocaleString()}`);
+            if (s.median_debt != null)
+                lines.push(`**Median Debt:** $${s.median_debt.toLocaleString()}`);
+            if (s.earnings_6yr_median != null)
+                lines.push(`**6-Yr Median Earnings:** $${s.earnings_6yr_median.toLocaleString()}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=search-schools.tool.js.map

package/dist/mcp-server/tools/definitions/search-schools.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-schools.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-schools.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/value-analysis.tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Value analysis workflow tool. Parallel-fetches cost, debt, repayment, and earnings
+ * data for a school and computes ROI metrics the API doesn't pre-calculate.
+ * @module mcp-server/tools/definitions/value-analysis.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const valueAnalysisTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    family_income: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    school_id: z.ZodNumber;
+    school_name: z.ZodString;
+    list_price: z.ZodOptional<z.ZodNumber>;
+    net_price_overall: z.ZodOptional<z.ZodNumber>;
+    net_price_for_income: z.ZodOptional<z.ZodNumber>;
+    applicable_income_bracket: z.ZodOptional<z.ZodString>;
+    median_debt: z.ZodOptional<z.ZodNumber>;
+    repayment_rate_3yr: z.ZodOptional<z.ZodNumber>;
+    graduation_rate: z.ZodOptional<z.ZodNumber>;
+    earnings_6yr_median: z.ZodOptional<z.ZodNumber>;
+    earnings_10yr_median: z.ZodOptional<z.ZodNumber>;
+    debt_to_earnings_ratio: z.ZodOptional<z.ZodNumber>;
+    net_price_to_annual_earnings: z.ZodOptional<z.ZodNumber>;
+    data_notes: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "school_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No school record found for the requested ID.";
+    readonly recovery: "Verify the school ID using scorecard_search_schools and retry.";
+}, {
+    readonly reason: "api_error";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The College Scorecard API returned an error.";
+    readonly recovery: "Check SCORECARD_API_KEY validity and retry after a brief delay.";
+}]>;
+//# sourceMappingURL=value-analysis.tool.d.ts.map

package/dist/mcp-server/tools/definitions/value-analysis.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-analysis.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/value-analysis.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAsBjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2P5B,CAAC"}

package/dist/mcp-server/tools/definitions/value-analysis.tool.js

@@ -0,0 +1,227 @@
+/**
+ * @fileoverview Value analysis workflow tool. Parallel-fetches cost, debt, repayment, and earnings
+ * data for a school and computes ROI metrics the API doesn't pre-calculate.
+ * @module mcp-server/tools/definitions/value-analysis.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getScorecardService } from '../../../services/scorecard/scorecard-service.js';
+/** Select the net price bracket matching family_income */
+function netPriceForIncome(income, brackets) {
+    if (income == null)
+        return;
+    if (income <= 30000)
+        return brackets.np0_30k ?? undefined;
+    if (income <= 48000)
+        return brackets.np30k_48k ?? undefined;
+    if (income <= 75000)
+        return brackets.np48k_75k ?? undefined;
+    if (income <= 110000)
+        return brackets.np75k_110k ?? undefined;
+    return brackets.np110k_plus ?? undefined;
+}
+export const valueAnalysisTool = tool('scorecard_value_analysis', {
+    title: 'Value Analysis',
+    description: 'Workflow tool: parallel-fetches cost, debt, repayment, and earnings data for one school and computes ROI metrics the API does not pre-calculate — debt-to-earnings ratio, net price by income bracket, 3-year loan repayment rate, and how these compare within the school\'s Carnegie peer group. family_income narrows the net price to the applicable bracket. Returns a structured summary with all source figures alongside derived metrics. Answers "is this school worth it?" without requiring multiple tool calls.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        id: z
+            .union([
+            z.string().describe('School unit ID as string.'),
+            z.number().describe('School unit ID as number.'),
+        ])
+            .describe('School unit ID from scorecard_search_schools.'),
+        family_income: z
+            .number()
+            .optional()
+            .describe('Annual family income in dollars. When provided, net price is shown for the applicable income bracket.'),
+    }),
+    output: z.object({
+        school_id: z.number().describe('School unit ID.'),
+        school_name: z.string().describe('Institution name.'),
+        // Cost
+        list_price: z
+            .number()
+            .optional()
+            .describe('Full tuition and fees (in-state, or out-of-state when no in-state exists).'),
+        net_price_overall: z
+            .number()
+            .optional()
+            .describe('Average net price across all income levels.'),
+        net_price_for_income: z
+            .number()
+            .optional()
+            .describe('Net price for the provided family income bracket. Omitted when family_income not provided.'),
+        applicable_income_bracket: z
+            .string()
+            .optional()
+            .describe('Income bracket used for net_price_for_income.'),
+        // Debt and repayment
+        median_debt: z.number().optional().describe('Median debt at graduation (completers).'),
+        repayment_rate_3yr: z.number().optional().describe('3-year loan repayment rate (0–1).'),
+        graduation_rate: z.number().optional().describe('Completion rate at 150% normal time (0–1).'),
+        // Earnings
+        earnings_6yr_median: z.number().optional().describe('Median earnings 6 years after entry.'),
+        earnings_10yr_median: z.number().optional().describe('Median earnings 10 years after entry.'),
+        // Derived metrics
+        debt_to_earnings_ratio: z
+            .number()
+            .optional()
+            .describe('Debt-to-earnings ratio: median_debt / earnings_6yr_median. Values >1 indicate debt exceeds annual earnings.'),
+        net_price_to_annual_earnings: z
+            .number()
+            .optional()
+            .describe('Net price divided by annualized 6-year earnings (net_price / (earnings_6yr / 6)). Rough payback-period indicator.'),
+        // Data quality notes
+        data_notes: z
+            .array(z.string())
+            .describe('Flags for suppressed, missing, or potentially unreliable data fields. Empty when all data is available.'),
+    }),
+    errors: [
+        {
+            reason: 'school_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No school record found for the requested ID.',
+            recovery: 'Verify the school ID using scorecard_search_schools and retry.',
+        },
+        {
+            reason: 'api_error',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The College Scorecard API returned an error.',
+            recovery: 'Check SCORECARD_API_KEY validity and retry after a brief delay.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Running value analysis', { id: input.id, family_income: input.family_income });
+        const service = getScorecardService();
+        const [costResponse, earningsResponse] = await service.getValueAnalysisData(input.id, ctx);
+        const costRecord = costResponse.results[0];
+        if (!costRecord) {
+            throw ctx.fail('school_not_found', `No school record found for ID ${input.id}.`, {
+                id: input.id,
+                recovery: { hint: 'Search for valid school IDs with scorecard_search_schools.' },
+            });
+        }
+        const earningsRecord = earningsResponse.results[0] ?? costRecord;
+        const schoolId = costRecord.id ?? Number(input.id);
+        const schoolName = costRecord['school.name'] ?? 'Unknown';
+        // Extract values
+        const inStateTuition = costRecord['latest.cost.tuition.in_state'];
+        const outOfStateTuition = costRecord['latest.cost.tuition.out_of_state'];
+        const list_price = inStateTuition ?? outOfStateTuition ?? undefined;
+        const net_price_overall = costRecord['latest.cost.avg_net_price.overall'] ?? undefined;
+        const brackets = {
+            np0_30k: costRecord['latest.cost.avg_net_price.by_income.0-30000'],
+            np30k_48k: costRecord['latest.cost.avg_net_price.by_income.30001-48000'],
+            np48k_75k: costRecord['latest.cost.avg_net_price.by_income.48001-75000'],
+            np75k_110k: costRecord['latest.cost.avg_net_price.by_income.75001-110000'],
+            np110k_plus: costRecord['latest.cost.avg_net_price.by_income.110001-plus'],
+        };
+        const net_price_for_income = input.family_income != null ? netPriceForIncome(input.family_income, brackets) : undefined;
+        const applicable_income_bracket = input.family_income != null
+            ? input.family_income <= 30000
+                ? '$0–$30,000'
+                : input.family_income <= 48000
+                    ? '$30,001–$48,000'
+                    : input.family_income <= 75000
+                        ? '$48,001–$75,000'
+                        : input.family_income <= 110000
+                            ? '$75,001–$110,000'
+                            : '$110,001+'
+            : undefined;
+        const median_debt = costRecord['latest.aid.median_debt.completers.overall'] ?? undefined;
+        const rawRepayment = costRecord['latest.repayment.3_yr_repayment.overall'];
+        const repayment_rate_3yr = rawRepayment != null ? rawRepayment / 1000 : undefined;
+        const graduation_rate = costRecord['latest.completion.rate_suppressed.overall'] ?? undefined;
+        const earnings_6yr_median = earningsRecord['latest.earnings.6_yrs_after_entry.median'] ?? undefined;
+        const earnings_10yr_median = earningsRecord['latest.earnings.10_yrs_after_entry.median'] ?? undefined;
+        // Compute derived metrics
+        const debt_to_earnings_ratio = median_debt != null && earnings_6yr_median != null && earnings_6yr_median > 0
+            ? Math.round((median_debt / earnings_6yr_median) * 100) / 100
+            : undefined;
+        const effectiveNetPrice = net_price_for_income ?? net_price_overall;
+        const net_price_to_annual_earnings = effectiveNetPrice != null && earnings_6yr_median != null && earnings_6yr_median > 0
+            ? Math.round((effectiveNetPrice / (earnings_6yr_median / 6)) * 100) / 100
+            : undefined;
+        // Collect data quality notes
+        const data_notes = [];
+        if (list_price == null)
+            data_notes.push('Tuition/fees not reported — school may be tuition-free or data unavailable.');
+        if (net_price_overall == null)
+            data_notes.push('Net price not reported — institution may not participate in Title IV aid programs.');
+        if (median_debt == null)
+            data_notes.push('Median debt suppressed or not reported.');
+        if (earnings_6yr_median == null)
+            data_notes.push('6-year earnings suppressed — cohort too small (FERPA) or program-level only data available.');
+        if (earnings_10yr_median == null)
+            data_notes.push('10-year earnings suppressed or not reported.');
+        if (graduation_rate == null)
+            data_notes.push('Completion rate not reported.');
+        if (repayment_rate_3yr == null)
+            data_notes.push('3-year repayment rate not reported.');
+        if (inStateTuition == null && outOfStateTuition != null) {
+            data_notes.push('No in-state tuition — using out-of-state tuition as list price.');
+        }
+        return {
+            school_id: schoolId,
+            school_name: schoolName,
+            ...(list_price != null && { list_price }),
+            ...(net_price_overall != null && { net_price_overall }),
+            ...(net_price_for_income != null && { net_price_for_income }),
+            ...(applicable_income_bracket && { applicable_income_bracket }),
+            ...(median_debt != null && { median_debt }),
+            ...(repayment_rate_3yr != null && { repayment_rate_3yr }),
+            ...(graduation_rate != null && { graduation_rate }),
+            ...(earnings_6yr_median != null && { earnings_6yr_median }),
+            ...(earnings_10yr_median != null && { earnings_10yr_median }),
+            ...(debt_to_earnings_ratio != null && { debt_to_earnings_ratio }),
+            ...(net_price_to_annual_earnings != null && { net_price_to_annual_earnings }),
+            data_notes,
+        };
+    },
+    format: (result) => {
+        const lines = [`## Value Analysis: ${result.school_name} (ID: ${result.school_id})`];
+        lines.push('\n**Cost**');
+        if (result.list_price != null)
+            lines.push(`List Price (tuition + fees): $${result.list_price.toLocaleString()}`);
+        if (result.net_price_overall != null)
+            lines.push(`Avg Net Price (overall): $${result.net_price_overall.toLocaleString()}`);
+        if (result.net_price_for_income != null) {
+            lines.push(`Net Price (${result.applicable_income_bracket ?? 'income bracket'}): $${result.net_price_for_income.toLocaleString()}`);
+        }
+        lines.push('\n**Debt & Repayment**');
+        if (result.median_debt != null)
+            lines.push(`Median Debt at Graduation: $${result.median_debt.toLocaleString()}`);
+        if (result.repayment_rate_3yr != null)
+            lines.push(`3-Year Repayment Rate: ${(result.repayment_rate_3yr * 100).toFixed(1)}%`);
+        if (result.graduation_rate != null)
+            lines.push(`Completion Rate (150%): ${(result.graduation_rate * 100).toFixed(1)}%`);
+        lines.push('\n**Earnings**');
+        if (result.earnings_6yr_median != null)
+            lines.push(`Median Earnings (6yr): $${result.earnings_6yr_median.toLocaleString()}`);
+        if (result.earnings_10yr_median != null)
+            lines.push(`Median Earnings (10yr): $${result.earnings_10yr_median.toLocaleString()}`);
+        lines.push('\n**Derived ROI Metrics**');
+        if (result.debt_to_earnings_ratio != null) {
+            const dter = result.debt_to_earnings_ratio;
+            const assessment = dter <= 0.5
+                ? 'Low (manageable)'
+                : dter <= 1.0
+                    ? 'Moderate'
+                    : dter <= 2.0
+                        ? 'High'
+                        : 'Very high';
+            lines.push(`Debt-to-Earnings Ratio: ${dter.toFixed(2)}x (${assessment})`);
+        }
+        if (result.net_price_to_annual_earnings != null) {
+            lines.push(`Net Price / Annual Earnings: ${result.net_price_to_annual_earnings.toFixed(2)}x`);
+        }
+        if (result.data_notes.length > 0) {
+            lines.push('\n**Data Notes**');
+            for (const note of result.data_notes)
+                lines.push(`- ${note}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=value-analysis.tool.js.map

package/dist/mcp-server/tools/definitions/value-analysis.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-analysis.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/value-analysis.tool.ts"],"names":[],"mappings":"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"}

package/dist/services/scorecard/scorecard-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview College Scorecard API service. Wraps the api.data.gov/ed/collegescorecard/v1
+ * endpoint with retry, field selection, and pagination support.
+ * @module services/scorecard/scorecard-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { ScorecardApiResponse, ScorecardSearchOptions } from './types.js';
+export declare class ScorecardService {
+    private readonly apiKey;
+    constructor(_config: AppConfig, _storage: StorageService);
+    /** Build URL with query parameters */
+    private buildUrl;
+    /** Fetch from the API with retry and error classification */
+    private fetchApi;
+    /** Search schools with filter params */
+    searchSchools(options: ScorecardSearchOptions, ctx: Context): Promise<ScorecardApiResponse>;
+    /** Fetch one or more school profiles by ID */
+    getSchoolProfiles(ids: Array<string | number>, fields: string | undefined, ctx: Context): Promise<ScorecardApiResponse>;
+    /** Fetch program data for a school */
+    getSchoolPrograms(id: string | number, cipCode: string | undefined, _minEarnings: number | undefined, _credentialLevel: number | undefined, ctx: Context): Promise<ScorecardApiResponse>;
+    /** Fetch earnings time series for a school */
+    getSchoolEarnings(id: string | number, years: number[], ctx: Context): Promise<ScorecardApiResponse>;
+    /** Search programs across schools */
+    searchPrograms(options: {
+        cipCode?: string;
+        programName?: string;
+        state?: string;
+        ownership?: number;
+        maxNetPrice?: number;
+        minEarnings?: number;
+        maxDebt?: number;
+        perPage?: number;
+        page?: number;
+    }, ctx: Context): Promise<ScorecardApiResponse>;
+    /** Fetch fields for value analysis (cost + earnings in parallel) */
+    getValueAnalysisData(id: string | number, ctx: Context): Promise<[ScorecardApiResponse, ScorecardApiResponse]>;
+    /** Fetch comparison data for multiple schools on a specific topic */
+    getComparisonData(ids: Array<string | number>, topic: 'costs' | 'admissions' | 'outcomes' | 'aid', ctx: Context): Promise<ScorecardApiResponse>;
+}
+export declare function initScorecardService(config: AppConfig, storage: StorageService): void;
+export declare function getScorecardService(): ScorecardService;
+//# sourceMappingURL=scorecard-service.d.ts.map

package/dist/services/scorecard/scorecard-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorecard-service.d.ts","sourceRoot":"","sources":["../../../src/services/scorecard/scorecard-service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAsF/E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAIxD,sCAAsC;IACtC,OAAO,CAAC,QAAQ;IAWhB,6DAA6D;IAC7D,OAAO,CAAC,QAAQ;IAuFhB,wCAAwC;IACxC,aAAa,CAAC,OAAO,EAAE,sBAAsB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkC3F,8CAA8C;IAC9C,iBAAiB,CACf,GAAG,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,oBAAoB,CAAC;IAYhC,sCAAsC;IACtC,iBAAiB,CACf,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,oBAAoB,CAAC;IAchC,8CAA8C;IAC9C,iBAAiB,CACf,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,KAAK,EAAE,MAAM,EAAE,EACf,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,oBAAoB,CAAC;IAoBhC,qCAAqC;IACrC,cAAc,CACZ,OAAO,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,oBAAoB,CAAC;IA+BhC,oEAAoE;IACpE,oBAAoB,CAClB,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,CAAC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC;IAkCxD,qEAAqE;IACrE,iBAAiB,CACf,GAAG,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAC3B,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,KAAK,EAClD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,oBAAoB,CAAC;CAsDjC;AAMD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAErF;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAKtD"}