grad-agent

grad-agent

全額支給の修士課程・博士課程への出願を支援する、自律型MCPエージェントです。

候補を探して下書きを作成

• 自分の研究分野に関連するarXiv上の教授を探すほか、プログラムごとの締切に基づいて探します（run_program_batch）
• 氏名ではなく、きっかけとなった論文のSemantic Scholar正規著者IDを基準にして各教授の身元を特定します。「Wei Zhang」のように同姓同名の候補を構造的に取り違えることはありません
• 身元を確実に特定できない場合は、下書きの作成を拒否します。不一致の詳細（例：identity ambiguous: 2 comparable candidates, h=40 vs h=38）は監査用にskippedシートへ保存されます
• 各候補が実際に教員であることを確認します（h-indexと論文数の基準を使用）
• 地域で絞り込みます（プロフィールのtarget_regions: [US, Canada]、キーワードテーブル、ホームページのTLD、LLMによるフォールバックを使用）
• 研究室のページをスクレイピングし、採用の兆候とメールアドレスを探します
• タグの重複、TF-IDFのセマンティックレイヤー、学習済みの返信率バイアスを使い、教授と自分の最も実績のあるプロジェクトをマッチングします
• 具体的で事実確認済みのコールドメールを作成します。Claude Haikuが教授の最近の論文を横断する導入文を書き、続く2回目の呼び出しで、すべての主張を論文の要旨と照合し、裏付けのない内容を書き直します
• マッチ度を1〜10で採点し、1行の理由を添えるので、数秒で優先順位を付けられます
• すべての下書きに最新情報に関する警告を表示します。S2の所属先を教授の現在のホームページと照合し、研究室を移った可能性がある場合はMISMATCHと表示します。また、2年以上論文を発表していない研究者にも警告します

学習して、その後の対応もサポート

• 読み取り専用のIMAPで教授からの返信を検出し、ログに自動でタグを付けます
• 結果から学習します。返信につながったプロジェクトは、今後のマッチングで順位が上がります（outcome_reportで効果のある内容を確認できます）
• 10日以上返信がない教授へのフォローアップメールを作成します。同じ教授にフォローアップを2回送ることはありません
• 教授から返信があった場合、面接準備用の1ページ資料を作成します。教授の論文の要約、想定される質問、自分のアピールポイントが含まれます

すべてを記録

• 学校ごとのSOPをPDF（LaTeX）にまとめます。バージョン管理されるため、下書きが上書きされることはありません
• アウトリーチ、推薦状（LOR）の依頼、プログラムの締切、外部奨学金（Mastercard、Commonwealth、Fulbright、Rhodesなど）をxlsx/yamlで管理します
• 確認用にすべての下書きを受信トレイへメールします。あなたの許可なく教授にメールが送られることはありません

同梱のClaude Code／Claude Desktopスキル

grad-agentをインストールすると、対応するClaudeクライアント（Claude Code、Claude Desktop、MCP対応IDE）から呼び出せるAnthropic Skillsがインストールされます。grad-agent initを実行すると、自動的に~/.claude/skills/へシンボリックリンクが作成されます。initを実行せずにインストールまたは再インストールするには、grad-agent install-skillsを使用してください（既存のエントリを置き換える場合は--forceを、別の場所にリンクする場合は--target <dir>を追加します）。

