YunoHost MCP

Prepare a Guestbook Join for the *caller* to sign and submit. Unlike armada_join (which signs with a server-held bot key), this authors the join as the calling identity's own pubkey - no bot key or armada_key_path needed for this identity at all, since community membership under this scheme is a signature over shared, already server-held invite/channel material, not a separately provisioned key. Returns an unsigned kind-20013 seal event to sign locally and a draft_id to pass to armada_join_submit along with the signed result.

Finish and publish a Guestbook Join drafted by armada_join_draft. ``signed_event`` must be the JSON-encoded event returned by signing the exact unsigned_event armada_join_draft handed out - any drift, an invalid signature, or a draft_id issued to a different identity is rejected.

Return one audit trail entry by id. Requires Scope.AUDIT_READ (app-admin and above) plus owner co-signature per call: unlike other confirmed reads, this isn't gated for the caller's own protection - it's gated because the trail exposes every *other* identity's calls too, so the owner approves each read rather than it being a standing grant.

List audit trail entries, newest first. Requires Scope.AUDIT_READ (app-admin and above) plus owner co-signature per call - see audit_get.

Create a new local backup archive.

Permanently delete one local backup archive. Requires owner approval.

Details for one backup archive - creation time, description, size, and its on-disk `path` - and, with `with_details=True`, the apps and system parts it actually contains. Read-only. There is no MCP tool to fetch the archive's bytes: `path` is where an admin retrieves it from (e.g. over SSH/SCP/SFTP) - YunoHost's own backup_download is an HTTP-file-serving action tied to its REST API, not something meaningfully callable as a plain function.

Restore from a local backup archive. Requires confirmation.

List available backup archives.

Optionally announce a successful catalogue publication in Armada.

Prepare a package announcement for the *caller* to sign and submit. Unlike catalog_announce (which signs with a server-held bot key), this authors the announcement as the calling identity's own pubkey. It needs only the shared Armada community invite (already required for catalog_announce/armada_join) - no bot key or armada_key_path for this identity at all. The caller must already hold a Guestbook Join under its own pubkey (see armada_join_draft/armada_join_submit) for the result to be recognized by the community. Returns an unsigned kind-20013 seal event for the caller to sign with its own…

Finish and publish a package announcement drafted by catalog_announce_draft. ``signed_event`` must be the JSON-encoded event returned by signing the exact unsigned_event catalog_announce_draft handed out - any drift in pubkey/kind/tags/content/created_at, an invalid signature, or a draft_id issued to a different identity is rejected.

Check durable delivery state for one announcement idempotency key.

List every app currently declared in the Nostr catalogue - not just what's installed on this server. Queries the configured relays fresh on every call (no local cache), applying the same trusted-publisher policy nostr-catalogd itself uses when more than one publisher has declared the same app id.

Inspect a local or remote YunoHost package for catalogue publication.

Publish an existing catalogue plan after administrator confirmation. If the plan was built with ci_result (see catalog_publish_plan), the same CI attestation is published alongside the declaration here, signed by the same publisher key - nothing further to pass at this step.

Build a signed catalogue declaration without contacting any relay. ci_result is optional: a ci-result.json body (internal/ciresult schema in nostr-yunohost) for this exact revision - e.g. the artifact static-security.yml produces. When given, the plan also builds a kind-30080 CI attestation for the same revision, signed by the same publisher key - self-attestation, folded into the normal publish flow rather than a separate tool or a second verifier identity. The plan refuses to build (and catalog_publish will refuse to publish) if ci_result's app_id/repository/commit/manifest/content don't ma…

Verify a signed declaration event or fetch and verify an naddr.

One-call app diagnostic: app info, the server's current diagnosis, and recent operation log entries mentioning this app. Read-only.

Return the current (cached) aggregated diagnosis report.

Trigger a fresh YunoHost diagnosis run. Can take real time (network/port checks).

Register a new domain or subdomain on this YunoHost server - a prerequisite for app_install's `domain` question, which only accepts already-registered domains. Always adds a plain custom domain, never subscribes to a new top-level DynDNS domain (nohost.me/noho.st/ynh.fr) even if the name would otherwise qualify - a same-host subdomain of an already-registered DynDNS domain (e.g. new-app.example.nohost.me) is unaffected and works normally. A self-signed certificate is always installed immediately. install_letsencrypt_cert additionally attempts a real Let's Encrypt certificate - this only relia…

Read-only certificate status for an already-registered domain (must already appear in domains_list()): CA type/name, remaining validity in days, a style/summary badge, whether it's ACME-eligible right now, and whether a wildcard covers it - the checks worth doing before calling domain_cert_install.

