NAME

anyevent-mcp-askpermission - graphical or terminal permission helper

DESCRIPTION

anyevent-mcp-askpermission asks you whether an MCP tool may perform an operation, such as reading a file or running a command. It shows the requested operation and privileges, and lets you allow or deny it once, or choose a rule for future requests.

Servers using AnyEvent::MCP::Server::Permissions normally start this helper automatically when a permission check needs your decision. The helper displays a local graphical dialog or asks in a terminal, then returns your choice to the server. You do not normally run it yourself. To change saved rules later, use anyevent-mcp manage-rules NAME or anyevent-mcp edit-rules NAME.

PERMISSION PROMPTS

The helper tries YAD first, leaving display backend selection to GTK. If YAD cannot start, it asks on /dev/tty. Closing a working dialog, terminal EOF, or having neither interface available means deny once.

Server, tool, action, workdir, subject and reason are shown as read-only GTK labels when present, including the multibroker alias when available. The requested sandbox grants appear together on one line. The initial YAD form also has a Denial reason (optional) field above four choices: Deny once, Deny always..., Allow always..., Allow once. The persistent rule editor can match the selected workdir (default) or any configured workdir, including future ones. This changes rule matching, not per-call sandbox grants. One-time decisions are on the outside; Deny once uses YAD's default OK response. Closing the dialog also denies once. The persistent choices open a separate rule editor for grant and scope settings, including exact requested-file scope on deny rules. Rules can last indefinitely (the default), 900 seconds or 16 hours. Expired rules disappear when the rules are read and are removed from disk on the next ordinary save. The reason is included in a denial result but is ignored on an allowance.

Optional display-only request details maps plain labels to Unicode text, for example { "View patch" => $diff }. Each entry appears as a size summary and a button. YAD adds an ellipsis to the label and opens a separate, read-only, resizable, monospace text window without dismissing the approval dialog. Content is written to a private temporary UTF-8 file, never interpolated into a command; control characters are escaped. The helper limits each preview to 65536 Unicode characters and identifies incomplete previews. Terminal and native MCP prompts include the same bounded text inline. Display-only details never constrain or become part of persistent permission rules; an allow-always rule for perl - permits future, different stdin scripts.

YAD uses GTK, so you can select a dark theme externally by setting GTK_THEME=Adwaita:dark in the server's environment before starting it. The permission helper inherits that setting and passes it to YAD; the theme is not changed for unrelated applications.

In a terminal, the four decisions are single-letter shortcuts and m edits the optional denial reason. Closing the dialog, cancelling or an unavailable terminal denies once. Rule management remains separate: anyevent-mcp manage-rules NAME or anyevent-mcp edit-rules NAME.

HELPER PROTOCOL

The helper reads one permission request on stdin and writes one JSON decision on stdout. Servers invoke it through AnyEvent::MCP::Permissions::Ask, which describes the helper interface and how to select a replacement helper. YAD's stderr is suppressed; startup failure is detected from its exit status.

OPTIONS

--manage-rules FILE

Open YAD rule list for FILE in evaluation order. Delete or reorder selected rules. File lock protects updates; changes fail if list changed elsewhere. Cannot combine with --edit-rules or prompt-mode flags.

--edit-rules FILE

Edit permission rules in FILE using $VISUAL, $EDITOR, sensible-editor or vi. Does not validate or overwrite editor output. Cannot combine with --manage-rules or prompt-mode flags.

--tty

Prompt only on /dev/tty, without YAD fallback. Unavailable terminal denies access. Cannot combine with --yad or rule-management flags.

--yad

Prompt only with YAD, without terminal fallback. Unavailable YAD denies access. Cannot combine with --tty or rule-management flags.

--help

Print short usage synopsis and exit.

Without explicit --tty or --yad, prompts try YAD first, then /dev/tty only if YAD cannot start. Closing or declining a working dialog never triggers fallback.