@hoststack.dev/mcp 0.8.0 → 0.9.1

package/README.md

@@ -52,7 +52,13 @@ Add to `~/.cursor/mcp.json` (or via Settings → MCP):
 #### Claude Code
 
 ```bash
-claude mcp add hoststack -- npx -y @hoststack.dev/mcp -e HOSTSTACK_API_KEY=hs_live_...
+claude mcp add hoststack --env HOSTSTACK_API_KEY=hs_live_... -- npx -y @hoststack.dev/mcp
+```
+
+Or — equivalently — use the hosted HTTP transport so credentials live only in your Claude Code config, not on disk:
+
+```bash
+claude mcp add --transport http hoststack https://hoststack.dev/api/mcp --header "Authorization: Bearer hs_live_..."
 ```
 
 #### Any other client (hosted)
@@ -79,7 +85,7 @@ If `HOSTSTACK_API_KEY` is set in your shell, it gets baked into the snippet; oth
 
 ## Tool inventory
 
-55 tools, grouped by resource:
+58 tools, grouped by resource:
 
 | Category          | Read                                                                                                                              | Write                                                                                                                    |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -87,7 +93,7 @@ If `HOSTSTACK_API_KEY` is set in your shell, it gets baked into the snippet; oth
 | **services**      | `list_services`, `get_service`, `get_service_metrics`, `get_service_metrics_history`, `get_service_logs`, `get_service_logs_bulk` | `update_service`, `update_service_config`, `suspend_service`, `resume_service`                                           |
 | **deploys**       | `list_deploys`, `get_deploy`, `get_deploy_logs`, `diagnose_deploy`                                                                | `trigger_deploy`, `cancel_deploy`                                                                                        |
 | **environments**  | `list_environments`                                                                                                               | `create_environment`, `delete_environment`, `promote_deploy`                                                             |
-| **databases**     | `list_databases`, `get_database`                                                                                                  | `update_database` (use the dashboard for create/delete/credentials)                                                      |
+| **databases**     | `list_databases`, `get_database`, `get_database_cluster`, `query_database`                                                        | `update_database`, `upgrade_database_to_ha` (use the dashboard for create/delete/credentials)                            |
 | **volumes**       | `list_volumes`                                                                                                                    | `create_volume`, `update_volume`, `delete_volume`                                                                        |
 | **domains**       | `list_domains`                                                                                                                    | `add_domain`, `verify_domain`, `remove_domain`                                                                           |
 | **dns**           | `list_dns_zones`, `list_dns_records`, `get_dns_record`                                                                            | `create_dns_record`, `update_dns_record`, `delete_dns_record`                                                            |

package/dist/hoststack-mcp.js

@@ -702,7 +702,7 @@ defineTool({
     "",
     "Returns: { columns: string[], rows: string[][], rowCount: number, truncated: boolean, durationMs: number }. Values come back as strings (psql --csv); cast on the caller side when needed.",
     "",
-    "Examples:",
+    "Example:",
     '  - query_database({ database_id: "db_abc", sql: "SELECT count(*) FROM users" }) \u2192 { columns: ["count"], rows: [["1234"]], \u2026 }',
     `  - query_database({ database_id: "db_abc", sql: "SELECT id, email FROM users WHERE created_at > now() - interval '1 day' LIMIT 50" })`
   ].join("\n"),
@@ -719,6 +719,60 @@ defineTool({
     return respond({ summary, data: result });
   }
 });
