内容
# Medify UCAT 服务器
用于 [Medify](https://app.medify.co) UCAT 账户的模型上下文协议（MCP）服务器。它作为会员身份验证，拉取已完成的模拟考试成绩和实践分析，并提供用于趋势分析、题目类型弱点、时间分配和实践推荐的工具。
Medify 没有提供文档化的公共 API。此服务器与 Medify 网页应用使用的相同的身份验证 `courses-api` 端点进行通信（会员邮箱/密码或会话 cookie）。
> **非官方。** 不隶属于或得到 Medify 的认可。仅可与您拥有的账户一起使用。凭证保留在您的机器上。
## 功能
- 列出已完成的完整/迷你模拟考试，包括 VR、DM、QR（和 SJ，如有）
- 趋势分析：总数、章节平均值、近期与早期、最佳/最差
- 题目分析：子类准确率与 Medify 群体对比（例如逻辑谜题、表格）
- 题目时间分配：时钟使用、早期/中期/后期三分之一、时间分配、快速猜测
- 焦点推荐，可选认知目标（例如 2250）
- 本地会话 + 成绩缓存存储在 `~/.medify-mcp-server`
## 工具
| 工具 | 描述 |
|------|-------------|
| `check_connection` | 验证 Medify 身份验证 |
| `list_completed_mocks` | 列出已完成的模拟考试（`full` / `mini` / `all`） |
| `get_mock_details` | 获取模拟考试详情， 按 ID 或标题 |
| `analyze_score_trends` | 随时间变化的总数 + 章节趋势 |
| `analyze_section_performance` | VR / DM / QR（+ SJ，如有）排名 |
| `analyze_topic_performance` | 题目子类与群体对比排名 |
| `analyze_question_timing` | 最近完整模拟考试的时间 / 标签分析 |
| `recommend_focus_areas` | 优先练习建议 |
| `compare_mocks` | 比较两个模拟考试 |
| `refresh_scores` | 强制重新获取（绕过缓存） |
## 需求
- Node.js 18+
- 具有已完成模拟考试的 Medify UCAT 会员资格
## 安装
```bash
git clone https://github.com/<you>/medify-mcp-server.git
cd medify-mcp-server
npm install
cp .env.example .env
# 编辑 .env — 设置 MEDIFY_EMAIL + MEDIFY_PASSWORD（或 MEDIFY_SESSION_COOKIE）
npm run build
```
### 环境
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `MEDIFY_EMAIL` | 邮箱+密码或cookie之一 | Medify 会员邮箱 |
| `MEDIFY_PASSWORD` | 邮箱必填 | Medify 密码 |
| `MEDIFY_SESSION_COOKIE` | 替代方案 | 登录浏览器中的 `_medify_session_` 值 |
| `MEDIFY_CACHE_DIR` | 否 | 缓存目录（默认为 `~/.medify-mcp-server`） |
| `MEDIFY_CACHE_TTL_MINUTES` | 否 | 成绩缓存 TTL（默认为 `15`） |
如果密码登录被阻止（验证码/MFA），请优先使用会话cookie。
## 光标 / MCP 客户端配置
添加一个stdio MCP服务器条目（路径和环境变量是示例）：
```json
{
"mcpServers": {
"medify-ucat": {
"command": "node",
"args": ["/absolute/path/to/medify-mcp-server/dist/index.js"],
"env": {
"MEDIFY_EMAIL": "you@example.com",
"MEDIFY_PASSWORD": "your-password"
}
}
}
}
```
或者，将 `env` 指向您自己加载的 dotenv 文件，并将密钥保留在 MCP 配置之外。
更改配置或重新构建后，请重启 MCP 客户端。
### npx（发布后）
```json
{
"mcpServers": {
"medify-ucat": {
"command": "npx",
"args": ["-y", "medify-mcp-server"],
"env": {
"MEDIFY_EMAIL": "you@example.com",
"MEDIFY_PASSWORD": "your-password"
}
}
}
}
```
## 示例提示
- “检查我的 Medify 连接并列出已完成的 UCAT 模拟考试。”
- “分析完整模拟考试的成绩趋势和章节优势。”
- “我的题目类型与 Medify 群体相比，哪一个最弱？”
- “我在最近的完整模拟考试中，VR、DM 和 QR 的哪些时间段表现不佳？”
- “为 2250 的认知目标推荐练习重点；忽略 SJ。”
- “比较模拟考试 10 和模拟考试 11。”
## 开发
```bash
npm run build
npm test
npm start # stdio MCP 服务器
```
项目布局：
```
src/
index.ts # MCP stdio 入口
medify/ # 身份验证客户端，获取，标准化
analysis/ # 趋势，主题，时间，推荐
tools/ # MCP 工具模式 + 处理程序
.cursor/skills/
medify-ucat-analysis/ # 代理技能：通过 MCP 运行成绩/时间报告
medify-mcp-maintain/ # 代理技能：安全更改此代码库
```
当您添加或更改 MCP 工具时，请在同一个 PR 中更新两个技能（和 `tools-reference.md`）。
## 工作原理
1. 通过 Devise 登录或注入 `_medify_session_` cookie 进行身份验证。
2. 从 `/courses-api/mock-scores-stats?course=ucat` 读取缩放成绩。
3. 可选地，从 `/courses-api/mock-exam-scripts` 加载 JSON:API 脚本用于时间分配。
4. 从 `/courses-api/courses/ucat/topic-performances` 读取实践分析。
5. 在本地缓存模拟考试；分析工具在缓存/新获取的数据上运行。
## 安全
- 永远不要提交 `.env` 或会话cookie。
- 像对待其他账户密钥一样对待 Medify 凭证。
- 此工具仅读取用于成绩分析所需的账户数据；它不会提交模拟考试。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
