college-scorecard-mcp-server

---

概要

米国教育省の College Scorecard が提供する米国の大学データを利用できます。約 6,500 校の費用、収入、プログラム、進路実績を掲載しています。学校を検索して比較したり、専攻分野別の収入を調べたり、債務対収入比率などの ROI 指標を算出したりできます。

ツール

ツール	説明
scorecard_search_schools	名称、所在地、種類、規模、合格率、男女別フラグで教育機関を検索し、対応する API フィールドで並べ替えます。基本的な機関情報と費用指標を返します。
scorecard_get_school	教育機関の詳細なプロフィールを返します。費用、入学、成果、学資援助、人口統計、男女別フラグ、修了率が含まれます。
scorecard_compare_schools	指定したトピックについて、2～5 校を正規化して横並びで比較します。指標値、順位、比較の概要を返します。
scorecard_get_programs	1 校の専攻プログラムについて、1 年後の収入中央値、Stafford／Grad PLUS の累積債務、および債務コホートの対象となる 2 年分の IPEDS 授与件数を返します。
scorecard_search_programs	CIP と資格またはキーワードでプログラムを検索し、学位の識別情報を保持したうえで、取得した学校ページごとに収入順で順位付けします。
scorecard_get_earnings	連邦学資援助を受けた学部入学者のうち、修了の有無を問わず、就労中で在学していない人の収入を返します。6／8／10 年後の中央値、6／10 年後の P25／P75、ならびに非男性／男性の 6 年後の中央値が含まれます。
scorecard_value_analysis	ワークフローツールです。費用、債務、返済、収入のデータを並行して取得し、ROI 指標（債務対収入比率、純費用対収入比率）を計算します。
scorecard_lookup_cip	コード、キーワード、または関連するプログラム名で、厳選された 186 件の NCES CIP 2020 4 桁グループを検索します。オフラインで提供されます。
scorecard_list_fields	キーワードで Scorecard のフィールドカタログを検索します。一致するフィールドパス、説明、データ型、並べ替えの対応状況を返します。カスタムの fields パラメーターを渡す前に使用してください。

リソース

リソース	説明
scorecard://school/{id}	単位 ID による教育機関のプロフィール。学校に特化した会話に注入できるコンテキストです。
scorecard://programs/{id}	学校のプログラムレベルの成果

すべてのリソースデータはツールからも取得できます。リソース URI を構築する前に、scorecard_search_schools または scorecard_get_school を使用して学校 ID を確認してください。

プロンプト

プロンプト	説明
scorecard_compare_prompt	Scorecard のデータを使用した複数校の比較分析を構成します。

機能リファレンス

scorecard_search_schools _tool

• 名称、州、設置者、学位レベル、規模、合格率、CIP コード、または ZIP コードと距離（マイルまたは km）で検索します。per_page の上限は 100 です。page は 0 始まりです。州のリストには WA,CA の形式を使用できます。
• すばやく確認できるよう、基本的な機関情報と費用指標を返します。
• sort には、latest.cost.avg_net_price.overall:asc のような API 式を指定します（:desc を指定すると逆順になります）。men_only と women_only には true または false を指定できます。

---

scorecard_get_school _tool

• 学校 ID、または最大 1,000 件の ID の配列を受け付けます。異なる ID のうち先頭の 100 件を取得します。missing_ids にはレコードがなかった取得済み ID が、unprocessed_ids には超過分が列挙されます。
• デフォルトのプロフィールには、費用、入学、成果、学資援助、人口統計、修了率が含まれます。カスタムの fields を指定すると、要求した値を含む selected_fields が返され、応答にない要求済みのパスは absent_fields に列挙されます。
• HBCU と男女別のフラグは、判明している場合は true／false、情報がない場合は unknown です。

---

scorecard_compare_schools _tool

• 2～5 件の学校単位 ID と、costs、admissions、outcomes、aid のいずれか 1 つのトピックを受け付けます。
• 1 回の API 呼び出しで指標値と順位を返します。同じ値は同じ順位になり（1、1、3）、利用できない値には順位が付きません。
• 各セルの availability では、値が利用可能か、利用不可か、プライバシー保護のために非表示かを区別します。

---

scorecard_get_programs _ツール

• 1つの学校 ID を受け取り、任意で CIP コード（ドットあり、またはドットなし）、credential_level、最低収入のフィルターを指定できます。一致するプログラムがない学校の場合は空のコレクションが返され、存在しない学校の場合は検索エラーになります。
• 最高位の資格取得から1年後の収入中央値と卒業者数を返します。earnings_availability は available、unavailable、privacy_suppressed のいずれかで、suppressed_count と unavailable_count も含まれます。
• median_debt は、修了者が累計で借り入れた Stafford／Grad PLUS ローンの額です。ipeds_awards_year1 と ipeds_awards_year2 は、借入額を集計したコホートの各年の受給者数ではなく、授与件数を示します。

