# StudyTools MCP

A Model Context Protocol (MCP) server that exposes four study tools — PDF summarization,
flashcard generation, math/code problem solving, and trust-filtered web search — to any
MCP-compatible client (Claude Desktop, MCP Inspector, custom agents, etc.).

See [Student_MCP_Server_PRD.md](Student_MCP_Server_PRD.md) and
[Student_MCP_Server_TechStack.md](Student_MCP_Server_TechStack.md) for the full spec and
design rationale.

## Tools

| Tool | Description |
|---|---|
| `summarize_pdf` | Extracts text from a PDF and returns a summary + 3-5 key points. |
| `generate_flashcards` | Turns raw notes/text into Q&A flashcard pairs (default 10). |
| `solve_and_explain` | `mode="math"`: symbolic solve via sympy, LLM fallback for word problems. `mode="code"`: explains/debugs a code snippet via LLM. |
| `web_search` | Searches the web via Tavily, filtered by default (`trusted_only=true`) to reference/educational domains + a relevance threshold. Optional `summarize=true` synthesizes an answer with citations. |

## Prerequisites

- Python 3.10+
- A free [Groq](https://console.groq.com) API key (LLM calls)
- A free [Tavily](https://tavily.com) API key (web search)

## Local setup

```bash
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux

pip install -r requirements.txt
cp .env.example .env            # then fill in GROQ_API_KEY and TAVILY_API_KEY
```

## Running locally

**MCP Inspector** (browser UI to call tools directly, no client wiring needed):

```bash
mcp dev server.py
```

Opens a browser at `localhost:6274` listing all four tools — fill in inputs and run them.

**Claude Desktop**: add an entry to your `claude_desktop_config.json`
(Windows: `%APPDATA%\Claude\claude_desktop_config.json`; some installs — e.g. Microsoft
Store builds — sandbox this under
`%LOCALAPPDATA%\Packages\<PackageName>\LocalCache\Roaming\Claude\`):

```json
{
  "mcpServers": {
    "studytools": {
      "command": "C:\\path\\to\\project\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\project\\server.py"]
    }
  }
}
```

Fully quit and relaunch Claude Desktop afterward, then check the tools/connectors icon
in a new chat for `studytools`.

By default the server runs over **stdio** (`MCP_TRANSPORT` unset). No host/port needed
for local client use.

## Deploying

The server supports **streamable-http** in addition to stdio, needed for any remotely
hosted deployment (a hosted process can't run stdio the way a local desktop client does).

### AWS EC2 (free tier) — primary target

Uses a t2.micro/t3.micro instance (750 hrs/month free for 12 months) running the server
as a systemd service so it survives reboots and restarts on crash.

1. **Launch an instance**: Ubuntu 22.04/24.04, `t2.micro` or `t3.micro` (free-tier
   eligible), with a key pair you can SSH in with.
2. **Security group**: allow inbound
   - port `22` (SSH) from **your IP only**, not `0.0.0.0/0`
   - port `8000` (the MCP endpoint) from `0.0.0.0/0` if you want it publicly reachable,
     or restrict it to known client IPs — note there's no auth in front of the server
     (matches the PRD's v1 scope, which excludes multi-user auth), so anything with
     network access can call your tools and consume your Groq/Tavily quota.
3. **SSH in, clone the repo, and run the setup script**:
   ```bash
   git clone <your-repo-url> studytools-mcp
   cd studytools-mcp
   bash deploy/setup_ec2.sh
   ```
   This installs Python deps into a venv, creates `.env` from `.env.example` if missing,
   and registers/starts `deploy/studytools-mcp.service` via systemd.
4. **Add your real API keys**: `nano .env`, fill in `GROQ_API_KEY` and `TAVILY_API_KEY`,
   then `sudo systemctl restart studytools-mcp`.
5. **Verify**: `curl http://<ec2-public-ip>:8000/mcp` (a 400/406 response is expected
   from a bare curl request — it means the server is up; a real MCP client will complete
   the full handshake). Logs: `sudo journalctl -u studytools-mcp -f`.

This serves plain HTTP, not HTTPS — fine for a free-tier demo, but note it if you ever
point a client that requires TLS at it (adding an Nginx reverse proxy + Let's Encrypt
would be the next step, out of scope for v1).

### Render — alternative

`render.yaml` is included as a documented fallback if you'd rather not manage a server
yourself:

1. Push this repo to GitHub/GitLab/Bitbucket.
2. In Render, choose **New > Blueprint** and point it at the repo — it reads
   [render.yaml](render.yaml) and provisions the service automatically.
3. Add `GROQ_API_KEY` and `TAVILY_API_KEY` under the service's **Environment** tab
   (marked `sync: false` in the blueprint, so Render won't set them for you).
4. The MCP endpoint is reachable at `https://<your-service>.onrender.com/mcp`.

If Render's health check fails against `/` (the MCP route only exists at `/mcp`), set
the service's **Health Check Path** to `/mcp` in the dashboard.

## Project structure

```
app.py                  # FastMCP instance, host/port/env config
llm.py                  # Groq client wrapper (chat_completion, JSON mode)
server.py               # Entrypoint — registers tools, runs stdio or streamable-http
tools/
  pdf_tools.py           # summarize_pdf
  flashcard_tools.py     # generate_flashcards
  solve_tools.py         # solve_and_explain
  search_tools.py        # web_search
deploy/
  studytools-mcp.service # systemd unit for AWS EC2
  setup_ec2.sh            # EC2 provisioning script
requirements.txt
render.yaml              # Render Blueprint (alternative deploy path)
.env.example
```