Metadata-Version: 2.4
Name: qrfile-mcp
Version: 0.2.4
Summary: QRFile: single-use local file downloads with QR codes for MCP clients
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp==2.3.0
Requires-Dist: qrcode[pil]<9,>=8
Requires-Dist: psutil<8,>=7
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"

# QRFile MCP

Ask an MCP-enabled LLM to send a local file to your phone or another device. The tool copies **only the explicitly selected files**, starts a single-use temporary server on the sender's private LAN address, and returns a **download URL, QR image which contains temporary confidentials for high security**.

The receiving device scans the QR code or opens the URL in its browser, and the download starts immediately. There is no intermediate download page or button. One file keeps its original name; multiple files arrive in a single **shared-files.zip** archive. The link already includes the temporary credentials: no typing, app installation, account, SFTP client or receiving-device setup is needed. Both devices must already be on the same Wi-Fi/LAN subnet.

## Package name

- Application: **QRFile**
- PyPI distribution and command: **`qrfile-mcp`**
- Python import and module launcher: **`qrfile_mcp`**

Requires **Python 3.11 or newer**. Install with `pip install qrfile-mcp` (or `pipx install qrfile-mcp`) and configure your MCP client to launch the `qrfile-mcp` command. It runs the MCP server over stdio. `python -m qrfile_mcp` is an equivalent launcher.

The source-tree `run.sh` and `server.py` launchers remain available for existing local installations.

## Usage

With QRFile connected to your MCP-enabled assistant, ask:

> Send `/Users/XXX/Downloads/report.pdf` to my phone and show the QR code.

Replace the example with the absolute path to your file. To share several files, name each one in your request; QRFile bundles them into one ZIP download.

1. Keep the sender and receiving device on the same trusted Wi-Fi/LAN subnet.
2. The assistant calls `create_file_share` and shows the download URL, QR image and expiration time.
3. Scan the QR code or open the URL on the receiving device. The download starts directly; the browser may show its own save confirmation.
4. After a complete server-side transfer, the link becomes inactive and temporary copies are removed. Keep the assistant's MCP process running until the transfer finishes.

You can also ask the assistant to check download status with `get_file_share` or `list_file_shares`, or cancel an unfinished share with `revoke_file_share`.

## Tools

| Tool | Purpose |
| --- | --- |
| `create_file_share` | Share 1–20 explicitly selected regular files; return QR, URL, credentials and expiration. |
| `get_file_share` | Recover an active share's QR/link or inspect its status. |
| `list_file_shares` | Show file names, expiration, status and completed download counts; omit credentials. |
| `revoke_file_share` | Stop the listener, invalidate the URL, interrupt active transfers and remove copied files. |
| `list_local_networks` | Inspect private LAN interfaces if automatic selection needs correction. |

Example arguments:

```json
{
  "file_paths": ["/Users/XXX/Downloads/report.pdf"],
  "expires_in_seconds": 600
}
```

Expiration defaults to **10 minutes**, configurable from 1 to 60 minutes. The timer begins after copying files, so copying a large file does not consume its download window. Five shares may run simultaneously; each share supports eight simultaneous connections. Repeated invalid credential requests revoke that share after ten attempts. Each share permits one successful download. After the server finishes sending the entire payload, the URL and QR are immediately invalidated, the listener stops, and staged files are deleted. HEAD metadata probes do not consume the link. A simultaneous second download receives HTTP 409; an interrupted send releases the transfer slot for retry until the original expiration. ZIP entry names are flattened and duplicate names are renamed to preserve all selected files.

The completion signal is the server successfully writing and flushing the complete payload; it does not verify the receiver’s saved file or browser storage. A browser can still show its own Save/Download confirmation, and the MCP cannot bypass that prompt. Direct download means there is no extra application Download button.

Restart the MCP connection (or quit/reopen the LLM app) after updating so its running process loads the updated version. Existing shares created by an older process keep their original behavior until revoked or expired.

## Scope and lifetime

- Every share gets its own private temporary directory and random port. Only indexed routes for copied files are served; there is no directory listing or arbitrary filesystem path route.
- Shared files are snapshots. Modifying the originals does not change the downloadable copies. Original files are never moved or deleted.
- The listener binds to a single RFC1918 IPv4 interface, never `0.0.0.0`. Requests from other subnets, public addresses and loopback are rejected. Known VPN/virtual interfaces are excluded from automatic discovery. An optional `interface` argument chooses among the discovered interfaces.
- Credentials are randomly generated per share. The URL/QR embeds them to avoid a manual login screen. Anyone holding the link on the allowed LAN can download while it is active; there is no receiver identity verification. A GET preview that actually fetches the entire file can consume a single-use link.
- Download completion, expiration and revocation close the server and delete staged copies, including the QR image. The MCP process must remain running during transfers; graceful shutdown also removes shares. A forced process kill cannot guarantee deletion of temporary copies, although the stopped process can no longer serve them.
- The download transport is **HTTP on the local network**, not encrypted HTTPS. Use trusted Wi-Fi/LAN; don't expose it through port forwarding, tunnels or public proxies. Source-address checks cannot distinguish a LAN relay from a local receiver.
- IPv6-only networks and routed devices on a different subnet are not supported. Wi-Fi guest/client isolation and sender firewalls can prevent a connection even when both devices use the same Wi-Fi name. A sleeping sender cannot serve downloads.
- Automatic interface discovery chooses the preferred active physical-looking private interface; it cannot universally classify custom VPN/virtual interface names. Use `list_local_networks` and specify the correct interface when necessary.

Optional sender restrictions:

- `LOCAL_SHARE_ALLOWED_ROOTS`: absolute directories separated by the OS path separator (`:` on macOS/Linux, `;` on Windows). If omitted, the trusted local MCP client can request any regular file readable by the sender's user account. The tool instructions require the exact user-requested paths and do not authorize inferred extra files.
- `LOCAL_SHARE_MAX_BYTES`: maximum total snapshot bytes per share, default 5 GiB.

mcp-name: io.github.hkturtco/qrfile
