# Automatic PPT Generator Agent (MCP + VS Code)

A beginner-friendly, end-to-end project that builds:
- An MCP server (Model Context Protocol) that can generate PowerPoint files
- A Node.js API backend
- A professional, interactive web UI
- Dynamic slide content that changes on every generation

## What You Will Build

- `MCP server`: exposes a `generate_ppt` tool
- `Backend API`: validates requests, calls generation pipeline, serves generated files
- `Presentation engine`: creates slide deck structure, design themes, and content variants
- `Interactive UI`: enter topic, audience, tone, style, and generate/download PPT

---

## 1) Prerequisites

Install these first:

1. Node.js 20+ (recommended LTS)
2. VS Code
3. npm (comes with Node.js)
4. Groq API key for AI-generated content
5. Internet access for live data lookup

Check versions in terminal:

```powershell
node -v
npm -v
```

---

## 2) Project Setup

From this project folder:

```powershell
npm install
npm run dev
```

The app starts at:
- UI: `http://localhost:5173`
- API: `http://localhost:8787`

---

## 3) Environment Variables

Copy `.env.example` to `.env` and update values:

```powershell
Copy-Item .env.example .env
```

Important variables:

- `PORT`: backend port
- `VITE_API_BASE_URL`: frontend API URL
- `PPT_PROVIDER`: set to `groq`
- `GROQ_API_KEY`: optional, required only when using Groq
- `GROQ_MODEL`: optional, default is `llama-3.1-70b-versatile`

Set `GROQ_API_KEY` in `.env` to enable AI-written slide content. The deck content is built from live web data first, using Wikipedia + GDELT signals, and then shaped into slides by Groq.

In MCP config, set the same Groq variables under `env`.

Security note: if a real key was ever pasted into a shared/example file, rotate it in your provider dashboard and replace it with a placeholder.

---

## 4) How Dynamic Content Works

Every generation changes because the app combines:

1. Live topic lookup from Wikipedia and current news signals
2. Topic-family slide blueprints that change by subject area
3. Variable slide structures and slide kinds
4. Rotating content angles and examples
5. Timestamp/seed-based variation
6. Groq-generated slide copy on top of live data

This ensures different wording and structure each run, while also grounding the output in current information.

---

## 5) How MCP Fits In

This project includes a local MCP server:

- File: `mcp/server.js`
- Tool exposed: `generate_ppt`

You can connect this MCP server from compatible MCP clients (including VS Code flows) so agent workflows can trigger PPT generation.

### MCP Tool Input

```json
{
  "topic": "AI in Healthcare",
  "audience": "college students",
  "tone": "engaging",
  "slides": 8,
  "theme": "corporate"
}
```

### MCP Tool Output

```json
{
  "ok": true,
  "fileName": "ai-in-healthcare-2026-06-19T10-00-00-000Z.pptx",
  "downloadUrl": "/generated/ai-in-healthcare-2026-06-19T10-00-00-000Z.pptx"
}
```

---

## 6) Beginner-Friendly Workflow in VS Code

1. Open this folder in VS Code.
2. Open terminal.
3. Run `npm install`.
4. Run `npm run dev`.
5. Open `http://localhost:5173`.
6. Enter topic and options.
7. Click **Generate PPT**.
8. Download the file.

---

## 7) Production Build

```powershell
npm run build
npm run start
```

---

## 8) Extend the Agent

Ideas:

1. Add charts from real data sources
2. Add image search integration
3. Add brand kit upload (logo/colors/fonts)
4. Add multilingual slide generation
5. Add speaker notes auto-generation

---

## 9) Troubleshooting

### Error: Cannot find module
Run:

```powershell
npm install
```

### UI opens but generate fails
- Check backend running on `8787`
- Check `.env` values
- Check terminal logs

### LLM not used
- Set `GROQ_API_KEY` in `.env`
- Restart `npm run dev`

---

## 10) File Structure

See project layout in this repository:

- `src/server/` backend + generation pipeline
- `src/client/` modern interactive frontend
- `mcp/` MCP server entrypoint
- `generated/` exported PowerPoint files

You can now use this as a foundation to build a strong custom PPT generation agent.