stackprep-mcp 0.1.0__py3-none-any.whl

stackprep_mcp/server.py

@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("stackprep")
+
+SKILLS_DIR = Path(__file__).parent / "skills"
+
+_sessions: dict[str, dict[str, Any]] = {}
+
+
+# ── Storage ────────────────────────────────────────────────────────────────────
+
+def _data_dir() -> Path:
+    env = os.environ.get("STACKPREP_PACKS_DIR")
+    d = Path(env) if env else Path.home() / ".stackprep"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _packs_dir() -> Path:
+    d = _data_dir() / "packs"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _sessions_dir() -> Path:
+    d = _data_dir() / "sessions"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _persist_session(session_id: str) -> None:
+    path = _sessions_dir() / f"{session_id}.json"
+    path.write_text(json.dumps(_sessions[session_id], indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def _restore_session(session_id: str) -> dict | None:
+    path = _sessions_dir() / f"{session_id}.json"
+    if path.exists():
+        data = json.loads(path.read_text(encoding="utf-8"))
+        _sessions[session_id] = data
+        return data
+    return None
+
+
+def _delete_session(session_id: str) -> None:
+    path = _sessions_dir() / f"{session_id}.json"
+    if path.exists():
+        path.unlink()
+    _sessions.pop(session_id, None)
+
+
+# ── Skill loading ──────────────────────────────────────────────────────────────
+
+def _load_skill(mode: str) -> str:
+    skill_file = SKILLS_DIR / f"{mode}.md"
+    if skill_file.exists():
+        return skill_file.read_text(encoding="utf-8")
+    return ""
+
+
+# ── Tools ──────────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+def start_session(
+    mode: str,
+    cert_name: str = "",
+    cv: str = "",
+    jd: str = "",
+    extra_topics: str = "",
+) -> str:
+    """Start a new stackprep session. Returns a session ID and the skill rules for the AI to follow.
+
+    Args:
+        mode: "interview" or "certification"
+        cert_name: For certification mode — the exam name (e.g. "AWS SAA-C03")
+        cv: For interview mode — the user's CV/resume text
+        jd: For interview mode — the job description text
+        extra_topics: Optional comma-separated extra topics to focus on
+    """
+    if mode not in ("interview", "certification"):
+        return "ERROR: mode must be 'interview' or 'certification'"
+    if mode == "certification" and not cert_name:
+        return "ERROR: cert_name is required for certification mode"
+    if mode == "interview" and not (cv and jd):
+        return "ERROR: cv and jd are required for interview mode"
+
+    session_id = secrets.token_hex(6)
+
+    _sessions[session_id] = {
+        "mode": mode,
+        "cert_name": cert_name,
+        "extra_topics": extra_topics,
+        "q_num": 0,
+        "score": {"correct": 0, "partial": 0, "incorrect": 0, "total": 0},
+        "auto_flagged": [],
+        "flagged": [],
+        "ended": False,
+        "all_flagged": [],
+    }
+    _persist_session(session_id)
+
+    skill = _load_skill(mode)
+    context_lines = [f"Session ID: {session_id}", f"Mode: {mode}"]
+    if cert_name:
+        context_lines.append(f"Certification: {cert_name}")
+    if extra_topics:
+        context_lines.append(f"Extra topics: {extra_topics}")
+    if cv:
+        context_lines.append(f"\n--- CV ---\n{cv}")
+    if jd:
+        context_lines.append(f"\n--- Job description ---\n{jd}")
+
+    return "\n".join([
+        "=== STACKPREP SESSION STARTED ===",
+        "\n".join(context_lines),
+        "\n=== SKILL RULES (follow these exactly) ===",
+        skill,
+    ])
+
+
+@mcp.tool()
+def submit_answer(session_id: str, result: str, question: str = "") -> str:
+    """Record the result of an answered question.
+
+    Args:
+        session_id: The session ID
+        result: "correct", "partial", or "incorrect"
+        question: The question text (used to build the study pack)
+    """
+    session = _sessions.get(session_id) or _restore_session(session_id)
+    if not session:
+        return f"ERROR: No session found with ID '{session_id}'."
+
+    result = result.lower().strip()
+    if result not in ("correct", "partial", "incorrect"):
+        return "ERROR: result must be 'correct', 'partial', or 'incorrect'"
+
+    session["q_num"] += 1
+    session["score"]["total"] += 1
+    q_num = session["q_num"]
+    snippet = question[:200] if question else f"Q{q_num}"
+
+    if result == "correct":
+        session["score"]["correct"] += 1
+    elif result == "partial":
+        session["score"]["partial"] += 1
+        session["score"]["correct"] += 1
+        session["auto_flagged"].append(f"Q{q_num}: {snippet}")
+    elif result == "incorrect":
+        session["score"]["incorrect"] += 1
+        session["auto_flagged"].append(f"Q{q_num}: {snippet}")
+
+    _persist_session(session_id)
+
+    score = session["score"]
+    return f"Recorded Q{q_num}: {result}. Score: {score['correct']}/{score['total']}"
+
+
+@mcp.tool()
+def flag_for_study(session_id: str, question: str = "") -> str:
+    """Manually flag the current question for the study pack.
+
+    Args:
+        session_id: The session ID
+        question: The question text to flag
+    """
+    session = _sessions.get(session_id) or _restore_session(session_id)
+    if not session:
+        return f"ERROR: No session found with ID '{session_id}'."
+
+    q_num = session["q_num"]
+    snippet = question[:200] if question else f"Q{q_num}"
+    entry = f"Q{q_num}: {snippet}"
+    if entry not in session["flagged"]:
+        session["flagged"].append(entry)
+    _persist_session(session_id)
+    return f"Flagged Q{q_num} for study. Total flagged: {len(session['flagged'])}."
+
+
+@mcp.tool()
+def end_session(session_id: str) -> str:
+    """End the session. Returns the score and flagged topics so the AI can generate a study plan and study pack.
+
+    Args:
+        session_id: The session ID
+    """
+    session = _sessions.get(session_id) or _restore_session(session_id)
+    if not session:
+        return f"ERROR: No session found with ID '{session_id}'."
+
+    all_flagged = list(dict.fromkeys(session["auto_flagged"] + session["flagged"]))
+    session["ended"] = True
+    session["all_flagged"] = all_flagged
+    _persist_session(session_id)
+
+    score = session["score"]
+    topics_list = "\n".join(f"  • {t}" for t in all_flagged) if all_flagged else "  (none — full score!)"
+
+    return "\n".join([
+        "=== SESSION ENDED ===",
+        f"Score: {score['correct']}/{score['total']} "
+        f"({score['incorrect']} incorrect, {score['partial']} partial)",
+        "",
+        "Auto-detected study topics:",
+        topics_list,
+        "",
+        "Generate a Study Plan now (see skill rules), then ask the user:",
+        '  "Want to add any extra topics to your study pack before I save it?"',
+        f"Then call save_study_pack(session_id='{session_id}', name=<chosen name>, content=<generated pack>)",
+    ])
+
+
+@mcp.tool()
+def save_study_pack(session_id: str, name: str, content: str) -> str:
+    """Save the study pack content to disk.
+
+    Args:
+        session_id: The session ID (must have called end_session first)
+        name: Slug name for this pack, e.g. "aws-saa-week1" or "python-interview-june"
+        content: The full study pack markdown generated by the AI
+    """
+    session = _sessions.get(session_id) or _restore_session(session_id)
+    if not session:
+        return f"ERROR: No session found with ID '{session_id}'."
+    if not session.get("ended"):
+        return "ERROR: Call end_session first before saving a study pack."
+
+    safe_name = re.sub(r"[^a-z0-9_-]", "-", name.lower().strip())
+    if not safe_name:
+        return "ERROR: Pack name must contain at least one letter or number."
+
+    packs = _packs_dir()
+    pack_json_path = packs / f"{safe_name}.json"
+    pack_md_path = packs / f"{safe_name}.md"
+
+    pack_data = {
+        "name": safe_name,
+        "mode": session["mode"],
+        "score": session["score"],
+        "topics": session.get("all_flagged", []),
+        "raw_markdown": content,
+    }
+    pack_json_path.write_text(json.dumps(pack_data, indent=2, ensure_ascii=False), encoding="utf-8")
+    pack_md_path.write_text(f"# Study Pack: {safe_name}\n\n{content}", encoding="utf-8")
+
+    _delete_session(session_id)
+
+    return (
+        f"Study pack '{safe_name}' saved.\n"
+        f"  JSON → {pack_json_path}\n"
+        f"  Markdown → {pack_md_path}"
+    )
+
+
+@mcp.tool()
+def list_sessions() -> str:
+    """List all saved sessions (pending and completed).
+
+    IMPORTANT: Call this at the start of every new conversation before doing anything else.
+    If there are pending (non-ended) sessions, ask the user whether they want to resume one
+    or start a new session. Use resume_session(session_id) to continue a pending session.
+    """
+    sessions_dir = _sessions_dir()
+    files = sorted(sessions_dir.glob("*.json"), key=lambda f: f.stat().st_mtime, reverse=True)
+    if not files:
+        return "No saved sessions found. Use start_session to begin."
+
+    lines = [f"Saved sessions ({len(files)}):\n"]
+    for f in files:
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+            session_id = f.stem
+            mode = data.get("mode", "?")
+            cert = data.get("cert_name", "")
+            score = data.get("score", {})
+            ended = data.get("ended", False)
+            status = "completed" if ended else "IN PROGRESS"
+            label = f"{mode}" + (f" — {cert}" if cert else "")
+            lines.append(
+                f"  • {session_id}  [{label}]  "
+                f"score: {score.get('correct','?')}/{score.get('total','?')}  [{status}]"
+            )
+        except Exception:
+            lines.append(f"  • {f.stem}  [unreadable]")
+
+    pending = sum(
+        1 for f in files
+        if not json.loads(f.read_text(encoding="utf-8")).get("ended", False)
+    )
+    if pending:
+        lines.append(f"\n{pending} session(s) in progress — use resume_session(session_id) to continue one.")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def resume_session(session_id: str) -> str:
+    """Resume a previously saved session. Returns full session state and skill rules.
+
+    Args:
+        session_id: The session ID to resume (from list_sessions)
+    """
+    session = _restore_session(session_id)
+    if not session:
+        return f"ERROR: No session found with ID '{session_id}'. Use list_sessions to see available sessions."
+    if session.get("ended"):
+        return f"ERROR: Session '{session_id}' has already ended. Use start_session to begin a new one."
+
+    mode = session["mode"]
+    skill = _load_skill(mode)
+    score = session["score"]
+    cert = session.get("cert_name", "")
+    q_num = session.get("q_num", 0)
+    auto_flagged = session.get("auto_flagged", [])
+
+    context_lines = [
+        f"Session ID: {session_id}",
+        f"Mode: {mode}",
+    ]
+    if cert:
+        context_lines.append(f"Certification: {cert}")
+    context_lines += [
+        f"Questions answered so far: {q_num}",
+        f"Score so far: {score['correct']}/{score['total']} "
+        f"({score['incorrect']} incorrect, {score['partial']} partial)",
+    ]
+    if auto_flagged:
+        context_lines.append("Topics flagged for study so far:")
+        for t in auto_flagged:
+            context_lines.append(f"  • {t}")
+
+    return "\n".join([
+        "=== STACKPREP SESSION RESUMED ===",
+        "\n".join(context_lines),
+        "\n=== SKILL RULES (follow these exactly) ===",
+        skill,
+    ])
+
+
+@mcp.tool()
+def list_study_packs() -> str:
+    """List all saved study packs."""
+    packs = _packs_dir()
+    files = sorted(packs.glob("*.json"))
+    if not files:
+        return f"No study packs saved yet. Packs are stored in: {packs}"
+
+    lines = [f"Saved study packs ({len(files)}) — {packs}\n"]
+    for f in files:
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+            mode = data.get("mode", "?")
+            score = data.get("score", {})
+            lines.append(f"  • {f.stem}  [{mode}]  score: {score.get('correct','?')}/{score.get('total','?')}")
+        except Exception:
+            lines.append(f"  • {f.stem}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def load_study_pack(name: str) -> str:
+    """Load a previously saved study pack by name.
+
+    Args:
+        name: The pack name (e.g. "aws-saa-week1"). Use list_study_packs to see available packs.
+    """
+    safe_name = re.sub(r"[^a-z0-9_-]", "-", name.lower().strip())
+    pack_path = _packs_dir() / f"{safe_name}.json"
+    if not pack_path.exists():
+        return f"ERROR: No study pack named '{safe_name}' found. Use list_study_packs to see available packs."
+
+    data = json.loads(pack_path.read_text(encoding="utf-8"))
+    return data.get("raw_markdown", json.dumps(data, indent=2))
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

stackprep_mcp/skills/certification.md

@@ -0,0 +1,110 @@
+---
+name: stackprep-certification
+description: Certification prep skill for the stackprep MCP server. Activated when mode is "certification". Drives question generation, scoring, adaptive difficulty, and study pack creation.
+---
+
+# stackprep — Certification Mode
+
+Adaptive certification exam prep — one question at a time, with instant feedback and doc links.
+
+## Session setup
+
+Inputs arrive via MCP (certification name, extra topics). Give a short 2–3 line summary:
+- Exam structure overview
+- Key domains and weightings from the latest official exam guide
+
+Then wait — questions are requested one at a time via `next_question`.
+
+## Question format
+
+Generate ONE question per turn. Never generate multiple questions at once.
+
+**Always multiple choice:**
+```
+Q. [Domain: <domain name>] <question text>
+  a) …
+  b) …
+  c) …
+  d) …
+```
+
+Do NOT include the answer in the question. Only reveal the correct answer in the EXPLANATION after the user has replied.
+
+## Scoring (after each answer)
+
+Keep scoring SHORT — 2 sentences max.
+
+- ⚠️ Partial = ✅ Correct. Note one improvement in 1 sentence.
+- ❌ Only if clearly wrong.
+
+Always use this exact structure:
+
+```
+RESULT: ✅ Correct   OR   RESULT: ⚠️ Partial   OR   RESULT: ❌ Incorrect
+
+EXPLANATION: <2 sentences max>
+
+DOCS: <Title>: <url>
+```
+
+Always include 1 real, publicly accessible URL relevant to the topic (official docs, RFC, vendor channel).
+
+After scoring, ask:
+**"Next question? [Y] — or type S to save a Study Pack, X to exit"**
+
+## Adaptive difficulty
+
+- Track topics the user gets wrong — weight subsequent questions toward those topics
+- Gradually increase difficulty on topics answered correctly
+- Never repeat the same question in a session
+
+## Study Pack
+
+A study pack is ALWAYS offered at the end of every session, regardless of score.
+
+The MCP server automatically tracks all ❌ Incorrect and ⚠️ Partial answers as study topics — the user does not need to flag them manually. If the user scored 100%, still offer the pack to reinforce the topics covered.
+
+When `end_session` is called, the server shows the auto-detected topics and asks:
+> "Want to add any extra topics before I generate it?"
+
+The user can say no or list extras, then call `save_study_pack` with a chosen name to persist it to disk.
+
+**Pack format** — produce a JSON block first, then a markdown summary:
+
+```json
+[
+  {
+    "topic": "",
+    "official_docs": [{"title": "", "url": ""}],
+    "videos": [{"title": "", "url": ""}],
+    "exam_prep": [{"title": "", "url": ""}],
+    "summary": ""
+  }
+]
+```
+
+Use only real, publicly accessible URLs. Never fabricate documentation links.
+
+## Exit / Study Plan
+
+When `end_session` is called, produce a **Study Plan**:
+- Topics mastered (≥ 80% correct)
+- Topics to review (50–79%)
+- Topics to focus on (< 50%)
+- 3–5 concrete study actions per weak area
+
+## Quality rules
+
+- Questions must reflect the latest stable documentation for every technology
+- Never repeat identical questions in the same session
+- For cert prep, always cite the exam domain and use the latest official exam guide
+- Only use real, publicly accessible URLs
+- **CRITICAL — answer position**: The correct answer MUST be placed at a genuinely random position (a, b, c, or d). Spread correct answers across all four letters throughout a session. Never default to b or c. If the last two questions shared the same correct letter, force a different one now.
+- Never use "all of the above" or "none of the above" unless it is the only honest way to test the concept.
+
+## Certifications with limited official documentation
+
+For newer or niche certifications (e.g. NVIDIA Agentic AI, emerging vendor certs) where the official exam guide is sparse:
+- Draw questions from course learning objectives and community exam reports (Reddit, Discord, LinkedIn posts from recent candidates).
+- Cite community sources in DOCS when no official docs exist.
+- Do NOT fabricate official documentation URLs.

stackprep_mcp/skills/interview.md

@@ -0,0 +1,109 @@
+---
+name: stackprep-interview
+description: Interview prep skill for the stackprep MCP server. Activated when mode is "interview". Drives question generation, scoring, adaptive difficulty, and study pack creation.
+---
+
+# stackprep — Interview Mode
+
+Adaptive technical interview prep — one question at a time, with instant feedback and doc links.
+
+## Session setup
+
+Inputs arrive via MCP (CV, job description, extra topics). Give a short 2–3 line summary:
+- Seniority level inferred from CV
+- Key domains
+- Top skill gaps vs. the job description
+
+Then wait — questions are requested one at a time via `next_question`.
+
+## Question format
+
+Generate ONE question per turn. Never generate multiple questions at once.
+
+**Open-ended** (only for simple one-sentence answers):
+```
+Q. [Conceptual | Scenario | Code | Gotcha] <question text>
+```
+
+**Multiple choice** (when the topic requires a long or detailed answer):
+```
+Q. [<domain>] <question text>
+  a) …
+  b) …
+  c) …
+  d) …
+```
+
+Do NOT include the answer in the question. Only reveal the correct answer in the EXPLANATION after the user has replied.
+
+## Scoring (after each answer)
+
+Keep scoring SHORT — 2 sentences max.
+
+- ⚠️ Partial = ✅ Correct. Note one improvement in 1 sentence.
+- ❌ Only if clearly wrong.
+
+Always use this exact structure:
+
+```
+RESULT: ✅ Correct   OR   RESULT: ⚠️ Partial   OR   RESULT: ❌ Incorrect
+
+EXPLANATION: <2 sentences max>
+
+DOCS: <Title>: <url>
+```
+
+Always include 1 real, publicly accessible URL relevant to the topic (official docs, RFC, vendor channel).
+
+After scoring, ask:
+**"Next question? [Y] — or type S to save a Study Pack, X to exit"**
+
+## Adaptive difficulty
+
+- Track topics the user gets wrong — weight subsequent questions toward those topics
+- Gradually increase difficulty on topics answered correctly
+- Never repeat the same question in a session
+
+## Study Pack
+
+A study pack is ALWAYS offered at the end of every session, regardless of score.
+
+The MCP server automatically tracks all ❌ Incorrect and ⚠️ Partial answers as study topics — the user does not need to flag them manually. If the user scored 100%, still offer the pack to reinforce the topics covered.
+
+When `end_session` is called, the server shows the auto-detected topics and asks:
+> "Want to add any extra topics before I generate it?"
+
+The user can say no or list extras, then call `save_study_pack` with a chosen name to persist it to disk.
+
+**Pack format** — produce a JSON block first, then a markdown summary:
+
+```json
+[
+  {
+    "topic": "",
+    "official_docs": [{"title": "", "url": ""}],
+    "videos": [{"title": "", "url": ""}],
+    "exam_prep": [{"title": "", "url": ""}],
+    "summary": ""
+  }
+]
+```
+
+Use only real, publicly accessible URLs. Never fabricate documentation links.
+
+## Exit / Study Plan
+
+When `end_session` is called, produce a **Study Plan**:
+- Topics mastered (≥ 80% correct)
+- Topics to review (50–79%)
+- Topics to focus on (< 50%)
+- 3–5 concrete study actions per weak area
+
+## Quality rules
+
+- Questions must reflect the latest stable documentation for every technology
+- Never repeat identical questions in the same session
+- For SQL/code, specify dialect/runtime (e.g. PostgreSQL 16, Python 3.12, dbt 1.8)
+- Only use real, publicly accessible URLs
+- **CRITICAL — answer position**: The correct answer MUST be placed at a genuinely random position (a, b, c, or d). Spread correct answers across all four letters throughout a session. Never default to b or c. If the last two questions shared the same correct letter, force a different one now.
+- Never use "all of the above" or "none of the above" unless it is the only honest way to test the concept.

stackprep_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: stackprep-mcp
+Version: 0.1.0
+Summary: stackprep as an MCP server — interview & certification prep for any AI client
+Project-URL: Homepage, https://github.com/youngpada1/stackprep-mcp
+Project-URL: Repository, https://github.com/youngpada1/stackprep-mcp
+Author-email: Flavia Fauconnet <flavsferr@gmail.com>
+License: MIT
+Keywords: ai,certification,interview,mcp,prep
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# stackprep-mcp
+
+> stackprep as an MCP server — interview & certification prep for any AI client
+
+Works with any MCP-compatible client: **Claude Code**, **Cursor**, **Cline**, **Windsurf**, **Continue.dev**, **Codex CLI**, and more. No API key required — your existing AI subscription does the work.
+
+---
+
+## What it does
+
+stackprep-mcp is a pure state-management MCP server. It tracks your session and study packs on disk; your AI client (Claude, Cursor, Codex, etc.) handles all the question generation and scoring logic using the skill rules returned at session start.
+
+- One question at a time — interview or certification mode
+- Instant scoring with doc links after every answer
+- Auto-detects wrong/partial answers and builds a named study pack
+- Sessions and study packs saved to disk — resume anytime, sync via iCloud
+- Resume in-progress sessions across conversations or devices
+
+---
+
+## Install
+
+Clone the repo and install dependencies with `uv`:
+
+```bash
+git clone https://github.com/youngpada1/stackprep-mcp
+cd stackprep-mcp
+uv sync
+```
+
+> Requires [uv](https://docs.astral.sh/uv/) and Python 3.11+.
+
+---
+
+## Configure your MCP client
+
+### Claude Code
+
+Create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "stackprep": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/stackprep-mcp", "stackprep-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Create `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "stackprep": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/stackprep-mcp", "stackprep-mcp"]
+    }
+  }
+}
+```
+
+Then open Cursor → **Cmd+Shift+J** → MCP tab — stackprep should appear with a green dot.
+
+### Codex CLI
+
+Add to `~/.codex/config.yaml`:
+
+```yaml
+mcpServers:
+  stackprep:
+    command: uv
+    args:
+      - run
+      - --directory
+      - /path/to/stackprep-mcp
+      - stackprep-mcp
+```
+
+Replace `/path/to/stackprep-mcp` with the absolute path to the cloned repo.
+
+---
+
+## Study pack storage
+
+Study packs and sessions are saved to `~/.stackprep/` by default.
+
+**Sync across devices with iCloud** (recommended on macOS):
+
+```bash
+# Add to ~/.zshrc or ~/.zprofile
+export STACKPREP_PACKS_DIR="$HOME/Documents/stackprep-packs"
+```
+
+`~/Documents` is synced to iCloud by default on macOS (requires iCloud Drive > Desktop & Documents enabled). Your packs will be available on any Mac signed into your Apple ID — and readable via the Files app on iPhone.
+
+**Custom path:**
+
+```bash
+export STACKPREP_PACKS_DIR="/path/to/your/folder"
+```
+
+Point this at any Dropbox, Google Drive, or OneDrive folder for cross-platform sync.
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `STACKPREP_PACKS_DIR` | `~/.stackprep` | Root directory for packs and sessions. |
+
+---
+
+## Skills (modes)
+
+| Mode | Description |
+|---|---|
+| `certification` | description: Certification prep skill for the stackprep MCP server. Activated when mode is "certification". Drives question generation, scoring, adaptive difficulty, and study pack creation. |
+| `interview` | description: Interview prep skill for the stackprep MCP server. Activated when mode is "interview". Drives question generation, scoring, adaptive difficulty, and study pack creation. |
+
+---
+
+## Tools
+
+| Tool | Description | Args |
+|---|---|---|
+| `start_session` | Start a new stackprep session. Returns a session ID and the skill rules for the AI to follow. | `mode`, `cert_name`, `cv`, `jd`, `extra_topics` |
+| `submit_answer` | Record the result of an answered question. | `session_id`, `result`, `question` |
+| `flag_for_study` | Manually flag the current question for the study pack. | `session_id`, `question` |
+| `end_session` | End the session. Returns the score and flagged topics so the AI can generate a study plan and study pack. | `session_id` |
+| `save_study_pack` | Save the study pack content to disk. | `session_id`, `name`, `content` |
+| `list_sessions` | List all saved sessions (pending and completed). |  |
+| `resume_session` | Resume a previously saved session. Returns full session state and skill rules. | `session_id` |
+| `list_study_packs` | List all saved study packs. |  |
+| `load_study_pack` | Load a previously saved study pack by name. | `name` |
+
+---
+
+## Session flow
+
+**Certification:**
+```
+list_sessions()                                          ← always called first
+→ start_session(mode="certification", cert_name="AWS SAA-C03")
+→ [AI generates questions one at a time]
+→ submit_answer(session_id, result="correct"|"partial"|"incorrect", question="...")
+→ ... repeat ...
+→ end_session(session_id)
+→ save_study_pack(session_id, name="aws-saa-week1", content="...")
+```
+
+**Interview:**
+```
+list_sessions()                                          ← always called first
+→ start_session(mode="interview", cv="...", jd="...")
+→ [AI generates questions one at a time]
+→ submit_answer(session_id, result="correct"|"partial"|"incorrect", question="...")
+→ ... repeat ...
+→ end_session(session_id)
+→ save_study_pack(session_id, name="python-interview-june", content="...")
+```
+
+**Resuming a session:**
+```
+list_sessions()                → shows in-progress sessions
+→ resume_session(session_id)  → loads state + skill rules, continues where you left off
+```
+
+**Loading a saved study pack:**
+```
+list_study_packs()
+→ load_study_pack(name="aws-saa-week1")
+```
+
+---
+
+## Session persistence
+
+Every session is saved to disk on every update. At the start of each new conversation the AI automatically calls `list_sessions` and asks whether you want to resume an in-progress session or start a new one. Sessions are stored in `~/.stackprep/sessions/` (or your custom `STACKPREP_PACKS_DIR`).
+
+---
+
+## Also available as a Claude Code plugin
+
+For Claude Projects or direct Claude.ai use, the behaviour rules are also available as a standalone skill file at [plugins/stackprep](https://github.com/youngpada1/stackprep/tree/main/plugins/stackprep) — no install needed.
+
+---
+
+## Contributing / Development
+
+```bash
+git clone https://github.com/youngpada1/stackprep-mcp
+cd stackprep-mcp
+
+# Install dependencies
+uv sync
+
+# Activate the pre-commit hook (auto-regenerates README on every commit)
+git config core.hooksPath .githooks
+
+# Run the server locally
+uv run stackprep-mcp
+```
+
+The README is auto-generated from `server.py` tool definitions and the skills files in `src/stackprep_mcp/skills/`.
+To regenerate manually:
+
+```bash
+uv run python scripts/generate_readme.py
+```
+
+---
+
+## License
+
+MIT — [Flavia Fauconnet](https://github.com/flavsferr)

stackprep_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+stackprep_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stackprep_mcp/server.py,sha256=Mt4c2iLFaS7M-hOd2JRY5Ua__5lRbTw0Vv-dGxLDA44,13353
+stackprep_mcp/skills/certification.md,sha256=8YcxfUM9coY93gHQVLPTgmzzptg3621p3mF9EwNkeME,3982
+stackprep_mcp/skills/interview.md,sha256=DmzfwO4xMDi7OfZFfIAFswQdGO--WQtuFvaeLcPT0DU,3698
+stackprep_mcp-0.1.0.dist-info/METADATA,sha256=xf2k18DvHkzi69FX5prWBYVoDkMLmUmdlfQS917Bcqw,7397
+stackprep_mcp-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+stackprep_mcp-0.1.0.dist-info/entry_points.txt,sha256=XYbSPfESAJ4JDMyc2UZd9Vt8HsDzr3X6XLPT1Wz-ER8,60
+stackprep_mcp-0.1.0.dist-info/RECORD,,

stackprep_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

stackprep_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stackprep-mcp = stackprep_mcp.server:main