@hatchbox/hatchbox-mcp 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,15 +13,17 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
13
13
  | Apps | `hatchbox_get_app` | `hatchbox_create_app`, `hatchbox_update_app`, `hatchbox_restart_app`, `hatchbox_deploy_app`, `hatchbox_enable_app_auto_deploy`, `hatchbox_disable_app_auto_deploy` |
14
14
  | Domains | `hatchbox_list_domains`, `hatchbox_get_domain` | `hatchbox_create_domain`, `hatchbox_update_domain`, `hatchbox_delete_domain` |
15
15
  | Env vars | — | `hatchbox_create_env_vars`, `hatchbox_update_env_vars`, `hatchbox_delete_env_vars` |
16
- | Processes | `hatchbox_list_processes`, `hatchbox_get_process` | `hatchbox_restart_process` |
16
+ | Processes | `hatchbox_list_processes`, `hatchbox_get_process` | `hatchbox_create_process`, `hatchbox_update_process`, `hatchbox_delete_process`, `hatchbox_enable_process`, `hatchbox_disable_process`, `hatchbox_restart_process` |
17
17
  | Cron jobs | `hatchbox_list_cron_jobs`, `hatchbox_get_cron_job` | `hatchbox_create_cron_job`, `hatchbox_update_cron_job`, `hatchbox_delete_cron_job` |
18
18
  | Databases | `hatchbox_list_app_databases`, `hatchbox_get_app_database`, `hatchbox_list_cluster_databases`, `hatchbox_get_cluster_database` | `hatchbox_create_database`, `hatchbox_update_database`, `hatchbox_attach_database`, `hatchbox_detach_database` |
19
19
  | Clusters | `hatchbox_get_cluster` (embeds servers) | — |
20
20
  | Servers | `hatchbox_list_servers`, `hatchbox_get_server` | `hatchbox_provision_server`, `hatchbox_reboot_server` |
21
21
  | Backups | `hatchbox_get_latest_backup`, `hatchbox_get_backup_configuration` | `hatchbox_create_backup`, `hatchbox_test_backup_connection`, `hatchbox_update_backup_configuration`, `hatchbox_disable_backups` |
22
- | Logs | `hatchbox_get_log` | — |
22
+ | Logs | `hatchbox_list_app_logs`, `hatchbox_get_log` | — |
23
23
 
24
- `hatchbox_restart_app`, `hatchbox_deploy_app`, `hatchbox_create_backup`, `hatchbox_test_backup_connection`, `hatchbox_update_backup_configuration`, `hatchbox_disable_backups`, `hatchbox_provision_server`, and `hatchbox_reboot_server` are asynchronous: they return a `log_id` you follow up on with `hatchbox_get_log` until `state` is `completed`/`failed`/`aborted`.
24
+ `hatchbox_restart_app`, `hatchbox_deploy_app`, `hatchbox_create_backup`, `hatchbox_test_backup_connection`, `hatchbox_update_backup_configuration`, `hatchbox_disable_backups`, `hatchbox_provision_server`, `hatchbox_reboot_server`, `hatchbox_create_process`, `hatchbox_update_process`, `hatchbox_delete_process`, `hatchbox_enable_process`, and `hatchbox_disable_process` are asynchronous: they return a log id (as `log_id`, except `hatchbox_delete_process` which returns it as `id`) you follow up on with `hatchbox_get_log` until `state` is `completed`/`failed`/`aborted`. `hatchbox_enable_process`/`hatchbox_disable_process` return no log id when the process was already in that state (a no-op).
25
+
26
+ `hatchbox_list_app_logs` is paginated (the only paginated tool so far): it returns `{ logs, pagination }`, where `pagination` carries `current_page`/`total_pages`/`total_count`/`page_limit`. `limit` defaults to and is capped at 100 server-side.
25
27
 
26
28
  ## Setup
27
29
 
@@ -32,7 +34,7 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
32
34
  ```
33
35
  claude mcp add hatchbox -- npx -y @hatchbox/hatchbox-mcp
34
36
  ```
