impreza-mcp

# impreza-mcp

[Model Context Protocol](https://modelcontextprotocol.io) server for
[Impreza Host](https://imprezahost.com). Lets AI coding tools (Claude
Code, Cursor, Codex CLI, Continue, Zed, ...) deploy customer-built
apps to managed Impreza VPSes without leaving the chat.

When you say "deploy this for me" to Claude with this MCP server
loaded, Claude calls `impreza_deploy_custom` directly — packages your
project, uploads it, builds + runs on your Impreza VPS, and reports
back the URL.

## Deployment progress and agent restarts

Compose review and deployment accept
`context_id` for one retained upload containing local build contexts and runtime
`env_file`, configs or secrets. The same context must be supplied at review and
deployment. Runtime files require agent 0.6.11+ with `compose-source-files-v1`.

Custom Node server/static deployments
accept `node_package_manager`, such as `pnpm@10.26.1` or `yarn@4.9.2`, matching the
project's exact `packageManager` and committed lockfile. Omit for npm. Supported
versions are standalone pnpm 10–12 and Yarn 4 projects, without combining
this field with `npm_workspace`. Inspection infers the pin and saved plans retain
it. See the deployment documentation for supported inputs and limits.

Read `last_operation.progress` from `impreza_list_deployments` for the last
reported step and timestamp. Agent 0.6.6+ saves final results before sending them;
after restart it resends the same receipt without repeating the deploy.
Agent 0.6.7+ can verify a completed preparation checkpoint and restore previous
configuration without replaying the deploy (`recovery=reconciling`). Wait for the
terminal failure or confirmed cancellation before retrying.
`recovery=required` means automatic reconciliation could not be verified; contact
support. Busy builds, missing checkpoints and replacement uncertainty stay blocked. A long-running build can
continue after the agent exits. Progress is not a live percentage or proof of
current runtime health. Existing agents update explicitly before the next deploy.
See [deployment progress](https://docs.imprezahost.com/deployment-progress.html).

## Cancel a deployment

Use `impreza_cancel_deployment` with the deployment ID and exact
`last_operation.command_id`. Requires manage permission. Queued cancellation
is immediate; running preparation needs agent 0.6.5+. Agent 0.6.12+ can interrupt an owned build after the server administrator
enables controlled builds on supported Ubuntu 24.04 amd64 hosts. Other preparation
waits for its current step. Confirmation still requires verified cleanup and restored
configuration. `requested` is not `cancelled`. Replacement/recovery cannot
be cancelled. Cancelling a tracking Task remains separate.
Read [the cancellation guide](https://docs.imprezahost.com/deployment-cancellation.html).

## Runtime health and deployment operations

`impreza_list_deployments` returns `runtime` and `last_operation` separately.
A failed build can leave the previous application healthy. Read runtime state,
observation time and reason; old or missing readings remain unknown.
Running without a confirmed healthcheck is not healthy. This requires agent
0.6.4+ for observations and does not verify external HTTP/DNS/TLS. Existing
servers update explicitly. See [runtime health](https://docs.imprezahost.com/runtime-health.html).

## Saved project plans and safe retries

`impreza_plan_project` also accepts
`git_url` and an exact 40-character `git_commit` instead of `context_id`.
Optional `git_username` and `git_token` are used only for the fetch. The server
captures an immutable retained archive, accounts for its upload quota, and
returns `source.origin` alongside the archive SHA256. Review those values before
preparing/applying the saved configuration. Only public-network HTTPS on port
443 is supported; redirects and submodules are refused. Project code is not
executed by inspection. These options require the corresponding control-plane
capabilities; update the local MCP package before using them.

Use `impreza_plan_project` with a retained `context_id` to inspect the archive
inventory and selected configuration files. Choose `project_dir`,
`dockerfile_path`, a Python `start_command` or `php_document_root` as needed.
Review the findings and `analysis.deployment_options`.

With MCP **0.32.0+**, call `impreza_prepare_project_deployment` with `plan_id`,
zero-based `option_index`, app name, server and runtime settings. It validates
and saves the effective configuration without creating an app, job or DNS
record. Review the returned configuration, then call
`impreza_apply_project_deployment` with only `execution_id` and
`configuration_digest`. Later form/request changes cannot override that record.

A repeat of the same saved deployment returns its original acceptance receipt,
including after expiry or app removal. The receipt, app and queue job commit
together. After an uncertain response, retry the same ID and digest instead of
preparing another deployment. Acceptance means queued; inspect app status,
logs and health. This does not restart a failed job or update an existing app.

`impreza_list_prepared_deployments` lists the latest 20 saved configurations or
retrieves one `execution_id`. Environment values are encrypted in the prepared
record, omitted from review responses and cleared from that record on acceptance;
the app then uses its normal environment storage. Reviews show variable names.
Use at most 100 string values, with no system/routing variable overrides.

At most 20 pending records per account, valid no longer than the source plan
and for at most 24 hours. Source, rules, target availability/IP and effective
settings are rechecked before first apply. There is no domain, port or capacity
reservation, dependency pinning or build guarantee. DNS is external to the app
transaction and can remain after an interrupted attempt. Expired pending records
are removed on the account's next preparation; accepted receipts are retained.

Source inspection remains available in MCP 0.31.0+. The older
`impreza_deploy_project_plan` creates directly from an option and is not
idempotent. Plan creation requires deploy scope; listing requires read scope;
preparation/apply require deploy scope. These account-wide tools require
credentials without resource restrictions. No agent update is needed solely for
this flow; recipe requirements still apply. See the
[project plan and review guide](https://docs.imprezahost.com/project-plans.html).

## Retained source uploads

Use `impreza_upload_context` with `dir` and an optional `label` to upload an immutable
source version without deploying. The response includes its `context_id`, SHA256,
size and expiry. List or inspect versions with `impreza_list_contexts`.

Create an app with `impreza_deploy_custom`, `mode: "dockerfile"` and `context_id`
(or deploy a local `dir` directly). Rebuild it with `impreza_redeploy_deployment`
and optionally another retained `context_id`. The app identity, domain, host port,
volumes and build recipe stay fixed. The selected source can differ from the
running release after failure or rollback; inspect deployment history.

Sources in use remain available. Unreferenced versions expire seven days after
upload or their last deployment request, not seven days after detachment. Default
quotas are 10 unexpired/referenced archives, 300 MiB per account and 100 MiB per
archive; referenced sources count. Delete an unused version with
`impreza_delete_context`, `context_id` and `confirm: true` after customer confirmation.
Metadata requires read scope, upload requires deploy, and deletion requires
manage. Resource-confined credentials cannot manage account uploads.

The packer excludes common dependency/VCS folders, .env and .env.* (except
example/sample/template files), .npmrc and .pypirc. It does not scan arbitrary
secrets or interpret .gitignore/.dockerignore; review what you upload. Portal
archives are sent unchanged. Legacy REST uploads remain temporary unless they
opt into `retain=true`. Older uploaded-source apps can migrate by selecting a
fresh retained context on redeploy. These MCP tools require 0.22.0+; no agent
update is needed solely for source retention. See the
[source upload guide](https://docs.imprezahost.com/source-uploads.html).

## Node.js npm builds

Deploy an independent npm HTTP application without a repository Dockerfile using
`impreza_deploy_custom` with `mode: "dockerfile"`, `build_strategy: "node_npm"`,
`git_url` (or local `dir`), and `target_port` (usually 3000).
The API generates a Node 24 recipe: npm ci, optional build script, production
pruning and npm start as a non-root user. The selected project folder must contain package.json, package-lock.json
and a production start script. Docker Compose 2.17+ and BuildKit
must be available on the server. Select npm workspaces explicitly with
`npm_workspace`. Use `build_secrets` for named credentials and the `npmrc` secret
for private npm installation; agent 0.6.11+ is required. The app must listen on 0.0.0.0 and the
configured port. Keep runtime PORT consistent with that port.

Git redeploys and previews reuse the recipe snapshot. Retained uploaded sources
support reuse and source-version selection; older temporary uploads remain single-use. The recipe excludes .git, node_modules, .env,
.env.* and .npmrc from the source copy; this does not scan arbitrary secrets.
Keep credentials out of source code. The HTTP startup probe accepts responses
below 500 at / and is not a functional application test.

## Public build variables

Required healthy start: opt in with require_healthy_start=true, an explicit healthcheck_path and build_strategy=node_npm. In the portal, enable Require a healthy start. Agent 0.6.3 or newer must be reported in Servers; update it explicitly and wait for the next heartbeat. startup_timeout_seconds accepts an integer from 30 to 600, default 60. The budget starts after containers are created and includes the stable health observa