@hatchbox/hatchbox-mcp 0.2.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 +5 -7
- package/build/client.js +2 -4
- package/build/server.js +1 -1
- package/build/tools/backups.js +74 -0
- package/build/tools/processes.js +84 -0
- package/build/tools/servers.js +23 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,15 +13,15 @@ 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
|
-
| Servers | `hatchbox_list_servers`, `hatchbox_get_server` |
|
|
21
|
-
| Backups | `hatchbox_get_latest_backup` | `hatchbox_create_backup` |
|
|
20
|
+
| Servers | `hatchbox_list_servers`, `hatchbox_get_server` | `hatchbox_provision_server`, `hatchbox_reboot_server` |
|
|
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`, 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/backups.js
CHANGED
|
@@ -3,6 +3,45 @@ import { jsonResult, READ_ONLY, runAction, WRITE } from "./helpers.js";
|
|
|
3
3
|
const databaseIdSchema = {
|
|
4
4
|
database_id: z.number().int().describe("Numeric database id (see hatchbox_list_app_databases)."),
|
|
5
5
|
};
|
|
6
|
+
const backupConfigWriteFields = {
|
|
7
|
+
backup_provider: z
|
|
8
|
+
.string()
|
|
9
|
+
.describe("Where to store backups. Valid values: local, s3, azureblob, r2, spaces, gcs, wasabi, other. " +
|
|
10
|
+
"backup_region is required for s3/spaces/wasabi. backup_endpoint is required for other. local stores on " +
|
|
11
|
+
"the server itself and needs no other backup_* fields.")
|
|
12
|
+
.optional(),
|
|
13
|
+
backup_region: z.string().describe("Storage region. Required when backup_provider is s3, spaces, or wasabi.").optional(),
|
|
14
|
+
backup_bucket: z.string().describe("Bucket/container name. Required for remote providers.").optional(),
|
|
15
|
+
backup_access_key_id: z.string().describe("Access key id for the backup provider. Required for remote providers.").optional(),
|
|
16
|
+
backup_secret_access_key: z
|
|
17
|
+
.string()
|
|
18
|
+
.describe("Secret access key for the backup provider. Required for remote providers. Encrypted at rest — never echoed " +
|
|
19
|
+
"back in responses.")
|
|
20
|
+
.optional(),
|
|
21
|
+
backup_endpoint: z.string().describe("Custom S3-compatible endpoint URL. Required when backup_provider is other.").optional(),
|
|
22
|
+
backup_frequency: z
|
|
23
|
+
.string()
|
|
24
|
+
.describe("Cron expression for how often to back up, e.g. '0 0 * * *' (daily at midnight UTC). Must be a valid cron expression.")
|
|
25
|
+
.optional(),
|
|
26
|
+
backup_retention_period: z
|
|
27
|
+
.string()
|
|
28
|
+
.describe("How long to keep backups, e.g. '30d', '6M', '1y' — a number followed by one of ms/s/m/h/d/w/M/y.")
|
|
29
|
+
.optional(),
|
|
30
|
+
appsignal_app_push_api_key: z
|
|
31
|
+
.string()
|
|
32
|
+
.describe("Wrap backup runs with AppSignal cron monitoring, using this app's push API key.")
|
|
33
|
+
.optional(),
|
|
34
|
+
honeybadger_checkin_id: z.string().describe("Wrap backup runs with a Honeybadger check-in, using this check-in id.").optional(),
|
|
35
|
+
};
|
|
36
|
+
const BACKUP_CONFIG_WRITE_KEYS = Object.keys(backupConfigWriteFields);
|
|
37
|
+
function backupConfigParams(args) {
|
|
38
|
+
const config = {};
|
|
39
|
+
for (const key of BACKUP_CONFIG_WRITE_KEYS) {
|
|
40
|
+
if (args[key] !== undefined)
|
|
41
|
+
config[key] = args[key];
|
|
42
|
+
}
|
|
43
|
+
return config;
|
|
44
|
+
}
|
|
6
45
|
export function registerBackupsTools(server, client) {
|
|
7
46
|
server.registerTool("hatchbox_create_backup", {
|
|
8
47
|
title: "Create Database Backup",
|
|
@@ -19,4 +58,39 @@ export function registerBackupsTools(server, client) {
|
|
|
19
58
|
inputSchema: databaseIdSchema,
|
|
20
59
|
annotations: READ_ONLY,
|
|
21
60
|
}, async ({ database_id }) => runAction(async () => jsonResult(await client.get(`/databases/${database_id}/backups/latest`))));
|
|
61
|
+
server.registerTool("hatchbox_test_backup_connection", {
|
|
62
|
+
title: "Test Database Backup Connection",
|
|
63
|
+
description: "Test the configured remote backup connection for a Hatchbox database. Fails with a 422 for local backups " +
|
|
64
|
+
"(nothing remote to test) or if backups aren't enabled. Asynchronous — returns a log id, follow up with " +
|
|
65
|
+
"hatchbox_get_log.",
|
|
66
|
+
inputSchema: databaseIdSchema,
|
|
67
|
+
annotations: WRITE,
|
|
68
|
+
}, async ({ database_id }) => runAction(async () => jsonResult(await client.post(`/databases/${database_id}/backups/test_connection`))));
|
|
69
|
+
server.registerTool("hatchbox_get_backup_configuration", {
|
|
70
|
+
title: "Get Database Backup Configuration",
|
|
71
|
+
description: "Fetch the backup configuration for a Hatchbox database. Credentials (access key/secret, AppSignal push " +
|
|
72
|
+
"key) are reported only as booleans (whether one is set on file) — never echoed back in plaintext.",
|
|
73
|
+
inputSchema: databaseIdSchema,
|
|
74
|
+
annotations: READ_ONLY,
|
|
75
|
+
}, async ({ database_id }) => runAction(async () => jsonResult(await client.get(`/databases/${database_id}/backup_configuration`))));
|
|
76
|
+
server.registerTool("hatchbox_update_backup_configuration", {
|
|
77
|
+
title: "Update Database Backup Configuration",
|
|
78
|
+
description: "Configure and enable backups for a Hatchbox database. Only the fields you pass are changed; any update " +
|
|
79
|
+
"implicitly enables backups. Not available for managed databases (back those up via their hosting provider " +
|
|
80
|
+
"instead). Asynchronous apply — returns a log id, follow up with hatchbox_get_log.",
|
|
81
|
+
inputSchema: { ...databaseIdSchema, ...backupConfigWriteFields },
|
|
82
|
+
annotations: WRITE,
|
|
83
|
+
}, async (args) => runAction(async () => {
|
|
84
|
+
const { database_id } = args;
|
|
85
|
+
return jsonResult(await client.patch(`/databases/${database_id}/backup_configuration`, {
|
|
86
|
+
backup_configuration: backupConfigParams(args),
|
|
87
|
+
}));
|
|
88
|
+
}));
|
|
89
|
+
server.registerTool("hatchbox_disable_backups", {
|
|
90
|
+
title: "Disable Database Backups",
|
|
91
|
+
description: "Disable backups for a Hatchbox database and clear its stored backup configuration/credentials. A no-op if " +
|
|
92
|
+
"backups are already disabled. Asynchronous apply — returns a log id when it actually changes state.",
|
|
93
|
+
inputSchema: databaseIdSchema,
|
|
94
|
+
annotations: WRITE,
|
|
95
|
+
}, async ({ database_id }) => runAction(async () => jsonResult(await client.delete(`/databases/${database_id}/backup_configuration`))));
|
|
22
96
|
}
|
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 " +
|
package/build/tools/servers.js
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
import { jsonResult, READ_ONLY, runAction } from "./helpers.js";
|
|
2
|
+
import { jsonResult, READ_ONLY, runAction, WRITE } from "./helpers.js";
|
|
3
3
|
const clusterIdSchema = {
|
|
4
4
|
cluster_id: z.number().int().describe("Numeric cluster id (see hatchbox_list_account_clusters)."),
|
|
5
5
|
};
|
|
6
|
+
const serverIdSchema = {
|
|
7
|
+
...clusterIdSchema,
|
|
8
|
+
server_id: z.number().int().describe("Numeric server id (see hatchbox_list_servers)."),
|
|
9
|
+
};
|
|
6
10
|
export function registerServersTools(server, client) {
|
|
7
11
|
server.registerTool("hatchbox_list_servers", {
|
|
8
12
|
title: "List Cluster Servers",
|
|
@@ -14,10 +18,24 @@ export function registerServersTools(server, client) {
|
|
|
14
18
|
server.registerTool("hatchbox_get_server", {
|
|
15
19
|
title: "Get Cluster Server",
|
|
16
20
|
description: "Fetch a single server in a Hatchbox cluster.",
|
|
17
|
-
inputSchema:
|
|
18
|
-
...clusterIdSchema,
|
|
19
|
-
server_id: z.number().int().describe("Numeric server id."),
|
|
20
|
-
},
|
|
21
|
+
inputSchema: serverIdSchema,
|
|
21
22
|
annotations: READ_ONLY,
|
|
22
23
|
}, async ({ cluster_id, server_id }) => runAction(async () => jsonResult(await client.get(`/clusters/${cluster_id}/servers/${server_id}`))));
|
|
24
|
+
server.registerTool("hatchbox_provision_server", {
|
|
25
|
+
title: "Provision Server",
|
|
26
|
+
description: "Re-provision a Hatchbox server, reinstalling/repairing its software stack on the cloud provider. Only " +
|
|
27
|
+
"works on a server that has already been created (has a public IP, or is a self-hosted 'custom' server) — " +
|
|
28
|
+
"creating a brand-new cloud instance isn't available through this API. Fails with a 409 if the server is " +
|
|
29
|
+
"still being created or a provision is already running, 422 if the server hasn't been created on its " +
|
|
30
|
+
"provider yet. Asynchronous — returns a log id, follow up with hatchbox_get_log.",
|
|
31
|
+
inputSchema: serverIdSchema,
|
|
32
|
+
annotations: WRITE,
|
|
33
|
+
}, async ({ cluster_id, server_id }) => runAction(async () => jsonResult(await client.post(`/clusters/${cluster_id}/servers/${server_id}/provision`))));
|
|
34
|
+
server.registerTool("hatchbox_reboot_server", {
|
|
35
|
+
title: "Reboot Server",
|
|
36
|
+
description: "Reboot a Hatchbox server over SSH. Fails with a 409 if the server is being created or provisioned, 422 if " +
|
|
37
|
+
"the server has no reachable IP address. Asynchronous — returns a log id, follow up with hatchbox_get_log.",
|
|
38
|
+
inputSchema: serverIdSchema,
|
|
39
|
+
annotations: WRITE,
|
|
40
|
+
}, async ({ cluster_id, server_id }) => runAction(async () => jsonResult(await client.post(`/clusters/${cluster_id}/servers/${server_id}/reboot`))));
|
|
23
41
|
}
|