35
- Then set `HATCHBOX_BASE_URL` and `HATCHBOX_API_TOKEN` for that server (see `claude mcp add --help` for passing env vars, or edit `.mcp.json` directly).
37
+ Then set `HATCHBOX_API_TOKEN` for that server (see `claude mcp add --help` for passing env vars, or edit `.mcp.json` directly).
36
38
 
37
39
  **Claude Desktop** (`claude_desktop_config.json`):
38
40
  ```json
@@ -42,14 +44,12 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
42
44
  "command": "npx",
43
45
  "args": ["-y", "@hatchbox/hatchbox-mcp"],
44
46
  "env": {
45
- "HATCHBOX_BASE_URL": "https://hatchbox.io/api/v1",
46
47
  "HATCHBOX_API_TOKEN": "your-token-here"
47
48
  }
48
49
  }
49
50
  }
50
51
  }
51
52
  ```
52
- `HATCHBOX_BASE_URL` should always be `https://hatchbox.io/api/v1` — it's the same for every customer, not a per-account or per-instance value.
53
53
 
54
54
  ## Development
55
55
 
package/build/client.js CHANGED
@@ -24,6 +24,10 @@ export class HatchboxClient {
24
24
  async get(path, query) {
25
25
  return this.request("GET", path, { query });
26
26
  }
27
+ /** For paginated endpoints, which advertise page state in response headers rather than the JSON body. */
28
+ async getPaginated(path, query) {
29
+ return this.request("GET", path, { query, includeHeaders: true });
30
+ }
27
31
  async post(path, body) {
28
32
  return this.request("POST", path, { body });
29
33
  }
@@ -54,6 +58,9 @@ export class HatchboxClient {
54
58
  if (!response.ok) {
55
59
  throw new HatchboxApiError(response.status, describeError(response.status, parsed), parsed);
56
60
  }
61
+ if (opts.includeHeaders) {
62
+ return { data: parsed, headers: Object.fromEntries(response.headers.entries()) };
63
+ }
57
64
  return parsed;
58
65
  }
59
66
  }
@@ -85,12 +92,10 @@ function describeError(status, body) {
85
92
  return `Request failed with status ${status}.`;
86
93
  }
87
94
  }
