# Study Buddy

> An MCP server that gives Claude Desktop structured access to your notes and past papers. Discovers topics, teaches in any style, quizzes you on grounded content, extracts PYQ patterns, and tracks mastery in local SQLite. Built with the official MCP Python SDK + FastMCP.

- **Type:** MCP server
- **Install:** `agentstack add mcp-eshitakundu-study-buddy`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [eshitakundu](https://agentstack.voostack.com/s/eshitakundu)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [eshitakundu](https://github.com/eshitakundu)
- **Source:** https://github.com/eshitakundu/study-buddy

## Install

```sh
agentstack add mcp-eshitakundu-study-buddy
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

[](https://python.org)
[](https://modelcontextprotocol.io)
[](https://docs.astral.sh/uv/)
[](https://sqlite.org)
[](LICENSE)

[**Quick Start**](#-quick-start) · [**How it Works**](#-how-it-works) · [**Tools & Prompts**](#-tools) · [**Extend**](#-extend) · [**Full Tutorial**](TUTORIAL.md)

---

## ✨ 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

```bash
# 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](#-connect-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

```mermaid
flowchart LR
    A[📁 materials/content + pyqs] --> B[⚙️ study_buddy.pyMCP server]
    B --> C[💾 SQLitetopics + results]
    B |stdio| D[🤖 Claude Desktop]
    D -->|calls tools| B
    D -->|renders prompts| B
    D -->|reads resources| B
```

### 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](https://docs.astral.sh/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,

Install

```bash
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

```bash
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:
> ```powershell
> 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`

```json
{
  "mcpServers": {
    "study-buddy": {
      "command": "C:\\Users\\\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\Users\\\\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

[](https://python.org)
[](https://github.com/modelcontextprotocol/python-sdk)
[](https://pydantic.dev)
[](https://sqlite.org)
[](https://docs.astral.sh/uv/)

- **[Official MCP Python SDK](https://github.com/modelcontextprotocol/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](https://github.com/eshitakundu) (see [LICENSE](LICENSE)).

---

**Built for the [Codédex Monthly Challenge, June 2026](https://www.codedex.io/community/monthly-challenge)**

⭐ Star if this taught you something · 🐛 [Issues](https://github.com/eshitakundu/study-buddy/issues) · 💬 [Discussions](https://github.com/eshitakundu/study-buddy/discussions)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [eshitakundu](https://github.com/eshitakundu)
- **Source:** [eshitakundu/study-buddy](https://github.com/eshitakundu/study-buddy)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-eshitakundu-study-buddy
- Seller: https://agentstack.voostack.com/s/eshitakundu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.