# Wajeeha Download Manager
A fast download manager for Windows with multi-connection accelerated downloads, dynamic segmentation, pause/resume, categories, queues with a scheduler, a site grabber, batch downloads, ZIP preview, a speed limiter, browser extensions, and support for AI agents through the Model Context Protocol (MCP).

## Main Screenshot
<img src="https://github.com/muhammad-wajeeh-uz-zaman/Wajeeha-Download-Manager/blob/main/screenshots/SS4.PNG">

## Other Screenshots
<div align="center">
<img src="https://raw.githubusercontent.com/muhammad-wajeeh-uz-zaman/Wajeeha-Download-Manager/main/screenshots/SS1.PNG" width="400">
<img src="https://raw.githubusercontent.com/muhammad-wajeeh-uz-zaman/Wajeeha-Download-Manager/main/screenshots/SS2.PNG" width="400">
<br>
<img src="https://raw.githubusercontent.com/muhammad-wajeeh-uz-zaman/Wajeeha-Download-Manager/main/screenshots/SS3.PNG" width="400">
<img src="https://raw.githubusercontent.com/muhammad-wajeeh-uz-zaman/Wajeeha-Download-Manager/main/screenshots/SS5.png" width="400">
</div>

## Contents

1. [Quick start](#1-quick-start)
2. [Build the .exe](#2-build-the-exe)
3. [Browser extension](#3-browser-extension)
4. [HTTPS certificate errors](#4-https-certificate-errors)
5. [Using the app](#5-using-the-app)
6. [AI agents (MCP)](#6-ai-agents-mcp)
7. [How it works](#7-how-it-works)
8. [Limitations](#8-limitations)
9. [Project layout](#9-project-layout)

---

## 1. Quick start

**Requirements:** Windows and Python 3.10 or newer.

1. Unzip the folder anywhere.
2. Double-click **`setup_and_run.bat`**. It installs PySide6 once, then starts the app.

   Or run it yourself in a Command Prompt inside the folder:

   ```bat
   pip install -r requirements.txt
   python main.py
   ```

On first start the app creates these folders inside your Windows Downloads folder:

```
Compressed   Documents   Images   Music   Programs   Video
```

Files that don't match a category stay in the Downloads folder itself. You can change the folders and file types at any time under **Options > Save to**, or by right-clicking a category.

---

## 2. Build the .exe

Double-click **`build_exe.bat`**. It creates a `dist` folder containing:

| File | Purpose |
|---|---|
| `Wajeeha Download Manager.exe` | The app |
| `wajeeha-mcp.exe` | Small helper so AI apps (Claude Code, etc.) can use the app |
| `extension\` | The browser extension. Keep it beside the exe |

Copy them together wherever you want.

> Windows SmartScreen may warn about an unsigned exe the first time you run it. Choose **More info > Run anyway**.

---

## 3. Browser extension

Install it once per browser. The app must be running (it can sit in the system tray).

### Chrome / Edge / Brave / Opera / Vivaldi

1. Open the extensions page: `chrome://extensions` (or `edge://extensions`, etc.).
2. Turn on **Developer mode**.
3. Click **Load unpacked** and choose the `extension` folder.

> **Tip:** in the app, **Help > Browser integration** shows the exact folder path.

### Firefox

1. Open `about:debugging#/runtime/this-firefox`.
2. Click **Load Temporary Add-on** and choose `extension\manifest.json`.
3. In `about:addons`, open the extension's **Permissions** and allow *Access your data for all websites*.

Firefox forgets temporary add-ons when it closes. A permanent install needs a signed add-on or Firefox Developer Edition.

### What the extension does

- Takes over downloads of the file types listed in **Options > Browser**.
- Right-click a link, image, or video: **Download with Wajeeha DM**.
- Right-click a page: **Download files from this page (Grabber)**.
- Shows a **Download this video** button over videos, and lists the media it saw in its popup (the blue number on the toolbar icon).
- Hold **Alt** while clicking a link to let the browser download it normally.
- If the app is not running, the browser just downloads as usual.

### Updating

If you update the app, also update the extension. Open the extensions page and click the circular **Reload** arrow on the Wajeeha extension (or remove it and **Load unpacked** again), then refresh any open tabs.

### If the extension says it can't reach the app

1. Look at the bottom-right of the app window. It should say `Browser link: port 49875, extension connected`. If it says *waiting for the browser extension*, the extension has not reached the app yet.
2. Click the extension's toolbar icon. The top line shows the exact reason (for example `port 49875: Failed to fetch`) plus a **Check again** button.
3. Make sure the extension has permission for all sites, and that no security software blocks `127.0.0.1` (localhost) connections.
4. Still stuck? Check `%APPDATA%\WajeehaDownloadManager\app.log` for details.

---

## 4. HTTPS certificate errors

Some sites open fine in your browser but fail in the app with a certificate message. The browser uses Windows' own certificate checker, which fetches missing certificates by itself. Since v1.0.2 the app uses that same Windows checker (the `truststore` package, installed by `setup_and_run.bat` and `build_exe.bat`), so most of these errors disappear.

After updating, run `setup_and_run.bat` again and rebuild the exe.

If a site still can't be verified, the message says why:

| Message | Likely cause |
|---|---|
| *can't confirm who issued its certificate* | Antivirus or a proxy that inspects HTTPS, or a server with an incomplete certificate chain |
| *expired or not valid yet* | Check your PC's date and time |
| *issued for a different web site* | The link points at the wrong server |

**To continue anyway for one file:** right-click it, choose **Properties**, tick **Don't verify this site's HTTPS certificate**, then **Resume**. (In the *New download* window the same tick appears automatically.)

A global switch exists in **Options > Connection**. Only use it on a network you trust, because it also hides tampering.

---

## 5. Using the app

| Feature | How |
|---|---|
| **Add URL** | `Ctrl+N`. Paste a link; the *Download File Info* window opens |
| **Add from clipboard** | `Ctrl+V` |
| **Drag & drop** | Drop links, or text containing links, onto the window |
| **Copy a file link** | The app offers to download it (turn off in **Options > General**) |
| **Batch** | `https://site.com/img(*).jpg` from 1 to 100 (zero-padding and letters a–z also work) |
| **Grabber** | Pick files from a page; optionally go deeper into linked pages |
| **Scheduler** | Queues with start/stop time, days, parallel downloads, and *when finished: exit / shut down / sleep / hibernate* |
| **Right-click a download** | Open, re-download, queue, move category, copy address, ZIP preview, properties |
| **ZIP preview** | Reads only the end of the zip over the network, not the whole file |
| **Speed limiter** | Status bar (bottom right) or the Downloads menu |
| **Command line** | `"Wajeeha Download Manager.exe" https://site.com/file.zip` — if the app is already running it hands the link to it |

---

## 6. AI agents (MCP)

Tell your AI agent *"download https://example.com/file.zip"* and it hands the job to Wajeeha Download Manager: fast, resumable, and sorted into your category folders.

The app speaks the **Model Context Protocol (MCP)**, so any MCP-capable app can use it. Both the older (`initialize`) and the newer stateless (`2026-07-28`, `server/discover`) versions of the protocol are supported.

### Set it up (one time)

Open the app, then **Help > AI agents (MCP)** (or **Options > AI agents**). Pick your AI app from the list. The box shows text already filled in with your paths and your private access token. Click **Copy**, then:

**Claude Code** — run the command in a terminal, then check with `claude mcp list`:

```bat
claude mcp add --scope user --transport stdio wajeeha -- "C:\path\wajeeha-mcp.exe"
```

The *HTTP* variant works too, but the app must already be running. The *stdio* variant starts the app by itself, hidden in the tray, the first time it's needed.

**Claude Desktop** — go to **Settings > Developer > Edit Config**, add the shown JSON under `"mcpServers"`, save, and restart Claude Desktop.

**Cursor / VS Code / others** — use the *HTTP settings* text (URL plus an `Authorization` header).

> **Running from source** (not the exe)? The snippets then use `python wajeeha_mcp.py`.

### What the agent can do

The agent gets 13 tools:

| Tool | What it does |
|---|---|
| `download_file` | Download one URL (optionally wait and get the final path) |
| `download_files` | Add up to 100 URLs at once |
| `probe_url` | What is this link? Name, size, type, resume support — no download |
| `grab_links` | List the files found on a web page |
| `list_downloads` | List downloads |
| `get_download` | Details of one download |
| `wait_for_download` | Wait until a download finishes |
| `get_status` | Overall status |
| `list_categories` | Categories and their folders |
| `pause_download` | Pause a download |
| `resume_download` | Resume a download |
| `cancel_download` | Cancel a download |
| `set_speed_limit` | Set the speed limit |

It also gets **3 read-only resources** (download list, categories, status) and **3 ready-made prompts** (`download`, `download_from_page`, `download_status`).

Downloads started by an agent are marked **AI agent: \<name\>** in the *Description* column.

### Safety

All of this is enforced inside the app, not left to the agent.

- Only `http`, `https`, and `ftp` links are accepted. Files go only into your Downloads folders (tricks like `..`, other drives, or symlinks are blocked) unless you allow more.
- The app asks **you** (Allow / Deny window) before:
  - downloading programs or scripts (`.exe`, `.msi`, `.bat`, …),
  - using addresses on this PC or your local network,
  - switching certificate checks off,
  - saving outside Downloads.

  Change this in **Options > AI agents** (*risky only / always / never*). No answer within 2 minutes counts as **Deny**.
- An agent can never delete a finished file, read your files, or change other settings.
- The HTTP endpoint needs your private token, only accepts connections from this PC, and refuses anything that comes from a web page.
- **Create a new access token** in **Options > AI agents** locks out everything using the old one.
- To switch the whole feature off, untick **Let AI agents (MCP) download files**.

### If it doesn't work

- In Claude Code, run `/mcp` to see the server's status and error text.
- *Can't reach / not running*: open the app once and check that **Options > AI agents** is ticked.
- *Rejected the access token*: restart that MCP entry (the stdio helper re-reads the token by itself).
- Details are written to `%APPDATA%\WajeehaDownloadManager\app.log`.

---

## 7. How it works

- **Dynamic segmentation ("in-half rule").** A download starts as one piece on one connection. Each extra connection takes the *largest* unfinished piece and splits it in half, so every connection stays busy until the very end.
- **Resume.** All piece positions are saved every few seconds, so after a stop, crash, or power cut the download resumes. While downloading, a `<name>.wdmpart` file sits beside the target; it is renamed to the real name when finished.
- **Categories.** Each has a name, folder, file types, and optional sites. The category is picked from the file name, or from the server's real name after probing.
- **Browser link.** The extension talks to the app over `http://127.0.0.1:49875-49879`. Web pages can't use it: requests from a normal web page are refused, and the app only listens on your own computer. The status bar (bottom right) shows *extension connected* once your browser extension has contacted the app.

---

## 8. Limitations

- HLS/DASH streaming playlists (`.m3u8` / `.mpd`) and sites that split video and audio (e.g. YouTube) can't be downloaded or merged. The extension lists them but marks them *not supported yet*.
- Not supported: Safari integration, dial-up/VPN redial, download quotas, SOCKS proxies, toolbar skins, and the MMS protocol.
- Connections are opened per piece; reusing keep-alive connections would be a speed-up.
- Site-login passwords are stored in plain text in the settings file: `%APPDATA%\WajeehaDownloadManager\settings.json`.
- FTP is implemented (resume with `REST`) but was not tested against a real FTP server.

---

## 9. Project layout

```
main.py             starts the app
wajeeha_mcp.py      AI-agent helper (becomes wajeeha-mcp.exe)
wdm/
  engine.py         download engine
  server.py         browser link + /mcp endpoint
  grabber.py        site grabber + batch patterns
  mcp.py            MCP server
  agent.py          rules for what agents may do
  mcp_relay.py      stdio relay for MCP clients
  ui/               windows, dialogs, theme
extension/          browser extension
tests/              engine/bridge tests (python tests\test_engine.py)
```

**Data locations**

| What | Where |
|---|---|
| Settings and download list | `%APPDATA%\WajeehaDownloadManager\` |
| Crash / error log | `%APPDATA%\WajeehaDownloadManager\app.log` |