• Developing and Deploying YunoHost Packages with yunohost‑mcp
  • 1. Prerequisites
  • 2. Install the MCP Server App
  • 3. Connect an MCP Client
  • 4. Package Development Workflow
    • 4.1 Evaluate the Upstream Project
    • 4.2 Scaffold the Package
    • 4.3 Test‑Install and Auto‑Fix
    • 4.4 Publish the Package
  • 5. Your Involvement

§Developing and Deploying YunoHost Packages with yunohost‑mcp

yunohost‑mcp gives an AI agent (Claude, Codex, Gemini, …) a typed, permission‑scoped connection to your YunoHost server instead of raw SSH. The agent can evaluate an upstream project, scaffold a _ynh package, test‑install it on your real server, fix failures, and finally publish the package—only stopping when a genuine human decision is required.

§1. Prerequisites

§2. Install the MCP Server App

sudo yunohost app install https://github.com/imattau/yunohost-mcp-ynh

Or use Webadmin → Applications → Install a custom app → From a Git repository.

You will be asked for your npub. This becomes the server’s first administrator (the owner) and can approve high‑risk actions later. After installation the MCP endpoint is reachable at https://your-domain/mcp.

If you already run the Nostr catalogue app, you can install by app ID instead of URL (see the reference section).

§3. Connect an MCP Client

The simplest way is to let the agent perform the whole setup: give it your server domain and the client you want, and it will install the bridge, generate a fresh key, configure the client, and return the new key’s npub for you to grant a role.

To run the process manually (useful for troubleshooting):

uvx --from yunohost-mcp-connect yunohost-mcp-connect setup \
  --server https://your-yunohost-domain/mcp \
  --client codex \
  --format json

• --client accepts codex, claude-desktop, claude-code, gemini, hermes, or opencode.
• The command prints the new key’s npub. Add it to identity.toml with the role package-developer (see the roles table below).
• Use a distinct key for each client and restart the client after any config change.
• Verify the connection with yunohost-mcp-connect doctor --server … --key-file ….

§4. Package Development Workflow

§4.1 Evaluate the Upstream Project

Give the agent the repository URL and ask whether the app can be packaged for YunoHost. The agent checks required runtimes, databases, ports, domain assumptions, and authentication models, returning a suitability verdict without touching your server.

§4.2 Scaffold the Package

If suitable, ask the agent to create a new package repository and generate the manifest, install/remove/upgrade scripts, Nginx and systemd configs, and any glue code. This is ordinary AI‑assisted coding, not an MCP call.

§4.3 Test‑Install and Auto‑Fix

Now the server connection shines. Instruct the agent to run the full test cycle on your real server:

1. Install the package
2. Back up the app
3. Remove it
4. Restore from the backup
5. Remove again

If any step fails, the agent reads the relevant logs, journal entries, and service status, diagnoses the cause, patches the package, and retries automatically.

Key points of this loop

• Failures are real‑infrastructure errors, not simulated CI results.
• No manual approval is needed for each retry; the agent skips the interactive confirmation a normal user would see.
• The test environment is cleaned after each attempt, leaving the server ready for the next run.
• Timeouts or ambiguous results trigger a fresh check of the server state.
• The agent’s key must have the package-developer role; app-admin is insufficient.

§4.4 Publish the Package

When the test cycle passes and a Nostr‑backed catalogue daemon is running, ask the agent to publish. It validates catalogue readiness, builds a signed declaration, and pushes it to the configured Nostr relays, showing you the plan first.

§5. Your Involvement

You only decide on high‑level items:

• Target domain or path for the app
• How to reconcile upstream assumptions with YunoHost conventions
• Any other design‑level