Study Buddy

Turn your notes and past papers into a focused, local AI study system.

An MCP server that gives Claude structured access to your study material, so it can teach, quiz, and drill you on your own content, and remember how you did.

Quick Start · How it Works · Tools & Prompts · Extend · Full Tutorial

---

✨ Why Study Buddy

LLMs can reason. They can't reach into your world: your notes, your past papers, your progress.

Study Buddy closes that gap with the Model Context Protocol (MCP). You drop material into two folders. Your MCP client (Claude Desktop, Cursor, anything MCP-compatible) can now:

📚 Learn Teach any topic from your material, in any style you ask for: Feynman, Socratic, exam-cram, ELI5, or anything else.

🧠 Practice Grounded quizzes from your notes. PYQ-pattern practice: real past questions verbatim, or new questions in that exact style.

📈 Track Local SQLite tracks mastery per topic across sessions. Weakest topics surface first. Archive what you've mastered.

Built to also serve as a complete reference for the MCP protocol: every primitive, exercised with production-shaped code.

---

⚡ Quick Start

# 1. Clone
git clone https://github.com/eshitakundu/study-buddy.git
cd study-buddy

# 2. Install
uv sync

# 3. Drop notes into materials/content/ and past papers into materials/pyqs/

# 4. Verify the server with the MCP Inspector
uv run mcp dev study_buddy.py

Then connect it to Claude Desktop and start a chat:

"Discover topics in my materials, register the real ones, then quiz me on the weakest one."

---

🧬 How it Works

flowchart LR
    A[📁 materials/<br/>content + pyqs] --> B[⚙️ study_buddy.py<br/>MCP server]
    B --> C[💾 SQLite<br/>topics + results]
    B <-->|stdio| D[🤖 Claude Desktop]
    D -->|calls tools| B
    D -->|renders prompts| B
    D -->|reads resources| B

Loading

The three MCP primitives, doing real work

Primitive	Role in Study Buddy	Examples
🔧 Tools	Actions the model invokes	search_content, log_result, extract_pyq_style
📖 Resources	Browsable, URI-addressed context	study://topics, study://content
💬 Prompts	Parameterized study workflows	study, quiz, pyq_test

Plus typed inputs via Pydantic Field, persistent state via SQLite, and path-traversal-safe file access.

---

📁 Project Structure

study-buddy/
├── 📦 study_buddy.py         ← the entire server, one file
├── 🗄️  study.db              ← auto-created SQLite tracker
├── 📚 materials/
│   ├── content/            ← notes, slides, textbook extracts
│   ├── pyqs/               ← previous-year question papers
│   └── archive/            ← files you've moved aside
├── 🖼️  assets/banner.png
├── pyproject.toml
├── uv.lock
└── README.md

Subfolders and study.db are auto-created on first run.

---

📥 Setup

Requirements

• Python 3.10+
• uv: fast Python package manager
• MCP-compatible client: Claude Desktop, Cursor, Cline, etc.
• Node.js: only for the MCP Inspector via mcp dev

Pinned dependencies:

• mcp[cli]>=1.27,<2: the <2 bound matters; SDK v2 changes import paths
• pypdf
• python-docx

Install

git clone https://github.com/eshitakundu/study-buddy.git
cd study-buddy
uv sync

Add your study material

Notes (materials/content/):

dbms-notes.md
transactions.pdf
normalization-slides.docx
er-diagram.png

Past papers (materials/pyqs/):

dbms-midterm-2024.pdf
dbms-final-2023.txt
operating-systems-pyq.docx

Files moved via archive_files land in materials/archive/.

---

🧪 Run and Test

uv run mcp dev study_buddy.py

Opens the MCP Inspector in your browser (via npx). List and call every tool, read resources, and preview rendered prompts, all before touching your client.

⚠️ Gotcha: if node stays alive on port 6277 after the Inspector closes, the next mcp dev fails with Proxy Server PORT IS IN USE. Fix on Windows:

Get-Process node | Stop-Process -Force

---

🔌 Connect to Claude Desktop

Config file:

