grad-agent

grad-agent

一款自主 MCP Agent，可帮助你申请有全额资助的硕士和博士项目。

发现并起草

• 在 arXiv 上发现你研究领域的教授，也可按项目截止日期发现（run_program_batch）
• 以触发论文在 Semantic Scholar 中对应的规范作者 ID 为锚点，确认每位教授的身份，而非依赖姓名字符串——从结构上杜绝将“Wei Zhang”这类重名者混淆
• 如果无法锚定身份，则拒绝起草；具体的不匹配原因（例如 identity ambiguous: 2 comparable candidates, h=40 vs h=38）会记录到 skipped 工作表中，以供审计
• 验证每位候选人确实是教职人员（设定 h 指数和论文数量门槛）
• 按地区筛选（在你的个人资料中设置 target_regions: [US, Canada]；结合关键词表、主页顶级域名和大模型回退判断）
• 抓取其实验室网页，查找招募信号和电子邮件地址
• 将教授与和你匹配度最高的已交付项目相匹配（标签重合度 + TF-IDF 语义层 + 基于学习的回复率偏差）
• 起草具体且经过事实核查的冷邮件：Claude Haiku 根据教授近期论文撰写切入点，然后通过第二次调用依据摘要核查每项陈述，并重写任何缺乏依据的内容
• 按 1 到 10 分评估每封草稿的匹配度，并给出一句理由，让你能在几秒内完成筛选
• 每封草稿都附有时效性警告：将 S2 所列的机构信息与教授当前的主页交叉核对（若教授可能已更换实验室，则标记为 MISMATCH），并标记超过 2 年未发表论文的研究人员

学习并跟进

• 通过只读 IMAP 检测教授回复，并自动为日志添加标签
• 从结果中学习：能获得回复的项目会在后续匹配中排名靠前（outcome_report 会显示哪些做法有效）
• 为超过 10 天未回复的教授起草跟进提醒；绝不对同一位教授提醒两次
• 教授回复后，生成一页式面试准备材料：总结其论文、列出可能的问题和你的谈话要点

追踪所有事项

• 将每所学校的个人陈述（SOP）编译为 PDF（LaTeX），并保留版本，绝不覆盖任何草稿
• 通过 xlsx/yaml 追踪联络、推荐信（LOR）申请、项目截止日期和外部奖学金（Mastercard、Commonwealth、Fulbright、Rhodes 等）
• 将每封草稿发送到你的收件箱供你审核；未经你的同意，绝不会向教授发送任何内容

内置的 Claude Code / Claude Desktop 技能

安装 grad-agent 后会附带一组 Anthropic Skills，可在支持这些技能的任何 Claude 客户端中调用（Claude Code、Claude Desktop、支持 MCP 的 IDE）。grad-agent init 会自动将其符号链接到 ~/.claude/skills/；若不运行 init 而是单独安装或重新安装，请使用 grad-agent install-skills（添加 --force 以替换现有条目，或添加 --target <dir> 以链接到其他位置）。

• sop-writing — 硕士/博士目的陈述（Statement of Purpose）起草规则，综合自 MIT CommLab、MIT CAPD、Berkeley Grad Div、Harvard GSAS、Stanford 以及计算机科学教职人员指南。与 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）——根据博士项目联络的最佳实践重新编写（锚定具体论文、明确一处具体重合点、不使用无依据的夸张表述、不声称“我读过您的论文”）。 作为 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（用于博士资格筛选）
• target_term、target_degree
• research_areas: [nlp, ai4health, ...]
• target_regions: [US, Canada] — 仅为这些地区的教授起草内容（留空 = 任意地区）
• seed_projects: 3 到 10 个旗舰项目，包含 name、pitch、link、tags

即使 MCP 会话正在长时间运行，修改个人资料也会立即生效。

然后：

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

注册到 Claude Code

按顺序执行以下三个命令：

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 上，运行 pipx ensurepath 后，你可能需要打开新的 PowerShell 或 Terminal 窗口， PATH 更改才能生效。

想用无需安装的一行命令？跳过 pipx，改用 uvx：

claude mcp add grad-agent uvx grad-agent server

然后在新的 Claude Code 会话中：

/mcp

你应该会看到 grad-agent 已连接，并提供约 36 个工具。在它开始执行有用操作之前，先运行 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。

每日自主运行

此软件包为三种操作系统都提供了调度器模板。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 记录与实时主页不一致时发出时效性警告，并提醒项目和奖学金截止日期——所有信息汇总在一封审核邮件中。被跳过的线索会连同具体不匹配原因一起保存（通过 skipped_log_view 查看，或打开 skipped 工作表）。

每个 MCP 工具的用途

工具	用途
run_daily_batch(n, area)	完整工作流：验证 → 招募 → hook + 验证 → 起草 → 记录
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)	截止日期驱动的批处理：为某个项目的教师起草邮件
skipped_log_view(limit)	跳过线索的审计记录，包含具体阶段和不匹配原因
s2_cache_invalidate(query, all)	按作者姓名或 ID 有选择地清除 Semantic Scholar 缓存条目
followups_due(days)	为 10 天以上未回复的教授起草跟进邮件
outreach_mark_followup(prof)	记录已发送的跟进邮件（每位教授最多跟进一次）
outreach_mark_response(prof, outcome)	标记回复；结果会反馈给匹配器的学习循环
outcome_report()	按领域和项目统计回复率
ingest_replies()	只读 IMAP 扫描；自动在日志中标记回复
interview_prep(prof)	一页简报：他们的论文、可能的问题以及你的谈话要点
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 作品集。大多数用户可以忽略这些工具。

Agent 不会做什么

• 不会向教授发送任何邮件。所有邮件都由你在阅读草稿后，从自己的 Gmail 手动发送。
• 除阅读外，不会操作你的收件箱。IMAP 访问权限为只读：不会发送、删除或标记邮件。
• 不会捏造论文论断。hook 会经过第二次 Claude 调用，该调用会拒绝摘要中未出现的论断并重写内容。
• 不会给同一位教授发送两次邮件。去重依据 Semantic Scholar 的 authorId；旧记录则回退使用姓名，并会标记跟进邮件，确保每位教授最多收到一次跟进。
• 当两位教授同名时，不会给错误的人起草邮件。身份根据触发论文的 authorId 而非姓名字符串进行解析；遇到有歧义的情况时，会拒绝处理并记录。
• 不会隐藏线索被拒绝的原因。每次跳过都会保存到 outreach_log.xlsx 的 skipped 工作表中，包含阶段（identity、faculty-gate、region、dedup、no-papers）和具体的不匹配原因，而不会将其埋在旧的审核邮件中。
• 不会超出 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 许可证。欢迎提交 PR，添加更多项目模板、非 Gmail 的 SMTP 预设、非 arXiv 来源适配器，以及更好的教授验证启发式方法。

Author

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