# Study Prep MCP Server

MCP tools to browse and prepare study materials from a local document folder — PDF, Markdown, plain text, and Word files.

The server extracts text and structure locally; your MCP client (e.g. Cursor) generates summaries and practice questions from the returned content.

## Tools

| Tool | What it does |
|------|----------------|
| `get_corpus_overview` | Categories, file counts, sizes, supported extensions |
| `list_documents` | List files with optional category or glob filter |
| `read_document` | Read or extract text from one file (PDF page range supported) |
| `search_documents` | Full-text search with snippet context |
| `extract_key_terms` | Keyword extraction via YAKE (one doc or whole category) |
| `get_document_outline` | Headings / outline for structured review |
| `get_study_chunks` | Split long docs into numbered study chunks |
| `prepare_study_session` | Bundle excerpts, key terms, and AI prompts for a topic |
| `get_quiz_source_material` | Labeled excerpts + instructions for Q&A generation |

## Quick start

```bash
git clone https://github.com/YOUR_ORG/study-md-mcp.git
cd study-md-mcp

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Smoke test on stdio (Ctrl+C to stop)
MD_DOCS_PATH=/path/to/your/study-documents python server.py
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/YOUR_ORG/study-md-mcp.git
cd study-md-mcp

uv venv && uv pip install -e .
MD_DOCS_PATH=/path/to/your/study-documents uv run server.py
```

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `MD_MCP_NAME` | `study-md` | FastMCP server name |
| `MD_DOCS_PATH` | `.` | Root folder for study documents |

Set `MD_DOCS_PATH` to the folder containing your study files. On WSL with Windows files, use the `/mnt/c/...` path.

## Connect to Cursor

Copy `examples/cursor-mcp-config.json` and adjust paths:

```json
{
  "mcpServers": {
    "study-md": {
      "command": "/path/to/study-md-mcp/.venv/bin/python",
      "args": ["/path/to/study-md-mcp/server.py"],
      "env": {
        "MD_MCP_NAME": "study-md",
        "MD_DOCS_PATH": "/path/to/your/study-documents"
      }
    }
  }
}
```

Then ask Cursor to use `study-md` tools, e.g. “Search my study docs for essay requirements” or “Prepare a study session on offer terms.”

## Connect to Claude Desktop (Windows + WSL)

If Claude Desktop runs on Windows but documents live in WSL, see `examples/claude-desktop-config.json`.

## Connect to Claude CLI

```bash
claude mcp add study-md \
  -e MD_MCP_NAME=study-md \
  -e MD_DOCS_PATH=/path/to/your/study-documents \
  -- /path/to/study-md-mcp/.venv/bin/python /path/to/study-md-mcp/server.py
```

## Supported formats

| Extension | Method |
|-----------|--------|
| `.md`, `.txt` | Direct UTF-8 read |
| `.pdf` | Text extraction via PyMuPDF |
| `.docx` | Paragraph text via python-docx |

Scanned/image-only PDFs are not supported (no OCR).

## Document layout

Organize files under `MD_DOCS_PATH` by category subfolder:

```
study-documents/
├── notes/
├── exams/
├── essays/
└── reference/
```

Empty category folders appear in `get_corpus_overview` with count 0.

## License

MIT — see [LICENSE](LICENSE).