@cyanheads/college-scorecard-mcp-server 0.1.1

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

@@ -0,0 +1,367 @@
+/**
+ * @fileoverview School comparison tool. Returns normalized side-by-side comparison
+ * of 2–5 schools with percentile ranks and relative deltas within the result set.
+ * @module mcp-server/tools/definitions/compare-schools.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';
+/** Compute rank within an array of values (0-indexed, higher is better for most metrics) */
+function computeRanks(values, higherIsBetter = true) {
+    const nonNull = values
+        .map((v, i) => ({ v: v, i }))
+        .filter((x) => x.v != null)
+        .sort((a, b) => (higherIsBetter ? b.v - a.v : a.v - b.v));
+    const rankMap = new Map();
+    for (const [rankIdx, { i }] of nonNull.entries()) {
+        rankMap.set(i, rankIdx + 1);
+    }
+    return values.map((_, i) => rankMap.get(i) ?? null);
+}
+const ComparisonRowSchema = z.object({
+    metric: z.string().describe('Metric name.'),
+    values: z
+        .array(z
+        .object({
+        school_id: z.number().describe('School unit ID.'),
+        value: z.number().optional().describe('Raw metric value. Omitted when not available.'),
+        rank: z.number().optional().describe('Rank within this comparison set (1=best).'),
+        suppressed: z.boolean().describe('True when data is unavailable for this school/metric.'),
+    })
+        .describe('Per-school data point for this metric.'))
+        .describe('Per-school values for this metric.'),
+    unit: z.string().optional().describe('Unit of measurement (e.g. "$", "%", "students").'),
+    note: z.string().optional().describe('Contextual note about this metric.'),
+});
+export const compareSchoolsTool = tool('scorecard_compare_schools', {
+    title: 'Compare Schools',
+    description: 'Normalized side-by-side comparison of 2–5 schools on a named topic. Returns percentile-ranked rows and relative deltas within the result set — structured output an agent cannot reconstruct from raw profiles. Topics: costs (tuition, net price by income bracket, debt), admissions (acceptance rate, SAT/ACT, enrollment), outcomes (graduation rate, earnings, repayment), aid (Pell grants, federal loans, debt, repayment). This is different from scorecard_get_school with multiple IDs — compare_schools adds within-set normalization.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        ids: z
+            .array(z
+            .union([
+            z.string().describe('School unit ID as string.'),
+            z.number().describe('School unit ID as number.'),
+        ])
+            .describe('School unit ID (string or number).'))
+            .min(2)
+            .max(5)
+            .describe('Array of 2–5 school unit IDs to compare.'),
+        topic: z
+            .enum(['costs', 'admissions', 'outcomes', 'aid'])
+            .describe('Comparison topic: costs, admissions, outcomes, or aid.'),
+    }),
+    output: z.object({
+        schools: z
+            .array(z
+            .object({
+            id: z.number().describe('School unit ID.'),
+            name: z.string().describe('Institution name.'),
+        })
+            .describe('School identity record.'))
+            .describe('Schools in the comparison set, in the same order as the ids input.'),
+        topic: z.string().describe('The comparison topic used.'),
+        rows: z
+            .array(ComparisonRowSchema.describe('Comparison row for one metric.'))
+            .describe('Comparison rows — one per metric, with per-school values and ranks.'),
+        summary: z
+            .string()
+            .optional()
+            .describe('Brief interpretive summary highlighting the most notable relative differences.'),
+        notice: z.string().optional().describe('Warning if some requested IDs returned no record.'),
+    }),
+    errors: [
+        {
+            reason: 'schools_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'None of the requested school IDs returned records.',
+            recovery: 'Verify school IDs with scorecard_search_schools and retry with valid IDs.',
+        },
+        {
+            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('Comparing schools', { ids: input.ids, topic: input.topic });
+        const service = getScorecardService();
+        const response = await service.getComparisonData(input.ids, input.topic, ctx);
+        if (response.results.length === 0) {
+            throw ctx.fail('schools_not_found', `No records found for the requested school IDs.`, {
+                ids: input.ids,
+                recovery: { hint: 'Use scorecard_search_schools to find valid school IDs first.' },
+            });
+        }
+        // Build a lookup by ID for consistent ordering
+        const byId = new Map();
+        for (const r of response.results) {
+            if (r.id != null)
+                byId.set(String(r.id), r);
+        }
+        const schools = input.ids.map((id) => {
+            const r = byId.get(String(id));
+            return { id: Number(id), name: r?.['school.name'] ?? '(Not found)' };
+        });
+        const found = schools.filter((s) => byId.has(String(s.id)));
+        const missing = schools.filter((s) => !byId.has(String(s.id)));
+        const notice = missing.length > 0
+            ? `${missing.length} of ${input.ids.length} requested IDs returned no record: ${missing.map((s) => s.id).join(', ')}`
+            : undefined;
+        const metricsByTopic = {
+            costs: [
+                {
+                    metric: 'In-State Tuition',
+                    key: 'latest.cost.tuition.in_state',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Out-of-State Tuition',
+                    key: 'latest.cost.tuition.out_of_state',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Avg Net Price (overall)',
+                    key: 'latest.cost.avg_net_price.overall',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Net Price ($0–30k income)',
+                    key: 'latest.cost.avg_net_price.by_income.0-30000',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Net Price ($30k–48k income)',
+                    key: 'latest.cost.avg_net_price.by_income.30001-48000',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Net Price ($48k–75k income)',
+                    key: 'latest.cost.avg_net_price.by_income.48001-75000',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Net Price ($75k–110k income)',
+                    key: 'latest.cost.avg_net_price.by_income.75001-110000',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Net Price ($110k+ income)',
+                    key: 'latest.cost.avg_net_price.by_income.110001-plus',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Median Debt at Graduation',
+                    key: 'latest.aid.median_debt.completers.overall',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+            ],
+            admissions: [
+                {
+                    metric: 'Acceptance Rate',
+                    key: 'latest.admissions.admission_rate.overall',
+                    unit: '%',
+                    higherIsBetter: false,
+                    note: 'Lower may indicate more selectivity',
+                },
+                {
+                    metric: 'SAT Average',
+                    key: 'latest.admissions.sat_scores.average.overall',
+                    higherIsBetter: true,
+                },
+                {
+                    metric: 'SAT Math 25th Pct',
+                    key: 'latest.admissions.sat_scores.25th_percentile.math',
+                    higherIsBetter: true,
+                },
+                {
+                    metric: 'SAT Math 75th Pct',
+                    key: 'latest.admissions.sat_scores.75th_percentile.math',
+                    higherIsBetter: true,
+                },
+                {
+                    metric: 'ACT 25th Pct',
+                    key: 'latest.admissions.act_scores.25th_percentile.cumulative',
+                    higherIsBetter: true,
+                },
+                {
+                    metric: 'ACT 75th Pct',
+                    key: 'latest.admissions.act_scores.75th_percentile.cumulative',
+                    higherIsBetter: true,
+                },
+                {
+                    metric: 'Enrollment',
+                    key: 'latest.student.size',
+                    unit: 'students',
+                    higherIsBetter: true,
+                },
+            ],
+            outcomes: [
+                {
+                    metric: 'Completion Rate',
+                    key: 'latest.completion.rate_suppressed.overall',
+                    unit: '%',
+                    higherIsBetter: true,
+                },
+                {
+                    metric: 'Median Earnings (6yr)',
+                    key: 'latest.earnings.6_yrs_after_entry.median',
+                    unit: '$',
+                    higherIsBetter: true,
+                },
+                {
+                    metric: 'Median Earnings (10yr)',
+                    key: 'latest.earnings.10_yrs_after_entry.median',
+                    unit: '$',
+                    higherIsBetter: true,
+                },
+                {
+                    metric: '3-Year Repayment Rate',
+                    key: 'latest.repayment.3_yr_repayment.overall',
+                    unit: '%',
+                    higherIsBetter: true,
+                    scale: 1 / 1000,
+                },
+                {
+                    metric: 'Median Debt at Graduation',
+                    key: 'latest.aid.median_debt.completers.overall',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+            ],
+            aid: [
+                {
+                    metric: 'Pell Grant Rate',
+                    key: 'latest.aid.pell_grant_rate',
+                    unit: '%',
+                    higherIsBetter: true,
+                    note: 'Share of students receiving Pell grants',
+                },
+                {
+                    metric: 'Federal Loan Rate',
+                    key: 'latest.aid.federal_loan_rate',
+                    unit: '%',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: 'Median Debt at Graduation',
+                    key: 'latest.aid.median_debt.completers.overall',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+                {
+                    metric: '3-Year Repayment Rate',
+                    key: 'latest.repayment.3_yr_repayment.overall',
+                    unit: '%',
+                    higherIsBetter: true,
+                    scale: 1 / 1000,
+                },
+                {
+                    metric: 'Avg Net Price (overall)',
+                    key: 'latest.cost.avg_net_price.overall',
+                    unit: '$',
+                    higherIsBetter: false,
+                },
+            ],
+        };
+        const metrics = metricsByTopic[input.topic] ?? [];
+        const rows = metrics.map((m) => {
+            const rawValues = found.map((s) => {
+                const r = byId.get(String(s.id));
+                if (!r)
+                    return null;
+                const raw = r[m.key];
+                if (raw == null)
+                    return null;
+                return m.scale != null ? raw * m.scale : raw;
+            });
+            const ranks = computeRanks(rawValues, m.higherIsBetter);
+            return {
+                metric: m.metric,
+                values: found.map((s, i) => {
+                    const rv = rawValues[i];
+                    const rk = ranks[i];
+                    return {
+                        school_id: s.id,
+                        ...(rv != null ? { value: rv } : {}),
+                        ...(rk != null ? { rank: rk } : {}),
+                        suppressed: rv == null,
+                    };
+                }),
+                ...(m.unit && { unit: m.unit }),
+                ...(m.note && { note: m.note }),
+            };
+        });
+        // Build a brief summary of the most notable differences
+        const bestByMetric = rows
+            .filter((r) => r.values.some((v) => !v.suppressed))
+            .slice(0, 3)
+            .map((r) => {
+            const best = r.values.find((v) => v.rank === 1 && !v.suppressed);
+            if (!best)
+                return null;
+            const school = schools.find((s) => s.id === best.school_id);
+            return `${school?.name ?? best.school_id} leads on ${r.metric}`;
+        })
+            .filter(Boolean);
+        const summary = bestByMetric.length > 0 ? `${bestByMetric.join('; ')}.` : undefined;
+        return {
+            schools,
+            topic: input.topic,
+            rows,
+            ...(summary && { summary }),
+            ...(notice && { notice }),
+        };
+    },
+    format: (result) => {
+        // Build a lookup: school_id → school name for readable cell headers
+        const schoolById = new Map(result.schools.map((s) => [s.id, s.name]));
+        const lines = [
+            `## School Comparison: ${result.topic}`,
+            `**Schools:** ${result.schools.map((s) => `${s.name} (ID: ${s.id})`).join(', ')}`,
+        ];
+        if (result.notice)
+            lines.push(`\n> **Note:** ${result.notice}`);
+        if (result.summary)
+            lines.push(`\n> **Summary:** ${result.summary}`);
+        for (const row of result.rows) {
+            const unitNote = row.unit ? ` (${row.unit})` : '';
+            const noteText = row.note ? ` — ${row.note}` : '';
+            lines.push(`\n**${row.metric}${unitNote}${noteText}**`);
+            for (const v of row.values) {
+                const schoolName = schoolById.get(v.school_id) ?? `School ${v.school_id}`;
+                let valueDisplay;
+                if (v.value != null) {
+                    const val = v.value;
+                    if (row.unit === '$')
+                        valueDisplay = `$${val.toLocaleString()}`;
+                    else if (row.unit === '%')
+                        valueDisplay = `${(val * 100).toFixed(1)}%`;
+                    else if (row.unit === 'students')
+                        valueDisplay = val.toLocaleString();
+                    else
+                        valueDisplay = String(val);
+                }
+                else {
+                    valueDisplay = 'N/A';
+                }
+                const rankDisplay = v.rank != null ? `#${v.rank}` : 'N/A';
+                const suppressedLabel = v.suppressed ? ' (suppressed)' : '';
+                lines.push(`  ${schoolName}: ${valueDisplay} (${rankDisplay})${suppressedLabel}`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=compare-schools.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Earnings tool. Returns institution-level post-graduation earnings
+ * for one school at 6, 8, and 10 years after entry, with optional gender breakdown.
+ * @module mcp-server/tools/definitions/get-earnings.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const getEarningsTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    years: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    school_id: z.ZodNumber;
+    school_name: z.ZodString;
+    current: z.ZodObject<{
+        earnings_6yr_median: z.ZodOptional<z.ZodNumber>;
+        earnings_6yr_p25: z.ZodOptional<z.ZodNumber>;
+        earnings_6yr_p75: z.ZodOptional<z.ZodNumber>;
+        earnings_8yr_median: z.ZodOptional<z.ZodNumber>;
+        earnings_10yr_median: z.ZodOptional<z.ZodNumber>;
+        earnings_10yr_p25: z.ZodOptional<z.ZodNumber>;
+        earnings_10yr_p75: z.ZodOptional<z.ZodNumber>;
+        earnings_6yr_female_median: z.ZodOptional<z.ZodNumber>;
+        earnings_6yr_male_median: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    trend: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        year: z.ZodNumber;
+        earnings_6yr_median: z.ZodOptional<z.ZodNumber>;
+        earnings_10yr_median: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    suppressed: z.ZodBoolean;
+    suppression_note: z.ZodOptional<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=get-earnings.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts.map

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

package/dist/mcp-server/tools/definitions/get-earnings.tool.js

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview Earnings tool. Returns institution-level post-graduation earnings
+ * for one school at 6, 8, and 10 years after entry, with optional gender breakdown.
+ * @module mcp-server/tools/definitions/get-earnings.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';
+export const getEarningsTool = tool('scorecard_get_earnings', {
+    title: 'Get School Earnings',
+    description: 'Institution-level post-graduation earnings for one school — median and percentiles at 6, 8, and 10 years after entry, with optional gender breakdown. This reflects outcomes across all graduates, not broken down by program. For program-specific earnings use scorecard_get_programs. For ROI analysis combining cost and debt data use scorecard_value_analysis. The years parameter accepts a list of cohort entry years for historical trend queries — omit for current snapshot only.',
+    annotations: { readOnlyHint: true, idempotentHint: 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.'),
+        years: z
+            .array(z.number().int())
+            .optional()
+            .describe('Optional list of cohort entry years for historical trend data (e.g. [2011, 2012, 2013]). Omit for current snapshot.'),
+    }),
+    output: z.object({
+        school_id: z.number().describe('School unit ID.'),
+        school_name: z.string().describe('Institution name.'),
+        current: z
+            .object({
+            earnings_6yr_median: z.number().optional().describe('Median earnings 6 years after entry.'),
+            earnings_6yr_p25: z
+                .number()
+                .optional()
+                .describe('25th percentile earnings 6 years after entry.'),
+            earnings_6yr_p75: z
+                .number()
+                .optional()
+                .describe('75th percentile earnings 6 years after entry.'),
+            earnings_8yr_median: z.number().optional().describe('Median earnings 8 years after entry.'),
+            earnings_10yr_median: z
+                .number()
+                .optional()
+                .describe('Median earnings 10 years after entry.'),
+            earnings_10yr_p25: z
+                .number()
+                .optional()
+                .describe('25th percentile earnings 10 years after entry.'),
+            earnings_10yr_p75: z
+                .number()
+                .optional()
+                .describe('75th percentile earnings 10 years after entry.'),
+            earnings_6yr_female_median: z
+                .number()
+                .optional()
+                .describe('Median earnings 6 years after entry for female students.'),
+            earnings_6yr_male_median: z
+                .number()
+                .optional()
+                .describe('Median earnings 6 years after entry for male students.'),
+        })
+            .describe('Most recent available earnings snapshot.'),
+        trend: z
+            .array(z
+            .object({
+            year: z.number().describe('Cohort entry year.'),
+            earnings_6yr_median: z
+                .number()
+                .optional()
+                .describe('Median earnings 6 years after entry for this cohort.'),
+            earnings_10yr_median: z
+                .number()
+                .optional()
+                .describe('Median earnings 10 years after entry for this cohort.'),
+        })
+            .describe('Earnings data point for one cohort entry year.'))
+            .optional()
+            .describe('Historical trend rows by cohort entry year. Present only when years parameter was supplied.'),
+        suppressed: z
+            .boolean()
+            .describe('True when earnings data is suppressed across all time points.'),
+        suppression_note: z.string().optional().describe('Explains suppression when suppressed=true.'),
+    }),
+    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('Fetching school earnings', { id: input.id, years: input.years });
+        const service = getScorecardService();
+        const response = await service.getSchoolEarnings(input.id, input.years ?? [], ctx);
+        const r = response.results[0];
+        if (!r) {
+            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 v6med = r['latest.earnings.6_yrs_after_entry.median'];
+        const v6p25 = r['latest.earnings.6_yrs_after_entry.percentile25'];
+        const v6p75 = r['latest.earnings.6_yrs_after_entry.percentile75'];
+        const v8med = r['latest.earnings.8_yrs_after_entry.median_earnings'];
+        const v10med = r['latest.earnings.10_yrs_after_entry.median'];
+        const v10p25 = r['latest.earnings.10_yrs_after_entry.percentile25'];
+        const v10p75 = r['latest.earnings.10_yrs_after_entry.percentile75'];
+        const v6fem = r['latest.earnings.6_yrs_after_entry.female_students.median_earnings'];
+        const v6mal = r['latest.earnings.6_yrs_after_entry.male_students.median_earnings'];
+        const current = {
+            ...(v6med != null && { earnings_6yr_median: v6med }),
+            ...(v6p25 != null && { earnings_6yr_p25: v6p25 }),
+            ...(v6p75 != null && { earnings_6yr_p75: v6p75 }),
+            ...(v8med != null && { earnings_8yr_median: v8med }),
+            ...(v10med != null && { earnings_10yr_median: v10med }),
+            ...(v10p25 != null && { earnings_10yr_p25: v10p25 }),
+            ...(v10p75 != null && { earnings_10yr_p75: v10p75 }),
+            ...(v6fem != null && { earnings_6yr_female_median: v6fem }),
+            ...(v6mal != null && { earnings_6yr_male_median: v6mal }),
+        };
+        const suppressed = Object.keys(current).length === 0;
+        const suppression_note = suppressed
+            ? 'Earnings data not available — likely suppressed due to small cohort size (FERPA).'
+            : undefined;
+        // Build trend rows for requested years
+        const trend = input.years && input.years.length > 0
+            ? input.years.map((year) => {
+                const row = { year };
+                const k6 = `${year}.earnings.6_yrs_after_entry.median`;
+                const k10 = `${year}.earnings.10_yrs_after_entry.median`;
+                if (r[k6] != null)
+                    row.earnings_6yr_median = r[k6];
+                if (r[k10] != null)
+                    row.earnings_10yr_median = r[k10];
+                return row;
+            })
+            : undefined;
+        return {
+            school_id: r.id ?? Number(input.id),
+            school_name: r['school.name'] ?? 'Unknown',
+            current,
+            ...(trend && { trend }),
+            suppressed,
+            ...(suppression_note && { suppression_note }),
+        };
+    },
+    format: (result) => {
+        const fmt = (n) => (n != null ? `$${n.toLocaleString()}` : 'Not available');
+        const lines = [`## Earnings: ${result.school_name} (ID: ${result.school_id})`];
+        lines.push('\n**Current Earnings Snapshot**');
+        const c = result.current;
+        if (result.suppressed) {
+            lines.push(`> **Suppressed:** ${result.suppression_note ?? 'Earnings data not available.'}`);
+        }
+        lines.push(`6-Year Median: ${fmt(c.earnings_6yr_median)}`);
+        lines.push(`6-Year P25/P75: ${fmt(c.earnings_6yr_p25)} / ${fmt(c.earnings_6yr_p75)}`);
+        lines.push(`8-Year Median: ${fmt(c.earnings_8yr_median)}`);
+        lines.push(`10-Year Median: ${fmt(c.earnings_10yr_median)}`);
+        lines.push(`10-Year P25/P75: ${fmt(c.earnings_10yr_p25)} / ${fmt(c.earnings_10yr_p75)}`);
+        lines.push(`6-Year Female Median: ${fmt(c.earnings_6yr_female_median)}`);
+        lines.push(`6-Year Male Median: ${fmt(c.earnings_6yr_male_median)}`);
+        if (result.trend && result.trend.length > 0) {
+            lines.push('\n**Historical Trend (by Entry Year)**');
+            for (const row of result.trend) {
+                const parts = [`Year: ${row.year}`];
+                if (row.earnings_6yr_median != null)
+                    parts.push(`6yr: $${row.earnings_6yr_median.toLocaleString()}`);
+                if (row.earnings_10yr_median != null)
+                    parts.push(`10yr: $${row.earnings_10yr_median.toLocaleString()}`);
+                lines.push(parts.join(' | '));
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-earnings.tool.js.map

package/dist/mcp-server/tools/definitions/get-earnings.tool.js.map

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