• sop-writing — MIT CommLab、MIT CAPD、Berkeley Grad Div、Harvard GSAS、Stanford、およびCS教員向けガイドをまとめた、修士課程・博士課程の志望理由書（Statement of Purpose）の執筆ルールです。LaTeXによるSOPコンパイル手順と併用できます。
• lor-writing — 推薦状の執筆ルールです。出願者が推薦者の署名用に推薦状の下書きを作成する一般的なケースも含まれます。複数の推薦状の差別化、推薦者としての現実味、HHMIバイアスへの配慮、禁止フレーズの正規表現チェックを扱います。LOR_LETTERHEAD_PATH環境変数（LOR_LETTERHEAD_WIDTHで幅を指定、デフォルトは2.2in）を使って、レターヘッド／会社ロゴを追加できます。LaTeXコンパイル時に画像がレター上部に挿入されます。設定しない場合は、推薦者が自分のレターヘッドに貼り付けられるシンプルな上部ブロックになります。grad-agent initではレターヘッドのパスを対話形式で指定できます。後から変更する場合（または推薦者ごとにレターヘッドを切り替える場合）は、grad-agent set-letterhead /path/to/image.png --width 2.5inを実行します（パスを指定せずに実行すると、設定が解除されます）。
• コールドメール作成ツール（grad_agent/drafters/cold_email.py）— 博士課程へのアウトリーチのベストプラクティス（具体的な論文を基準にする、共通点を1つ具体的に示す、根拠のない最上級表現を避ける、「論文を読みました」という主張をしない）に沿って書き直されています。 stdio MCP サーバーとして Claude Code／Claude Desktop／任意の MCP クライアントで実行するか、通常の CLI として実行できます。

公開先：

• PyPI：grad-agent
• MCP Registry：io.github.i-ninte/grad-agent

インストール

次のいずれかを選んでください。

# Recommended for MCP clients (Claude Desktop, Claude Code, etc.)
uvx grad-agent server      # single-shot, no persistent install

# Persistent CLI install
pipx install grad-agent

# Or in a venv
python3 -m venv .venv && source .venv/bin/activate
pip install grad-agent

5 分でセットアップ

grad-agent init

次のファイルが作成されます。

• ~/.grad-agent/profile.yaml — あなたのアイデンティティ、プロジェクト、設定
• ~/.grad-agent/programs.yaml — 志望プログラム（初期データを設定）
• ~/.grad-agent/scholarships.yaml — 締め切りのある外部奨学金（初期データを設定）
• ~/.grad-agent/.env — シークレットのテンプレート

~/.grad-agent/.env に必要事項を記入します。

ANTHROPIC_API_KEY=sk-ant-...
SMTP_SERVER=smtp.gmail.com        # presets for Outlook/Yahoo/Zoho in the template
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=<gmail app password>
[email protected]
# Optional:
S2_API_KEY=                       # free Semantic Scholar key, dedicated rate limits
                                  # (client-side throttle already enforces >=1.1s between requests)
IMAP_SERVER=imap.gmail.com        # read-only reply detection; defaults to SMTP creds
GITHUB_USERNAME=your-gh
GITHUB_TOKEN=github_pat_...
HF_USERNAME=your-hf

~/.grad-agent/profile.yaml の重要な項目を記入します。

• name、identity_line、portfolio
• cv_path、transcript_path（絶対パス）
• degree_status: bachelors | masters（PhD の応募資格判定に使用）
• target_term、target_degree
• research_areas: [nlp, ai4health, ...]
• target_regions: [US, Canada] — これらの地域にいる教授のみ、ドラフトの作成対象にします（空の場合は地域を問いません）
• seed_projects: name、pitch、link、tags を含む、代表的なプロジェクトを 3～10 件

プロフィールの編集内容は、長時間実行中の MCP セッションにも即時反映されます。

次に実行します。

grad-agent sync        # scan projects (GitHub + HF + local)
grad-agent run         # one batch, drafts land in your inbox

Claude Code に登録する

次のコマンドを順番に 3 つ実行します。

pipx install grad-agent
pipx ensurepath                              # macOS/Linux: opens ~/.local/bin on PATH
                                             # Windows: opens %USERPROFILE%\.local\bin on PATH
claude mcp add grad-agent grad-agent server

Windows では、PATH の変更を反映するために pipx ensurepath の実行後、新しい PowerShell または Terminal ウィンドウを開く必要がある場合があります。

インストール不要のワンライナーを使いたい場合は、pipx を使わず uvx を使用します。

claude mcp add grad-agent uvx grad-agent server

続いて、新しい Claude Code セッションで次を実行します。

/mcp