95
+ const DEFAULT_BASE_URL = "https://hatchbox.io/api/v1";
88
96
  export function clientFromEnv() {
89
- const baseUrl = process.env.HATCHBOX_BASE_URL;
97
+ const baseUrl = process.env.HATCHBOX_BASE_URL || DEFAULT_BASE_URL;
90
98
  const token = process.env.HATCHBOX_API_TOKEN;
91
- if (!baseUrl) {
92
- throw new Error("HATCHBOX_BASE_URL is not set. Point it at the Hatchbox API, e.g. https://hatchbox.io/api/v1");
93
- }
94
99
  if (!token) {
95
100
  throw new Error("HATCHBOX_API_TOKEN is not set. Create one at https://hatchbox.io/api_tokens and set it in the MCP server config.");
96
101
  }
package/build/server.js CHANGED
@@ -14,7 +14,7 @@ import { registerLogsTools } from "./tools/logs.js";
14
14
  export function createServer(client) {
15
15
  const server = new McpServer({
16
16
  name: "hatchbox-mcp",
17
- version: "0.3.0",
17
+ version: "0.5.0",
18
18
  });
19
19
  registerAccountsTools(server, client);
20
20
  registerMeTools(server, client);
@@ -1,6 +1,31 @@
1
1
  import { z } from "zod";
2
2
  import { jsonResult, READ_ONLY, runAction } from "./helpers.js";
3
3
  export function registerLogsTools(server, client) {
4
+ server.registerTool("hatchbox_list_app_logs", {
5
+ title: "List App Logs",
6
+ description: "List a Hatchbox app's job logs (deploys, restarts, backups, provisioning), newest first — including " +
7
+ "auto-deploys triggered by a git push, not just ones started through this API. Summaries only, without " +
8
+ "the log body (use hatchbox_get_log for a single entry's full body). Paginated: results come back as " +
9
+ "`{ logs, pagination }`, where `pagination` has current_page/total_pages/total_count/page_limit; " +
10
+ "`limit` is capped at 100 server-side regardless of what's requested.",
11
+ inputSchema: {
12
+ app_id: z.number().int().describe("Numeric app id."),
13
+ page: z.number().int().optional().describe("Page number, 1-indexed. Defaults to 1."),
14
+ limit: z.number().int().optional().describe("Results per page. Defaults to and is capped at 100."),
15
+ },
16
+ annotations: READ_ONLY,
17
+ }, async ({ app_id, page, limit }) => runAction(async () => {
18
+ const { data, headers } = await client.getPaginated(`/apps/${app_id}/logs`, { page, limit });
19
+ return jsonResult({
20
+ logs: data,
21
+ pagination: {
22
+ current_page: Number(headers["current-page"]),
23
+ total_pages: Number(headers["total-pages"]),
24
+ total_count: Number(headers["total-count"]),
25
+ page_limit: Number(headers["page-limit"]),
26
+ },
27
+ });
28
+ }));
4
29
  server.registerTool("hatchbox_get_log", {
5
30
  title: "Get Hatchbox Log",
6
31
  description: "Read a Hatchbox job log (deploys, restarts, backups, provisioning) and its child logs. Poll this after " +
@@ -7,6 +7,44 @@ const processIdSchema = {
7
7
  ...appIdSchema,
8
8
  process_id: z.number().int().describe("Numeric process id (see hatchbox_list_processes)."),
9
9
  };
10
+ const PROCESS_NAME_REGEX = /^[\w-]+$/;
11
+ const processWriteFields = {
12
+ name: z.string().regex(PROCESS_NAME_REGEX).describe("Process name, letters/numbers/underscore/hyphen only. Unique per app.").optional(),
13
+ start_command: z.string().describe("Shell command that starts the process. Required on create.").optional(),
14
+ stop_command: z.string().describe("Shell command that stops the process.").optional(),
15
+ reload_command: z.string().describe("Shell command that reloads the process without a full restart.").optional(),
16
+ restart_on_deploy: z.boolean().describe("Whether to restart this process automatically on every deploy. Defaults to true.").optional(),
17
+ server_id: z
18
+ .number()
19
+ .int()
20
+ .describe("Pin this process to a specific server (see hatchbox_list_servers). Mutually exclusive with roles — set one " +
21
+ "or the other, not both.")
22
+ .optional(),
23
+ roles: z
24
+ .array(z.string())
25
+ .describe("Run this process on every server in the cluster carrying any of these roles, instead of a single pinned " +
26
+ "server. Mutually exclusive with server_id.")
27
+ .optional(),
28
+ socket: z
29
+ .boolean()
30
+ .describe("Enable socket activation for this process. Only one process per app may have this set.")
31
+ .optional(),
32
+ systemd_type: z.enum(["simple", "oneshot"]).describe("Systemd service type. Defaults to 'simple'.").optional(),
33
+ appsignal: z
34
+ .boolean()
35
+ .describe("Wrap the process with AppSignal monitoring. Requires the app to already have AppSignal connected.")
36
+ .optional(),
37
+ appsignal_options: z.string().describe("Extra CLI options passed to appsignal-wrap when appsignal is enabled.").optional(),
38
+ };
39
+ const PROCESS_WRITE_KEYS = Object.keys(processWriteFields);
40
+ function processParams(args) {
41
+ const process = {};
42
+ for (const key of PROCESS_WRITE_KEYS) {
43
+ if (args[key] !== undefined)
44
+ process[key] = args[key];
45
+ }
46
+ return process;
47
+ }
10
48
  export function registerProcessesTools(server, client) {
11
49
  server.registerTool("hatchbox_list_processes", {
12
50
  title: "List App Processes",
@@ -20,6 +58,52 @@ export function registerProcessesTools(server, client) {
20
58
  inputSchema: processIdSchema,
21
59
  annotations: READ_ONLY,
22
60
  }, async ({ app_id, process_id }) => runAction(async () => jsonResult(await client.get(`/apps/${app_id}/processes/${process_id}`))));
61
+ server.registerTool("hatchbox_create_process", {
62
+ title: "Create App Process",
63
+ description: "Create a new process (web/worker/cron) on a Hatchbox app. Requires name and start_command. Set either " +
64
+ "server_id or roles to control where it runs (not both) — omit both to leave it unscheduled. Asynchronous " +
65
+ "— returns a log_id, follow up with hatchbox_get_log.",
66
+ inputSchema: {
67
+ ...appIdSchema,
68
+ ...processWriteFields,
69
+ name: z.string().regex(PROCESS_NAME_REGEX).describe("Process name, letters/numbers/underscore/hyphen only. Unique per app."),
70
+ start_command: z.string().describe("Shell command that starts the process."),
71
+ },
72
+ annotations: WRITE,
73
+ }, async (args) => runAction(async () => {
74
+ const { app_id } = args;
75
+ return jsonResult(await client.post(`/apps/${app_id}/processes`, { process: processParams(args) }));
76
+ }));
77
+ server.registerTool("hatchbox_update_process", {
78
+ title: "Update App Process",
79
+ description: "Update a process on a Hatchbox app. Only the fields you pass are changed. Asynchronous — returns a log_id, follow up with hatchbox_get_log.",
80
+ inputSchema: { ...processIdSchema, ...processWriteFields },
81
+ annotations: WRITE,
82
+ }, async (args) => runAction(async () => {
83
+ const { app_id, process_id } = args;
84
+ return jsonResult(await client.patch(`/apps/${app_id}/processes/${process_id}`, { process: processParams(args) }));
85
+ }));
86
+ server.registerTool("hatchbox_delete_process", {
87
+ title: "Delete App Process",
88
+ description: "Delete a process from a Hatchbox app. Asynchronous — returns an id (the log id, not named log_id for this " +
89
+ "endpoint), follow up with hatchbox_get_log.",
90
+ inputSchema: processIdSchema,
91
+ annotations: WRITE,
92
+ }, async ({ app_id, process_id }) => runAction(async () => jsonResult(await client.delete(`/apps/${app_id}/processes/${process_id}`))));
93
+ server.registerTool("hatchbox_enable_process", {
94
+ title: "Enable App Process",
95
+ description: "Enable a disabled process on a Hatchbox app. A no-op if already enabled (no log_id is returned in that " +
96
+ "case). Otherwise asynchronous — returns a log_id, follow up with hatchbox_get_log.",
97
+ inputSchema: processIdSchema,
98
+ annotations: WRITE,
99
+ }, async ({ app_id, process_id }) => runAction(async () => jsonResult(await client.post(`/apps/${app_id}/processes/${process_id}/activation`))));
100
+ server.registerTool("hatchbox_disable_process", {
101
+ title: "Disable App Process",
102
+ description: "Disable a process on a Hatchbox app. A no-op if already disabled (no log_id is returned in that case). " +
103
+ "Otherwise asynchronous — returns a log_id, follow up with hatchbox_get_log.",
104
+ inputSchema: processIdSchema,
105
+ annotations: WRITE,
106
+ }, async ({ app_id, process_id }) => runAction(async () => jsonResult(await client.delete(`/apps/${app_id}/processes/${process_id}/activation`))));
23
107
  server.registerTool("hatchbox_restart_process", {
24
108
  title: "Restart App Process",
25
109
  description: "Restart a single process on a Hatchbox app. To restart every process on an app at once, use " +
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hatchbox/hatchbox-mcp",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "MCP server that wraps the Hatchbox /api/v1 API",
5
5
  "type": "module",
6
6
  "main": "build/index.js",