iriai-feedback

A reverse-proxy QA annotation tool. Sits between a reviewer and a locally-running web app, injecting an overlay UI for leaving feedback -- annotations, screenshots, and checklists. Also provides an MCP server so AI agents can start sessions, poll for feedback, and act on it programmatically.

Requirements

• Node >= 20

Installation

npm install -g iriai-feedback

Also installed automatically as a dependency of iriai-build.

Binaries

| Binary | Purpose | |---|---| | iriai-feedback | CLI for starting sessions and querying feedback | | iriai-feedback-mcp | MCP server (stdio transport) for AI agent access |

CLI Usage

Start a QA session

Proxy a local app and inject the annotation overlay:

iriai-feedback start <target-url> [--port <port>] [--public]

• --port sets the proxy port (default: 9000).
• --public opens an ephemeral public tunnel via localtunnel.

Example:

iriai-feedback start http://localhost:3000 --port 9001

Start a document review session

Render a Markdown, HTML, or plain-text file with an annotation overlay:

iriai-feedback review <doc-path> [--title "Doc Title"] [--port 9000]

List sessions

iriai-feedback list

Check session status

iriai-feedback status <session-id>

Session IDs have the form qs_<12 hex chars>.

MCP Tools

The MCP server (iriai-feedback-mcp) exposes the following tools over stdio:

| Tool | Description | |---|---| | start_qa_session | Start a QA session. Spins up the reverse proxy on a given port and returns the session ID and QA URL. Accepts optional context (gate name, journey checklist) and public flag for a tunnel. | | get_qa_status | Get session status (active or submitted), annotation count, and timestamps. | | get_qa_feedback | Retrieve all non-deleted annotations for a session as structured JSON. Each annotation includes type, page URL, comment, and type-specific data. | | delete_qa_feedback | Soft-delete a specific annotation by ID. | | list_qa_sessions | List all sessions with status and annotation counts. | | stop_qa_session | Stop the QA server for a session. Does not delete session data. | | start_doc_review | Start a document review session. Converts a file (.md, .html, .txt) to HTML and serves it with an annotation overlay. |

Data Storage

Session and annotation data is stored as JSON files under:

~/.qa-feedback/sessions/<session-id>/
  session.json
  annotations/
    <annotation-id>.json

Annotation IDs have the form an_<12 hex chars>.

Overlay API

The injected overlay communicates with the proxy server via internal HTTP endpoints under /__qa__/api/. These are not intended for direct use -- interact through the CLI or MCP tools instead.