# Medify UCAT MCP Server

[![medify-mcp-server MCP server](https://glama.ai/mcp/servers/ankitforcode/medify-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/ankitforcode/medify-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

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.

Listed on [Glama](https://glama.ai/mcp/servers/ankitforcode/medify-mcp-server). Maintainer claim / release steps: [docs/glama-release.md](./docs/glama-release.md).

## 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/ankitforcode/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).