@hatchbox/hatchbox-mcp 0.3.0 → 0.4.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 +3 -5
- package/build/client.js +2 -4
- package/build/server.js +1 -1
- package/build/tools/processes.js +84 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ 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) | — |
|
|
@@ -21,7 +21,7 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
|
|
|
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
22
|
| 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 `
|
|
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
25
|
|
|
26
26
|
## Setup
|
|
27
27
|
|
|
@@ -32,7 +32,7 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
|
|
|
32
32
|
```
|
|
33
33
|
claude mcp add hatchbox -- npx -y @hatchbox/hatchbox-mcp
|
|
34
34
|
```
|
|
35
|
-
Then set `
|
|
35
|
+
Then set `HATCHBOX_API_TOKEN` for that server (see `claude mcp add --help` for passing env vars, or edit `.mcp.json` directly).
|
|
36
36
|
|
|
37
37
|
**Claude Desktop** (`claude_desktop_config.json`):
|
|
38
38
|
```json
|
|
@@ -42,14 +42,12 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
|
|
|
42
42
|
"command": "npx",
|
|
43
43
|
"args": ["-y", "@hatchbox/hatchbox-mcp"],
|
|
44
44
|
"env": {
|
|
45
|
-
"HATCHBOX_BASE_URL": "https://hatchbox.io/api/v1",
|
|
46
45
|
"HATCHBOX_API_TOKEN": "your-token-here"
|
|
47
46
|
}
|
|
48
47
|
}
|
|
49
48
|
}
|
|
50
49
|
}
|
|
51
50
|
```
|
|
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
51
|
|
|
54
52
|
## Development
|
|
55
53
|
|
package/build/client.js
CHANGED
|
@@ -85,12 +85,10 @@ function describeError(status, body) {
|
|
|
85
85
|
return `Request failed with status ${status}.`;
|
|
86
86
|
}
|
|
87
87
|
}
|
|
88
|
+
const DEFAULT_BASE_URL = "https://hatchbox.io/api/v1";
|
|
88
89
|
export function clientFromEnv() {
|
|
89
|
-
const baseUrl = process.env.HATCHBOX_BASE_URL;
|
|
90
|
+
const baseUrl = process.env.HATCHBOX_BASE_URL || DEFAULT_BASE_URL;
|
|
90
91
|
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
92
|
if (!token) {
|
|
95
93
|
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
94
|
}
|
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.
|
|
17
|
+
version: "0.4.0",
|
|
18
18
|
});
|
|
19
19
|
registerAccountsTools(server, client);
|
|
20
20
|
registerMeTools(server, client);
|
package/build/tools/processes.js
CHANGED
|
@@ -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 " +
|