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

Opens a YAD list of rules in evaluation order. Select a rule to delete or move up/down. Under the file lock, changes are rejected if the list has changed.

--edit-rules $file

Edits the actual permission file with $VISUAL, $EDITOR, sensible-editor or vi. The editor handles external changes itself; this command does not validate or overwrite its saved contents.

PROMPT INTERFACE

--tty uses only /dev/tty; --yad uses only YAD. These options are mutually exclusive and apply only to permission prompts. Neither explicit mode falls back to another interface. Unavailable prompting denies access. Without either option the helper tries YAD, then a terminal if YAD cannot start. Closing or declining a working dialog never triggers fallback.