• Windows → %APPDATA%\Claude\claude_desktop_config.json
• macOS → ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "study-buddy": {
      "command": "C:\\Users\\<you>\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\Users\\<you>\\path\\to\\study-buddy",
        "run",
        "study_buddy.py"
      ]
    }
  }
}

🔑 Three things that trip everyone up:

1. Use absolute paths: Claude Desktop's working directory isn't your project folder.
2. On Windows, escape backslashes as \\.
3. Fully quit Claude Desktop from the system tray before reopening. Closing the window isn't enough.

Debug logs → %APPDATA%\Claude\logs\mcp-server-study-buddy.log

---

🔧 Tools

📚 Material

Tool	Purpose
list_content	List files in materials/content/
list_pyqs	List files in materials/pyqs/
read_file	Read a file from content, pyqs, or archive
search_content	Substring search across content files
archive_files	Physically move files into materials/archive/

🎯 Topics & Progress

Tool	Purpose
discover_topics	Rank candidate topics from headings, bold text, question stems
register_topic	Add a topic to the tracker
list_topics	Active topics with attempts, mastery %, last-attempt time
archive_topic	Mark a topic as mastered (metadata only)
log_result	Record a quiz score against a registered topic
weakest_topics	Lowest-mastery active topics

📋 PYQ Analysis

Tool	Purpose
extract_pyq_style	Structural profile: types, marks, stems, samples
extract_pyq_questions	Parsed list of actual questions from a past paper

---

📖 Resources

URI	Content
study://content	Markdown index of materials/content/
study://pyqs	Markdown index of materials/pyqs/
study://topics	Mastery tracker: active + archived

💡 Important: in Claude Desktop, resources are user-attached, not auto-fetched. Tools are model-initiated. Design accordingly.

---

💬 Prompts

🎓 study Teach a topic from your content in any style. topic: normalization style: feynman Styles: default, feynman, socratic, eli5, summary, exam-cram, or anything else the model can interpret.	🏫 study_all Walk through every active registered topic. style: default order: weakest_first | registered
📝 quiz Grounded quiz drawn only from your content. One question at a time. Results logged automatically. topic: functional dependencies n: 5	🎯 pyq_test Real past questions or new ones matching the paper's style. topic: normalization mode: ask | verbatim | style n: 5

---

🛡️ Safety

• All file access confined to materials/content/, materials/pyqs/, materials/archive/
• Paths validated via Path.is_relative_to: blocks ../../.env traversal
• Topic strings normalized and fuzzy-matched against registered rows: no silent row creation
• Every input bound (n, days, max_results) enforced via Pydantic Field metadata

---

📄 Supported Files

Type	Extensions	Handling
Text	.txt, .md	Direct read
PDF	.pdf	pypdf text extraction
Word	.docx	python-docx extraction
Image	.png, .jpg, .jpeg, .webp	Returned as MCP ImageContent: vision-capable clients read it directly

⚠️ Scanned PDFs have no extractable text. pypdf returns empty. OCR (Tesseract) or a text-based version before dropping in.

---

🎬 Example Session

1. Discover topics from my material.
2. Register normalization and functional dependencies.
3. Teach me normalization in exam-cram style.
4. Quiz me on normalization with 5 questions.
5. Show my weakest topics.
6. Give me a PYQ-style test on functional dependencies.

The client chains discovery → registration → retrieval → quiz → logging, all against your own material.

---

🚀 Extend

Same MCP scaffolding, different domain:

📄 Research-paper assistant	📚 Local docs navigator	🧑‍💻 Codebase explainer
💼 Job-application tracker	💰 Personal finance coach	🍳 Recipe & meal planner

The recipe:

safe data access
+ tools           (actions)
+ resources       (browsable context)
+ prompts         (workflows)
+ persistent state (SQLite)
= a practical MCP server

---

🛠️ Built With

• Official MCP Python SDK: mcp[cli] with FastMCP
• SQLite: persistent state (stdlib)
• Pydantic: typed inputs (via the SDK)
• pypdf, python-docx: file extraction
• uv: dependency management

---

📜 License

MIT © Eshita Kundu (see LICENSE).

---

Built for the Codédex Monthly Challenge, June 2026

⭐ Star if this taught you something · 🐛 Issues · 💬 Discussions