install-app · diff
git:20260803.8514455 to git:20260803.a2d1136
25 added, 6 removed. Audit A to A.
---
name: install-app
description: Install an app from the registry or a GitHub URL. Interactive — shows permissions summary, prompts for env vars, polls to completion, and reports proxy URLs.
user-invocable: true
allowed-tools:
- mcp__gateway__install_app
+ - mcp__gateway__inspect_app
- mcp__gateway__poll_install_job
- mcp__gateway__browse_registry
---
# /install-app — Install an App Store App
Arguments passed: `$ARGUMENTS`
---
## Argument formats
- `/install-app <registry-name>` — install latest version from registry
- `/install-app <registry-name> <version>` — install specific version
- `/install-app <github-url>` — custom GitHub install (installs the latest commit on the default branch)
- `/install-app <github-url> <40-hex-commit>` — custom GitHub install pinned to a specific commit
---
## Step 1 — Resolve the app
**Registry install:** call `browse_registry` with the app name to get its versions list.
Show the user:
- App name and description
- Repo URL
- Version you will install (and whether it is latest)
**GitHub install:** the commit is **optional**.
- If the user supplied a commit, validate it is a 40-char hex string; if it is malformed,
tell the user and stop.
- If **no commit** was given, do **not** ask the user to find one — call `install_app` with
just the `github_url` and the installer resolves the default branch's latest commit (HEAD)
automatically and pins it. Report the resolved commit in Step 5.
If the app is not found in the registry and no GitHub URL given, stop with a helpful message.
---
## Step 2 — Check for required env vars
- Call `browse_registry` to get the app definition. If the app has `secretKeys` listed, those
- env vars must be supplied. Prompt the user for each missing secret before proceeding:
+ Call `inspect_app` with the same source you will install (`github_url` [+ `commit`],
+ `registry_app` [+ `version`], or `local_path`). It fetches and parses the app's
+ `app.yaml` **without installing** and returns the real secret requirements:
+ - `secretKeys` — env vars the operator **must** supply (no default). Prompt for
+ each one before proceeding.
+ - `generatedKeys` — secrets the gateway **auto-generates** at install time
+ (declared as `KEY=!generate:...`). Do **not** prompt for these; just note they
+ will be generated.
+
+ This is essential for a **GitHub-URL** install: such apps have no registry entry,
+ so `browse_registry` cannot reveal their secrets — only `inspect_app` can.
+
+ If `inspect_app` reports `secretKeys`, prompt the user for each:
+
```
This app requires the following environment variables:
MY_API_KEY — (no default)
SOME_TOKEN — (no default)
Please provide values, e.g.:
MY_API_KEY=xxx
SOME_TOKEN=yyy
```
Wait for the user's reply. Parse key=value pairs.
- If no secrets are needed, proceed immediately.
+ If `secretKeys` is empty (only `generatedKeys`, or no secrets at all), proceed
+ immediately — do not invent secrets or ask for ones the app did not declare.
+ > If `inspect_app` fails (e.g. the repo is unreachable), tell the user the error
+ > and stop — do not fall back to assuming "no secrets".
+
---
## Step 3 — Show permissions summary
- Before installing, show a brief summary:
+ Before installing, show a brief summary (use the `name`, `version`, `ports`,
+ `secretKeys`, and `generatedKeys` returned by `inspect_app`):
```
Installing: <app-name> v<version>
Source: <registry|github>
Repo: <url>
Commit: <first 8 chars, or "latest on default branch (auto-resolved)" for a GitHub install with no pinned commit>
- Proxy routes: (from registry metadata if available)
- Secrets to inject: <list or "none">
+ Proxy routes: <from inspect_app ports, or "none">
+ Secrets to provide: <secretKeys the user supplied, or "none">
+ Secrets auto-generated: <generatedKeys, or "none">
Proceed? (yes/no)
```
Wait for confirmation.
---
## Step 4 — Install
Call `install_app` with the resolved parameters and any collected env vars.
Store the returned `jobId`.
---
## Step 5 — Poll to completion
Poll `poll_install_job` every 3 seconds. Show a brief progress line after each poll
(use the last log entry from the job). Stop when status is `completed` or `failed`.
On **completed**: show proxy URLs from `result.proxyUrls`. For a GitHub install with no
pinned commit, also report the commit that was resolved and installed (the job logs a
`Resolved HEAD → <short>` line) so the user knows exactly what was pinned.
On **failed**: show the error message and last 5 log entries.
---
## Notes
- The `commit` is optional for GitHub installs; when omitted the installer pins the latest
commit on the default branch. When a commit **is** supplied it must be a 40-char hex string
— never pass a branch name as `commit`.
- `env_vars` values should not be echoed back to the user after collection.
- If the user cancels at any confirmation step, say so and stop.