内容
# grad-agent
<!-- mcp-name: io.github.i-ninte/grad-agent -->
一款自主的MCP代理，帮助您申请全额资助的硕士和博士项目。
**发现和起草**
- 在arXiv上发现您研究领域的教授，或按项目截止日期驱动（`run_program_batch`）
- 通过触发论文的规范Semantic Scholar作者ID来解析每位教授的身份，而不是姓名字符串——像“韦江”这样的姓名冲突在结构上是不可能混淆的
- 当身份无法确定时，拒绝起草；将特定的不匹配（例如`identity ambiguous: 2 comparable candidates, h=40 vs h=38`）持久化到`skipped`表格进行审计
- 验证每位候选人是否为教师（h指数和论文数量门槛）
- 按地区过滤（您的个人资料中的`target_regions: [US, Canada]`；关键词表格 + 首页TLD + LLM备用）
- 爬取他们的实验室页面以获取招聘信号 + 电子邮件地址
- 将他们与您最强的已完成项目匹配（标签重叠 + TF-IDF语义层 + 学习到的响应率偏差）
- 起草一封特定的、事实核实的冷邮件：Claude Haiku编写一个钩子，涵盖教授最近的论文，然后第二个调用验证每个声明并重写任何不受支持的内容
- 为每份草稿评分1-10，附上一句原因，以便您在几秒钟内进行分类
- **新鲜度警告** 在每份草稿中：与教授的实时首页进行交叉检查S2隶属关系（如果他们可能已经更换实验室，则标记`MISMATCH`），并标记近2年内没有发表论文的研究人员
**学习和跟进**
- 通过只读IMAP检测教授的回复，并自动标记日志
- 从结果中学习：获得回复的项目在未来的匹配中排名上升（`outcome_report`显示有效的内容）
- 为沉默10天以上的教授起草后续提醒；绝不提醒同一位教授两次
- 当教授回复时，生成面试准备单页：总结他们的论文，可能的问题，您的谈话要点
**跟踪一切**
- 编制每所学校的SOP为PDF（LaTeX），版本控制，确保任何草稿都不会被覆盖
- 在xlsx/yaml中跟踪外联、推荐信请求、项目截止日期和外部奖学金（Mastercard、Commonwealth、Fulbright、Rhodes等）
- 每个草稿都通过电子邮件发送到您的收件箱进行审查；任何内容都不会在未经您同意的情况下发送给教授
作为Claude Code / Claude Desktop / 任意MCP客户端的标准输入输出MCP服务器运行，或作为纯命令行界面运行。
已发布于：
- **PyPI**： [`grad-agent`](https://pypi.org/project/grad-agent/)
- **MCP Registry**： [`io.github.i-ninte/grad-agent`](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.i-ninte/grad-agent)
## 安装
选择一个：
```bash
# 推荐用于MCP客户端（Claude Desktop，Claude Code等）
uvx grad-agent server # 单次运行，无需持久安装
# 持久CLI安装
pipx install grad-agent
# 或在虚拟环境中
python3 -m venv .venv && source .venv/bin/activate
pip install grad-agent
```
## 5分钟设置
```bash
grad-agent init
```
这将写入：
- `~/.grad-agent/profile.yaml` — 您的身份、项目、偏好
- `~-agent/programs.yaml` — 目标项目（已初始化）
- `~/.grad-agent/scholarships.yaml` — 具有截止日期的学金（已初始化）
- `~/.grad-agent/.env` — 机密模板
填写 `~/.grad-agent/.env`：
```
ANTHROPIC_API_KEY=sk-ant-...
SMTP_SERVER=smtp # Outlook/Yahoo/Zoho的预设在模板中
SMTP_PORT=587
SMTP_USERNAME=you@gmail.com
SMTP_PASSWORD=<gmail应用密码>
SMTP_FROM=you@gmail.com
# 可选：
S2_API_KEY= # 免费的Semantic Scholar密钥，专属速率限制
# （客户端节流已经强制执行>=1.1s的请求间隔）
IMAP_SERVER=imap.gmail.com # 只读回复检测；默认为SMTP凭证
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会话也是如此。
然后：
```bash
grad-agent sync # 扫描项目（GitHub + HF + 本地）
grad-agent run # 一批，草稿进入您的收件箱
```
## 注册到Claude Code
三个命令，按顺序：
```bash
pipx install grad-agent
pipx ensurepath # 打开~/.local/bin到PATH
claude mcp add grad-agent grad-agent server
```
更喜欢零安装一键操作？跳过 `pipx` 并使用 `uvx`：
```bash
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`：
```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` 即可。
## 每天自动运行（macOS）
软件包附带一个launchd plist模板。要每天08:00触发：
```bash
cp /path/to/grad_agent/templates/com.gradagent.daily.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.gradagent.daily.plist
```
每天早上：通过IMAP自动检测回复，为沉默的教授起草后续提醒，为3个身份验证的教师提供带有适合度评分的潜在人选（最佳适合度优先），钩子根据论文摘要进行事实核查，当教授的S2记录与实时首页不符时发出新鲜度警告，以及项目和奖学金截止日期警告 — 所有这些都集中在一封审查电子邮件中。跳过的潜在人选会将其特定的不匹配原因持久化（通过ipped_log_view` 查看或打开 `skipped` 表格）。
## 每个MCP工具的作用
| 工具 | 用途 |
|---|---|
| `run_daily_batch(n, area)` | 完整流程：验证 → 招募 → 钩子 + 验证 → 草稿 → 日志 |
| `outreach_log_view(limit)` | 显示最近N行外联xlsx |
| `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)` | 奖学日期临近 |
|_cold_email(...)` | 手动逐位教授起草 |
| `draft_sop(...)` | 编译哥伦比亚风格的SOP PDF（版本控制：sop_v1，v2，...） |
| `send_draft_to_me(path)` | 将任何草稿文件发送到您的审查收件箱 |
| `discover_profs(area)` | arXiv + OpenReview扫描（原始候选人，无需验证） |
博客发布工具（`publish_article`、`update_article`等）被`blog.enabled: true` 限制在 `profile.yaml` 中，并且特定于作者的Turso支持的Next.js投资组合。大多数用户可以忽略它们。
## 代理不会做的事情
发送任何电子邮件。每次发送都是手动的，从您的Gmail，在您阅读草稿后。
- 超出您的收件箱。IMAP访问是只读的：它从不发送、删除或标记消息。
- 编造论文声明。钩子经过第二次Claude调用，拒绝任何摘要中存在的声明，并重写。
- 向同一位教授发送两次电子邮件。重复数据删除基于Semantic Scholar作者ID，并带有名称备用方案用于旧行，并且后续跟进被标记，以便教授不会被提醒超过一次。
- 当两位教授具有相同的姓名时，为错误的人起草。对于具有相同姓名的教授，身份从触发论文的作者ID中解析，而不是姓名字符串；模糊情况被拒绝并记录。
- 隐藏拒绝潜在候选人的原因。每个跳过都被持久化到 `` 表格中，位于 `outreach_log.xlsx` 中，带有阶段（身份、教师门控、地区、重复数据删除、无论文）和确切的不匹配 — 不会隐藏在旧的审查电子邮件中。
- 超出Semantic Scholar的速率限制。客户端节流强制执行 ≥1.1s 之间的请求，并对任何429或5xx进行指数级回退。
- 为您不具备资格的项目起草。为需要MSc的博士项目过滤，如果您的 `degree_status` 是 `bachelors`。对于您资格地区以外的奖学金也是如此。
## 要求
- Python 3.10+
- macOS 或 Linux（Windows 未测试）
- 如果您想要 SOP PDF，则需要 `pdflatex`（macOS：MacTeX；Ubuntu：`texlive-latex-recommended`）
- Anthropic API 密钥
- Gmail（或其他SMTP）用于审查邮件发送
## 您的数据存储位置
所有数据默认位于 `~/.grad-agent/` 下，或如果设置了 `$GRAD_AGENT_HOME` 则位于其下：
```
~/.grad-agent/
profile.yaml 身份 + 偏好（地区、种子项目...）
programs.yaml 具有资格规则和截止日期的目标项目
scholarships.yaml 具有地区资格和截止日期的外部奖学金
.env 机密（gitignored）
data/
outreach_log.xlsx 外联表格（草稿 + 结果）+ 跳过表格（审计跟踪）
lor_log.xlsx 推荐信跟踪器
catalog.json 同步项目（GitHub + HF + 本地）
s2_cache.json Semantic Scholar查找（14天TTL）
region_cache.json 非典型隶属关系的LLM推断地区
db.sqlite 草稿 + 状态
drafts/ 每所学校的SOP版本 + 电子邮件草稿
prep/ 面试准备单页
```
## 贡献
MIT许可。欢迎为以下内容提交PR：更多项目模板、非Gmail SMTP预设、非arXiv源适配器和更好的教授验证启发式。
## 作者
Kwabena Obeng · [i-ninte.github.io/portfolio/](https://i-ninte.github.io/portfolio/)
