Skip to main content
Glama
ipp-bridge-mcp

ipp-bridge-mcp

README.md
# 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

B3.4/5.0

Scored across 13 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues