@hoststack.dev/mcp 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -83,7 +83,7 @@ interface CreateServerOptions {
     onToolCall?: ToolCallSink;
 }
 declare const PACKAGE_NAME = "hoststack";
-declare const PACKAGE_VERSION = "0.6.0";
+declare const PACKAGE_VERSION = "0.9.1";
 /**
  * Build a fully-wired MCP server. Used by both the stdio CLI entry-point and
  * the HTTP transport mounted by the API server. A new server (and its

package/dist/index.js

@@ -838,13 +838,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".',
     "",
@@ -852,12 +853,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 (args, ctx) => {
     const teamId = await ctx.resolveTeamId();
     const input = {};
-    if (args.clear_cache !== void 0) input.clearCache = args.clear_cache;
+    if (args.commit_hash !== void 0) input.commitHash = args.commit_hash;
+    if (args.branch !== void 0) input.branch = args.branch;
     const response = await ctx.hoststack.deploys.trigger(teamId, args.service_id, input);
     const data = { deploy: shapeDeploy(response.deploy) };
     const publicId = data.deploy && "publicId" in data.deploy ? data.deploy.publicId : "unknown";
@@ -900,7 +903,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.",
     "",
@@ -1155,20 +1158,23 @@ defineTool({
     "",
     "Inputs:",
     '  - type: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS" | "SRV" | "CAA" | "ALIAS".',
-    '  - name: "@" for the zone apex, or a subdomain label ("www", "api", "_acme-challenge").',
-    "  - content: the literal record value. For TXT pass the unquoted string \u2014 the PowerDNS layer handles quoting.",
+    '  - name: "@" for the zone apex, or a subdomain label ("www", "api", "_acme-challenge"). Do NOT include the zone suffix \u2014 the backend prepends it. "bounce" on zone "micci.dk" publishes "bounce.micci.dk"; passing "bounce.micci.dk" works (the backend strips the suffix) but is non-idiomatic.',
+    "  - content: the literal record value. For TXT pass the unquoted string \u2014 the PowerDNS layer handles quoting. For CNAME / MX / NS / SRV / ALIAS the target may be passed with or without a trailing dot; the adapter FQDN-izes it.",
     "  - ttl (optional): 60\u201386400 seconds, default 3600.",
     "  - priority (optional, required for MX and SRV): 0\u201365535.",
     "",
     "Returns: { record: Record } \u2014 see get_dns_record for the shape.",
     "",
+    "Notes:",
+    '  - CNAME at the apex is rejected (RFC 1034 forbids CNAME coexisting with NS/SOA). Use type="ALIAS" for apex aliasing.',
+    "",
     'Example: create_dns_record({ domain: "micci.dk", type: "TXT", name: "@", content: "google-site-verification=C0V0scK48g2\u2026", ttl: 300 })'
   ].join("\n"),
   input: {
     zone_id: z7.string().optional().describe("Zone publicId."),
     domain: z7.string().optional().describe("Apex or subdomain to resolve a hosted zone."),
     type: z7.enum(DNS_RECORD_TYPES).describe("DNS record type."),
-    name: z7.string().min(1).max(253).describe('"@" for apex, or label (no trailing dot).'),
+    name: z7.string().min(1).max(253).describe('"@" for apex, or a bare label. Do NOT include the zone suffix.'),
     content: z7.string().min(1).max(2e3).describe("Record value; TXT values are unquoted."),
     ttl: z7.number().int().min(60).max(86400).optional().describe("TTL in seconds (default 3600)."),
     priority: z7.number().int().min(0).max(65535).optional().describe("Required for MX / SRV.")
@@ -1222,7 +1228,7 @@ defineTool({
   input: {
     record_id: z7.string().describe("Record publicId."),
     type: z7.enum(DNS_RECORD_TYPES).describe("DNS record type."),
-    name: z7.string().min(1).max(253).describe('"@" for apex, or label.'),
+    name: z7.string().min(1).max(253).describe('"@" for apex, or a bare label. Do NOT include the zone suffix.'),
     content: z7.string().min(1).max(2e3).describe("Record value; TXT unquoted."),
     ttl: z7.number().int().min(60).max(86400).optional().describe("TTL in seconds (default 3600)."),
     priority: z7.number().int().min(0).max(65535).optional().describe("Required for MX / SRV.")
@@ -1341,7 +1347,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).",
     "",
@@ -1349,12 +1356,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 (args, ctx) => {
     const teamId = await ctx.resolveTeamId();
-    const input = { domain: args.hostname };
-    if (args.service_id !== void 0) input.serviceId = args.service_id;
+    const input = {
+      domain: args.hostname,
+      serviceId: args.service_id
+    };
+    if (args.path_prefix !== void 0) input.pathPrefix = args.path_prefix;
     const response = await ctx.hoststack.domains.add(teamId, input);
     const data = { domain: shapeDomain(response.domain) };
     return respond({
@@ -1455,7 +1466,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" }.',
     "",
@@ -1469,18 +1480,16 @@ defineTool({
   },
   handler: async (args, ctx) => {
     const teamId = await ctx.resolveTeamId();
-    const isSecret = args.is_secret ?? true;
     const existing = await ctx.hoststack.envVars.list(teamId, args.service_id);
     const match = existing.envVars.find((v) => v.key === args.key);
     if (match) {
+      const updatePayload = { value: args.value };
+      if (args.is_secret !== void 0) updatePayload.isSecret = args.is_secret;
       const response2 = await ctx.hoststack.envVars.update(
         teamId,
         args.service_id,
         String(match.id),
-        {
-          value: args.value,
-          isSecret
-        }
+        updatePayload
       );
       const data2 = {
         envVar: shapeEnvVar(response2.envVar),
@@ -1491,7 +1500,7 @@ defineTool({
     const response = await ctx.hoststack.envVars.create(teamId, args.service_id, {
       key: args.key,
       value: args.value,
-      isSecret
+      isSecret: args.is_secret ?? true
     });
     const data = {
       envVar: shapeEnvVar(response.envVar),
@@ -1627,7 +1636,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."),
@@ -1664,7 +1673,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."),
@@ -1696,7 +1705,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."),
@@ -2056,6 +2065,24 @@ defineTool({
 
 // src/tools/services.ts
 import { z as z13 } from "zod";
+var DEV_ENV_IMAGE = "hoststack/dev-env:claude";
+var DEV_ENV_VOLUME = { name: "workspace", mountPath: "/workspace", sizeGb: 10 };
+var SERVICE_TYPES = [
+  "web_service",
+  "private_service",
+  "worker",
+  "cron_job",
+  "static_site"
+];
+var SERVICE_PLANS = [
+  "pico",
+  "nano",
+  "micro",
+  "starter",
+  "standard",
+  "pro_standard",
+  "pro_large"
+];
 defineTool({
   name: "list_services",
   category: "services",
@@ -2107,10 +2134,171 @@ defineTool({
       args.status ? `status=${args.status}` : null,
       args.type ? `type=${args.type}` : 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 via the dashboard." : `Found ${data.items.length} service${data.items.length === 1 ? "" : "s"}${filterDesc ? ` matching ${filterDesc}` : ""}.`;
+    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 });
   }
 });
+defineTool({
+  name: "create_service",
+  category: "services",
+  description: [
+    "Create a new service in a project. Source is either a connected git repo (github_repo_id) OR a pre-built docker_image \u2014 never both.",
+    "",
+    "When to use: the user wants to deploy something new. For a one-command AI dev environment specifically, prefer create_dev_environment (it also attaches the /workspace volume and sets the MCP keys).",
+    "",
+    "Inputs:",
+    '  - project_id: numeric id or publicId ("prj_\u2026") of the target project.',
+    "  - name: service name (1\u2013100 chars).",
+    '  - type: "web_service" | "private_service" | "worker" | "cron_job" | "static_site".',
+    "  - docker_image (optional): pre-built image ref to deploy instead of building from source.",
+    "  - github_repo_id (optional): connect a previously-linked GitHub repo by numeric id.",
+    '  - branch (optional): git branch (default "main").',
+    "  - install_command / build_command / start_command (optional): build/run shell commands. start_command is required for web/private services without a docker_image.",
+    "  - cron_schedule (optional): cron expression \u2014 required for cron_job.",
+    '  - publish_path (optional): static-site output dir (e.g. "dist").',
+    '  - runtime (optional): "node" | "bun" | "python" | \u2026 (auto-detected from a repo when omitted).',
+    '  - plan (optional): service size (default "micro").',
+    "  - environment_id (optional): bind to a specific environment; defaults to the project Production env.",
+    "  - auto_deploy (optional, default true): trigger the first deploy immediately when a source is present.",
+    "",
+    "Returns: { service: Service, deployId: number | null }.",
+    "",
+    'Example: create_service({ project_id: "prj_abc", name: "api", type: "web_service", github_repo_id: 42 }) \u2192 { service: { publicId: "svc_\u2026" }, deployId: 1234 }'
+  ].join("\n"),
+  input: {
+    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).describe("Service name (1\u2013100 chars)."),
+    type: z13.enum(SERVICE_TYPES).describe("Service type."),
+    docker_image: z13.string().max(500).optional().describe("Pre-built image ref. Mutually exclusive with github_repo_id."),
+    github_repo_id: z13.number().int().positive().optional().describe("Linked GitHub repo numeric id. Mutually exclusive with docker_image."),
+    branch: z13.string().max(200).optional().describe('Git branch (default "main").'),
+    install_command: z13.string().max(1e3).optional().describe("Install shell command."),
+    build_command: z13.string().max(1e3).optional().describe("Build shell command."),
+    start_command: z13.string().max(1e3).optional().describe("Start shell command (required for web/private services without an image)."),
+    cron_schedule: z13.string().max(100).optional().describe("Cron expression \u2014 required for cron_job."),
+    publish_path: z13.string().max(500).optional().describe("Static-site output dir."),
+    runtime: z13.string().max(50).optional().describe("Runtime hint (node/bun/python/\u2026)."),
+    plan: z13.enum(SERVICE_PLANS).optional().describe('Service size (default "micro").'),
+    environment_id: z13.union([z13.number().int().positive(), z13.string()]).optional().describe("Bind to a specific environment; defaults to Production."),
+    auto_deploy: z13.boolean().optional().describe("Trigger the first deploy immediately (default true).")
+  },
+  handler: async (args, ctx) => {
+    const teamId = await ctx.resolveTeamId();
+    const projectId = await ctx.hoststack.resolveId(args.project_id, {
+      kind: "project",
+      teamId
+    });
+    const input = {
+      name: args.name,
+      type: args.type,
+      projectId
+    };
+    if (args.docker_image !== void 0) input.dockerImage = args.docker_image;
+    if (args.github_repo_id !== void 0) input.githubRepoId = args.github_repo_id;
+    if (args.branch !== void 0) input.branch = args.branch;
+    if (args.install_command !== void 0) input.installCommand = args.install_command;
+    if (args.build_command !== void 0) input.buildCommand = args.build_command;
+    if (args.start_command !== void 0) input.startCommand = args.start_command;
+    if (args.cron_schedule !== void 0) input.cronSchedule = args.cron_schedule;
+    if (args.publish_path !== void 0) input.publishPath = args.publish_path;
+    if (args.runtime !== void 0) input.runtime = args.runtime;
+    if (args.plan !== void 0) input.plan = args.plan;
+    if (args.auto_deploy !== void 0) input.autoDeploy = args.auto_deploy;
+    if (args.environment_id !== void 0) {
+      input.environmentId = await ctx.hoststack.resolveId(args.environment_id, {
+        kind: "environment",
+        teamId
+      });
+    }
+    const response = await ctx.hoststack.services.create(teamId, input);
+    const data = {
+      service: shapeService(response.service),
+      deployId: response.deployId ?? null
+    };
+    const publicId = data.service && "publicId" in data.service ? data.service.publicId : "unknown";
+    return respond({ summary: `Created service "${args.name}" (${publicId}).`, data });
+  }
+});
+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.",
+    "",
+    `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 "micro").',
+    "  - 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.",
+    "",
+    "Returns: { service: Service, volumeAttached: boolean, deployId: number | null }. Open the Terminal tab on the service (dashboard or phone) once it is running; log in once with `claude /login` inside the container.",
+    "",
+    'Example: create_dev_environment({ project_id: "prj_abc", name: "scratch", hoststack_api_key: "hs_live_\u2026" })'
+  ].join("\n"),
+  input: {
+    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 "micro").'),
+    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)."),
+    poststack_api_key: z13.string().optional().describe("Value for POSTSTACK_API_KEY (enables the poststack MCP in-container).")
+  },
+  handler: async (args, ctx) => {
+    const teamId = await ctx.resolveTeamId();
+    const projectId = await ctx.hoststack.resolveId(args.project_id, {
+      kind: "project",
+      teamId
+    });
+    const name = args.name ?? "dev-environment";
+    const sizeGb = args.disk_gb ?? DEV_ENV_VOLUME.sizeGb;
+    const createInput = {
+      name,
+      type: "private_service",
+      projectId,
+      dockerImage: DEV_ENV_IMAGE,
+      autoDeploy: false
+    };
+    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 (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
+      });
+      volumeAttached = true;
+    } catch {
+    }
+    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 its Terminal tab once running.`,
+      data: { service: shapeService(service), volumeAttached, deployId }
+    });
+  }
+});
 defineTool({
   name: "get_service",
   category: "services",
@@ -2718,7 +2906,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 baseUrl = (options.baseUrl ?? "https://hoststack.dev").replace(/\/$/, "");
   const hoststack = new HostStack({ apiKey: options.apiKey, baseUrl });