@hoststack.dev/mcp 0.3.0 → 0.4.0

package/README.md

@@ -79,7 +79,7 @@ If `HOSTSTACK_API_KEY` is set in your shell, it gets baked into the snippet; oth
 
 ## Tool inventory
 
-31 tools, grouped by resource:
+35 tools, grouped by resource:
 
 | Category | Read | Write |
 |---|---|---|
@@ -89,6 +89,7 @@ If `HOSTSTACK_API_KEY` is set in your shell, it gets baked into the snippet; oth
 | **databases** | `list_databases`, `get_database` | — (use the dashboard for create/delete/credentials) |
 | **domains** | `list_domains` | `add_domain`, `verify_domain`, `remove_domain` |
 | **env-vars** | `list_env_vars` | `set_env_var`, `delete_env_var`, `bulk_set_env_vars` |
+| **environments** | `list_environments` | `create_environment`, `delete_environment`, `promote_deploy` |
 | **cron** | `list_cron_executions`, `get_cron_execution` | — |
 | **activity-log** | `list_activity_log` | — |
 | **meta** | `get_me` | — |

package/dist/hoststack-mcp.js

@@ -992,6 +992,146 @@ defineTool({
   }
 });
 
+// src/tools/environments.ts
+import { z as z8 } from "zod";
+defineTool({
+  name: "list_environments",
+  category: "environments",
+  description: [
+    "List every environment for a project (production / staging / development / preview).",
+    "",
+    "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.",
+    "",
+    "Inputs:",
+    '  - project_id: project publicId (e.g. "prj_abc123").',
+    "",
+    "Returns: { items: Environment[] } \u2014 id, publicId, name, type, isDefault, isProtected.",
+    "",
+    'Example: list_environments({ project_id: "prj_abc" }) \u2192 { items: [{ name: "Production", type: "production", isDefault: true }, { name: "Staging", type: "staging" }] }'
+  ].join("\n"),
+  input: {
+    project_id: z8.string().describe("Project publicId.")
+  },
+  handler: async (args2, ctx) => {
+    const teamId = await ctx.resolveTeamId();
+    const response = await ctx.hoststack.environments.list(teamId, args2.project_id);
+    const data = shapeList(response, "environments", shape);
+    const summary = data.items.length === 0 ? "No environments yet \u2014 every project should have Production by default." : `Found ${data.items.length} environment${data.items.length === 1 ? "" : "s"}.`;
+    return respond({ summary, data });
+  }
+});
+defineTool({
+  name: "create_environment",
+  category: "environments",
+  description: [
+    "Create a new environment in a project (e.g. Staging, QA, Preview).",
+    "",
+    "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.",
+    "",
+    "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).',
+    "  - is_protected (optional): require admin role for destructive actions in this env. Default false.",
+    "",
+    "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" } }'
+  ].join("\n"),
+  input: {
+    project_id: z8.string().describe("Project publicId."),
+    name: z8.string().min(1).max(64).describe("Environment name (1\u201364 chars)."),
+    type: z8.enum(["production", "staging", "development", "preview"]).describe("Environment type \u2014 drives the hostname suffix."),
+    is_protected: z8.boolean().optional().describe("Require admin role for destructive actions. Default false.")
+  },
+  handler: async (args2, ctx) => {
+    const teamId = await ctx.resolveTeamId();
+    const input = {
+      name: args2.name,
+      type: args2.type
+    };
+    if (args2.is_protected !== void 0) input.isProtected = args2.is_protected;
+    const response = await ctx.hoststack.environments.create(teamId, args2.project_id, input);
+    const data = { environment: shape(response.environment) };
+    return respond({
+      summary: `Created environment "${args2.name}" (${args2.type}) in project ${args2.project_id}.`,
+      data
+    });
+  }
+});
+defineTool({
+  name: "delete_environment",
+  category: "environments",
+  description: [
+    "Delete an environment from a project.",
+    "",
+    "When to use: an env is no longer used (e.g. tearing down a feature branch staging). Blocked when the env still has live services or databases attached \u2014 destroy or move them first. The default env (usually Production) cannot be deleted.",
+    "",
+    "Inputs:",
+    "  - project_id: project publicId.",
+    "  - environment_id: environment publicId or numeric id.",
+    "",
+    "Returns: { success: true } on success.",
+    "",
+    'Example: delete_environment({ project_id: "prj_abc", environment_id: "environment_xyz" }) \u2192 { success: true }'
+  ].join("\n"),
+  input: {
+    project_id: z8.string().describe("Project publicId."),
+    environment_id: z8.union([z8.string(), z8.number()]).describe("Environment publicId or numeric id.")
+  },
+  handler: async (args2, ctx) => {
+    const teamId = await ctx.resolveTeamId();
+    await ctx.hoststack.environments.delete(teamId, args2.project_id, args2.environment_id);
+    return respond({
+      summary: `Deleted environment ${String(args2.environment_id)} from project ${args2.project_id}.`,
+      data: { success: true }
+    });
+  }
+});
+defineTool({
+  name: "promote_deploy",
+  category: "environments",
+  description: [
+    "Promote a built deploy from one environment to another (build-once, run-many).",
+    "",
+    "When to use: the user has tested a deploy in staging and wants to ship that exact image to production without rebuilding. Atomic and image-based \u2014 same docker image runs on the sibling service in the target env.",
+    "",
+    "Inputs:",
+    "  - service_id: source service publicId (the one that owns the deploy).",
+    "  - deploy_id: source deploy publicId. Must have `dockerImageId` set (i.e. a successful build).",
+    "  - target_environment_id: env publicId or numeric id to promote into. Must be in the same project. Cannot be the source service's own env.",
+    "",
+    "Behaviour: if a sibling service with the same name already exists in the target env, the new deploy lands on it. Otherwise the API auto-clones the source service's build/runtime config into the target env first. Env-specific config (env vars, secret files, volumes, IP allowlists, custom domains) is NOT copied \u2014 those are per-env by design.",
+    "",
+    "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" } }'
+  ].join("\n"),
+  input: {
+    service_id: z8.string().describe("Source service publicId."),
+    deploy_id: z8.string().describe("Source deploy publicId (must have a built image)."),
+    target_environment_id: z8.union([z8.string(), z8.number()]).describe("Target environment publicId or numeric id.")
+  },
+  handler: async (args2, ctx) => {
+    const teamId = await ctx.resolveTeamId();
+    const targetEnvId = await ctx.hoststack.resolveId(args2.target_environment_id, {
+      kind: "environment",
+      teamId: await ctx.hoststack.resolveId(teamId, { kind: "team" })
+    });
+    const response = await ctx.hoststack.deploys.promote(
+      teamId,
+      args2.service_id,
+      args2.deploy_id,
+      targetEnvId
+    );
+    const data = { deploy: shape(response.deploy) };
+    return respond({
+      summary: `Promoted deploy ${args2.deploy_id} from service ${args2.service_id} to env ${String(args2.target_environment_id)}.`,
+      data
+    });
+  }
+});
+
 // src/tools/meta.ts
 defineTool({
   name: "get_me",
@@ -1019,7 +1159,7 @@ defineTool({
 });
 
 // src/tools/projects.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 defineTool({
   name: "list_projects",
   category: "projects",
@@ -1059,9 +1199,9 @@ defineTool({
     'Example: create_project({ name: "billing-api", description: "Stripe webhooks", region: "fsn1" }) \u2192 { project: { id: 12, publicId: "prj_\u2026", \u2026 } }'
   ].join("\n"),
   input: {
-    name: z8.string().min(1).max(60).describe("Project name (1\u201360 chars)."),
-    description: z8.string().max(500).optional().describe("Short description (\u2264500 chars)."),
-    region: z8.enum(["fsn1", "nbg1", "hel1"]).optional().describe("Hetzner region: fsn1 | nbg1 | hel1.")
+    name: z9.string().min(1).max(60).describe("Project name (1\u201360 chars)."),
+    description: z9.string().max(500).optional().describe("Short description (\u2264500 chars)."),
+    region: z9.enum(["fsn1", "nbg1", "hel1"]).optional().describe("Hetzner region: fsn1 | nbg1 | hel1.")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1092,9 +1232,9 @@ defineTool({
     'Example: update_project({ project_id: "prj_abc", name: "billing-prod" }) \u2192 { project: { name: "billing-prod", \u2026 } }'
   ].join("\n"),
   input: {
-    project_id: z8.string().describe("Project publicId."),
-    name: z8.string().min(1).max(60).optional().describe("New name (1\u201360 chars)."),
-    description: z8.string().max(500).optional().describe("New description (\u2264500 chars).")
+    project_id: z9.string().describe("Project publicId."),
+    name: z9.string().min(1).max(60).optional().describe("New name (1\u201360 chars)."),
+    description: z9.string().max(500).optional().describe("New description (\u2264500 chars).")
   },
   handler: async (args2, ctx) => {
     if (args2.name === void 0 && args2.description === void 0) {
@@ -1128,7 +1268,7 @@ defineTool({
     'Example: get_project({ project_id: "prj_abc" }) \u2192 { project: { id: 12, name: "billing", \u2026 } }'
   ].join("\n"),
   input: {
-    project_id: z8.string().describe("Project publicId (e.g. prj_abc123).")
+    project_id: z9.string().describe("Project publicId (e.g. prj_abc123).")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1140,7 +1280,7 @@ defineTool({
 });
 
 // src/tools/services.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 defineTool({
   name: "list_services",
   category: "services",
@@ -1178,7 +1318,7 @@ defineTool({
     'Example: get_service({ service_id: "svc_abc" }) \u2192 { service: { type: "web", status: "running", \u2026 } }'
   ].join("\n"),
   input: {
-    service_id: z9.string().describe("Service publicId (e.g. svc_abc123).")
+    service_id: z10.string().describe("Service publicId (e.g. svc_abc123).")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1204,7 +1344,7 @@ defineTool({
     'Example: get_service_metrics({ service_id: "svc_abc" }) \u2192 { metrics: { cpu: 0.42, memory: 0.71, \u2026 } }'
   ].join("\n"),
   input: {
-    service_id: z9.string().describe("Service publicId.")
+    service_id: z10.string().describe("Service publicId.")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1230,8 +1370,8 @@ defineTool({
     'Example: update_service({ service_id: "svc_abc", name: "api-prod" }) \u2192 { service: { name: "api-prod", \u2026 } }'
   ].join("\n"),
   input: {
-    service_id: z9.string().describe("Service publicId."),
-    name: z9.string().min(1).max(60).describe("New service name (1\u201360 chars).")
+    service_id: z10.string().describe("Service publicId."),
+    name: z10.string().min(1).max(60).describe("New service name (1\u201360 chars).")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1264,15 +1404,15 @@ defineTool({
     'Example: update_service_config({ service_id: "svc_abc", start_command: "bun apps/api/src/index.ts" }) \u2192 { service: { startCommand: "bun apps/api/src/index.ts", \u2026 } }'
   ].join("\n"),
   input: {
-    service_id: z9.string().describe("Service publicId."),
-    install_command: z9.string().nullable().optional().describe("Install shell command. Null clears."),
-    build_command: z9.string().nullable().optional().describe("Build shell command. Null clears."),
-    start_command: z9.string().nullable().optional().describe("Start shell command. Null clears."),
-    branch: z9.string().optional().describe("Git branch to track."),
-    root_directory: z9.string().optional().describe("Build context root."),
-    dockerfile_path: z9.string().nullable().optional().describe("Path to Dockerfile relative to root. Null clears."),
-    auto_deploy: z9.boolean().optional().describe("Auto-deploy on push."),
-    instance_count: z9.number().int().positive().max(50).optional().describe("Pin min and max instances to this value (1\u201350).")
+    service_id: z10.string().describe("Service publicId."),
+    install_command: z10.string().nullable().optional().describe("Install shell command. Null clears."),
+    build_command: z10.string().nullable().optional().describe("Build shell command. Null clears."),
+    start_command: z10.string().nullable().optional().describe("Start shell command. Null clears."),
+    branch: z10.string().optional().describe("Git branch to track."),
+    root_directory: z10.string().optional().describe("Build context root."),
+    dockerfile_path: z10.string().nullable().optional().describe("Path to Dockerfile relative to root. Null clears."),
+    auto_deploy: z10.boolean().optional().describe("Auto-deploy on push."),
+    instance_count: z10.number().int().positive().max(50).optional().describe("Pin min and max instances to this value (1\u201350).")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1337,7 +1477,7 @@ defineTool({
     'Example: suspend_service({ service_id: "svc_dev" }) \u2192 { ok: true }'
   ].join("\n"),
   input: {
-    service_id: z9.string().describe("Service publicId.")
+    service_id: z10.string().describe("Service publicId.")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1361,7 +1501,7 @@ defineTool({
     'Example: resume_service({ service_id: "svc_dev" }) \u2192 { ok: true }'
   ].join("\n"),
   input: {
-    service_id: z9.string().describe("Service publicId.")
+    service_id: z10.string().describe("Service publicId.")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1380,18 +1520,29 @@ defineTool({
     "Inputs:",
     "  - service_id: publicId of the service.",
     "  - lines (optional): tail size (default 200, max 1000).",
-    "  - since (optional): ISO-8601 timestamp; only return entries newer than this.",
+    '  - since/until (optional): ISO-8601 timestamp OR a relative offset like "-5m", "-1h", "-2d".',
     '  - stream (optional): "stdout" | "stderr". Omit to combine.',
+    "  - level (optional): friendly synonym \u2014 info/debug \u2192 stdout, warn/error \u2192 stderr.",
+    "  - search (optional): case-insensitive substring grep, \u2264100 chars.",
+    '  - count_only (optional): when true, returns { count } only \u2014 much cheaper for "how many error lines in last 5m" polling.',
+    "",
+    "Returns: { logs: LogEntry[] | string } when count_only is false (each entry has { timestamp, level?, stream?, message }), or { count: number } when count_only is true.",
     "",
-    "Returns: { logs: LogEntry[] | string } \u2014 each entry has { timestamp, level?, stream?, message }. Older HostStack agents return a single string blob.",
+    'Example: get_service_logs({ service_id: "svc_abc", search: "OOM", since: "-15m" }) \u2192 { logs: [...] }.',
     "",
-    'Example: get_service_logs({ service_id: "svc_abc", lines: 100 }) \u2192 { logs: [{ timestamp: "2026-04-25T\u2026", message: "GET /health 200" }, \u2026] }'
+    "More examples:",
+    '  - Last 50 stderr lines from the past hour: get_service_logs({ service_id: "svc_abc", lines: 50, stream: "stderr", since: "-1h" })',
+    '  - Just count error lines without fetching them: get_service_logs({ service_id: "svc_abc", level: "error", since: "-5m", count_only: true }) \u2192 { count: 47 }'
   ].join("\n"),
   input: {
-    service_id: z9.string().describe("Service publicId."),
-    lines: z9.number().int().positive().max(1e3).optional().describe("Tail size; default 200, hard cap 1000."),
-    since: z9.string().datetime().optional().describe("ISO-8601 timestamp lower bound."),
-    stream: z9.enum(["stdout", "stderr"]).optional().describe("Restrict to one stream.")
+    service_id: z10.string().describe("Service publicId."),
+    lines: z10.number().int().positive().max(1e3).optional().describe("Tail size; default 200, hard cap 1000."),
+    since: z10.string().optional().describe('ISO-8601 timestamp or relative offset (e.g. "-5m", "-1h").'),
+    until: z10.string().optional().describe("ISO-8601 timestamp or relative offset upper bound."),
+    stream: z10.enum(["stdout", "stderr"]).optional().describe("Restrict to one stream."),
+    level: z10.enum(["stdout", "stderr", "info", "warn", "error", "debug"]).optional().describe("Friendly stream alias: info/debug\u2192stdout, warn/error\u2192stderr."),
+    search: z10.string().max(100).optional().describe("Case-insensitive substring filter."),
+    count_only: z10.boolean().optional().describe("When true, return only { count } \u2014 skips the log payload.")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1399,8 +1550,18 @@ defineTool({
       lines: args2.lines ?? 200
     };
     if (args2.since) opts.since = args2.since;
+    if (args2.until) opts.until = args2.until;
     if (args2.stream) opts.stream = args2.stream;
+    if (args2.level) opts.level = args2.level;
+    if (args2.search) opts.search = args2.search;
+    if (args2.count_only) opts.countOnly = args2.count_only;
     const response = await ctx.hoststack.services.getRuntimeLogs(teamId, args2.service_id, opts);
+    if ("count" in response) {
+      return respond({
+        summary: `${response.count} matching log line${response.count === 1 ? "" : "s"} for service ${args2.service_id}.`,
+        data: { count: response.count }
+      });
+    }
     const count = Array.isArray(response.logs) ? response.logs.length : typeof response.logs === "string" ? response.logs.split("\n").length : 0;
     return respond({
       summary: `Fetched ${count} log line${count === 1 ? "" : "s"} for service ${args2.service_id}.`,
@@ -1410,7 +1571,7 @@ defineTool({
 });
 
 // src/tools/volumes.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 defineTool({
   name: "list_volumes",
   category: "volumes",
@@ -1427,7 +1588,7 @@ defineTool({
     'Example: list_volumes({ service_id: "svc_abc" }) \u2192 { items: [{ name: "data", mountPath: "/var/data", sizeGb: 10, status: "active" }] }'
   ].join("\n"),
   input: {
-    service_id: z10.string().describe("Service publicId (e.g. svc_abc123).")
+    service_id: z11.string().describe("Service publicId (e.g. svc_abc123).")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1456,10 +1617,10 @@ defineTool({
     'Example: create_volume({ service_id: "svc_abc", name: "data", mount_path: "/var/data", size_gb: 10 }) \u2192 { volume: { name: "data", mountPath: "/var/data", sizeGb: 10, status: "active" } }'
   ].join("\n"),
   input: {
-    service_id: z10.string().describe("Service publicId."),
-    name: z10.string().min(1).max(64).regex(/^[a-z0-9-]+$/).describe("Volume name (lowercase alphanumeric + hyphens)."),
-    mount_path: z10.string().startsWith("/").max(500).describe("In-container mount path (absolute)."),
-    size_gb: z10.number().int().min(1).max(100).optional().describe("Disk size in GB (default 1, max 100).")
+    service_id: z11.string().describe("Service publicId."),
+    name: z11.string().min(1).max(64).regex(/^[a-z0-9-]+$/).describe("Volume name (lowercase alphanumeric + hyphens)."),
+    mount_path: z11.string().startsWith("/").max(500).describe("In-container mount path (absolute)."),
+    size_gb: z11.number().int().min(1).max(100).optional().describe("Disk size in GB (default 1, max 100).")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1495,10 +1656,10 @@ defineTool({
     'Example: update_volume({ service_id: "svc_abc", volume_id: "vol_xyz", size_gb: 20 }) \u2192 { volume: { sizeGb: 20, \u2026 } }'
   ].join("\n"),
   input: {
-    service_id: z10.string().describe("Service publicId."),
-    volume_id: z10.string().describe("Volume publicId (e.g. vol_\u2026)."),
-    mount_path: z10.string().startsWith("/").max(500).optional().describe("New mount path."),
-    size_gb: z10.number().int().min(1).max(100).optional().describe("New size in GB.")
+    service_id: z11.string().describe("Service publicId."),
+    volume_id: z11.string().describe("Volume publicId (e.g. vol_\u2026)."),
+    mount_path: z11.string().startsWith("/").max(500).optional().describe("New mount path."),
+    size_gb: z11.number().int().min(1).max(100).optional().describe("New size in GB.")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();
@@ -1536,8 +1697,8 @@ defineTool({
     'Example: delete_volume({ service_id: "svc_abc", volume_id: "vol_xyz" }) \u2192 { ok: true }'
   ].join("\n"),
   input: {
-    service_id: z10.string().describe("Service publicId."),
-    volume_id: z10.string().describe("Volume publicId.")
+    service_id: z11.string().describe("Service publicId."),
+    volume_id: z11.string().describe("Volume publicId.")
   },
   handler: async (args2, ctx) => {
     const teamId = await ctx.resolveTeamId();