Content
# Medify UCAT MCP Server
Model Context Protocol (MCP) server for [Medify](https://app.medify.co) UCAT accounts. It authenticates as a member, pulls completed mock scores and practice analytics, and exposes tools for score trends, question-type weaknesses, timing sinks, and practice recommendations.
Medify does not publish a documented public API. This server talks to the same authenticated `courses-api` endpoints the Medify web app uses (member email/password or session cookie).
> **Unofficial.** Not affiliated with or endorsed by Medify. Use only with accounts you own. Credentials stay on your machine.
## Features
- List completed full / mini mocks with VR, DM, QR (and SJ when present)
- Trend analysis: totals, section averages, recent vs earlier, best / worst
- Topic analytics: subtype accuracy vs Medify population (e.g. logic puzzles, tables)
- Question timing: clock usage, early/mid/late thirds, time sinks, fast guesses
- Focus recommendations with optional cognitive target (e.g. 2250)
- Local session + score cache under `~/.medify-mcp-server`
## Tools
| Tool | Description |
|------|-------------|
| `check_connection` | Verify Medify authentication |
| `list_completed_mocks` | List completed mocks (`full` / `mini` / `all`) |
| `get_mock_details` | Detail for one mock by id or title |
| `analyze_score_trends` | Totals + section trends over time |
| `analyze_section_performance` | Rank VR / DM / QR (+ SJ when present) |
| `analyze_topic_performance` | Rank question subtypes vs population |
| `analyze_question_timing` | Timing / tag analysis from recent full mocks |
| `recommend_focus_areas` | Prioritised practice suggestions |
| `compare_mocks` | Diff two mocks |
| `refresh_scores` | Force re-fetch (bypass cache) |
## Requirements
- Node.js 18+
- A Medify UCAT membership with completed mocks
## Setup
```bash
git clone https://github.com/<you>/medify-mcp-server.git
cd medify-mcp-server
npm install
cp .env.example .env
# edit .env — set MEDIFY_EMAIL + MEDIFY_PASSWORD (or MEDIFY_SESSION_COOKIE)
npm run build
```
### Environment
| Variable | Required | Description |
|----------|----------|-------------|
| `MEDIFY_EMAIL` | one of email+password or cookie | Medify member email |
| `MEDIFY_PASSWORD` | with email | Medify password |
| `MEDIFY_SESSION_COOKIE` | alternative | Value of `_medify_session_` from a logged-in browser |
| `MEDIFY_CACHE_DIR` | no | Cache directory (default `~/.medify-mcp-server`) |
| `MEDIFY_CACHE_TTL_MINUTES` | no | Score cache TTL (default `15`) |
Prefer a session cookie if password login is blocked (captcha / MFA).
## Cursor / MCP client config
Add a stdio MCP server entry (path and env are examples):
```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"
}
}
}
}
```
Or point `env` at a dotenv file you load yourself, and keep secrets out of the MCP config.
Restart the MCP client after changing config or rebuilding.
### npx (after publish)
```json
{
"mcpServers": {
"medify-ucat": {
"command": "npx",
"args": ["-y", "medify-mcp-server"],
"env": {
"MEDIFY_EMAIL": "you@example.com",
"MEDIFY_PASSWORD": "your-password"
}
}
}
}
```
## Example prompts
- “Check my Medify connection and list completed UCAT mocks.”
- “Analyse score trends and section strengths for full mocks only.”
- “Which question types am I weakest on vs the Medify population?”
- “Where do I lose time in VR, DM, and QR on recent full mocks?”
- “Recommend focus areas for a 2250 cognitive target; ignore SJ.”
- “Compare Mock 10 and Mock 11.”
## Development
```bash
npm run build
npm test
npm start # stdio MCP server
```
Project layout:
```
src/
index.ts # MCP stdio entry
medify/ # auth client, fetch, normalize
analysis/ # trends, topics, timing, recommendations
tools/ # MCP tool schemas + handlers
.cursor/skills/
medify-ucat-analysis/ # agent skill: run score/timing reports via MCP
medify-mcp-maintain/ # agent skill: change this codebase safely
```
When you add or change MCP tools, update both skills (and `tools-reference.md`) in the same PR.
## How it works
1. Authenticate via Devise login or an injected `_medify_session_` cookie.
2. Read scaled scores from `/courses-api/mock-scores-stats?course=ucat`.
3. Optionally load JSON:API scripts from `/courses-api/mock-exam-scripts` for timing.
4. Read practice analytics from `/courses-api/courses/ucat/topic-performances`.
5. Cache mocks locally; analysis tools run on the cached / freshly fetched data.
## Security
- Never commit `.env` or session cookies.
- Treat Medify credentials like any other account secret.
- This tool only reads account data needed for score analysis; it does not submit mocks.
## License
MIT — see [LICENSE](LICENSE).
