Skip to content

feat: add App Watch tools to MCP server (EPINIO-719) - #4

Merged
dcharles525 merged 3 commits into
mainfrom
feat/epinio-719-app-watch
Sep 2, 2026
Merged

dcharles525 merged 3 commits into
mainfrom
feat/epinio-719-app-watch

Conversation

@psanghvi17

Copy link
Copy Markdown
Contributor

What changed

Adds the App Watch inner-loop workflow to the MCP server so an agent can live-reload a running app without a full buildpack push on every change.

New core tools

  • watch_app_startup — uploads full source via PATCH .../applications/:app/source, waits for staging + ready, installs the supervisor wrapper
  • sync_app — uploads changed files (files mode) or a rebuilt binary (binary mode) via POST .../applications/:app/sync; supervisor restarts the app in place

Client

  • AppSourcePatch, AppSync, and WatchAppStartup on the Epinio REST client, plus a shared uploadMultipart helper
  • APIResponse type for the sync status envelope

Agent UX for the stale-supervisor gotcha

  • Tool descriptions warn that push_app / deploy_staged / restart_app recreate the pod without the supervisor, so watch_app_startup must be re-run before further sync_app calls
  • sync_app wraps no ready pod / 503 errors with an explicit hint to call watch_app_startup again (same signals the CLI uses)

Docs / skill

  • AGENTS.md, README.md, and skills/epinio-cli/SKILL.md updated to describe the new tools and CLI mapping

This is not a local filesystem watcher and does not shell out to epinio app watch. The agent supplies a files map (same pattern as push_app) and owns change detection.

Stacked on #3 (feat/epinio-702-cli-skill) because this branch was cut from that work. Only the EPINIO-719 commit is in scope for this PR; rebase onto main after #3 merges if preferred.

Why

Move MCP closer to UI/CLI parity for the experimental App Watch / inner-loop sync flow already available via epinio app watch.

Closes EPINIO-719

What to test

Unit (no cluster)

  1. gofmt -l tools/watch.go tools/watch_test.go client/client.go — expect empty output
  2. go test ./client/... ./tools/... — expect pass (covers AppSourcePatch/AppSync multipart, buildTar, wrapSyncError)

CI gate (Linux / make available)
3. make check — fmt-check, vet, lint, test

Against a live Epinio cluster (≥ 1.14.x with App Watch APIs)
4. Run MCP locally with EPINIO_API_URL / credentials, then:

  • push_app a simple Node (or Python) app so it exists
  • Call watch_app_startup with the full files map — expect staging + ready, status mentions supervisor installed
  • Call sync_app with mode: files and only a changed source file — expect success; verify the running app reflects the change (route / logs)
  1. Stale-supervisor path:
    • After a successful watch session, call restart_app or push_app
    • Call sync_app again without watch_app_startup — expect an error that mentions calling watch_app_startup again
  2. Optional binary mode (Go app with a built binary as a single files entry, mode: binary) — sync succeeds and app reloads

Possible regressions

  • Push path: buildTar was added next to buildTarGz in tools/push.go; push_app / upload_and_stage still use buildTarGz only — re-check those tools still package source correctly
  • Multipart uploads: shared uploadMultipart is new; existing UploadApp is unchanged, but any future callers should keep gzip vs plain-tar expectations straight (source patch = tar.gz, sync = plain tar)
  • Mutation guard: both new tools consult appMutationGuard like other mutators — elevated adoption should still block sync/startup on adopted apps when elevated is enabled
  • No change to auth, RBAC, or elevated registration

Type

feature

Checklist

  • make check passes (fmt-check, vet, lint, test) — gofmt + go test ./... verified locally on Windows; full make check needs Linux/make (please confirm in CI)
  • New or changed behavior has tests, or the test impact is noted above
  • Tool names, inputs, or outputs changed? The MCP server reference is updated — follow-up: docs PR in epinio/docs still needed for watch_app_startup / sync_app
  • New or changed capability sits in the right tier: core (Epinio API only, runs as the caller) vs elevated (EPINIO_MCP_ELEVATED, reaches directly into Kubernetes and needs the standard-elevated RBAC)
  • Touches auth, credentials, or the RBAC/appchart surface? Flagged for security review — N/A (core Epinio API only; no new credentials/RBAC)
  • User-facing behavior changed? A matching PR is opened in epinio/docs — still to open
  • No secrets, tokens, or real cluster credentials committed

Environments that cannot use MCP still have the Epinio CLI and an LLM; this skill maps core tools to epinio commands they can run instead.
Expose the inner-loop dev workflow as two new MCP tools so an AI agent
can live-reload a running app without a full buildpack push on every change:

- watch_app_startup: uploads full source, runs buildpack staging, installs
  the supervisor wrapper, and waits for the app to be ready. Must be called
  after any push_app/deploy_staged/restart_app that recreates the pod.
- sync_app: streams only changed files (files mode) or a rebuilt binary
  (binary mode) into the running pod. The supervisor restarts the app
  in place. Returns an actionable error with watch_app_startup guidance
  when it detects the supervisor is missing (no ready pod / 503).

Both tools follow the existing files-map pattern from push_app and go
through the Epinio REST API (PATCH .../source, POST .../sync) — no CLI
subprocess, no local filesystem polling.

Supporting changes:
- client: AppSourcePatch, AppSync, WatchAppStartup methods + shared
  uploadMultipart helper
- client/types: APIResponse type
- tools/push: buildTar helper for plain (non-gzip) sync archives
- tests: client_test covers AppSourcePatch/AppSync; watch_test covers
  buildTar, binary-name defaulting, and wrapSyncError branching
- docs: AGENTS.md, README, skills/epinio-cli/SKILL.md updated
@dcharles525
dcharles525 changed the base branch from feat/epinio-702-cli-skill to main August 31, 2026 18:31
@dcharles525
dcharles525 self-requested a review September 2, 2026 19:53

@dcharles525 dcharles525 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@dcharles525
dcharles525 merged commit 906d17f into main Sep 2, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants