@hatchbox/hatchbox-mcp 0.1.0 → 0.3.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
@@ -14,13 +14,14 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
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_restart_process` |
17
+ | Cron jobs | `hatchbox_list_cron_jobs`, `hatchbox_get_cron_job` | `hatchbox_create_cron_job`, `hatchbox_update_cron_job`, `hatchbox_delete_cron_job` |
17
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` |
18
19
  | Clusters | `hatchbox_get_cluster` (embeds servers) | — |
19
- | Servers | `hatchbox_list_servers`, `hatchbox_get_server` | — |
20
- | 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` |
21
22
  | Logs | `hatchbox_get_log` | — |
22
23
 
23
- `hatchbox_restart_app`, `hatchbox_deploy_app`, and `hatchbox_create_backup` 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`, 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
25
 
25
26
  ## Setup
26
27
 
package/build/server.js CHANGED
@@ -5,6 +5,7 @@ import { registerAppsTools } from "./tools/apps.js";
5
5
  import { registerDomainsTools } from "./tools/domains.js";
6
6
  import { registerEnvVarsTools } from "./tools/envVars.js";
7
7
  import { registerProcessesTools } from "./tools/processes.js";
8
+ import { registerCronJobsTools } from "./tools/cronJobs.js";
8
9
  import { registerDatabasesTools } from "./tools/databases.js";
9
10
  import { registerClustersTools } from "./tools/clusters.js";
10
11
  import { registerServersTools } from "./tools/servers.js";
