appcrane-mcp 1.0.0 → 1.1.1

package/catalog.json

@@ -158,7 +158,7 @@
   },
   {
     "name": "appcrane_deploy",
-    "description": "Trigger a deployment — this IS how you \"update an env to the latest\". For github and managed apps it pulls the latest commit from the app's configured branch on GitHub (server-side, using the app's stored credentials — you do NOT need your own github token or to push/upload anything), builds a fresh Docker image, and swaps in a new container. Use it whenever the user says things like \"update sandbox to the latest\", \"deploy the newest version\", \"pull my latest github changes\", or \"redeploy\". Returns a deployment ID; use appcrane_get_logs to monitor progress. Defaults to sandbox; production requires explicit confirmation from the user.",
+    "description": "Trigger a deployment — this IS how you \"update an env to the latest\". For github and managed apps it pulls the latest commit from the app's configured branch on GitHub (server-side, using the app's stored credentials — you do NOT need your own github token or to push/upload anything), builds a fresh Docker image, and swaps in a new container. Use it whenever the user says things like \"update sandbox to the latest\", \"deploy the newest version\", \"pull my latest github changes\", or \"redeploy\". Returns a deployment ID; use appcrane_get_logs to monitor progress. Defaults to sandbox; production requires explicit confirmation from the user. DATA LOSS: a deploy destroys and recreates the container, so any path the app persists that AppCrane is not mounting is lost. When that is the case this tool REFUSES and its error names the exact paths; show them to the user, get a real answer, and only then retry with acknowledge_data_loss=true. Do not set acknowledge_data_loss pre-emptively.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -174,6 +174,10 @@
           ],
           "default": "sandbox",
           "description": "Target stage (legacy alias: env)."
+        },
+        "acknowledge_data_loss": {
+          "type": "boolean",
+          "description": "Confirms that the state at the paths named in this tool's DATA_LOSS_NOT_ACKNOWLEDGED error may be destroyed. Only set it after the error has told you which paths those are AND the user has agreed to lose them. Ignored when nothing is at risk."
         }
       },
       "required": [
@@ -502,7 +506,7 @@
   },
   {
     "name": "appcrane_deploy_artifact",
-    "description": "Deploy a release from an uploaded BUNDLE instead of from git. For an app with no GitHub repo, and the fallback when the repo path is unavailable — an expired service-account PAT blocks every managed-repo write, and this route does not touch GitHub at all. Two steps: (1) upload the bundle with `curl -F file=@dist.zip -H \"X-API-Key: <your dhk_mcp_ key>\" https://<host>/api/files/staged` — your MCP key IS allowed on that endpoint; it returns { token, sha256, size_bytes }. (2) Call this tool with that token. Accepts .zip, .tar.gz, .tgz, up to the staged-file limit. The release is identified by a SHA-256 AppCrane computes over the bytes, recorded as commit_hash \"sha256:<digest>\"; the tool re-hashes the staged bytes and refuses if they no longer match what was staged. Returns that digest — compare it against the one you computed locally. Deploys to sandbox unless env=production.",
+    "description": "Deploy a release from an uploaded BUNDLE instead of from git. For an app with no GitHub repo, and the fallback when the repo path is unavailable — an expired service-account PAT blocks every managed-repo write, and this route does not touch GitHub at all. Two steps: (1) upload the bundle with `curl -F file=@dist.zip -H \"X-API-Key: <your dhk_mcp_ key>\" https://<host>/api/files/staged` — your MCP key IS allowed on that endpoint; it returns { token, sha256, size_bytes }. (2) Call this tool with that token. Accepts .zip, .tar.gz, .tgz, up to the staged-file limit. The release is identified by a SHA-256 AppCrane computes over the bytes, recorded as commit_hash \"sha256:<digest>\"; the tool re-hashes the staged bytes and refuses if they no longer match what was staged. Returns that digest — compare it against the one you computed locally. Deploys to sandbox unless env=production. DATA LOSS: like appcrane_deploy, this replaces the container. If the app persists paths AppCrane is not mounting, the tool refuses and names them; retry with acknowledge_data_loss=true only after the user has agreed to lose exactly those paths.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -530,6 +534,10 @@
         "commit_sha": {
           "type": "string",
           "description": "Optional git SHA from the machine that BUILT the bundle. Recorded as context only — it is not verified and does not become the release identity."
+        },
+        "acknowledge_data_loss": {
+          "type": "boolean",
+          "description": "Confirms that the state at the paths named in this tool's DATA_LOSS_NOT_ACKNOWLEDGED error may be destroyed. Set it only after the error has named those paths and the user has agreed."
         }
       },
       "required": [
@@ -1215,7 +1223,7 @@
   },
   {
     "name": "appcrane_create_managed_app",
-    "description": "Create a new app using AppCrane's GitHub service-account — the platform creates a repo on the configured org/user, owns it, and the agent works against it through github_* tools without the end user ever needing their own PAT. Use this when the user does not have a GitHub account or does not want to deal with GitHub at all. Requires the platform admin to have configured the service-account in Settings → GitHub. Returns the same shape as appcrane_create_app, plus the auto-created repo metadata. IDEMPOTENT RECOVERY: if the slug already exists as a managed app but its AMC_ repo was never created (a half-created app from an earlier failure — push then returns REPO_NOT_FOUND), calling this again re-provisions the missing repo and returns { repaired: true } instead of erroring. So if a create attempt half-failed, just call it again with the same slug. Owner-or-admin to repair an existing one.",
+    "description": "Create a new managed app — AppCrane creates and owns its git repository, and the agent works against it through appcrane_push_to_managed_app / appcrane_managed_* tools without the end user ever needing a GitHub account or PAT. New managed apps are hosted on this AppCrane server: there is no GitHub repo and no web URL, so github_* tools cannot reach it (managed apps created before this keep their GitHub repo and work as before). Use this when the user does not have a GitHub account or does not want to deal with GitHub at all. Returns the same shape as appcrane_create_app, plus the repo metadata. IDEMPOTENT RECOVERY: if the slug already exists as a managed app but its AMC_ repo was never created (a half-created app from an earlier failure — push then returns REPO_NOT_FOUND), calling this again re-provisions the missing repo where that app's repo belongs and returns { repaired: true } instead of erroring. So if a create attempt half-failed, just call it again with the same slug. Owner-or-admin to repair an existing one.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1726,5 +1734,50 @@
       },
       "additionalProperties": false
     }
