内容
# 工作评估 MCP 服务器
用于评估 AI 产品经理候选人的 MCP 服务器 — 读取面试记录，根据评分卡模板对候选人进行评分，并将评估结果提交给 Workable。
## 前置条件
- Python 3.12+
- [Poetry](https://python-poetry.org/)
- Workable API token（管理员或招聘人员权限）
- 在 Workable 中配置的评分卡/面试工具包
- 存储为 `data/interview-{name}.md` 的面试记录
## 设置
```bash
cd eval-mcp
poetry install
# 确保 WORKABLE_API_TOKEN 和 WORKABLE_EMAIL 已在您的 shell 中设置
```
## 配置
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
| `WORKABLE_API_TOKEN` | 是 | — | Workable API token |
| `WORKABLE_EMAIL` | 是 | — | 评估者邮箱（所有工具使用，无需手动输入） |
| `WORKABLE_SUBDOMAIN` | 否 | 自动发现 | Workable 账户子域名 |
| `WORKABLE_TRANSCRIPTS_DIR` | 否 | `<project-root>/data` | 面试记录目录 |
## 运行
```bash
cd eval-mcp && poetry run python server.py
```
## opencode 集成
添加到 `opencode.json`:
```json
{
"mcp": {
"workable": {
"type": "local",
"command": ["poetry", "-C", "eval-mcp", "run", "python", "server.py"],
"env": {
"WORKABLE_API_TOKEN": "${WORKABLE_API_TOKEN}",
"WORKABLE_TRANSCRIPTS_DIR": "${WORKABLE_TRANSCRIPTS_DIR}",
"WORKABLE_EMAIL": "${WORKABLE_EMAIL}"
}
}
}
}
```
## 工作流程
```
1. evaluate_candidate(name) → 有指导：读取记录，评分 traits，预览，提交
2. edit_draft(name) → 查看和更新已保存的草稿
3. list_pending_evaluations → 查看需要评估的候选人
4. get_scorecard_template → 查看 8 个 traits 和问题
5. read_transcript(candidate) → 读取面试记录
6. preview_evaluation(...) → 保存草稿（重新调用更新）
7. list_drafts → 查看已保存的草稿
8. submit_evaluation(candidate) → 提交给 Workable
```
## 工具
| 工具 | 描述 |
|---|---|
| `list_pending_evaluations` | 需要您评估的候选人 |
| `get_scorecard_template` | 显示评分卡结构和 traits 问题 |
| `read_transcript` | 读取候选人的面试记录 |
| `preview_evaluation` | 创建或更新草稿评估，返回 Markdown 摘要 |
| `submit_evaluation` | 将保存的草稿提交给 Workable |
| `list_drafts` | 显示已保存的草稿评估 |
| `list_evaluations` | 显示过去提交的评估（`detail=true` 显示完整 traits 分解） |
| `get_evaluation` | 获取单个候选人的完整评估 |
## 提示
| 提示 | 描述 |
|---|---|
| `evaluate_candidate` | 有指导的端到端工作流程 — 读取记录，评分 8 个 traits，编写评论，预览草稿，在提交前请求确认 |
| `edit_draft` | 加载已保存的草稿，显示当前值，指导更新评分，评论或 traits 评分 |
## 命令
| 命令 | 描述 |
|---|---|
| `/eval-past` | 列出您过去提交的评估 |
| `/eval-pending` | 列出需要您评估的候选人 |
| `/eval-view` [name] | 查看提交的评估；如果省略，则提示输入名称 |
| `/eval-draft` [name] | 使用有指导的工作流程草拟或编辑评估；如果省略，则提示输入候选人 |
## 项目结构
```
eval-mcp/
server.py — MCP 服务器入口点（8 个工具，2 个提示，stdio）
workable.py — Workable API 客户端，带速率限制重试
scorecard.py — 评分卡模板加载器和 payload 组装器
scorecard.json — AI PM 评分卡模板（4 个部分，8 个 traits）
draft_store.py — 草稿和提交评估的磁盘持久性
drafts/ — 运行时草稿文件（gitignored）
submitted/ — 已提交评估的本地存档（gitignored）
```
## 备注
- **编辑草稿：** `edit_draft` 提示加载已保存的草稿并指导更新。底层调用 `preview_evaluation`，使用相同的候选人名称覆盖草稿。
- **速率限制：** Workable API 在 ~7-9 请求/分钟时限制速率。客户端使用指数退避（4 次尝试，2s/4s/8s）重试。
- **评分卡：** `scorecard.json` 是本地副本 — Workable API 不公开评分卡模板。更换此文件以更改不同角色的评估模板。
- **Traits 存储：** Workable API 不返回已提交评估的每个 traits 评分。详细的 traits 数据存储在 `submitted/` 中，并通过 `list_evaluations(detail=true)` 和 `get_evaluation` 提供。
- **记录：** 面试记录是 `data/` 中的纯 Markdown 文件。`read_transcript` 工具按名称读取它们。
