@hatchbox/hatchbox-mcp 0.7.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 CHANGED
@@ -58,6 +58,24 @@ One tool per operation, each with a `readOnlyHint` or `destructiveHint` annotati
58
58
  }
59
59
  ```
60
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
+
61
79
  ## Development
62
80
 
63
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
- 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.");
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
  }
@@ -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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hatchbox/hatchbox-mcp",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "MCP server that wraps the Hatchbox /api/v1 API",
5
5
  "type": "module",
6
6
  "main": "build/index.js",