ipp-bridge-mcp
# ipp-bridge-mcp
A lightweight **HTTP Upload + IPP / CUPS Bridge** built with **FastAPI** and **FastMCP**.
External clients or web workflows upload documents via `POST /upload` (`multipart/form-data`), which saves them securely to a temporary staging directory and returns a `file_id` and `local_path`. The FastMCP server then passes the staged file directly to an IPP/IPPS printer (RFC 8010/8011 binary protocol) or the CUPS `lp` command.
```
┌────────────┐ POST /upload (multipart) ┌──────────────────────┐
│ HTTP / AI ├────────────────────────────►│ FastAPI Upload API │
│ Client │◄────────────────────────────┤ (temp staging store) │
└─────┬──────┘ {file_id, local_path} └──────────┬───────────┘
│ │
│ MCP tool: print_file(file_id / local_path) │ resolves file_id / local_path
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ FastMCP Server (ipp-bridge-mcp) │
├──────────────────────────────┬──────────────────────────────────┤
│ Direct IPP/IPPS Backend │ CUPS CLI Backend │
│ (Print-Job / Validate-Job / │ (lp / lpstat / lpoptions / │
│ Get-Printer-Attributes) │ cancel) │
└──────────────┬───────────────┴──────────────────┬───────────────┘
▼ ▼
ipps://localhost:6250/ipp/print CUPS daemon (lp)
```
## Features
- **Lightweight Multipart Upload API (`FastAPI`)**:
- Streaming uploads with SHA-256 checksums, filename sanitization, path-traversal protection, magic-byte MIME detection (`application/pdf`, `application/postscript`, `image/png`, `image/jpeg`, `image/tiff`, `text/plain`, etc.), configurable max byte size, and automatic TTL expiration cleanup.
- Optional API key protection (`--api-key` / `IPP_BRIDGE_API_KEY`) via `Authorization: Bearer` or `X-API-Key`.
- **Dual Print Backends (`auto` | `ipp` | `lp`)**:
- **Direct IPP/IPPS (`httpx` + RFC 8010/8011 codec)**: Handles `ipp://`, `ipps://`, `http://`, and `https://` printer URIs, normalizes root URLs to `/ipp/print`, supports `--insecure` self-signed certs and automatic TLS 1.2 (`@SECLEVEL=1`) compatibility for enterprise/embedded printer firmware (verified against HP LaserJet M806).
- **CUPS `lp` CLI**: Argument-safe `asyncio.create_subprocess_exec` wrappers for `lp`, `lpstat`, `lpoptions`, and `cancel`.
- **Flexible Deployment Topologies**:
1. **Embedded stdio mode (`--with-upload-api`)**: FastMCP over `stdio` + background FastAPI Upload API in one `uvx` command.
2. **Combined HTTP mode (`--transport streamable-http`)**: Serves both FastAPI upload routes (`/upload`, `/files`, `/print`, `/health`) and FastMCP (`/mcp`) on a single port.
3. **Split-host mode**: Run `ipp-bridge-api` on your CUPS host and point `ipp-bridge-mcp --upload-api-url http://cups-host:8000` at it.
---
## Quick Start with `uvx`
### 1. Run MCP (stdio) + Upload API against a forwarded IPPS printer
```bash
uvx --from git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git \
ipp-bridge-mcp \
--printer-uri https://localhost:6250 \
--insecure \
--with-upload-api \
--upload-port 8000
```
Upload a file via HTTP:
```bash
curl -F "file=@document.pdf" http://127.0.0.1:8000/upload
```
Response:
```json
{
"file_id": "a7f9c1...",
"filename": "document.pdf",
"local_path": "/tmp/ipp-bridge-uploads/a7f9c1.../document.pdf",
"content_type": "application/pdf",
"size_bytes": 48210,
"sha256": "...",
"created_at": "2026-11-16T08:00:00Z",
"expires_at": "2026-11-16T09:00:00Z"
}
```
Then ask your MCP client to validate and print `file_id` (or `local_path`) via `validate_print_job` and `print_file`.
### 2. Run Combined Streamable HTTP + Upload API on one port
```bash
uvx --from git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git \
ipp-bridge-mcp \
--transport streamable-http \
--host 127.0.0.1 \
--port 8000 \
--printer-uri https://localhost:6250 \
--insecure
```
- Upload API: `http://127.0.0.1:8000/upload`, `/files`, `/health`, `/docs`
- FastMCP endpoint: `http://127.0.0.1:8000/mcp`
### 3. Split-Host Mode (CUPS Host Upload API + Remote FastMCP)
On the **CUPS host**:
```bash
uvx --from git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git \
ipp-bridge-api \
--host 0.0.0.0 \
--port 8000 \
--backend lp \
--cups-printer Office_LaserJet
```
On the **MCP client host**:
```bash
uvx --from git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git \
ipp-bridge-mcp \
--upload-api-url http://cups-host:8000 \
--backend lp \
--cups-printer Office_LaserJet
```
### MCP Client Configuration (`mcp_config.json`)
```json
{
"mcpServers": {
"ipp-bridge": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git",
"ipp-bridge-mcp",
"--printer-uri",
"https://localhost:6250",
"--insecure",
"--with-upload-api",
"--upload-port",
"8000"
]
}
}
}
```
---
## FastMCP Tools, Resources, and Prompts
| Tool | Description |
| --- | --- |
| `bridge_status` | Bridge config, staging dir, and backend availability |
| `upload_file` | Stage text or base64 content through the upload bridge |
| `list_uploaded_files` | List non-expired staged files |
| `get_uploaded_file` | Fetch metadata and `local_path` by `file_id` |
| `delete_uploaded_file` | Delete a staged file |
| `list_printers` | Discover configured IPP and/or CUPS printers |
| `get_printer_attributes` | Query supported formats, media, state, and toner markers |
| `validate_print_job` | Preflight validate via IPP `Validate-Job` or CUPS check (no paper printed) |
| `print_file` | Print staged `file_id` or `local_path` via IPP `Print-Job` or CUPS `lp` |
| `list_jobs` | List active or completed jobs |
| `get_job_status` | Query status for a specific `job_id` |
| `cancel_job` | Cancel a queued or active job |
| `identify_printer` | Trigger IPP `Identify-Printer` (`display`, `flash`, `sound`) |
**Resources**: `ipp-bridge://status`, `ipp-bridge://files`, `ipp-bridge://printer/attributes`
**Prompt**: `print_uploaded_document`
## HTTP Upload + Bridge API Endpoints
- `GET /health` — Service health & staged file count
- `POST /upload` — Multipart file upload (`file`), returns `file_id` & `local_path`
- `GET /files` — List staged uploads
- `GET /files/{file_id}` — Get staged file metadata
- `GET /files/{file_id}/content` — Download staged file bytes
- `DELETE /files/{file_id}` — Remove staged file
- `POST /print` — Print a staged `file_id` or `local_path` directly via IPP or `lp`
- `GET /printers`, `GET /jobs`, `GET /jobs/{job_id}`, `POST /jobs/{job_id}/cancel`
## Configuration Environment Variables
| Variable | Description | Default |
| --- | --- | --- |
| `IPP_BRIDGE_PRINTER_URI` | Target IPP/IPPS/HTTP(S) printer URI | `None` |
| `IPP_BRIDGE_CUPS_PRINTER` | Default CUPS destination for `lp` | `None` |
| `IPP_BRIDGE_BACKEND` | `auto`, `ipp`, or `lp` | `auto` |
| `IPP_BRIDGE_INSECURE` | Disable TLS certificate verification (`1`/`true`) | `false` |
| `IPP_BRIDGE_UPLOAD_DIR` | Staging directory | `<temp>/ipp-bridge-uploads` |
| `IPP_BRIDGE_UPLOAD_API_URL` | Remote Upload API URL | `None` |
| `IPP_BRIDGE_API_KEY` | Optional auth key for Upload API | `None` |
| `IPP_BRIDGE_MAX_UPLOAD_BYTES` | Max upload size in bytes | `52428800` (50 MiB) |
| `IPP_BRIDGE_FILE_TTL` | Staging TTL in seconds | `3600` |
| `IPP_BRIDGE_ALLOW_LOCAL_PATHS` | Allow printing paths outside `upload_dir` | `false` |
---
## Development & Testing
```bash
uv sync --extra dev
uv run ruff check src tests
uv run mypy src
uv run pytest -v -m "not live"
```
Run live printer E2E tests (uses `Get-Printer-Attributes`, `Validate-Job`, `Create-Job`, `Get-Job-Attributes`, and `Cancel-Job` — **zero paper consumed**):
```bash
IPP_BRIDGE_LIVE_PRINTER_URI=https://localhost:6250 uv run pytest -v -m live
```
## License
MIT
TDQS
Scored across 13 tools
Each tool maps to a distinct resource+action across three clear groups (uploaded files, print jobs, printers), and descriptions make boundaries readable. Minor overlap exists between bridge_status and get_printer_attributes (both report 'status' at different layers), which could cause an occasional misselection.
Strong snake_case verb_noun convention throughout (upload_file, list_jobs, get_job_status, cancel_job, delete_uploaded_file). The lone deviation is bridge_status, which puts the noun first instead of following the get_/list_ verb pattern.
13 tools is well within the ideal range for a print-bridge server, with sensible coverage of uploads, jobs, and printer discovery. Each tool appears to earn its place; nothing looks redundant or padded.
Full lifecycle is covered for staged uploads (upload, list, get, delete) and jobs (list, status, cancel, submit via print_file), plus printer discovery and validation. Gaps remain around job control (hold/release/pause/resume) and any cleanup of expired jobs, but core workflows have no dead ends.