+  },
+  {
+    "name": "appcrane_provision_database",
+    "description": "Create a real managed database for an app: one dedicated database plus its own login inside the platform's shared Postgres or MariaDB server. Reach for this when an app 503s, restarts in a loop, or logs a connection error against a database nobody ever created — most catalogue apps (BookStack, Ghost, Akaunting, Gitea and ~50 more) ship no database of their own and cannot boot without one. THIS CREATES REAL INFRASTRUCTURE: it starts the shared engine container if it is not already running, then creates a database and a login role that exist until somebody deletes them. Idempotent per app+engine — a second call returns the existing database rather than making another, and never rotates the password out from under a running container — so retrying after a timeout is safe. IT DOES NOT RETURN THE PASSWORD, and no AppCrane tool does. The credential is generated server-side, stored encrypted, and injected into the container's environment AT DEPLOY TIME under the variable names that app's own image reads. Do not ask for it, do not try to reconstruct it, and do not tell the user to paste it anywhere — no supported workflow needs a human or an agent to hold it. WHAT THIS DOES NOT DO: it does not restart or redeploy the app, so a container that is already running sees nothing change — call appcrane_deploy afterwards or the app will keep failing in exactly the same way. It does not create or migrate a schema; the app does that on its first successful boot. It does not delete anything, and deprovisioning is deliberately absent from the MCP surface — dropping a database is unrecoverable data loss and belongs to a human in the dashboard, not to an agent recovering from a 503. You must name the engine: pass the one the image documents (BookStack and most linuxserver.io images want mariadb; Postgres-native apps want postgres). Guessing wrong is not destructive but does not help either — it leaves an unused empty database and the app keeps 503ing. An app may hold one of each. ACCESS: requires an app-user assignment on that app, the same tier as env vars and backups. Being an AppCrane admin is NOT enough on its own — assign yourself with appcrane_grant_app_access first, which is the audited step the dashboard also requires.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "slug": {
+          "type": "string",
+          "description": "App slug the database belongs to, e.g. \"bookstack\"."
+        },
+        "engine": {
+          "type": "string",
+          "enum": [
+            "postgres",
+            "mariadb",
+            "mongo",
+            "redis"
+          ],
+          "description": "Which shared engine to create the database in. Required — an app may hold one of each, and this is not guessed for you."
+        }
+      },
+      "required": [
+        "slug",
+        "engine"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "appcrane_list_databases",
+    "description": "What managed databases an app already has: engine, database name, login name and when it was created. Call it before appcrane_provision_database so you do not ask for something that exists, and when debugging a database-related failure to settle which fault you are looking at — \"this app has no database\" and \"this app has a database it cannot reach\" are different problems with different fixes, and they look identical from the app's error message. AN EMPTY LIST IS AN ANSWER, NOT AN ERROR: it means no managed database has been provisioned, which is the correct and expected state for an app that brings its own database or needs none. Do not read it as a failure. NEVER returns a password, a connection URL, a host or a port — no AppCrane surface hands the credential out, because the deployer injects it into the container environment and nothing asks a human or an agent to hold it. What is here is identity, not access. It reports what AppCrane has on file; it does not connect to the engine, so it cannot tell you whether the server is up or whether the app's own connection is working. ACCESS: requires access to the app.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "slug": {
+          "type": "string",
+          "description": "App slug, e.g. \"bookstack\"."
+        }
+      },
+      "required": [
+        "slug"
+      ],
+      "additionalProperties": false
+    }
   }
 ]

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "appcrane-mcp",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "mcpName": "io.github.gitayg/appcrane",
-  "description": "Standalone MCP connector for AppCrane — the self-hosted deployment platform for AI-built apps. Serves the appcrane_* tool catalog for offline introspection and proxies real tool calls to your AppCrane instance.",
+  "description": "Standalone MCP connector for AppCrane \u2014 the self-hosted deployment platform for AI-built apps. Serves the appcrane_* tool catalog for offline introspection and proxies real tool calls to your AppCrane instance.",
   "type": "module",
   "license": "MIT",
   "author": "AppCrane",
@@ -35,7 +35,7 @@
     "build": "tsc",
     "gen:catalog": "node scripts/gen-catalog.mjs",
     "check:catalog": "node scripts/gen-catalog.mjs --check",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run check:catalog && npm run build",
     "start": "node dist/index.js"
   },
   "engines": {