Issue or renew a certificate for an existing domain (must already be registered - see domain_add/domains_list) via YunoHost's own certificate-install path, not a remove-and-recreate of the domain. `letsencrypt=True` (default) requests a real Let's Encrypt certificate; `letsencrypt=False` installs a self-signed one instead. `staging` must be passed explicitly and must be False - this YunoHost version has no ACME staging endpoint configured, so staging=True is rejected rather than silently falling back to production. Check the response's `certificate.CA_type` ("letsencrypt" vs "selfsigned") an…

Push domain_dns_suggest's recommended records to the domain's configured DNS registrar. Requires a registrar to already be set up via the domain's own `dns.registrar` config panel (`app_config_get`/ `app_config_set` don't cover per-domain config panels - this fails with a clear error if none is configured, it does not silently no-op). Call domain_dns_push_preview first, always - it shows the exact same diff this call would apply, without touching anything. Without `force`, only records YunoHost itself previously created are touched; `force=True` extends that to any matching record regardless o…

Compute what domain_dns_push would actually change on the domain's configured DNS registrar - a create/update/delete/unchanged diff against the records currently live there - without touching anything. Read-only; requires the domain to already have a registrar configured (fails clearly if not - see domain_dns_push's docstring). Without `force`, the diff only considers records YunoHost itself previously created; `force=True` extends that to any matching record regardless of origin, matching what domain_dns_push would do with the same flag. Always call this before domain_dns_push, especially wit…

Suggest DNS records for an already-registered domain - basic A/AAAA, mail (MX/SPF/DKIM/DMARC), and any extra records YunoHost's installed apps contribute - as a formatted zone-file-style block of text, the same output `yunohost domain dns suggest` prints. Read-only, computed locally from this server's own state; does not contact or compare against the domain's actual registrar (see domain_dns_push_preview for that). Useful to hand the user something to paste at their DNS provider by hand, or to sanity-check before domain_dns_push.

Remove a registered domain. Refuses to run - and lists the offending apps - if any app is still installed on this domain, unless `remove_apps=True`, which removes those apps too as part of the same call (each one via its own app_remove-equivalent path, with the same data loss that implies - check apps_list for this domain first). Cannot remove the main domain while any other domain still exists. `force` skips YunoHost's own domain-existence assertion (only meaningful for cleaning up a domain left in a broken half-added state, per domain_add's own `force` semantics - not a way to bypass the app…

List domains configured on this YunoHost server.

Execute a plan previously returned by plan_app_upgrade(). Re-checks apps.upgrade's hard policy at execute time, not just at plan time - state (free space, backup age) may have drifted in between.

Close a port. `protocol` is "tcp" or "udp"; `port` may be a dash-separated range. Requires confirmation and owner co-signature - see the warning in the confirmation plan before approving this on port 22/80/443.

Return whether a port is open. `protocol` is "tcp" or "udp". Read-only.

List firewall rules. `protocol` is "tcp" or "udp" (ignored if `raw`); `forwarded` lists UPnP-forwarded ports instead of open ports. Read-only.

Open a port. `protocol` is "tcp" or "udp"; `port` may be a dash-separated range. Requires confirmation and owner co-signature - a wrong port/protocol here is externally visible and reachable, same risk tier as system_upgrade/backup_restore.

Re-apply the full current firewall rule set. Requires confirmation and owner co-signature, same tier as firewall_open/firewall_close - this is the point at which any pending rule change actually takes effect.

Return a summary YunoHost diagnosis report.

Probe an HTTP(S) endpoint and return status, timing, and content type.

Collect the main read-only evidence for one incident time window.

Query allowlisted system journals, including kernel, OOM, SSH, fail2ban, firewall, systemd, and application units.

Assemble bounded working context from Polypack.

Record whether a Polypack memory helped this authenticated agent.

Return one Polypack memory by exact ID.

List Polypack context namespaces visible to the local store.

Recall bounded Polypack memories for an authenticated agent.

Store durable Polypack memory with server-authored provenance.

Walk a bounded Polypack response/supersession thread.

List known migrations. `pending`/`done` filter; the default (neither set) returns all of them. Read-only - same scope as updates_check.

Run (or skip, or force-rerun) migrations. Defaults to all pending migrations if `targets` is empty. `skip` and `force_rerun` require explicit `targets` (never applied to "all pending"). Requires confirmation and owner co-signature - same tier as system_upgrade.

Return the recorded state (done/pending/skipped) of every migration that has ever run on this server. Read-only.