+defineTool({
+  name: "upgrade_database_to_ha",
+  category: "databases",
+  description: [
+    "Trigger a single-node \u2192 HA migration on a managed Postgres database. The agent runs pg_dump \u2192 bootstrap 3-node Patroni cluster (1 leader + 2 sync replicas + HAProxy) \u2192 pg_restore. Customer connections to this database are briefly read-only during the cutover; the standalone container stays running (read-only) for 24 h as a rollback target before automatic decommission.",
+    "",
+    "Requires: PATRONI_ENABLED env on the HostStack deployment + `teams.ha_beta = true` on the calling team. Returns 403 otherwise. Returns 400 if the database is already HA, not Postgres, not on the standard or pro tier, or has a pg_database_size over 1 GB (in-memory archive transfer cap).",
+    "",
+    "When to use: a customer needs failover protection on an existing standalone Postgres. For new databases on an HA-eligible team, just call create_database \u2014 the cluster path is automatic.",
+    "",
+    "Inputs:",
+    "  - database_id: publicId of the postgres database to upgrade.",
+    "",
+    'Returns: 202 Accepted. The upgrade is async \u2014 poll get_database until `pg_engine_type === "patroni"` and `status === "available"` to confirm completion. The Cluster tab on the dashboard mirrors the same data.',
+    "",
+    'Example: upgrade_database_to_ha({ database_id: "db_abc" }) \u2192 { ok: true }'
+  ].join("\n"),
+  input: {
+    database_id: z5.string().describe("Database publicId (e.g. db_abc) to upgrade to HA.")
+  },
+  handler: async (args2, ctx) => {
+    const teamId = await ctx.resolveTeamId();
+    await ctx.hoststack.databases.upgradeToHa(teamId, args2.database_id);
+    return respond({
+      summary: `HA migration started for ${args2.database_id}. Poll get_database until pg_engine_type=patroni to confirm.`
+    });
+  }
+});
+defineTool({
+  name: "get_database_cluster",
+  category: "databases",
+  description: [
+    "Get the live + retired cluster members and failover history for a Patroni HA Postgres database.",
+    "",
+    "When to use: confirm an HA cluster is healthy (1 leader + 2 sync replicas + 1 proxy + 1 etcd live) or investigate a failover that fired. For standalone databases this returns 400 \u2014 call get_database first if you need to branch.",
+    "",
+    "Inputs:",
+    "  - database_id: publicId of the postgres database (must be HA).",
+    "",
+    "Returns: { members: { id, memberRole: 'etcd' | 'primary-candidate' | 'replica' | 'proxy', containerId, workerHostId, joinedAt, leftAt }[], failovers: { id, createdAt, oldLeader, newLeader }[] }.",
+    "",
+    'Example: get_database_cluster({ database_id: "db_abc" }) \u2192 { members: [...5 live rows], failovers: [] }'
+  ].join("\n"),
+  input: {
+    database_id: z5.string().describe("Database publicId for the HA cluster.")
+  },
+  handler: async (args2, ctx) => {
+    const teamId = await ctx.resolveTeamId();
+    const result = await ctx.hoststack.databases.getCluster(teamId, args2.database_id);
+    const live = result.members.filter((m) => m.leftAt === null);
+    const summary = `${live.length} live members (${live.map((m) => m.memberRole).join(", ")}); ${result.failovers.length} historical failovers.`;
+    return respond({ summary, data: result });
+  }
+});
 
 // src/tools/deploys.ts
 import { z as z6 } from "zod";
