@hoststack.dev/mcp 0.13.1 → 0.15.0

package/dist/index.js

@@ -2,6 +2,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { HostStack } from "@hoststack.dev/sdk";
 
+// src/version.ts
+var MCP_VERSION = true ? "0.15.0" : "0.0.0-dev";
+var USER_AGENT = `hoststack-mcp/${MCP_VERSION}`;
+
 // src/api-client.ts
 var ApiClient = class {
   constructor(apiKey, baseUrl) {
@@ -11,7 +15,8 @@ var ApiClient = class {
   get headers() {
     return {
       Authorization: `Bearer ${this.apiKey}`,
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT
     };
   }
   async get(path, params) {
@@ -1054,10 +1059,20 @@ defineTool({
 
 // src/tools/dns-records.ts
 import { z as z7 } from "zod";
-var DNS_RECORD_TYPES = ["A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "CAA", "ALIAS"];
-async function resolveZonePublicId(api, teamId, input) {
+var DNS_RECORD_TYPES = [
+  "A",
+  "AAAA",
+  "CNAME",
+  "MX",
+  "TXT",
+  "NS",
+  "SRV",
+  "CAA",
+  "ALIAS"
+];
+async function resolveZonePublicId(hoststack, teamId, input) {
   if (input.zone_id) {
-    const { zones: zones2 } = await api.get(`/api/dns-zones/${teamId}`);
+    const { zones: zones2 } = await hoststack.dns.listZones(teamId);
     const match = zones2.find((z15) => z15.publicId === input.zone_id);
     if (!match) {
       throw new Error(`Zone ${input.zone_id} not found on this team.`);
@@ -1067,7 +1082,7 @@ async function resolveZonePublicId(api, teamId, input) {
   if (!input.domain) {
     throw new Error("Provide either zone_id or domain.");
   }
-  const { zones } = await api.get(`/api/dns-zones/${teamId}`);
+  const { zones } = await hoststack.dns.listZones(teamId);
   const fqdn = input.domain.toLowerCase().replace(/\.$/, "");
   const labels = fqdn.split(".");
   for (let i = 0; i < labels.length - 1; i++) {
@@ -1096,7 +1111,7 @@ defineTool({
   input: {},
   handler: async (_args, ctx) => {
     const teamId = await ctx.resolveTeamId();
-    const response = await ctx.api.get(`/api/dns-zones/${teamId}`);
+    const response = await ctx.hoststack.dns.listZones(teamId);
     const items = Array.isArray(response.zones) ? response.zones.map(shape) : [];
     const summary = items.length === 0 ? "No DNS zones hosted on this team. Create one in the dashboard (Domains \u2192 DNS)." : `Found ${items.length} hosted DNS zone${items.length === 1 ? "" : "s"}.`;
     return respond({ summary, data: { items } });
@@ -1125,10 +1140,8 @@ defineTool({
     const zoneInput = {};
     if (args.zone_id !== void 0) zoneInput.zone_id = args.zone_id;
     if (args.domain !== void 0) zoneInput.domain = args.domain;
-    const zone = await resolveZonePublicId(ctx.api, teamId, zoneInput);
-    const response = await ctx.api.get(
-      `/api/dns-zones/${teamId}/${zone.publicId}/records`
-    );
+    const zone = await resolveZonePublicId(ctx.hoststack, teamId, zoneInput);
+    const response = await ctx.hoststack.dns.listRecords(teamId, zone.publicId);
     const items = Array.isArray(response.records) ? response.records.map(shape) : [];
     const summary = items.length === 0 ? `Zone ${zone.domainName} has no records yet.` : `Returned ${items.length} record${items.length === 1 ? "" : "s"} for ${zone.domainName}.`;
     return respond({
@@ -1157,11 +1170,9 @@ defineTool({
   },
   handler: async (args, ctx) => {
     const teamId = await ctx.resolveTeamId();
-    const { zones } = await ctx.api.get(`/api/dns-zones/${teamId}`);
+    const { zones } = await ctx.hoststack.dns.listZones(teamId);
     for (const zone of zones) {
-      const { records } = await ctx.api.get(
-        `/api/dns-zones/${teamId}/${zone.publicId}/records`
-      );
+      const { records } = await ctx.hoststack.dns.listRecords(teamId, zone.publicId);
       const match = records.find((r) => r.publicId === args.record_id);
       if (match) {
         return respond({
@@ -1217,7 +1228,7 @@ defineTool({
     const zoneInput = {};
     if (args.zone_id !== void 0) zoneInput.zone_id = args.zone_id;
     if (args.domain !== void 0) zoneInput.domain = args.domain;
-    const zone = await resolveZonePublicId(ctx.api, teamId, zoneInput);
+    const zone = await resolveZonePublicId(ctx.hoststack, teamId, zoneInput);
     const body = {
       type: args.type,
       name: args.name,
@@ -1225,10 +1236,7 @@ defineTool({
     };
     if (args.ttl !== void 0) body.ttl = args.ttl;
     if (args.priority !== void 0) body.priority = args.priority;
-    const response = await ctx.api.post(
-      `/api/dns-zones/${teamId}/${zone.publicId}/records`,
-      body
-    );
+    const response = await ctx.hoststack.dns.createRecord(teamId, zone.publicId, body);
     return respond({
       summary: `Created ${args.type} ${args.name} on ${zone.domainName}.`,
       data: {
@@ -1268,7 +1276,7 @@ defineTool({
       return respondError(`Priority is required for ${args.type} records (0\u201365535).`);
     }
     const teamId = await ctx.resolveTeamId();
-    const target = await findRecordZone(ctx.api, teamId, args.record_id);
+    const target = await findRecordZone(ctx.hoststack, teamId, args.record_id);
     if (!target) {
       return respondError(
         `Record ${args.record_id} not found on any zone owned by this team.`
@@ -1281,8 +1289,10 @@ defineTool({
     };
     if (args.ttl !== void 0) body.ttl = args.ttl;
     if (args.priority !== void 0) body.priority = args.priority;
-    const response = await ctx.api.put(
-      `/api/dns-zones/${teamId}/${target.zone.publicId}/records/${args.record_id}`,
+    const response = await ctx.hoststack.dns.updateRecord(
+      teamId,
+      target.zone.publicId,
+      args.record_id,
       body
     );
     return respond({
@@ -1317,27 +1327,23 @@ defineTool({
   },
   handler: async (args, ctx) => {
     const teamId = await ctx.resolveTeamId();
-    const target = await findRecordZone(ctx.api, teamId, args.record_id);
+    const target = await findRecordZone(ctx.hoststack, teamId, args.record_id);
     if (!target) {
       return respondError(
         `Record ${args.record_id} not found on any zone owned by this team.`
       );
     }
-    await ctx.api.delete(
-      `/api/dns-zones/${teamId}/${target.zone.publicId}/records/${args.record_id}`
-    );
+    await ctx.hoststack.dns.deleteRecord(teamId, target.zone.publicId, args.record_id);
     return respond({
       summary: `Deleted record ${args.record_id} from ${target.zone.domainName}.`,
       data: { ok: true }
     });
   }
 });
-async function findRecordZone(api, teamId, recordPublicId) {
-  const { zones } = await api.get(`/api/dns-zones/${teamId}`);
+async function findRecordZone(hoststack, teamId, recordPublicId) {
+  const { zones } = await hoststack.dns.listZones(teamId);
   for (const zone of zones) {
-    const { records } = await api.get(
-      `/api/dns-zones/${teamId}/${zone.publicId}/records`
-    );
+    const { records } = await hoststack.dns.listRecords(teamId, zone.publicId);
     const match = records.find((r) => r.publicId === recordPublicId);
     if (match) return { zone, record: match };
   }
@@ -1497,6 +1503,7 @@ defineTool({
     '  - 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). 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.",
+    '  - target (optional): where the var is injected \u2014 "build", "runtime", or "both". On create, defaults to "both". On update, omitting it leaves the existing target untouched.',
     "",
     'Returns: { envVar: EnvVar, action: "created" | "updated" }.',
     "",
@@ -1506,7 +1513,8 @@ defineTool({
     service_id: z9.string().describe("Service publicId."),
     key: z9.string().min(1).max(128).describe("Env-var key."),
     value: z9.string().describe("New value."),
-    is_secret: z9.boolean().optional().describe("Mark as secret (encrypted, masked on read). Default true.")
+    is_secret: z9.boolean().optional().describe("Mark as secret (encrypted, masked on read). Default true."),
+    target: z9.enum(["build", "runtime", "both"]).optional().describe("Injection target: build, runtime, or both. Default both.")
   },
   handler: async (args, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1515,6 +1523,7 @@ defineTool({
     if (match) {
       const updatePayload = { value: args.value };
       if (args.is_secret !== void 0) updatePayload.isSecret = args.is_secret;
+      if (args.target !== void 0) updatePayload.target = args.target;
       const response2 = await ctx.hoststack.envVars.update(
         teamId,
         args.service_id,
@@ -1530,7 +1539,8 @@ defineTool({
     const response = await ctx.hoststack.envVars.create(teamId, args.service_id, {
       key: args.key,
       value: args.value,
-      isSecret: args.is_secret ?? true
+      isSecret: args.is_secret ?? true,
+      ...args.target !== void 0 ? { target: args.target } : {}
     });
     const data = {
       envVar: shapeEnvVar(response.envVar),
@@ -1586,7 +1596,7 @@ defineTool({
     "",
     "Inputs:",
     "  - service_id: publicId of the service.",
-    "  - env_vars: array of { key, value, is_secret? }. is_secret defaults to true per row.",
+    '  - env_vars: array of { key, value, is_secret?, target? }. is_secret defaults to FALSE per row (a row is stored in the clear unless you set is_secret:true); target defaults to "both". Note this differs from set_env_var, which defaults a newly-created var to secret.',
     "",
     "Returns: { ok: true }. Re-list with list_env_vars to confirm the new state.",
     "",
@@ -1598,7 +1608,8 @@ defineTool({
       z9.object({
         key: z9.string().min(1).max(128),
         value: z9.string(),
-        is_secret: z9.boolean().optional()
+        is_secret: z9.boolean().optional(),
+        target: z9.enum(["build", "runtime", "both"]).optional()
       })
     ).max(500).describe("Array of env-var rows. Hard cap 500.")
   },
@@ -1611,6 +1622,7 @@ defineTool({
           value: v.value
         };
         if (v.is_secret !== void 0) row.isSecret = v.is_secret;
+        if (v.target !== void 0) row.target = v.target;
         return row;
       })
     };
@@ -1632,6 +1644,10 @@ defineTool({
     "",
     "When to use: the user wants to see what envs exist before creating a service in one or promoting a deploy. Every project has at least Production.",
     "",
+    // §2.2: these are project deployment environments, not cloud Dev Boxes — point agents at the
+    // right surface so the two "dev" concepts stay distinct (bidirectional cross-reference).
+    "NOTE \u2014 these are project deployment environments (Production / Staging / Preview), NOT agentic cloud Dev Boxes. To list Dev Boxes use list_dev_environments; to create one use create_dev_environment / create_standalone_dev_environment / spin_up_dev_environment.",
+    "",
     "Inputs:",
     '  - project_id: project publicId (e.g. "prj_abc123").',
     "",
@@ -1658,10 +1674,15 @@ defineTool({
     "",
     "When to use: the user wants to add an env so they can run a sibling service alongside production for testing or staging before release.",
     "",
+    // §2.1/§2.2: steer callers away from the agentic cloud Dev Box tools (which live in
+    // services.ts) — an environment is a deployment target, NOT a Dev Box. Bidirectional with
+    // the cross-references those dev-box tools point back here.
+    'NOTE \u2014 this is NOT a cloud Dev Box. An environment is a project deployment target (Production / Staging / Preview); type="development" just gives services a -dev hostname suffix. For an agentic cloud Dev Box (a terminal you drive coding agents in) use create_dev_environment / create_standalone_dev_environment / spin_up_dev_environment instead.',
+    "",
     "Inputs:",
     "  - project_id: project publicId.",
     "  - name: human-readable name (1\u201364 chars). Shown in the env switcher.",
-    '  - type: "production" | "staging" | "development" | "preview". Determines the hostname suffix on services in this env (production stays clean; others get -staging / -dev / -preview).',
+    '  - type: "production" | "staging" | "development" | "preview". Determines the hostname suffix on services in this env (production stays clean; others get -staging / -dev / -preview). type="development" creates a PROJECT deployment environment (a -dev hostname suffix), NOT an agentic Dev Box \u2014 for a cloud dev box use create_dev_environment / create_standalone_dev_environment / spin_up_dev_environment.',
     "  - is_protected (optional): require admin role for destructive actions in this env. Default false.",
     "",
     "Returns: { environment: Environment }.",
@@ -1671,7 +1692,10 @@ defineTool({
   input: {
     project_id: z10.string().describe("Project publicId."),
     name: z10.string().min(1).max(64).describe("Environment name (1\u201364 chars)."),
-    type: z10.enum(["production", "staging", "development", "preview"]).describe("Environment type \u2014 drives the hostname suffix."),
+    type: z10.enum(["production", "staging", "development", "preview"]).describe(
+      // §2.1: "development" here is a project deployment env, NOT a cloud Dev Box.
+      'Environment type \u2014 drives the hostname suffix. type="development" creates a PROJECT deployment environment (a -dev hostname suffix), NOT an agentic Dev Box \u2014 for a cloud dev box use create_dev_environment / create_standalone_dev_environment / spin_up_dev_environment.'
+    ),
     is_protected: z10.boolean().optional().describe("Require admin role for destructive actions. Default false.")
   },
   handler: async (args, ctx) => {
@@ -1763,6 +1787,14 @@ defineTool({
 });
 
 // src/tools/meta.ts
+var DEV_ENV_TOOL_NAMES = [
+  "create_dev_environment",
+  "create_standalone_dev_environment",
+  "spin_up_dev_environment",
+  "list_dev_environments",
+  "resize_dev_environment",
+  "delete_dev_environment"
+];
 defineTool({
   name: "get_me",
   category: "meta",
@@ -1787,6 +1819,36 @@ defineTool({
     return respond({ summary: `Authenticated as ${userEmail}${teamLabel}.`, data });
   }
 });
+defineTool({
+  name: "describe_mcp",
+  category: "meta",
+  description: [
+    "Report this MCP build: its package version, total tool count, and the list of Dev Box tools it exposes. Read-only \u2014 touches no account data.",
+    "",
+    "When to use: at the start of a session to confirm the live MCP build, OR when a Dev Box tool you expect (create_dev_environment, create_standalone_dev_environment, spin_up_dev_environment, list_dev_environments, resize_dev_environment, delete_dev_environment) seems to be missing. A STALE npx/npm cache can silently present an old tool set with no other signal \u2014 call this and check `devEnvToolsPresent`; if it is false, the cached build predates the Dev Box tools and the user should refresh it (e.g. `npx --yes @hoststack.dev/mcp@latest` / clear the npx cache).",
+    "",
+    'Note on terminology: a "Dev Box" (a.k.a. Cloud Dev Box) is an agentic cloud box you code inside (create_dev_environment & friends). It is NOT a project "environment" (create_environment), which is a deployment target like Production / Staging / Preview. This tool only reports the Dev Box tool set.',
+    "",
+    "Inputs: none.",
+    "",
+    "Returns: { version, toolCount, devEnvTools: string[], devEnvToolsPresent: boolean } \u2014 version is the @hoststack.dev/mcp package version, toolCount is every registered tool, devEnvTools is the expected Dev Box tool names, and devEnvToolsPresent is true only if all of them are actually registered in this build.",
+    "",
+    'Example: describe_mcp() \u2192 { version: "0.14.0", toolCount: 30, devEnvTools: ["create_dev_environment", \u2026], devEnvToolsPresent: true }'
+  ].join("\n"),
+  input: {},
+  handler: async (_args, _ctx) => {
+    const registered = new Set(listToolDefinitions().map((t) => t.name));
+    const devEnvToolsPresent = DEV_ENV_TOOL_NAMES.every((name) => registered.has(name));
+    const data = {
+      version: MCP_VERSION,
+      toolCount: registered.size,
+      devEnvTools: [...DEV_ENV_TOOL_NAMES],
+      devEnvToolsPresent
+    };
+    const summary = devEnvToolsPresent ? `hoststack MCP v${MCP_VERSION} \u2014 ${data.toolCount} tools, all ${DEV_ENV_TOOL_NAMES.length} Dev Box tools present.` : `hoststack MCP v${MCP_VERSION} \u2014 ${data.toolCount} tools, but Dev Box tools are MISSING (stale build \u2014 refresh the npx/npm cache).`;
+    return respond({ summary, data });
+  }
+});
 
 // src/tools/notifications.ts
 import { z as z11 } from "zod";
@@ -2111,11 +2173,19 @@ var SERVICE_PLANS = [
   "pico",
   "nano",
   "micro",
-  "starter",
+  "small",
   "standard",
+  "large",
+  "xlarge",
   "pro_standard",
   "pro_large"
 ];
+var DEV_ENV_MIN_SIZE = "standard";
+function coerceDevEnvSize(value) {
+  const minIdx = SERVICE_PLANS.indexOf(DEV_ENV_MIN_SIZE);
+  const idx = value ? SERVICE_PLANS.indexOf(value) : -1;
+  return idx >= minIdx ? value : DEV_ENV_MIN_SIZE;
+}
 defineTool({
   name: "list_services",
   category: "services",
@@ -2124,11 +2194,14 @@ defineTool({
     "",
     "When to use: the agent needs to find a service by name, check what is deployed, or pick a target for a follow-up tool (logs, deploys, env vars). This is the canonical way to resolve a publicId from a human-friendly name.",
     "",
+    "Note: agentic Dev Boxes (cloud dev environments) are EXCLUDED by default. Pass dev_environment:true to include them, or use list_dev_environments for the dedicated, annotated dev-box listing.",
+    "",
     "Inputs (all optional):",
     '  - project_id: narrow to one project (numeric id or publicId "prj_\u2026").',
     '  - environment_id: narrow to one environment (numeric id or publicId "env_\u2026").',
     '  - status: "active" | "deploying" | "suspended" | "failed" | "not_deployed".',
     '  - type: "web_service" | "private_service" | "worker" | "cron_job" | "static_site".',
+    "  - dev_environment: include Dev Boxes in the results (excluded by default).",
     "",
     "Returns: { items: Service[] } \u2014 each service includes id, publicId, name, type, status, projectId, repoUrl, branch, runtime, createdAt.",
     "",
@@ -2138,11 +2211,15 @@ defineTool({
     project_id: z13.union([z13.number().int().positive(), z13.string()]).optional().describe("Project filter \u2014 numeric id or publicId."),
     environment_id: z13.union([z13.number().int().positive(), z13.string()]).optional().describe("Environment filter \u2014 numeric id or publicId."),
     status: z13.enum(["active", "deploying", "suspended", "failed", "not_deployed"]).optional().describe("Filter by current runtime status."),
-    type: z13.enum(["web_service", "private_service", "worker", "cron_job", "static_site"]).optional().describe("Filter by service type.")
+    type: z13.enum(["web_service", "private_service", "worker", "cron_job", "static_site"]).optional().describe("Filter by service type."),
+    dev_environment: z13.boolean().optional().describe(
+      "Include agentic Dev Boxes in the results (excluded by default; see list_dev_environments)."
+    )
   },
   handler: async (args, ctx) => {
     const teamId = await ctx.resolveTeamId();
     const filters = {};
+    if (args.dev_environment) filters.devEnvironment = true;
     if (args.project_id !== void 0) {
       const resolved = await ctx.hoststack.resolveId(args.project_id, {
         kind: "project",
@@ -2165,7 +2242,8 @@ defineTool({
       args.project_id !== void 0 ? `project=${args.project_id}` : null,
       args.environment_id !== void 0 ? `env=${args.environment_id}` : null,
       args.status ? `status=${args.status}` : null,
-      args.type ? `type=${args.type}` : null
+      args.type ? `type=${args.type}` : null,
+      args.dev_environment ? "devBoxes=included" : null
     ].filter(Boolean).join(", ");
     const summary = data.items.length === 0 ? filterDesc ? `No services match the given filters (${filterDesc}).` : "No services yet \u2014 create one with create_service (or create_dev_environment for an AI dev box), or via the dashboard." : `Found ${data.items.length} service${data.items.length === 1 ? "" : "s"}${filterDesc ? ` matching ${filterDesc}` : ""}.`;
     return respond({ summary, data });
@@ -2256,14 +2334,16 @@ defineTool({
   name: "create_dev_environment",
   category: "services",
   description: [
-    "Spin up an AI dev environment in one call: a private service from the agentic dev-env image (Claude Code + Codex + OpenCode + MCPs preinstalled), with a persistent /workspace volume and the MCP API keys set, then fire the first deploy.",
+    'Spin up an AI Dev Box in one call: a cloud "Dev Box" (an agentic container from the dev-env image \u2014 Claude Code + Codex + OpenCode + MCPs preinstalled) inside a project, with a persistent /workspace volume and the MCP API keys set, then fire the first deploy.',
+    "",
+    'This makes a cloud Dev Box, NOT a project deploy environment. A project "environment" (create_environment \u2192 Production / Staging / Preview) is a deployment target; this is a workspace you code in. If you actually want a -dev deploy target, use create_environment instead.',
     "",
-    `When to use: the user wants a cloud terminal / dev box they can drive coding agents in (from a desk or a phone). This mirrors the dashboard's "AI Dev Environment" wizard preset \u2014 create (deploy deferred) \u2192 set keys \u2192 attach /workspace \u2192 deploy, so the first container boots with its volume and keys already in place.`,
+    `When to use: the user wants a cloud terminal / Dev Box they can drive coding agents in (from a desk or a phone). This mirrors the dashboard's "AI Dev Environment" wizard preset \u2014 create (deploy deferred) \u2192 set keys \u2192 attach /workspace \u2192 deploy, so the first container boots with its volume and keys already in place.`,
     "",
     "Inputs:",
     '  - project_id: numeric id or publicId ("prj_\u2026") of the target project.',
     '  - name (optional): service name (default "dev-environment").',
-    '  - plan (optional): service size (default "standard" \u2014 2 GB, the smallest that fits a coding agent + build).',
+    '  - plan (optional): box size. Defaults to "standard" (2 GB) \u2014 the OOM-safe floor (DEV_ENV_MIN_SIZE); a coding agent + build OOMs below it. A smaller plan is clamped up to "standard".',
     "  - disk_gb (optional): /workspace volume size in GB (default 10, 1\u2013100).",
     "  - hoststack_api_key (optional): sets HOSTSTACK_API_KEY so the hoststack MCP works inside the container.",
     "  - poststack_api_key (optional): sets POSTSTACK_API_KEY so the poststack MCP works inside the container.",
@@ -2277,7 +2357,7 @@ defineTool({
     project_id: z13.union([z13.number().int().positive(), z13.string()]).describe("Target project \u2014 numeric id or publicId."),
     name: z13.string().min(1).max(100).optional().describe('Service name (default "dev-environment").'),
     plan: z13.enum(SERVICE_PLANS).optional().describe(
-      'Service size (default "standard" \u2014 2 GB; smallest that fits a coding agent).'
+      'Box size (default "standard" \u2014 2 GB, the OOM-safe floor; a smaller plan is clamped up to "standard").'
     ),
     disk_gb: z13.number().int().min(1).max(100).optional().describe("/workspace volume size in GB (default 10)."),
     hoststack_api_key: z13.string().optional().describe("Value for HOSTSTACK_API_KEY (enables the hoststack MCP in-container)."),
@@ -2295,68 +2375,94 @@ defineTool({
     });
     const name = args.name ?? "dev-environment";
     const sizeGb = args.disk_gb ?? DEV_ENV_VOLUME.sizeGb;
+    const plan = coerceDevEnvSize(args.plan);
     const createInput = {
       name,
       type: "private_service",
       projectId,
       dockerImage: DEV_ENV_IMAGE,
-      autoDeploy: false
+      autoDeploy: false,
+      plan
     };
-    if (args.plan !== void 0) createInput.plan = args.plan;
     const created = await ctx.hoststack.services.create(teamId, createInput);
     const service = created.service;
-    const envVars = [];
-    if (args.hoststack_api_key)
-      envVars.push({
-        key: "HOSTSTACK_API_KEY",
-        value: args.hoststack_api_key,
-        isSecret: true
-      });
-    if (args.poststack_api_key)
-      envVars.push({
-        key: "POSTSTACK_API_KEY",
-        value: args.poststack_api_key,
-        isSecret: true
-      });
-    if (args.repo_url) {
-      envVars.push({
-        key: "HOSTSTACK_DEVENV_REPO_URL",
-        value: args.repo_url,
-        isSecret: false
-      });
-      if (args.branch)
+    const rollback = async () => {
+      try {
+        await ctx.hoststack.services.tearDownDevEnvironment(teamId, service.id);
+      } catch {
+        try {
+          await ctx.hoststack.services.delete(teamId, service.id);
+        } catch {
+        }
+      }
+    };
+    try {
+      const envVars = [];
+      if (args.hoststack_api_key)
         envVars.push({
-          key: "HOSTSTACK_DEVENV_BRANCH",
-          value: args.branch,
+          key: "HOSTSTACK_API_KEY",
+          value: args.hoststack_api_key,
+          isSecret: true
+        });
+      if (args.poststack_api_key)
+        envVars.push({
+          key: "POSTSTACK_API_KEY",
+          value: args.poststack_api_key,
+          isSecret: true
+        });
+      if (args.repo_url) {
+        envVars.push({
+          key: "HOSTSTACK_DEVENV_REPO_URL",
+          value: args.repo_url,
           isSecret: false
         });
-    }
-    if (envVars.length > 0) {
-      await ctx.hoststack.envVars.bulkSet(teamId, service.id, { vars: envVars });
-    }
-    let volumeAttached = false;
-    try {
-      await ctx.hoststack.volumes.create(teamId, service.id, {
-        name: DEV_ENV_VOLUME.name,
-        mountPath: DEV_ENV_VOLUME.mountPath,
-        sizeGb
+        if (args.branch)
+          envVars.push({
+            key: "HOSTSTACK_DEVENV_BRANCH",
+            value: args.branch,
+            isSecret: false
+          });
+      }
+      if (envVars.length > 0) {
+        await ctx.hoststack.envVars.bulkSet(teamId, service.id, { vars: envVars });
+      }
+      try {
+        await ctx.hoststack.volumes.create(teamId, service.id, {
+          name: DEV_ENV_VOLUME.name,
+          mountPath: DEV_ENV_VOLUME.mountPath,
+          sizeGb
+        });
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        await rollback();
+        return respondError(
+          `Failed to attach the /workspace volume for Dev Box "${name}" \u2014 aborted and rolled back rather than deploy a box that would lose all work on recreate. Volume error: ${reason}`,
+          { volumeError: reason, rolledBack: true }
+        );
+      }
+      const deploy = await ctx.hoststack.deploys.trigger(teamId, service.id);
+      const deployId = deploy.deploy?.id ?? null;
+      return respond({
+        summary: `Created AI Dev Box "${name}" (${service.publicId}) with a /workspace volume \u2014 deploying. Open it in the dashboard's Dev Boxes section (or the service's Terminal tab) once running.`,
+        data: { service: shapeService(service), volumeAttached: true, deployId }
       });
-      volumeAttached = true;
-    } catch {
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      await rollback();
+      return respondError(
+        `Failed to provision Dev Box "${name}" \u2014 rolled back the partially-created box. Error: ${reason}`,
+        { rolledBack: true }
+      );
     }
-    const deploy = await ctx.hoststack.deploys.trigger(teamId, service.id);
-    const deployId = deploy.deploy?.id ?? null;
-    return respond({
-      summary: `Created AI dev environment "${name}" (${service.publicId})${volumeAttached ? " with a /workspace volume" : ""} \u2014 deploying. Open it in the dashboard's Development section (or the service's Terminal tab) once running.`,
-      data: { service: shapeService(service), volumeAttached, deployId }
-    });
   }
 });
 defineTool({
   name: "spin_up_dev_environment",
   category: "services",
   description: [
-    "Spin up an agentic dev environment FROM an existing service so you can reproduce a bug, fix it, view it, and ship it. Creates a dev box (Claude/Codex/OpenCode + MCPs) that RUNS a clone of the app: the repo is auto-cloned into /workspace, the service env-vars are copied, and its linked database is cloned (so the box never touches the prod DB). The box gets an unguessable public dev URL and seamless `git push`.",
+    "Spin up an agentic Dev Box FROM an existing service so you can reproduce a bug, fix it, view it, and ship it. Creates a cloud Dev Box (Claude/Codex/OpenCode + MCPs) that RUNS a clone of the app: the repo is auto-cloned into /workspace, the service env-vars are copied, and its linked database is cloned (so the box never touches the prod DB). The box gets an unguessable public dev URL and seamless `git push`.",
+    "",
+    "This makes a cloud Dev Box, NOT a project deploy environment \u2014 for a -dev/-staging deploy target use create_environment instead.",
     "",
     'When to use: "spin up a dev environment for <service>", "I found a bug on <service>, give me a box to fix it". Distinct from create_dev_environment, which makes a BARE box not tied to any app.',
     "",
@@ -2399,7 +2505,9 @@ defineTool({
   name: "delete_dev_environment",
   category: "services",
   description: [
-    "Tear down an agentic dev environment in one call: removes the dev box AND cascade-deletes its cloned database, its /workspace volume, and the auto-created `development` environment if it is now empty.",
+    "Tear down an agentic Dev Box in one call: removes the cloud Dev Box AND cascade-deletes its cloned database, its /workspace volume, and the auto-created `development` environment if it is now empty.",
+    "",
+    "This deletes a cloud Dev Box, NOT a project deploy environment \u2014 to remove a -dev/-staging deploy target use delete_environment instead.",
     "",
     'When to use: "delete / tear down the dev environment", once you have shipped the fix and no longer need the box.',
     "",
@@ -2430,15 +2538,17 @@ defineTool({
   name: "resize_dev_environment",
   category: "services",
   description: [
-    "Resize a dev box (or any service) to a different size tier \u2014 the supported way to give it more memory/CPU/disk headroom (e.g. when ESLint/tsc OOMs).",
+    "Resize a cloud Dev Box (or any service) to a different size tier \u2014 the supported way to give it more memory/CPU/disk headroom (e.g. when ESLint/tsc OOMs).",
     "",
-    "When to use: a dev box OOM-killed (see exitReason/recommendedSize from list_dev_environments), or you just want more headroom. This changes the SIZE TIER \u2014 unlike per-config memory/CPU overrides, which are clamped to the current tier and so cannot grow a box past it.",
+    "This resizes a cloud Dev Box, NOT a project deploy environment.",
+    "",
+    "When to use: a Dev Box OOM-killed (see exitReason/recommendedSize from list_dev_environments), or you just want more headroom. This changes the SIZE TIER \u2014 unlike per-config memory/CPU overrides, which are clamped to the current tier and so cannot grow a box past it.",
     "",
     "How it applies: the new tier's memory + CPU take effect LIVE on the running container (no recreate, no dropped shell sessions); a larger disk takes effect on the next recreate (suspend\u2192resume). Dev boxes are floored to the OOM-safe minimum size server-side.",
     "",
     "Inputs:",
     "  - service_id: the box to resize \u2014 numeric id or publicId.",
-    '  - size: target tier (e.g. "standard", "large", "xlarge").',
+    '  - size: target tier \u2014 one of the service catalog sizes (e.g. "standard", "large", "xlarge").',
     "",
     "Returns: { service } with the new plan.",
     "",
@@ -2446,7 +2556,9 @@ defineTool({
   ].join("\n"),
   input: {
     service_id: z13.union([z13.number().int().positive(), z13.string()]).describe("The box to resize \u2014 numeric id or publicId."),
-    size: z13.string().min(1).describe('Target size tier, e.g. "standard", "large", "xlarge".')
+    size: z13.enum(SERVICE_PLANS).describe(
+      'Target size tier (service catalog size, e.g. "standard", "large", "xlarge").'
+    )
   },
   handler: async (args, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -2465,7 +2577,9 @@ defineTool({
   name: "list_dev_environments",
   category: "services",
   description: [
-    `List the team's dev environments (the dashboard "Development" section), each annotated with the companion services attached to it.`,
+    `List the team's cloud Dev Boxes (the dashboard "Dev Boxes" / Development section), each annotated with the companion services attached to it.`,
+    "",
+    "These are cloud Dev Boxes, NOT project deploy environments \u2014 to list a project's deploy targets (Production / Staging / Preview) use list_environments instead.",
     "",
     `When to use: "show my dev environments", before opening/tearing one down, to find a box's id.`,
     "",
@@ -2492,22 +2606,60 @@ defineTool({
     });
   }
 });
+defineTool({
+  name: "list_templates",
+  category: "services",
+  description: [
+    "List the canonical Dev Box (AI dev environment) preset so an agent can see, without guessing, what a `create_standalone_dev_environment` / `create_dev_environment` actually provisions: the container image, the persistent /workspace volume (mount + default size), the OOM-safe size floor, and the companion database options.",
+    "",
+    "When to use: before creating a Dev Box, to confirm the image, the default /workspace size, the minimum plan, or which companion engines can be attached \u2014 instead of hand-duplicating those constants.",
+    "",
+    'Returns: { templates: [{ id, name, image, volume: { name, mountPath, sizeGb }, minPlan, companions }] }. Today there is one preset ("dev-environment").',
+    "",
+    'Example: list_templates() \u2192 { templates: [{ id: "dev-environment", image: "hoststack/dev-env:latest", volume: { mountPath: "/workspace", sizeGb: 10 }, minPlan: "standard", companions: ["postgres","redis","meilisearch"] }] }'
+  ].join("\n"),
+  input: {},
+  handler: async () => {
+    const templates = [
+      {
+        id: "dev-environment",
+        name: "AI Dev Environment",
+        image: DEV_ENV_IMAGE,
+        volume: {
+          name: DEV_ENV_VOLUME.name,
+          mountPath: DEV_ENV_VOLUME.mountPath,
+          sizeGb: DEV_ENV_VOLUME.sizeGb
+        },
+        /** OOM-safe plan floor — a coding agent + build needs at least this. */
+        minPlan: DEV_ENV_MIN_SIZE,
+        /** Companion engines you can attach (fresh + empty), like local `make db-up`. */
+        companions: ["postgres", "redis", "meilisearch"]
+      }
+    ];
+    return respond({
+      summary: `${templates.length} Dev Box template${templates.length === 1 ? "" : "s"} available (image ${DEV_ENV_IMAGE}, /workspace ${DEV_ENV_VOLUME.sizeGb} GB, floor "${DEV_ENV_MIN_SIZE}").`,
+      data: { templates }
+    });
+  }
+});
 defineTool({
   name: "create_standalone_dev_environment",
   category: "services",
   description: [
-    "Create a STANDALONE dev environment in one call: a cloud box (Claude Code + Codex + OpenCode + MCPs) on a persistent /workspace, from a connected GitHub repo, an arbitrary clone URL, or blank \u2014 with optional companion Postgres / Redis / Meilisearch wired into its env (mirrors a local `make db-up`). The box lives in the team's hidden Development home, NOT under a project.",
+    "Create a STANDALONE Dev Box in one call: a cloud box (Claude Code + Codex + OpenCode + MCPs) on a persistent /workspace, from a connected GitHub repo, an arbitrary clone URL, or blank \u2014 with optional companion Postgres / Redis / Meilisearch wired into its env (mirrors a local `make db-up`). The box lives in the team's hidden Development home, NOT under a project.",
+    "",
+    "This makes a cloud Dev Box, NOT a project deploy environment (create_environment \u2192 Production / Staging / Preview). It is a workspace you code in, not a deployment target.",
     "",
     'When to use: "create a dev environment for <repo>", "spin me up a cloud dev box with a Postgres". Distinct from spin_up_dev_environment (which clones an EXISTING service) and create_dev_environment (a bare box in a chosen project).',
     "",
     "Inputs:",
-    "  - name: the dev box name.",
+    "  - name: the Dev Box name.",
     '  - source_kind: "github_repo" (clone a connected repo \u2014 needs github_repo_id), "url" (clone any http(s) git URL \u2014 needs clone_url), or "blank" (empty box).',
     "  - github_repo_id (for github_repo): numeric id of a connected GitHub repo.",
     "  - clone_url (for url): an http(s) git clone URL.",
     "  - branch (optional): branch to clone.",
     '  - databases (optional): companion services to attach \u2014 any of "postgres", "redis", "meilisearch".',
-    '  - plan (optional): box size (default "micro").',
+    '  - plan (optional): box size. Defaults to "standard" (2 GB) \u2014 the OOM-safe floor (DEV_ENV_MIN_SIZE); a smaller plan is floored up to "standard" server-side.',
     "  - agent_accounts (optional): bind specific saved agent logins by account id per provider. OMIT to auto-inherit the box owner's default logins (claude/codex/opencode), so `claude` is already authenticated on first boot \u2014 no manual login.",
     "",
     "Returns: { service, devUrl, deployId } \u2014 deploying. Once live: open the Terminal tab, run `claude`, start the dev server on $PORT, view at https://<devUrl>. Tear down with delete_dev_environment.",
@@ -2515,13 +2667,15 @@ defineTool({
     'Example: create_standalone_dev_environment({ name: "app-dev", source_kind: "github_repo", github_repo_id: 42, databases: ["postgres","redis"] })'
   ].join("\n"),
   input: {
-    name: z13.string().min(1).max(100).describe("Dev box name."),
+    name: z13.string().min(1).max(100).describe("Dev Box name."),
     source_kind: z13.enum(["github_repo", "url", "blank"]).describe("Where the code comes from."),
     github_repo_id: z13.number().int().positive().optional().describe('Connected GitHub repo id (required when source_kind="github_repo").'),
     clone_url: z13.string().url().optional().describe('http(s) git clone URL (required when source_kind="url").'),
     branch: z13.string().min(1).max(255).optional().describe("Branch to clone."),
     databases: z13.array(z13.enum(["postgres", "redis", "meilisearch"])).optional().describe("Companion services to attach (fresh + empty)."),
-    plan: z13.enum(SERVICE_PLANS).optional().describe('Box size (default "micro").'),
+    plan: z13.enum(SERVICE_PLANS).optional().describe(
+      'Box size (default "standard" \u2014 2 GB; a smaller plan is floored to "standard").'
+    ),
     agent_accounts: z13.array(
       z13.object({
         provider: z13.enum(["claude", "codex", "opencode"]),
@@ -3191,7 +3345,7 @@ defineTool({
 
 // src/server-factory.ts
 var PACKAGE_NAME = "hoststack";
-var PACKAGE_VERSION = "0.9.1";
+var PACKAGE_VERSION = MCP_VERSION;
 function createMcpServer(options) {
   const baseUrl = (options.baseUrl ?? "https://hoststack.dev").replace(/\/$/, "");
   const hoststack = new HostStack({ apiKey: options.apiKey, baseUrl });