Submit a registered YunoHost operation to the signed Nostr control plane. The operation daemon performs the final scope and administrator approval checks; this MCP server never executes the operation locally. Enable with ``YUNOHOST_MCP_NATIVE_CONTROL_PLANE_ENABLED=true`` and provision the dedicated agent key at the configured key path.

Return local addresses, routes, and listening sockets.

Return the log content for one YunoHost operation - most recent `tail_lines` lines only (default: a bounded tail, not the whole log; pass a larger tail_lines for more). Secret-shaped content (a password/token/api_key/... assignment) in the log text is redacted.

Return success/failure status and metadata for one YunoHost operation.

List recent YunoHost operation log entries. with_suboperations defaults to False (matching yunohost's own default), which silently excludes any operation with a parent operation set - in practice this hides most app config-panel action/button clicks, since those commonly inherit a parent from whatever operation context the webadmin was already in. Pass with_suboperations=True to see those too.

Create a backup of an installed test app, to verify its backup script works.

Move a test app to a new domain/path, to verify its change_url script works.

Return the manifest and declared resources for a candidate package. `source` is a local path or git URL (not the app catalog) - does not install anything.

Install a candidate package from a local path/git URL, for testing.

Run the upstream package_linter against a local package path. Returns {"unavailable": true} rather than an error if no package_linter checkout is configured (YUNOHOST_MCP_PACKAGE_LINTER_PATH) - it's optional tooling, not part of yunohost core.

Return the log for one operation - an alias over operation_logs() for the package-development workflow (PLAN.md Phase 8). See that tool's docstring for the default tail size and log-text redaction.

Remove a test app, to verify its remove script works. Purges data by default.

Restore a test app from a backup archive, to verify its restore script works.

Run the standard install -> backup -> remove -> restore -> remove cycle against a candidate package in one call. Stops at the first failing step; see yunohost/adapter.py's package_run_tests for exactly what each step does and why this isn't package_check's full CI matrix.

Prepare a short-lived package-test session without changing the host. The returned session binds later package-test writes to this exact source, app id, and requester identity. ``app`` is required when preparing a test against an already-installed app; otherwise it is read from the candidate manifest.

Upgrade an already-installed `app` from a candidate local path/tarball, for testing.

Report what an upgrade of `app` would involve, without doing it: current/target version, and whether apps.upgrade's policy (recent backup, free space) would currently block it and why. Pass the returned plan_id to execute_plan() to actually upgrade - read-only, no lock, no audit entry (nothing in YunoHost changes here).

Regenerate (apply) pending system-service config files. `names` restricts this to specific categories (default: all pending); `force` additionally overwrites manually-edited files. Requires confirmation and owner co-signature, same tier as firewall_open/firewall_close - a bad regeneration can lock the admin out the same way a bad firewall rule can.

List system-service config files (nginx, ssowat, mysql, ...) that are out of date versus YunoHost's current internal state, without changing anything. `names` restricts the check to specific categories (default: all); `with_diff` includes the actual diff text. Read-only - call this before regenconf_apply to see what would change.

Diagnose an app and attempt bounded remediation. Only "conservative" is implemented: restart services whose name contains this app id, then re-diagnose - no reinstall, upgrade, or forced removal regardless of findings.

PLAN.md Phase 14's flagship workflow: diagnosis -> inspect app -> create a fresh safety backup -> upgrade -> check app/HTTP endpoint -> re-diagnose -> one report. Runs through apps.upgrade's own policy: free space is checked up front (nothing in this workflow can create disk space), and the backup requirement is re-verified after this workflow's own backup step actually happens, not just assumed to have worked.

Return this server's own Nostr identity (Phase 12): its npub and hex pubkey. A delegation (Phase 11) must name this exact pubkey in its 'server' tag to be accepted here. No scope required - this is public information a caller needs *before* it can construct a valid delegation naming this server, not something to gate behind auth for this server.

Return YunoHost server/component version information.

Return service state, exit details, restart counts, and timestamps.

Structured systemd journal entries for one YunoHost-managed service (must be a name services_list() reports) - normalized timestamp/service/priority/message per entry. `since`/`until` accept journalctl's own syntax ("-1h", "2026-09-03 07:00:00", "today", ...). `priority` is a syslog level (emerg/alert/crit/err/warning/notice/info/debug, or a range like "err..emerg") - e.g. priority="err..emerg" for error-level entries only. `grep` filters by a text/regex pattern. `lines` caps how many of the most recent matching entries come back (server-enforced maximum applies regardless of what's requested…

Restart one or more YunoHost services.

Start one or more stopped YunoHost services.

Return status for one or more named services.

Stop one or more YunoHost services. Call service_start to bring them back up.

List all YunoHost-managed services and their status.

Read one global setting by key (see settings_list for known keys). `full` additionally returns its type/description/default. Read-only.

List YunoHost's global settings (SSO behavior, security toggles, misc display options) and their current values. `full` additionally returns each setting's type/description/default. Read-only.

Set one global setting (see settings_list for known keys). `value` is always passed as a string - YunoHost coerces it to the setting's actual type internally. Requires confirmation and owner co-signature, same tier as firewall_open/firewall_close.

Sign one small Nostr event locally with this bridge's own key - the same key it already uses to sign every NIP-98 request - without the key ever leaving this process. Only Concord seal events (kind 20013) are accepted: pass the exact unsigned_event returned by catalog_announce_draft or armada_join_draft, then hand the signed result to the matching *_submit tool.

Collect SSH listener, fail2ban, firewall, service, and auth evidence.

Reboot the host (`systemctl reboot`) immediately once confirmed - no further in-process delay or grace period. Requires confirmation and owner co-signature, same tier as system_upgrade. Comes back up on its own; contrast with system_shutdown, which does not.

Power off the host (`systemctl poweroff`) immediately once confirmed. Requires confirmation and owner co-signature, same tier as system_upgrade. Does NOT come back up on its own - without remote power management, someone needs physical access to the machine to restore it. Prefer system_reboot unless a real power-off is actually what's wanted.

Return host uptime, boot, resource, process, disk, and OOM evidence.

Upgrade system (OS-level) packages. Requires confirmation.

Alias for package_run_tests() - PLAN.md Phase 14 names this separately from Phase 8's package_run_tests, but it's the same install -> backup -> remove -> restore cycle; see yunohost/adapter.py's package_run_tests for what each step does.

List apps and system components with pending updates, from cache (no network refresh).

Refresh cached update metadata over the network: apt-get update and/or a re-fetch of every registered app catalog source (including a local nostr_catalog feed, if installed), then report what's now upgradable. target is "apps", "system", or "all". Can take real time. Use this after catalog_publish to confirm a package actually shows up in the live catalog - updates_check alone only reads the existing cache and won't see a just-published change.

Create a YunoHost user account/mailbox on `domain` (must already be registered - see domain_add/domains_list). `admin` adds the new user to the `admins` group, granting webadmin/SSH access - grant with care.

Delete a YunoHost user account. Requires owner co-signature (approve_operation) in addition to confirmation - see PLAN.md Phase 13.

Create a new YunoHost user group - a prerequisite for granting a custom set of users access to an app permission (see user_permission_add) rather than an individual username.

Delete a YunoHost user group. Requires owner co-signature (approve_operation) in addition to confirmation - see PLAN.md Phase 13.

List YunoHost user groups (e.g. `all_users`, `admins`, and any per-app permission groups) and their members.

Add or remove usernames from a YunoHost group (e.g. adding a user to `admins` grants webadmin/SSH access - grant with care).

Grant a user or group access to an app permission (e.g. "myapp.main" - see user_permission_list for existing permission names). Requires owner co-signature (approve_operation) in addition to confirmation - see PLAN.md Phase 13's "permission changes" candidate.

Read one permission's full info (allowed users/groups, label, show_tile, protected, URL(s)) - see user_permission_list for known permission names. Read-only.

List app/system permissions and which users/groups are allowed each one (e.g. which apps a given group can access).

Revoke a user or group's access to an app permission. Requires owner co-signature (approve_operation) in addition to confirmation - see PLAN.md Phase 13's "permission changes" candidate.

Update a permission's label or dashboard tile visibility (`show_tile`) - not who has access, use user_permission_add/ user_permission_remove for that. Leave an argument None to leave it unchanged. `protected` is accepted for backward compatibility but, on the currently-installed YunoHost version, raises rather than silently doing nothing - the real user_permission_update() has no such parameter; protected is only settable via user_permission_add/ user_permission_remove, alongside a names change. `protected=False` on a permission that's meant to require login is a real access-control change, no…

Update an existing YunoHost user's mail/password/quota/fullname. Only the fields passed are changed; omitted fields are left as-is.

List YunoHost user accounts.

A broad server health snapshot in one call: version info, diagnosis, pending updates, service status, and backup archives. Read-only.

Read bounded, structured Nginx access and error logs.

Return the caller's resolved Nostr identity: pubkey, name, roles, and scopes. Requires no scope of its own — any authenticated, identity.toml-mapped caller may ask who they are, even one whose roles grant nothing else. Only meaningful over the HTTP transport; over stdio there is no NIP-98 handshake, so this returns unauthenticated.