---

scorecard_search_programs _ツール

• CIP コードまたはプログラム名で検索し、任意で整数の credential_level（1～8および99）、州、設置者区分、実質授業料、収入、借入額のフィルターを指定できます。0始まりの page と per_page（最大100）で学校をページ分割するため、返されるプログラム行数が per_page を超える場合があります。
• プログラム指標、credential_level、credential_title とともに、学校 ID と学校名を返します。利用可能な収入が先に並び、収入の利用可否、借入額、授与件数の各フィールドは scorecard_get_programs と同じです。
• min_earnings はローカルでフィルタリングされるため、合計数とページネーションには、フィルタリング前の上流の学校数が使用されます。収入と借入額のしきい値は境界値を含み、不明な値は除外されます。

---

scorecard_get_earnings _ツール

• 1つの学校 ID を受け取り、任意でデータファイルの開始年を years に指定できます（1996～2025。入学年ではなく、データファイルの版を示します）。years を省略するか [] を渡すと、スナップショットのみが返されます。
• 連邦政府の援助を受けた学部課程の入学者のうち、修了の有無を問わず、就業中で在学していない人を対象とします。入学から6／8／10年後の中央値、入学から6／10年後の P25／P75、入学から6年後の男性以外／男性の中央値を返します。
• current_availability と trend[].availability は各指標の分類を示します。current_context と trend[].context は data_file_year、entry_cohorts、measurement_years、dollar_year を示します。値はプロバイダーのドル基準を保持するため、版をまたいで比較する前に確認してください。

---

scorecard_value_analysis _ツール

• 1つの学校 ID を受け取り、任意の family_income で該当する実質授業料の所得区分（0～3万ドル、3万～4万8,000ドル、4万8,000～7万5,000ドル、7万5,000～11万ドル、または11万ドル以上）を選択できます。
• 比率と併せて、その算出元の数値を返します。effective_net_price は使用された価格で、net_price_basis は income_bracket、overall、unavailable のいずれかです。
• 該当する所得区分がない場合は全体の価格が使用され、その旨が data_notes に記載されます。比率の算出には、正の年間収入が必要です。

---

scorecard_lookup_cip _ツール

• 空白以外のキーワードまたは部分的な名前で検索します（デフォルトの上限は20、最大50）。ドット付きの 11.07 とドットなしの 1107 は同じものとして扱われます。
• 現行の NCES CIP 2020 の4桁グループ186件から、正確なグループ名と分野の識別情報を返します。これは分類体系全体の一部です。関連する6桁のプログラム名も一致し、所属グループが返されます。一致するものがない場合は、案内を添えて空のコレクションが返されます。

---

scorecard_list_fields _ツール

• 空白以外のクエリで、厳選されたオフラインのフィールド項目78件を検索します（デフォルトの上限は30、最大100）。scorecard_get_school にカスタム fields を渡す前に使用してください。
• フィールドパス、説明、データ型、カテゴリ、API のソート対応状況を返します。ソートできないフィールドを含む結果には、tip が付けられます。

---

scorecard://school/{id} _リソース

• application/json 形式の学校プロフィール。学校の識別情報、費用、入学、進路、援助、修了に関するデータを含みます。
• id は、scorecard_search_schools から取得する学校単位の ID（文字列形式の整数）です。
• list は学校 URI の例をいくつか返します。他の学校を見つけるには scorecard_search_schools を使用してください。

---

scorecard://programs/{id} _リソース

• application/json としてプログラムレベルの成果を返します — CIP コード、タイトル、資格レベル、1年間の収入、Stafford／Grad PLUS の累積債務、およびプログラムツールと同じ意味を持つ ipeds_awards_year1 ／ ipeds_awards_year2 が含まれます。欠損している指標は null です。
• id は scorecard_search_schools の学校単位 ID です。
• list は学校 URI の例をいくつか返します。他の URI を見つけるには scorecard_search_schools を使用してください。

---

scorecard_compare_prompt _{プロンプト}

• 引数：school_names（カンマ区切りのリスト）と focus（costs | outcomes | programs）。どちらも必須です。
• costs と outcomes は、学校の検索、scorecard_compare_schools、プロフィール、価値分析を実行します。programs は、学校の検索、CIP の検索、各学校に対する scorecard_get_programs の実行を行い、一致する資格について収入、債務、IPEDS の修了者数を比較します。