@@ -780,13 +834,14 @@ defineTool({
   name: "trigger_deploy",
   category: "deploys",
   description: [
-    "Kick off a new deploy from the latest commit on the service branch. Optionally clear the build cache for a clean rebuild.",
+    "Kick off a new deploy. Defaults to the latest commit on the service branch; pass commit_hash or branch to deploy something else.",
     "",
-    'When to use: the user explicitly asks to deploy ("ship it", "redeploy", "kick off a new build"). For services with auto-deploy enabled, a fresh git push already triggers a deploy automatically \u2014 only call this for manual triggers, cache-clearing, or after a config change.',
+    'When to use: the user explicitly asks to deploy ("ship it", "redeploy", "kick off a new build"). For services with auto-deploy enabled, a fresh git push already triggers a deploy automatically \u2014 only call this for manual triggers or after a config change.',
     "",
     "Inputs:",
     "  - service_id: publicId of the service.",
-    "  - clear_cache (optional): boolean \u2014 discard the cached build layers. Default false.",
+    "  - commit_hash (optional): build a specific commit instead of HEAD on the configured branch.",
+    "  - branch (optional): build the tip of a non-default branch.",
     "",
     'Returns: { deploy: Deploy } \u2014 the new deploy record. Status will start as "pending" then transition through "building" \u2192 "deploying" \u2192 "live" or "failed".',
     "",
@@ -794,12 +849,14 @@ defineTool({
   ].join("\n"),
   input: {
     service_id: z6.string().describe("Service publicId."),
-    clear_cache: z6.boolean().optional().describe("Clear the build cache (default false).")
+    commit_hash: z6.string().max(40).optional().describe("Specific commit to build (default: branch HEAD)."),
+    branch: z6.string().max(200).optional().describe("Branch to build (default: service configured branch).")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
     const input = {};
-    if (args2.clear_cache !== void 0) input.clearCache = args2.clear_cache;
+    if (args2.commit_hash !== void 0) input.commitHash = args2.commit_hash;
+    if (args2.branch !== void 0) input.branch = args2.branch;
     const response = await ctx.hoststack.deploys.trigger(teamId, args2.service_id, input);
     const data = { deploy: shapeDeploy(response.deploy) };
     const publicId = data.deploy && "publicId" in data.deploy ? data.deploy.publicId : "unknown";
@@ -842,7 +899,7 @@ defineTool({
   name: "get_deploy_logs",
   category: "deploys",
   description: [
-    "Fetch the build/deploy logs for a single deploy. Returns the entire log buffer the agent can the search for errors.",
+    "Fetch the build/deploy logs for a single deploy. Returns the entire log buffer the agent can then search for errors.",
     "",
     "When to use: a deploy failed and you need to read the build output to diagnose. Pair with get_deploy to find a failed deploy_id, then call this. For runtime (post-deploy) logs of the running container, use get_service_logs instead.",
     "",
@@ -1283,7 +1340,8 @@ defineTool({
     "",
     "Inputs:",
     '  - hostname: the domain to add (e.g. "api.example.com").',
-    "  - service_id (optional): publicId of the service to bind to. If omitted, the domain is added unbound and you can attach it later with update_domain.",
+    "  - service_id: publicId of the service to bind the domain to.",
+    "  - path_prefix (optional): when set, only requests under this URL prefix route to this service. Use for path-based fan-out (e.g. `/api` to an api service, `/` to a web service on the same hostname).",
     "",
     "Returns: { domain: Domain } \u2014 includes dnsTargets you must configure (CNAME / A records).",
     "",
@@ -1291,12 +1349,16 @@ defineTool({
   ].join("\n"),
   input: {
     hostname: z8.string().min(3).max(253).describe("Fully-qualified hostname (e.g. api.example.com)."),
-    service_id: z8.string().optional().describe("Optional service publicId to bind to.")
+    service_id: z8.string().describe("Service publicId to bind to."),
+    path_prefix: z8.string().optional().describe('Optional URL prefix for path-based routing (e.g. "/api").')
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
-    const input = { domain: args2.hostname };
-    if (args2.service_id !== void 0) input.serviceId = args2.service_id;
+    const input = {
+      domain: args2.hostname,
+      serviceId: args2.service_id
+    };
+    if (args2.path_prefix !== void 0) input.pathPrefix = args2.path_prefix;
     const response = await ctx.hoststack.domains.add(teamId, input);
     const data = { domain: shapeDomain(response.domain) };
     return respond({
@@ -1397,7 +1459,7 @@ defineTool({
     "  - service_id: publicId of the service.",
     '  - key: env-var name (e.g. "DATABASE_URL").',
     "  - value: new value (will be encrypted at rest if is_secret=true).",
-    "  - is_secret (optional): true marks the value as secret (masked on read). Default true for safety; pass false for boring config like PORT or NODE_ENV.",
+    "  - is_secret (optional): true marks the value as secret (masked on read). On create, defaults to true for safety. On update, omitting it leaves the existing flag untouched \u2014 pass it explicitly only when you want to change classification.",
     "",
     'Returns: { envVar: EnvVar, action: "created" | "updated" }.',
     "",
@@ -1411,18 +1473,16 @@ defineTool({
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
-    const isSecret = args2.is_secret ?? true;
     const existing = await ctx.hoststack.envVars.list(teamId, args2.service_id);
     const match = existing.envVars.find((v) => v.key === args2.key);
     if (match) {
+      const updatePayload = { value: args2.value };
+      if (args2.is_secret !== void 0) updatePayload.isSecret = args2.is_secret;
       const response2 = await ctx.hoststack.envVars.update(
         teamId,
         args2.service_id,
         String(match.id),
-        {
-          value: args2.value,
-          isSecret
-        }
+        updatePayload
       );
       const data2 = {
         envVar: shapeEnvVar(response2.envVar),
@@ -1433,7 +1493,7 @@ defineTool({
     const response = await ctx.hoststack.envVars.create(teamId, args2.service_id, {
       key: args2.key,
       value: args2.value,
-      isSecret
+      isSecret: args2.is_secret ?? true
     });
     const data = {
       envVar: shapeEnvVar(response.envVar),
@@ -1569,7 +1629,7 @@ defineTool({
     "",
     "Returns: { environment: Environment }.",
     "",
-    'Example: create_environment({ project_id: "prj_abc", name: "Staging", type: "staging" }) \u2192 { environment: { id: 7, publicId: "environment_\u2026", name: "Staging", type: "staging" } }'
+    'Example: create_environment({ project_id: "prj_abc", name: "Staging", type: "staging" }) \u2192 { environment: { id: 7, publicId: "env_\u2026", name: "Staging", type: "staging" } }'
   ].join("\n"),
   input: {
     project_id: z10.string().describe("Project publicId."),
@@ -1606,7 +1666,7 @@ defineTool({
     "",
     "Returns: { success: true } on success.",
     "",
-    'Example: delete_environment({ project_id: "prj_abc", environment_id: "environment_xyz" }) \u2192 { success: true }'
+    'Example: delete_environment({ project_id: "prj_abc", environment_id: "env_xyz" }) \u2192 { success: true }'
   ].join("\n"),
   input: {
     project_id: z10.string().describe("Project publicId."),
@@ -1638,7 +1698,7 @@ defineTool({
     "",
     "Returns: { deploy: Deploy } \u2014 the new deploy on the target service.",
     "",
-    'Example: promote_deploy({ service_id: "svc_staging", deploy_id: "dpl_built", target_environment_id: "environment_prod" }) \u2192 { deploy: { id: 99, status: "pending", trigger: "rollback", dockerImageId: "sha256:\u2026" } }'
+    'Example: promote_deploy({ service_id: "svc_staging", deploy_id: "dpl_built", target_environment_id: "env_prod" }) \u2192 { deploy: { id: 99, status: "pending", trigger: "rollback", dockerImageId: "sha256:\u2026" } }'
   ].join("\n"),
   input: {
     service_id: z10.string().describe("Source service publicId."),
@@ -2660,7 +2720,7 @@ defineTool({
 
 // src/server-factory.ts
 var PACKAGE_NAME = "hoststack";
-var PACKAGE_VERSION = "0.6.0";
+var PACKAGE_VERSION = "0.9.1";
 function createMcpServer(options) {
   const baseUrl2 = (options.baseUrl ?? "https://hoststack.dev").replace(/\/$/, "");
   const hoststack = new HostStack({ apiKey: options.apiKey, baseUrl: baseUrl2 });
@@ -2725,7 +2785,7 @@ if (printIdx !== -1) {
   }
   if (target === "claude-code") {
     process.stdout.write(
-      `claude mcp add hoststack -- npx -y @hoststack.dev/mcp -e HOSTSTACK_API_KEY=${apiKeyPlaceholder}
+      `claude mcp add hoststack --env HOSTSTACK_API_KEY=${apiKeyPlaceholder} -- npx -y @hoststack.dev/mcp
 `
     );
     process.exit(0);