約 36 個のツールを持つ grad-agent が接続されたことを確認できます。便利な機能を使う前に、grad-agent init（または uvx grad-agent init）を実行し、上記のセットアップ手順に従って ~/.grad-agent/.env と ~/.grad-agent/profile.yaml に必要事項を記入してください。

pipx ensurepath を省略した場合、grad-agent register-claude は PATH を変更せずに動作する、絶対パスを使ったコマンドを出力します。

Claude Desktop に登録する

~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "grad-agent": {
      "command": "uvx",
      "args": ["grad-agent", "server"]
    }
  }
}

uvx コマンドは事前のインストールが不要です。すでに pipx install grad-agent を実行している場合は、代わりに "command": "grad-agent", "args": ["server"] を使用できます。

その他の MCP クライアント（Cursor、Zed、Windsurf）でも同じ形式のマニフェストを使います。uvx grad-agent server を指定してください。

毎日の自動実行

このパッケージには、3 つすべての OS 用のスケジューラーテンプレートが含まれています。grad-agent schedule を実行すると、お使いのプラットフォームに適したものが出力されます。

grad-agent schedule --dest .

コマンドが表示するインストール手順に従ってください。事前に確認したい場合は、以下をご覧ください。

macOS（launchd）：

cp com.gradagent.daily.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.gradagent.daily.plist

Linux（systemd ユーザータイマー、現地時間 08:00 に実行）：

mkdir -p ~/.config/systemd/user
cp grad-agent-daily.service grad-agent-daily.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now grad-agent-daily.timer

Windows（タスク スケジューラ）：

# In an elevated PowerShell prompt:
schtasks /Create /TN "grad-agent-daily" /XML .\grad-agent-daily.xml

または、タスク スケジューラの GUI から XML をインポートします（操作 → タスクのインポート）。

毎朝、IMAP 経由で返信を自動検出し、返信のない教授へのフォローアップメッセージを作成します。適合度スコア付きの、本人確認済み教員候補を 3 件（適合度の高い順）提示し、アプローチ文の根拠を論文の要旨と照合して事実確認します。教授の S2 レコードと最新のホームページの内容に食い違いがある場合は、情報の鮮度に関する警告を表示します。さらに、プログラムと奨学金の締め切りに関する警告も、すべて 1 通のレビューメールにまとめて届きます。見送った候補は、具体的な不一致理由とともに保存されます（skipped_log_view で確認するか、skipped シートを開いてください）。

各 MCP ツールの機能

ツール	目的
run_daily_batch(n, area)	パイプライン全体：検証 → 募集 → フック＋検証 → 下書き → 記録
outreach_log_view(limit)	outreach xlsx の直近 N 行を表示します
outreach_mark_sent(prof, uni)	教授に実際に送信したことを行に記録します
sync_catalog(source)	github、hf、local からプロジェクトを取得します
list_projects_in_catalog()	マッチング処理が参照できるすべてのプロジェクトを表示します
list_programs()	志望するプログラムを表示します
upcoming_deadlines(days)	今後 N 日以内に締め切りを迎えるプログラムがあるか確認します
lor_add / lor_outstanding / lor_mark	推薦状のトラッカー
run_program_batch(program_id, n)	締め切り主導のバッチ処理：1 つのプログラムの教員向けに下書きを作成します
skipped_log_view(limit)	見送りになった候補の監査記録を表示します。具体的な段階と不一致の理由を確認できます
s2_cache_invalidate(query, all)	著者名または ID を指定して Semantic Scholar のキャッシュ項目を選択的に削除します
followups_due(days)	10 日以上返信のない教授向けに作成されたフォローアップ文を表示します
outreach_mark_followup(prof)	フォローアップを送信したことを記録します（同じ相手へのフォローアップは 1 回のみです）
outreach_mark_response(prof, outcome)	返信にタグを付け、マッチング処理の学習ループに反映します
outcome_report()	分野別およびプロジェクト別の返信率を表示します
ingest_replies()	IMAP を読み取り専用でスキャンし、ログ内の返信に自動でタグを付けます
interview_prep(prof)	1 ページのブリーフ：相手の論文、想定される質問、自分の話すポイント
list_scholarships(region)	応募資格の地域で絞り込んだ外部奨学金を表示します
upcoming_scholarship_deadlines(days)	締め切りが近い奨学金を表示します
draft_cold_email(...)	教授ごとの手動メール下書きを作成します
draft_sop(...)	Columbia 形式の SOP PDF を生成します（バージョン管理：sop_v1、v2、...）
send_draft_to_me(path)	任意の下書きファイルを確認用受信トレイに送ります
discover_profs(area)	arXiv と OpenReview をスキャンします（未検証の候補のみ）