機能

@cyanheads/mcp-ts-core を基盤としています。stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none ／ jwt ／ oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログに対応しています。

College Scorecard 固有の機能：

• College Scorecard API を全面的にカバー：Title IV 対象機関約 6,500 校、費用、成果、人口統計、学資援助、専攻分野別収入にまたがる約 2,800 のデータフィールド
• プログラムレベルの収入：学校 × CIP コード × 資格レベルごとに、最高位の資格取得後 1 年時点で就業しており、かつ就学していない卒業生の収入中央値
• ツールごとのフィールド事前選択 — 各ツールの目的に適した厳選フィールドセット。カスタムクエリ用に fields で任意に上書き可能
• CIP 分類体系（186 グループ）とフィールドカタログ（78 フィールド）を組み込み、オフラインで提供
• 米国の郵便番号と距離半径による地域フィルタリング

エージェントに適した出力：

• 数値（ゼロを含む）、欠損値、プロバイダーによる明示的な PS ／ PrivacySuppressed マーカーを区別します。
• 算出指標は scorecard_value_analysis でソースの数値とともに表示され、scorecard_compare_schools には順位も追加されます。
• 学校の並べ替えにはインデックス付き API フィールドを使用します。並べ替え式を選ぶ前に scorecard_list_fields を確認してください。6 年間の収入は API による並べ替えに対応していません。
• プロバイダーの障害は、検証、認証、リクエスト制限、タイムアウト、可用性の各理由を区別して報告します。可用性エラーには api_error を使用し、キャンセルは RequestCancelled のままです。

はじめに

公開ホストインスタンス

公開インスタンスは https://college-scorecard.caseyjhand.com/mcp で利用できます。インストールは不要です。API キーも必要ありません。インスタンスが独自のキーを使用します。Streamable HTTP 経由で任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "streamable-http",
      "url": "https://college-scorecard.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。無料の API キーについては、api.data.gov/signup をご覧ください。

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/college-scorecard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SCORECARD_API_KEY": "your-api-key"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/college-scorecard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SCORECARD_API_KEY": "your-api-key"
      }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "SCORECARD_API_KEY=your-api-key",
        "ghcr.io/cyanheads/college-scorecard-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 SCORECARD_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以上）。
• College Scorecard API キー — api.data.gov/signup で無料登録できます。レート制限：キーごとに 1 時間あたり 1,000 リクエスト。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/college-scorecard-mcp-server.git

2. ディレクトリに移動します：

cd college-scorecard-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set SCORECARD_API_KEY

設定

すべての設定は、src/config/server-config.ts の Zod スキーマを使用して起動時に検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
SCORECARD_API_KEY	必須。 api.data.gov の API キー（1 時間あたり 1,000 リクエスト）。	—
MCP_TRANSPORT_TYPE	トランスポート：stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_HTTP_ENDPOINT_PATH	MCP サーバーをマウントする HTTP エンドポイントのパス	/mcp
MCP_PUBLIC_URL	TLS を終端するリバースプロキシ環境での公開オリジンの上書き値	なし
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）	info
MCP_GC_PRESSURE_INTERVAL_MS	オプトイン方式の強制 GC ループの間隔（ミリ秒、Bun のみ）。HTTP 負荷時にヒープが増加する場合は 60000 を試してください	0（無効）
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	OpenTelemetry のインストルメンテーションを有効化	false

オプションで上書きできる設定の全一覧は、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t college-scorecard-mcp-server .
docker run --rm -e SCORECARD_API_KEY=your-key -p 3010:3010 college-scorecard-mcp-server

Dockerfile のデフォルトでは、HTTP トランスポート、ステートレスセッションモードを使用し、ログは /var/log/college-scorecard-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツール、リソース、プロンプトを登録し、サービスを初期化します。
src/config	サーバー固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）。検索、プロフィール、プログラム、収益、分析にわたる 9 つのツールがあります。
src/mcp-server/resources	リソース定義。学校プロフィールとプログラムの成果に関するリソースがあります。
src/mcp-server/prompts	プロンプト定義。複数の学校を比較するプロンプトがあります。
src/services	ScorecardService — リトライ、フィールド選択、ページネーションに対応し、College Scorecard API にアクセスするフェッチラッパーです。
tests/	src/ の構成に対応するユニットテストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使用しないでください
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用してください
• 新しいツール、リソース、プロンプトは、src/index.ts の createApp() 配列に登録してください
• 外部 API の呼び出しはラップし、生データを検証してからドメイン型に正規化し、出力スキーマに沿って返してください。不足しているフィールドを捏造しないでください

貢献

Issue の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。