@hatchbox/hatchbox-mcp 0.6.0 → 0.8.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 +24 -2
- package/build/client.js +18 -1
- package/build/server.js +1 -1
- package/build/tools/apps.js +34 -4
- package/build/tools/helpers.js +4 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
|
|
|
10
10
|
|---|---|---|
|
|
11
11
|
| Accounts | `hatchbox_list_accounts`, `hatchbox_get_account`, `hatchbox_list_account_apps`, `hatchbox_list_account_clusters`, `hatchbox_list_account_database_clusters`, `hatchbox_list_account_git_providers` | — |
|
|
12
12
|
| User | `hatchbox_get_me` | — |
|
|
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` |
|
|
13
|
+
| Apps | `hatchbox_get_app` | `hatchbox_create_app`, `hatchbox_update_app`, `hatchbox_rename_app`, `hatchbox_enable_app_maintenance`, `hatchbox_disable_app_maintenance`, `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
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` |
|
|
@@ -22,12 +22,16 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
|
|
|
22
22
|
| Backups | `hatchbox_get_latest_backup`, `hatchbox_get_backup_configuration` | `hatchbox_create_backup`, `hatchbox_test_backup_connection`, `hatchbox_update_backup_configuration`, `hatchbox_disable_backups` |
|
|
23
23
|
| Logs | `hatchbox_list_app_logs`, `hatchbox_get_log` | — |
|
|
24
24
|
|
|
25
|
-
`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`, `hatchbox_disable_process`, `hatchbox_create_firewall_rule`, and `hatchbox_delete_firewall_rule` are asynchronous: they return a log id (as `log_id`, except `hatchbox_delete_process` and `
|
|
25
|
+
`hatchbox_restart_app`, `hatchbox_deploy_app`, `hatchbox_rename_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`, `hatchbox_disable_process`, `hatchbox_create_firewall_rule`, and `hatchbox_delete_firewall_rule` are asynchronous: they return a log id (as `log_id`, except `hatchbox_delete_process`, `hatchbox_delete_firewall_rule`, and `hatchbox_rename_app`, which return 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).
|
|
26
|
+
|
|
27
|
+
`hatchbox_enable_app_maintenance`/`hatchbox_disable_app_maintenance` are *not* async in this sense: they return the updated app record immediately (`maintenance: true`/`false`). The Caddy config reload that actually flips the served page happens on the app's servers in the background, with no log id to poll.
|
|
26
28
|
|
|
27
29
|
`hatchbox_list_app_logs` and `hatchbox_list_firewall_rules` are paginated: they return `{ logs, pagination }` / `{ firewall_rules, pagination }` respectively, where `pagination` carries `current_page`/`total_pages`/`total_count`/`page_limit`. `limit` defaults to and is capped at 100 server-side.
|
|
28
30
|
|
|
29
31
|
`hatchbox_delete_firewall_rule` fails with a 422 if the rule is one Hatchbox manages itself (SSH, and 80/443 on web servers) — check the `removable` field from `hatchbox_list_firewall_rules`/`hatchbox_get_firewall_rule` before attempting to delete a rule.
|
|
30
32
|
|
|
33
|
+
`hatchbox_update_app` rejects the `name` field entirely (422) — renaming moves the app's directory and rewrites server config, so it's handled separately by `hatchbox_rename_app`, which also 422s if the new name is unchanged, blank, contains characters other than letters/numbers/hyphens/underscores, or is already taken by another app in the same cluster.
|
|
34
|
+
|
|
31
35
|
## Setup
|
|
32
36
|
|
|
33
37
|
1. **Get an API token.** Log into your Hatchbox web app, go to `/api_tokens` → New API Token, name it, and copy the revealed token value.
|
|
@@ -54,6 +58,24 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
|
|
|
54
58
|
}
|
|
55
59
|
```
|
|
56
60
|
|
|
61
|
+
## Plugin (Claude Code)
|
|
62
|
+
|
|
63
|
+
Claude Code users can install the MCP server and the Heroku migration skill together:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
/plugin marketplace add hatchboxio/hatchbox-mcp
|
|
67
|
+
/plugin install hatchbox@hatchbox
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Set `HATCHBOX_API_TOKEN` in your environment first — the plugin passes it through to the server.
|
|
71
|
+
|
|
72
|
+
The bundled `migrate-from-heroku` skill takes a Rails app from Heroku to Hatchbox. It currently
|
|
73
|
+
covers preflight, inventory and planning; all of it is read-only and writes nothing to Hatchbox
|
|
74
|
+
or Heroku.
|
|
75
|
+
|
|
76
|
+
Users of other MCP clients configure the server directly per the Setup section above; the skill
|
|
77
|
+
is Claude Code specific.
|
|
78
|
+
|
|
57
79
|
## Development
|
|
58
80
|
|
|
59
81
|
To work on `hatchbox-mcp` itself rather than just using it:
|
package/build/client.js
CHANGED
|
@@ -17,9 +17,13 @@ export class HatchboxApiError extends Error {
|
|
|
17
17
|
export class HatchboxClient {
|
|
18
18
|
baseUrl;
|
|
19
19
|
token;
|
|
20
|
+
/** Set when the client was built without usable credentials. Raised on first use, not at
|
|
21
|
+
* construction, so the MCP transport can still connect and report it to the caller. */
|
|
22
|
+
configError;
|
|
20
23
|
constructor(config) {
|
|
21
24
|
this.baseUrl = config.baseUrl.replace(/\/+$/, "");
|
|
22
25
|
this.token = config.token;
|
|
26
|
+
this.configError = config.configError;
|
|
23
27
|
}
|
|
24
28
|
async get(path, query) {
|
|
25
29
|
return this.request("GET", path, { query });
|
|
@@ -38,6 +42,8 @@ export class HatchboxClient {
|
|
|
38
42
|
return this.request("DELETE", path, { body });
|
|
39
43
|
}
|
|
40
44
|
async request(method, path, opts = {}) {
|
|
45
|
+
if (this.configError)
|
|
46
|
+
throw new HatchboxConfigError(this.configError);
|
|
41
47
|
const url = new URL(`${this.baseUrl}${path}`);
|
|
42
48
|
for (const [key, value] of Object.entries(opts.query ?? {})) {
|
|
43
49
|
if (value !== undefined)
|
|
@@ -92,12 +98,23 @@ function describeError(status, body) {
|
|
|
92
98
|
return `Request failed with status ${status}.`;
|
|
93
99
|
}
|
|
94
100
|
}
|
|
101
|
+
/** The server is misconfigured — a missing token, say. Not a failure of the request, and not a
|
|
102
|
+
* bug: the message says what the operator has to do, so it is surfaced without crash framing. */
|
|
103
|
+
export class HatchboxConfigError extends Error {
|
|
104
|
+
}
|
|
95
105
|
const DEFAULT_BASE_URL = "https://hatchbox.io/api/v1";
|
|
96
106
|
export function clientFromEnv() {
|
|
97
107
|
const baseUrl = process.env.HATCHBOX_BASE_URL || DEFAULT_BASE_URL;
|
|
98
108
|
const token = process.env.HATCHBOX_API_TOKEN;
|
|
99
109
|
if (!token) {
|
|
100
|
-
|
|
110
|
+
// Deliberately not thrown here. Throwing killed the process before the transport
|
|
111
|
+
// connected, so the client showed a generic connection failure and this message -- the
|
|
112
|
+
// only one that tells the user what to do -- was lost with the process.
|
|
113
|
+
return new HatchboxClient({
|
|
114
|
+
baseUrl,
|
|
115
|
+
token: "",
|
|
116
|
+
configError: "HATCHBOX_API_TOKEN is not set. Create one at https://hatchbox.io/api_tokens and set it in the MCP server config (for the Claude Code plugin, export it in the environment you launch Claude Code from).",
|
|
117
|
+
});
|
|
101
118
|
}
|
|
102
119
|
return new HatchboxClient({ baseUrl, token });
|
|
103
120
|
}
|
package/build/server.js
CHANGED
|
@@ -15,7 +15,7 @@ import { registerFirewallRulesTools } from "./tools/firewallRules.js";
|
|
|
15
15
|
export function createServer(client) {
|
|
16
16
|
const server = new McpServer({
|
|
17
17
|
name: "hatchbox-mcp",
|
|
18
|
-
version: "0.
|
|
18
|
+
version: "0.7.0",
|
|
19
19
|
});
|
|
20
20
|
registerAccountsTools(server, client);
|
|
21
21
|
registerMeTools(server, client);
|
package/build/tools/apps.js
CHANGED
|
@@ -5,7 +5,6 @@ const appIdSchema = {
|
|
|
5
5
|
};
|
|
6
6
|
const APP_NAME_REGEX = /^[\w-]+$/;
|
|
7
7
|
const appWriteFields = {
|
|
8
|
-
name: z.string().regex(APP_NAME_REGEX).describe("App name, letters/numbers/underscore/hyphen only.").optional(),
|
|
9
8
|
branch: z.string().describe("Git branch to deploy from.").optional(),
|
|
10
9
|
repo_path: z.string().describe("Repository path, e.g. 'org/repo'.").optional(),
|
|
11
10
|
connected_account_id: z
|
|
@@ -50,18 +49,49 @@ export function registerAppsTools(server, client) {
|
|
|
50
49
|
},
|
|
51
50
|
annotations: WRITE,
|
|
52
51
|
}, async (args) => runAction(async () => {
|
|
53
|
-
const { cluster_id } = args;
|
|
54
|
-
return jsonResult(await client.post(`/apps`, { app: { cluster_id, ...appParams(args) } }));
|
|
52
|
+
const { cluster_id, name } = args;
|
|
53
|
+
return jsonResult(await client.post(`/apps`, { app: { cluster_id, name, ...appParams(args) } }));
|
|
55
54
|
}));
|
|
56
55
|
server.registerTool("hatchbox_update_app", {
|
|
57
56
|
title: "Update Hatchbox App",
|
|
58
|
-
description: "Update a Hatchbox app's configuration. Only the fields you pass are changed."
|
|
57
|
+
description: "Update a Hatchbox app's configuration. Only the fields you pass are changed. Renaming isn't supported here " +
|
|
58
|
+
"(a rename moves the app directory and rewrites server config, so it's a separate async operation) — use " +
|
|
59
|
+
"hatchbox_rename_app instead.",
|
|
59
60
|
inputSchema: { ...appIdSchema, ...appWriteFields },
|
|
60
61
|
annotations: WRITE,
|
|
61
62
|
}, async (args) => runAction(async () => {
|
|
62
63
|
const { app_id } = args;
|
|
63
64
|
return jsonResult(await client.patch(`/apps/${app_id}`, { app: appParams(args) }));
|
|
64
65
|
}));
|
|
66
|
+
server.registerTool("hatchbox_rename_app", {
|
|
67
|
+
title: "Rename Hatchbox App",
|
|
68
|
+
description: "Rename a Hatchbox app. Moves the app directory and rewrites every systemd unit on its servers, so it runs " +
|
|
69
|
+
"as a background script rather than a plain field update — the app keeps its old name until the script " +
|
|
70
|
+
"completes. Asynchronous — returns an id (the log id, not named log_id for this endpoint), follow up with " +
|
|
71
|
+
"hatchbox_get_log. Fails with a 422 if the new name matches the current name, is blank, contains characters " +
|
|
72
|
+
"other than letters/numbers/hyphens/underscores, or is already taken by another app in the same cluster.",
|
|
73
|
+
inputSchema: {
|
|
74
|
+
...appIdSchema,
|
|
75
|
+
name: z.string().regex(APP_NAME_REGEX).describe("New app name, letters/numbers/underscore/hyphen only."),
|
|
76
|
+
},
|
|
77
|
+
annotations: WRITE,
|
|
78
|
+
}, async ({ app_id, name }) => runAction(async () => jsonResult(await client.post(`/apps/${app_id}/rename`, { app: { name } }))));
|
|
79
|
+
server.registerTool("hatchbox_enable_app_maintenance", {
|
|
80
|
+
title: "Enable App Maintenance Mode",
|
|
81
|
+
description: "Put a Hatchbox app into maintenance mode, serving a maintenance page instead of the app. Returns the " +
|
|
82
|
+
"updated app record immediately with `maintenance: true` — the actual Caddy config reload on the app's " +
|
|
83
|
+
"servers happens in the background, with no log id to follow up on.",
|
|
84
|
+
inputSchema: appIdSchema,
|
|
85
|
+
annotations: WRITE,
|
|
86
|
+
}, async ({ app_id }) => runAction(async () => jsonResult(await client.post(`/apps/${app_id}/maintenance`))));
|
|
87
|
+
server.registerTool("hatchbox_disable_app_maintenance", {
|
|
88
|
+
title: "Disable App Maintenance Mode",
|
|
89
|
+
description: "Take a Hatchbox app out of maintenance mode. Returns the updated app record immediately with " +
|
|
90
|
+
"`maintenance: false` — the actual Caddy config reload on the app's servers happens in the background, " +
|
|
91
|
+
"with no log id to follow up on.",
|
|
92
|
+
inputSchema: appIdSchema,
|
|
93
|
+
annotations: WRITE,
|
|
94
|
+
}, async ({ app_id }) => runAction(async () => jsonResult(await client.delete(`/apps/${app_id}/maintenance`))));
|
|
65
95
|
server.registerTool("hatchbox_restart_app", {
|
|
66
96
|
title: "Restart Hatchbox App",
|
|
67
97
|
description: "Restart every process on a Hatchbox app. Asynchronous — returns a log id, follow up with hatchbox_get_log " +
|
package/build/tools/helpers.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { HatchboxApiError } from "../client.js";
|
|
1
|
+
import { HatchboxApiError, HatchboxConfigError } from "../client.js";
|
|
2
2
|
/** Annotations for tools that only read data (safe HTTP methods). */
|
|
3
3
|
export const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
|
|
4
4
|
/** Annotations for tools that create/update/delete data (unsafe HTTP methods). */
|
|
@@ -18,6 +18,9 @@ export async function runAction(fn) {
|
|
|
18
18
|
return await fn();
|
|
19
19
|
}
|
|
20
20
|
catch (err) {
|
|
21
|
+
if (err instanceof HatchboxConfigError) {
|
|
22
|
+
return errorResult(err.message);
|
|
23
|
+
}
|
|
21
24
|
if (err instanceof HatchboxApiError) {
|
|
22
25
|
return errorResult(`Hatchbox API error (${err.status}): ${err.message}`);
|
|
23
26
|
}
|