examintel-mcp

An MCP (Model Context Protocol) server that turns your own PYQ/syllabus PDFs and HTML documents into a queryable exam-intelligence tool — usable from Claude Desktop or any MCP client. Runs fully locally. No API keys, no signups, no per-query cost.

1. Prerequisites

Python 3.10+ installed. Check with:

python3 --version

(On Windows, this is usually just python --version in Command Prompt or PowerShell.)

2. Setup

# from inside the examintel-mcp folder
python3 -m venv venv

# activate it:
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows (Command Prompt or PowerShell)

pip install -r requirements.txt

3. Add your PYQs

Organize PDFs or HTML files under data/pdfs/<subject>/<year>.pdf or data/pdfs/<subject>/<source_name>.html — the folder name becomes the subject tag, and the filename (without extension) becomes the year/source tag. Example:

data/pdfs/COA/2022.pdf
data/pdfs/COA/2023.pdf
data/pdfs/COA/2024.pdf
data/pdfs/CN/CN_Master_Guide.html
data/pdfs/JAVA/Java_Master_Guide.html

Start with 2 subjects, not your whole semester — get the pipeline working end to end first, then scale up.

4. Build the index

python ingest.py

First run downloads a small (~67MB) embedding model from Hugging Face — that's the only time this needs internet. Every run after that, and every query, is fully offline. You'll see a per-file chunk count printed; if a file shows 0 chunks, it's probably a scanned/image-only PDF (see Limitations below).

5. Connect it to Claude Desktop

Claude Desktop installs local MCP servers as "Desktop Extensions" (.mcpb files), not through manual JSON config editing.

1. Open Claude Desktop → Settings → Extensions → Advanced settings → Extension Developer section → "Install Extension..."
2. Select the .mcpb file built from extension/.
3. When prompted for Project Data Folder, select this project's folder (the one with data/pdfs and chroma_db).
4. Restart Claude Desktop, then ask something like: "Use examintel to find COA pipelining questions"

6. The three tools

• search_topic(subject, query) — semantic search across indexed papers, returns matches with year + source
• topic_frequency(subject) — ranks recurring terms by how often they appear
• generate_study_plan(subject, days_remaining) — combines frequency with your timeline into a revision order

7. Limitations (be upfront about these in interviews — it reads better than pretending they don't exist)

Scanned/photocopied PDFs with no embedded text won't extract anything — OCR fallback (pytesseract) isn't wired in yet; that's a clean, well-scoped v2 feature to mention if asked "what would you add next." The question-boundary chunker is a regex heuristic tuned for "Q1.", "Q.1", "1.", "1)" style numbering — unusual paper formats may fall back to fixed-window chunking, which still works but loses the "one chunk = one question" cleanliness. topic_frequency is keyword counting, not true topic modeling — a fast, transparent first version, not a final one.

8. Next step: publish it

Once this works locally, publish to the official MCP registry (modelcontextprotocol/registry on GitHub, via the mcp-publisher CLI) and cross-list on mcp.so / smithery.ai. That's what turns this from "a project on my laptop" into a public, clickable artifact — see the PRD for the full checklist.