ブログ公開ツール（publish_article、update_article、...）は、profile.yaml の blog.enabled: true が設定されている場合にのみ有効で、作者の Turso を利用した Next.js ポートフォリオ専用です。ほとんどのユーザーは無視してかまいません。

エージェントが行わないこと

• 教授へのメール送信は行いません。メールはすべて、下書きを読んだ後に Gmail から手動で送信します。
• メッセージを読む以外の操作は行いません。IMAP アクセスは読み取り専用で、メッセージの送信、削除、既読化は行いません。
• 論文に関する主張を捏造しません。フックは 2 回目の Claude 呼び出しによるチェックを経て、要旨に記載されていない主張は却下され、書き直されます。
• 同じ教授に 2 回メールを作成しません。重複排除には Semantic Scholar の authorId をキーとして使用し、古い行では名前を代替キーにします。また、フォローアップ済みの相手には 2 回以上フォローアップを送りません。
• 同姓の教授がいる場合に、誤った相手向けの下書きを作成しません。名前の文字列ではなく、きっかけとなった論文の authorId から本人を特定します。曖昧な場合は処理を拒否し、記録します。
• 候補が見送られた理由を隠しません。見送りのたびに、段階（identity、faculty-gate、region、dedup、no-papers）と正確な不一致内容を outreach_log.xlsx の skipped シートに記録します。古い確認メールに埋もれることはありません。
• Semantic Scholar のレート制限を超えません。クライアント側のスロットルによってリクエスト間隔を 1.1 秒以上に保ち、429 または 5xx が発生した場合は指数バックオフを行います。
• 応募資格のないプログラム向けに下書きを作成しません。degree_status が bachelors の場合、先に MSc が必要な PhD プログラムは除外されます。応募資格の対象地域外の奨学金にも同じ制限が適用されます。

要件

• Python 3.10+
• macOS、Linux、または Windows（CI で 3.10／3.11／3.12 のすべてをテスト済み）
• SOP PDF が必要な場合は、PATH 上に pdflatex が必要です （macOS：MacTeX、Ubuntu：texlive-latex-recommended、Windows：MiKTeX）
• Anthropic API キー
• 確認メール送信機能用の Gmail（または別の SMTP）

データの保存場所

デフォルトではすべて ~/.grad-agent/ 以下に保存されます。$GRAD_AGENT_HOME が設定されている場合は、その場所が使用されます。

~/.grad-agent/
  profile.yaml         identity + preferences (regions, seed projects, ...)
  programs.yaml        target programs with eligibility rules + deadlines
  scholarships.yaml    external scholarships with region eligibility + deadlines
  .env                 secrets (gitignored)
  data/
    outreach_log.xlsx  outreach sheet (drafts + outcomes) + skipped sheet (audit trail)
    lor_log.xlsx       recommendation-letter tracker
    catalog.json       synced projects (GitHub + HF + local)
    s2_cache.json      Semantic Scholar lookups (14 day TTL)
    region_cache.json  LLM-inferred regions for unusual affiliations
    db.sqlite          drafts + status
  drafts/              per-school SOP versions + email drafts
    prep/              interview prep one-pagers

コントリビューション

MIT ライセンスです。プログラムテンプレートの追加、Gmail 以外の SMTP プリセット、arXiv 以外のソースアダプター、教授の検証ヒューリスティクスの改善に関する PR を歓迎します。

Author

Kwabena Obeng · i-ninte.github.io/portfolio/