@@ -13,7 +14,7 @@ import { registerLogsTools } from "./tools/logs.js";
13
14
  export function createServer(client) {
14
15
  const server = new McpServer({
15
16
  name: "hatchbox-mcp",
16
- version: "0.1.0",
17
+ version: "0.3.0",
17
18
  });
18
19
  registerAccountsTools(server, client);
19
20
  registerMeTools(server, client);
@@ -21,6 +22,7 @@ export function createServer(client) {
21
22
  registerDomainsTools(server, client);
22
23
  registerEnvVarsTools(server, client);
23
24
  registerProcessesTools(server, client);
25
+ registerCronJobsTools(server, client);
24
26
  registerDatabasesTools(server, client);
25
27
  registerClustersTools(server, client);
26
28
  registerServersTools(server, client);
@@ -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
  }
@@ -0,0 +1,88 @@
1
+ import { z } from "zod";
2
+ import { jsonResult, READ_ONLY, runAction, textResult, WRITE } from "./helpers.js";
3
+ const appIdSchema = {
4
+ app_id: z.number().int().describe("Numeric app id."),
5
+ };
6
+ const cronJobIdSchema = {
7
+ ...appIdSchema,
8
+ cron_job_id: z.number().int().describe("Numeric cron job id (see hatchbox_list_cron_jobs)."),
9
+ };
10
+ const cronJobWriteFields = {
11
+ name: z.string().describe("Cron job name.").optional(),
12
+ run_at: z
13
+ .string()
14
+ .describe("Cron expression for when to run, e.g. '0 0 * * *' (daily at midnight UTC). Must be a valid cron expression.")
15
+ .optional(),
16
+ command: z.string().describe("Shell command to run, executed from the app's current release directory.").optional(),
17
+ appsignal: z
18
+ .boolean()
19
+ .describe("Wrap the command with AppSignal cron monitoring. Requires AppSignal to already be connected to the app — " +
20
+ "fails with a 422 otherwise.")
21
+ .optional(),
22
+ honeybadger_checkin_id: z
23
+ .string()
24
+ .describe("Wrap the command with a Honeybadger check-in, using this check-in id.")
25
+ .optional(),
26
+ };
27
+ const CRON_JOB_WRITE_KEYS = Object.keys(cronJobWriteFields);
28
+ function cronJobParams(args) {
29
+ const cronJob = {};
30
+ for (const key of CRON_JOB_WRITE_KEYS) {
31
+ if (args[key] !== undefined)
32
+ cronJob[key] = args[key];
33
+ }
34
+ return cronJob;
35
+ }
36
+ const ASYNC_APPLY_NOTE = "Applied to the server asynchronously via a background job with no pollable status — unlike " +
37
+ "hatchbox_restart_app/hatchbox_deploy_app, there's no log id to follow up on.";
38
+ export function registerCronJobsTools(server, client) {
39
+ server.registerTool("hatchbox_list_cron_jobs", {
40
+ title: "List App Cron Jobs",
41
+ description: "List the cron jobs configured on a Hatchbox app.",
42
+ inputSchema: appIdSchema,
43
+ annotations: READ_ONLY,
44
+ }, async ({ app_id }) => runAction(async () => jsonResult(await client.get(`/apps/${app_id}/cron_jobs`))));
45
+ server.registerTool("hatchbox_get_cron_job", {
46
+ title: "Get App Cron Job",
47
+ description: "Fetch a single cron job configured on a Hatchbox app.",
48
+ inputSchema: cronJobIdSchema,
49
+ annotations: READ_ONLY,
50
+ }, async ({ app_id, cron_job_id }) => runAction(async () => jsonResult(await client.get(`/apps/${app_id}/cron_jobs/${cron_job_id}`))));
51
+ server.registerTool("hatchbox_create_cron_job", {
52
+ title: "Create App Cron Job",
53
+ description: `Create a new cron job on a Hatchbox app. Fails with a 422 if the app's cluster has no active server with ` +
54
+ `the cron role. ${ASYNC_APPLY_NOTE}`,
55
+ inputSchema: {
56
+ ...cronJobWriteFields,
57
+ ...appIdSchema,
58
+ name: z.string().describe("Cron job name."),
59
+ run_at: z
60
+ .string()
61
+ .describe("Cron expression for when to run, e.g. '0 0 * * *' (daily at midnight UTC). Must be a valid cron expression."),
62
+ command: z.string().describe("Shell command to run, executed from the app's current release directory."),
63
+ },
64
+ annotations: WRITE,
65
+ }, async (args) => runAction(async () => {
66
+ const { app_id } = args;
67
+ return jsonResult(await client.post(`/apps/${app_id}/cron_jobs`, { cron_job: cronJobParams(args) }));
68
+ }));
69
+ server.registerTool("hatchbox_update_cron_job", {
70
+ title: "Update App Cron Job",
71
+ description: `Update a cron job on a Hatchbox app. Only the fields you pass are changed. Fails with a 422 if the app's ` +
72
+ `cluster has no active server with the cron role. ${ASYNC_APPLY_NOTE}`,
73
+ inputSchema: { ...cronJobIdSchema, ...cronJobWriteFields },
74
+ annotations: WRITE,
75
+ }, async (args) => runAction(async () => {
76
+ const { app_id, cron_job_id } = args;
77
+ return jsonResult(await client.patch(`/apps/${app_id}/cron_jobs/${cron_job_id}`, { cron_job: cronJobParams(args) }));
78
+ }));
79
+ server.registerTool("hatchbox_delete_cron_job", {
80
+ title: "Delete App Cron Job",
81
+ description: `Delete a cron job from a Hatchbox app. Allowed even if the app's cluster has no active cron server. ${ASYNC_APPLY_NOTE}`,
82
+ inputSchema: cronJobIdSchema,
83
+ annotations: WRITE,
84
+ }, async ({ app_id, cron_job_id }) => runAction(async () => {
85
+ await client.delete(`/apps/${app_id}/cron_jobs/${cron_job_id}`);
86
+ return textResult(`Deleted cron job ${cron_job_id} from app ${app_id}.`);
87
+ }));
88
+ }
@@ -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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hatchbox/hatchbox-mcp",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "MCP server that wraps the Hatchbox /api/v1 API",
5
5
  "type": "module",
6
6
  "main": "build/index.js",