内容
# handshake-mcp
一款让Claude等AI助手访问 [Handshake](https://joinhandshake.com) 的MCP服务器 —— 通过您自己的浏览器会话搜索工作、申请、跟踪申请并研究雇主。
> **免责声明：** 本项目独立且与Handshake无关。自动访问可能会违反Handshake的服务条款。仅用于个人生产力。
## 工具列表
| 工具 | 描述 |
|---|---|
| `hs_search_jobs` | 按关键词、地点或工作类型搜索 |
| `hs_get_job` | 完整描述、要求、薪水、截止日期 |
| `hs_apply` | 提交申请、附上简历/求职信 |
| `hs_save_job` / `hs_unsave_job` | 保存/取消保存工作（关注） |
| `hs_get_applications` / `hs_withdraw_application` | 申请跟踪 |
| `hs_search_employers` / `hs_get_employer` | 公司研究（关键词搜索） |
| `hs_get_profile` | 您的Handshake学生个人资料 |
| `hs_upload_document` / `hs_get_documents` / `hs_delete_document` | 管理简历和求职信 |
## 快速开始
### 使用 uvx（推荐）
```bash
# 首次登录
uvx handshake-mcp --login
# 添加到Claude Code (~/.claude/.mcp.json)
```
```json
{
"mcpServers": {
"handshake": {
"command": "uvx",
"args": ["handshake-mcp"]
}
}
}
```
### 从源码
```bash
git clone https://github.com/shahparam11/handshake-mcp-server.git
cd handshake-mcp
uv sync
# 首次登录
uv run handshake-mcp --login
```
添加至 `~/.claude/.mcp.json`:
```json
{
"mcpServers": {
"handshake": {
"command": "uv",
"args": ["run", "--project", "/path/to/handshake-mcp", "handshake-mcp"]
}
}
}
```
重启Claude Code。现在 `hs_*` 工具可用。
### 使用Docker
```bash
docker build -t handshake-mcp .
# 登录（挂载会话存储）
docker run -it -v ~/.handshake-mcp:/root/.handshake-mcp handshake-mcp --login
# 作为MCP服务器运行
docker run -i -v ~/.handshake-mcp:/root/.handshake-mcp handshake-mcp
```
## 命令行界面
```bash
handshake-mcp --login # 通过浏览器认证
handshake-mcp --status # 检查会话有效性
handshake-mcp --logout # 清除保存的会话
handshake-mcp --version # 打印版本
```
## 工作原理
在 `--login` 时，会打开一个Patchright Chromium浏览器。登录后，完整的浏览器配置文件（cookie、localStorage、IndexedDB）将保存到 `~/.handshake-mcp/`。后续工具调用通过 `httpx` 客户端使用这些cookie，对Handshake的内部REST API `app.joinhandshake.com/stu/` 进行调用。
CSRF保护使用 **双提交cookie** 模式 —— `CSRF-TOKEN` cookie值会作为 `X-CSRF-Token` 请求头返回。
> **注意：** Handshake的内部API未公开文档。如果工具返回404，请在Handshake的浏览器开发者工具中打开网络标签页，找到匹配的请求路径，并更新相关的 `handshake_mcp/tools/*.py` 文件。
## 会话刷新
```bash
handshake-mcp --login
```
## 项目布局
```
handshake_mcp/
├── cli_main.py # 入口点 — --login/--logout/--status/服务器
├── server.py # FastMCP服务器工厂
├── auth.py # Patchright登录 + 配置文件/cookie存储
├── client.py # 身份验证的httpx客户端
├── exceptions.py # CredentialsNotFoundError, SessionExpiredError
└── tools/
├── jobs.py # hs_search_jobs, hs_get_job, hs_apply, hs_save/unsave_job
├── employers.py # hs_search_employers, hs_get_employer
├── applications.py # hs_get_applications, hs_withdraw_application
└── profile.py # hs_get_profile, hs_upload/get/delete_document
```
## 开发
```bash
uv sync --group dev
uv run pytest --cov
uv run ruff check .
```
## 许可证
MIT — 见 [LICENSE](LICENSE)。
