@heroku/mcp-server 1.0.1 → 1.0.3

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
@@ -18,14 +18,6 @@ Note: The Heroku Platform MCP Server is currently in early development. As we co
18
18
  implementation, the available functionality and tools may evolve. We welcome feedback and contributions to help shape
19
19
  the future of this project.
20
20
 
21
- ## Install the Heroku Platform MCP Server
22
-
23
- Install the Heroku Platform MCP Server globally using`npm`:
24
-
25
- ```sh
26
- npm i -g @heroku/mcp-server
27
- ```
28
-
29
21
  ## Authentication
30
22
 
31
23
  Generate a Heroku authorization token with one of these methods:
@@ -51,7 +43,7 @@ Generate a Heroku authorization token with one of these methods:
51
43
 
52
44
  ## Configure the Heroku Platform MCP Server
53
45
 
54
- You can configure Claude Desktop, Zed, Cursor, and Windsurf to work with the Heroku Platform MCP Server.
46
+ You can configure Claude Desktop, Zed, Cursor, Windsurf and others to work with the Heroku Platform MCP Server.
55
47
 
56
48
  ### [Claude Desktop](https://claude.ai/download)
57
49
 
@@ -61,7 +53,8 @@ Add this snippet to your `claude_desktop_config.json`:
61
53
  {
62
54
  "mcpServers": {
63
55
  "heroku": {
64
- "command": "npx -y @heroku/mcp-server",
56
+ "command": "npx",
57
+ "args": ["-y", "@heroku/mcp-server"],
65
58
  "env": {
66
59
  "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
67
60
  }
@@ -80,10 +73,10 @@ Add this snippet to your Zed `settings.json`:
80
73
  "heroku": {
81
74
  "command": {
82
75
  "path": "npx",
83
- "args": ["-y", "@heroku/mcp-server"],
84
- "env": {
85
- "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
86
- }
76
+ "args": ["-y", "@heroku/mcp-server"]
77
+ },
78
+ "env": {
79
+ "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
87
80
  }
88
81
  }
89
82
  }
@@ -98,7 +91,10 @@ Add this snippet to your Cursor `mcp.json`:
98
91
  {
99
92
  "mcpServers": {
100
93
  "heroku": {
101
- "command": "npx -y @heroku/mcp-server",
94
+ "command": {
95
+ "path": "npx",
96
+ "args": ["-y", "@heroku/mcp-server"]
97
+ },
102
98
  "env": {
103
99
  "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
104
100
  }
@@ -115,7 +111,67 @@ Add this snippet to your Windsurf `mcp_config.json`:
115
111
  {
116
112
  "mcpServers": {
117
113
  "heroku": {
118
- "command": "npx -y @heroku/mcp-server",
114
+ "command": {
115
+ "path": "npx",
116
+ "args": ["-y", "@heroku/mcp-server"]
117
+ },
118
+ "env": {
119
+ "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
120
+ }
121
+ }
122
+ }
123
+ }
124
+ ```
125
+
126
+ ### [Cline](https://cline.bot)
127
+
128
+ Add this snippet to your Cline `config.json`:
129
+
130
+ ```json
131
+ {
132
+ "mcpServers": {
133
+ "heroku": {
134
+ "command": "npx",
135
+ "args": ["-y", "@heroku/mcp-server"],
136
+ "env": {
137
+ "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
138
+ }
139
+ }
140
+ }
141
+ }
142
+ ```
143
+
144
+ ### [VSCode](https://code.visualstudio.com/)
145
+
146
+ Add this snippet to your VSCode `settings.json` or `.vscode/mcp.json`:
147
+
148
+ ```json
149
+ {
150
+ "mcp": {
151
+ "servers": {
152
+ "heroku": {
153
+ "type": "stdio",
154
+ "command": "npx",
155
+ "args": ["-y", "@heroku/mcp-server"],
156
+ "env": {
157
+ "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
158
+ }
159
+ }
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ ### [Trae](https://trae.ai)
166
+
167
+ Add this snippet to your Trae `mcp_settings.json`:
168
+
169
+ ```json
170
+ {
171
+ "mcpServers": {
172
+ "heroku": {
173
+ "command": "npx",
174
+ "args": ["-y", "@heroku/mcp-server"],
119
175
  "env": {
120
176
  "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
121
177
  }
@@ -135,6 +191,9 @@ Add this snippet to your Windsurf `mcp_config.json`:
135
191
  - `transfer_app` - Transfer ownership of an app to another user or team.
136
192
  - `deploy_to_heroku` - Deploy projects to Heroku with an `app.json` configuration, supporting team deployments, private
137
193
  spaces, and environment setups.
194
+ - `deploy_one_off_dyno` - Execute code or commands in a sandboxed environment on a Heroku one-off dyno. Supports file
195
+ creation, network access, environment variables, and automatic cleanup. Ideal for running scripts, tests, or temporary
196
+ workloads.
138
197
 
139
198
  ### Process & Dyno Management
140
199
 
@@ -3,56 +3,30 @@ import { handleCliOutput } from '../utils/handle-cli-output.js';
3
3
  import { CommandBuilder } from '../utils/command-builder.js';
4
4
  import { TOOL_COMMAND_MAP } from '../utils/tool-commands.js';
5
5
  /**
6
- * Schema for listing Heroku add-ons with filtering and output format options.
7
- * This schema defines the structure and validation rules for the list add-ons operation.
6
+ * Schema for listing Heroku add-ons with filters
8
7
  */
9
8
  export const listAddonsOptionsSchema = z.object({
10
9
  all: z
11
10
  .boolean()
12
11
  .optional()
13
- .describe('Forces the tool to list all add-ons across all apps accessible to the user. When true, this flag: ' +
14
- '1) Overrides any default app setting from Git remote configuration, ' +
15
- '2) Ignores the app flag if provided, ' +
16
- '3) Shows a comprehensive list including: app name, add-on name, service plan, billing status, and ' +
17
- 'provisioning status for each add-on. When false or omitted, respects the default app setting and ' +
18
- 'the app flag.'),
12
+ .describe('List all add-ons across accessible apps. Overrides app param, shows full status'),
19
13
  app: z
20
14
  .string()
21
15
  .optional()
22
- .describe('Specifies a single Heroku app whose add-ons you want to list. Important behaviors: ' +
23
- '1) When provided, shows add-ons and attachments only for this specific app, ' +
24
- '2) When omitted, falls back to the default app from Git remote if configured, ' +
25
- '3) If no default app exists, lists add-ons for all accessible apps, ' +
26
- '4) This flag is completely ignored when all=true. ' +
27
- 'The response includes both provisioned add-ons and add-on attachments from other apps.'),
28
- json: z
29
- .boolean()
30
- .optional()
31
- .describe('Controls the response format and detail level. When true, returns a structured JSON response containing: ' +
32
- '1) Complete add-on metadata including ID, name, and creation timestamp, ' +
33
- '2) Detailed plan information including tier and cost, ' +
34
- '3) Configuration variables set by the add-on, ' +
35
- '4) Attachment details if the add-on is shared with other apps, ' +
36
- '5) Billing and compliance status information. ' +
37
- 'When false or omitted, returns a human-readable text format with basic information.')
16
+ .describe('Filter by app name. Shows add-ons and attachments. Uses Git remote default if omitted')
38
17
  });
39
18
  /**
40
19
  * Registers the list_addons tool with the MCP server.
41
- * This tool enables listing of Heroku add-ons with various filtering options
42
- * and output formats. It can show add-ons for specific apps or across all accessible apps.
43
20
  *
44
21
  * @param server - The MCP server instance to register the tool with
45
22
  * @param herokuRepl - The Heroku REPL instance for executing commands
46
23
  */
47
24
  export const registerListAddonsTool = (server, herokuRepl) => {
48
- server.tool('list_addons', 'List Heroku add-ons with flexible filtering options. Use this tool when you need to: ' +
49
- '1) View all add-ons across your apps, 2) List add-ons for a specific app, ' +
50
- '3) Get detailed add-on metadata in JSON format.', listAddonsOptionsSchema.shape, async (options) => {
25
+ server.tool('list_addons', 'List add-ons: all apps or specific app, detailed metadata', listAddonsOptionsSchema.shape, async (options) => {
51
26
  const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDONS)
52
27
  .addFlags({
53
28
  all: options.all,
54
- app: options.app,
55
- json: options.json
29
+ app: options.app
56
30
  })
57
31
  .build();
58
32
  const output = await herokuRepl.executeCommand(command);
@@ -63,43 +37,20 @@ export const registerListAddonsTool = (server, herokuRepl) => {
63
37
  * Schema for getting information about a specific Heroku add-on.
64
38
  */
65
39
  export const getAddonInfoOptionsSchema = z.object({
66
- addon: z
67
- .string()
68
- .describe('Identifies the add-on to retrieve information about. Accepts three types of identifiers: ' +
69
- '1) Add-on ID (uuid format, works globally without app context), ' +
70
- '2) Add-on name (e.g., "postgresql-curved-12345", works globally without app context), ' +
71
- '3) Attachment name (e.g., "DATABASE", requires app context). ' +
72
- 'Important behaviors: ' +
73
- '- When using attachment name, must provide app flag or have default app set, ' +
74
- '- Attachment name must be from the app where attached, not the provisioning app, ' +
75
- '- Add-on ID and unique names work with correct app context or without app context, ' +
76
- '- Must have access to the app where the add-on is either provisioned or attached.'),
40
+ addon: z.string().describe('Add-on identifier: UUID, name (postgresql-curved-12345), or attachment name (DATABASE)'),
77
41
  app: z
78
42
  .string()
79
43
  .optional()
80
- .describe('Provides application context for finding the add-on. Affects how the addon parameter is interpreted: ' +
81
- '1) When provided: ' +
82
- ' - Searches for the add-on only within this specific app, ' +
83
- ' - Enables use of attachment names in the addon parameter, ' +
84
- ' - Must have access to this app. ' +
85
- '2) When omitted: ' +
86
- ' - First tries using default app from Git remote configuration, ' +
87
- ' - If no default app, addon parameter must be an ID or globally unique name, ' +
88
- ' - Cannot use attachment names without app context. ' +
89
- 'Best practice: Always provide when using attachment names.')
44
+ .describe('App context for add-on lookup. Required for attachment names. Uses Git remote default')
90
45
  });
91
46
  /**
92
47
  * Registers the get_addon_info tool with the MCP server.
93
- * This tool provides detailed information about a specific Heroku add-on,
94
- * including its attachments, billing and state.
95
48
  *
96
49
  * @param server - The MCP server instance to register the tool with
97
50
  * @param herokuRepl - The Heroku REPL instance for executing commands
98
51
  */
99
52
  export const registerGetAddonInfoTool = (server, herokuRepl) => {
100
- server.tool('get_addon_info', 'Get comprehensive information about a Heroku add-on. Use this tool when you need to: ' +
101
- '1) View add-on details, 2) Check plan details and state, ' +
102
- '3) View billing information. Accepts add-on ID, name, or attachment name.', getAddonInfoOptionsSchema.shape, async (options) => {
53
+ server.tool('get_addon_info', 'Get add-on details: plan, state, billing', getAddonInfoOptionsSchema.shape, async (options) => {
103
54
  const command = new CommandBuilder(TOOL_COMMAND_MAP.GET_ADDON_INFO)
104
55
  .addFlags({ app: options.app })
105
56
  .addPositionalArguments({ addon: options.addon })
@@ -112,52 +63,19 @@ export const registerGetAddonInfoTool = (server, herokuRepl) => {
112
63
  * Schema for creating a new Heroku add-on.
113
64
  */
114
65
  export const createAddonOptionsSchema = z.object({
115
- app: z
116
- .string()
117
- .describe('Specifies the target Heroku app for add-on provisioning. Requirements and behaviors: ' +
118
- '1) App must exist and be accessible to you with write permissions, ' +
119
- '2) App region may affect which add-on services are available, ' +
120
- '3) If app is in a Private Space, only add-ons compliant with the space requirements can be provisioned. ' +
121
- 'The add-on will be provisioned directly to this app and config vars will be set automatically.'),
122
- as: z
123
- .string()
124
- .optional()
125
- .describe('Sets a custom local name for the add-on attachment in the app. Important details: ' +
126
- '1) Must be unique within the app (no other attachment can use the same name), ' +
127
- '2) Used as a prefix for config vars (e.g., "CUSTOM_NAME_URL" instead of "HEROKU_POSTGRESQL_URL"), ' +
128
- '3) Makes the add-on easier to identify in app context (e.g., "as: DATABASE" is clearer than "postgresql-curved-12345"), ' +
129
- '4) When omitted, Heroku generates a default name based on the add-on service. ' +
130
- 'Best practice: Use meaningful names that indicate the add-on\'s purpose (e.g., "PRIMARY_DB", "CACHE").'),
131
- name: z
132
- .string()
133
- .optional()
134
- .describe('Assigns a custom global identifier for the add-on instance. Key characteristics: ' +
135
- '1) Must be unique across all add-ons in Heroku (not just your apps), ' +
136
- '2) Can be used to reference the add-on from any app or context, ' +
137
- '3) Useful for identifying the add-on in cross-app scenarios or automation, ' +
138
- '4) When omitted, Heroku generates a unique name (e.g., "postgresql-curved-12345"). ' +
139
- 'Best practice: Include app name or environment if using custom names (e.g., "myapp-prod-db").'),
140
- serviceAndPlan: z
141
- .string()
142
- .describe('Specifies which add-on service and plan to provision. Format and behavior: ' +
143
- '1) Required format: "service_slug:plan_slug" (e.g., "heroku-postgresql:essential-0"), ' +
144
- '2) If only service slug provided, the default (usually the cheapest or free) plan will be selected, ' +
145
- '3) Some plans may have prerequisites (e.g., inside a private space, specific regions). ' +
146
- 'Use list_addon_services and list_addon_plans tools to discover available options.')
66
+ app: z.string().describe('Target app for add-on. Must have write access. Region/space affects availability'),
67
+ as: z.string().optional().describe('Custom attachment name. Used for config vars prefix. Must be unique in app'),
68
+ name: z.string().optional().describe('Global add-on identifier. Must be unique across all Heroku add-ons'),
69
+ serviceAndPlan: z.string().describe('Format: service_slug:plan_slug (e.g., heroku-postgresql:essential-0)')
147
70
  });
148
71
  /**
149
72
  * Registers the create_addon tool with the MCP server.
150
- * This tool enables provisioning of new Heroku add-ons with customizable settings
151
- * for service plans, attachment names, and global identifiers.
152
73
  *
153
74
  * @param server - The MCP server instance to register the tool with
154
75
  * @param herokuRepl - The Heroku REPL instance for executing commands
155
76
  */
156
77
  export const registerCreateAddonTool = (server, herokuRepl) => {
157
- server.tool('create_addon', 'Create a new Heroku add-on for an application. Use this tool when you need to: ' +
158
- '1) Provision a new add-on for your app, 2) Specify a particular service and plan, ' +
159
- '3) Set a custom name for the add-on or attachment. The tool handles the provisioning process ' +
160
- "and returns the new add-on's details.", createAddonOptionsSchema.shape, async (options) => {
78
+ server.tool('create_addon', 'Create add-on: specify service, plan, custom names', createAddonOptionsSchema.shape, async (options) => {
161
79
  const command = new CommandBuilder(TOOL_COMMAND_MAP.CREATE_ADDON)
162
80
  .addFlags({
163
81
  app: options.app,
@@ -177,21 +95,16 @@ export const listAddonServicesOptionsSchema = z.object({
177
95
  json: z
178
96
  .boolean()
179
97
  .optional()
180
- .describe('Controls the output format. When true, returns a detailed JSON response containing additional add-on service ' +
181
- 'metadata such as sharing options and supported app generations. When false or omitted, returns a simplified ' +
182
- 'text format including only the add-on service slug, name and state.')
98
+ .describe('JSON output with sharing options and app generation support. Default: basic text')
183
99
  });
184
100
  /**
185
101
  * Registers the list_addon_services tool with the MCP server.
186
- * This tool provides information about available Heroku add-on services,
187
- * including their current state and supported features.
188
102
  *
189
103
  * @param server - The MCP server instance to register the tool with
190
104
  * @param herokuRepl - The Heroku REPL instance for executing commands
191
105
  */
192
106
  export const registerListAddonServicesTool = (server, herokuRepl) => {
193
- server.tool('list_addon_services', 'List available Heroku add-on services. Use this tool when you need to view all available add-on services. ' +
194
- 'Returns a list of add-on services with their basic information.', listAddonServicesOptionsSchema.shape, async (options) => {
107
+ server.tool('list_addon_services', 'List available add-on services and features', listAddonServicesOptionsSchema.shape, async (options) => {
195
108
  const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDON_SERVICES)
196
109
  .addFlags({
197
110
  json: options.json
@@ -205,30 +118,17 @@ export const registerListAddonServicesTool = (server, herokuRepl) => {
205
118
  * Schema for listing plans for a specific add-on service.
206
119
  */
207
120
  export const listAddonPlansOptionsSchema = z.object({
208
- service: z
209
- .string()
210
- .describe('Identifies the add-on service whose plans you want to list. Requirements and behaviors: ' +
211
- '1) Must be a valid service slug (e.g., "heroku-postgresql", "heroku-redis", etc.), ' +
212
- '2) Can be obtained from the list_addon_services command output. '),
213
- json: z
214
- .boolean()
215
- .optional()
216
- .describe('Controls the response format and detail level. When true, returns a structured JSON response containing ' +
217
- 'additional add-on plan metadata including descriptions, pricing and indicating if the plan is installable' +
218
- 'inside a private space or not. When false or omitted, returns a human-readable text format.')
121
+ service: z.string().describe('Service slug (e.g., heroku-postgresql). Get from list_addon_services'),
122
+ json: z.boolean().optional().describe('JSON output with pricing, features, space compatibility. Default: text format')
219
123
  });
220
124
  /**
221
125
  * Registers the list_addon_plans tool with the MCP server.
222
- * This tool provides detailed information about available plans for a specific
223
- * add-on service, including pricing, features, and provisioning requirements.
224
126
  *
225
127
  * @param server - The MCP server instance to register the tool with
226
128
  * @param herokuRepl - The Heroku REPL instance for executing commands
227
129
  */
228
130
  export const registerListAddonPlansTool = (server, herokuRepl) => {
229
- server.tool('list_addon_plans', 'List available plans for a specific Heroku add-on service. Use this tool when you need to: ' +
230
- '1) View all plans for a service, 2) Compare plan pricing, ' +
231
- '3) Check plan availability. Requires add-on service slug and returns detailed plan information.', listAddonPlansOptionsSchema.shape, async (options) => {
131
+ server.tool('list_addon_plans', 'List service plans: features, pricing, availability', listAddonPlansOptionsSchema.shape, async (options) => {
232
132
  const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDON_PLANS)
233
133
  .addFlags({
234
134
  json: options.json
@@ -54,18 +54,6 @@ describe('addons topic tools', () => {
54
54
  content: [{ type: 'text', text: expectedOutput }]
55
55
  });
56
56
  });
57
- it('executes command successfully with json flag', async () => {
58
- const expectedOutput = '[{"name": "postgresql-curved-12345", "plan": {"name": "heroku-postgresql:essential-0"}}]';
59
- const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDONS)
60
- .addFlags({ app: 'test-app', json: true })
61
- .build();
62
- herokuRepl.executeCommand.resolves(expectedOutput);
63
- const result = await toolCallback({ app: 'test-app', json: true }, {});
64
- expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
65
- expect(result).to.deep.equal({
66
- content: [{ type: 'text', text: expectedOutput }]
67
- });
68
- });
69
57
  });
70
58
  describe('registerGetAddonInfoTool', () => {
71
59
  let server;
@@ -208,18 +196,7 @@ describe('addons topic tools', () => {
208
196
  expect(call.args[0]).to.equal('list_addon_services');
209
197
  expect(call.args[2]).to.deep.equal(listAddonServicesOptionsSchema.shape);
210
198
  });
211
- it('executes command successfully with json flag', async () => {
212
- const expectedOutput = '[{"human_name": "Heroku PostgreSQL", "name": "heroku-postgresql", "state": "ga"},' +
213
- ' {"human_name": "Heroku Key-Value Store", "name": "heroku-redis", "state": "ga"}]';
214
- const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDON_SERVICES).addFlags({ json: true }).build();
215
- herokuRepl.executeCommand.resolves(expectedOutput);
216
- const result = await toolCallback({ json: true }, {});
217
- expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
218
- expect(result).to.deep.equal({
219
- content: [{ type: 'text', text: expectedOutput }]
220
- });
221
- });
222
- it('executes command successfully without json flag', async () => {
199
+ it('executes command successfully', async () => {
223
200
  const expectedOutput = ' Slug Name State \n' +
224
201
  ' ───────────────── ────────────────────── ───── \n' +
225
202
  ' heroku-postgresql Heroku PostgreSQL ga \n' +
@@ -255,21 +232,7 @@ describe('addons topic tools', () => {
255
232
  expect(call.args[0]).to.equal('list_addon_plans');
256
233
  expect(call.args[2]).to.deep.equal(listAddonPlansOptionsSchema.shape);
257
234
  });
258
- it('executes command successfully with json flag', async () => {
259
- const expectedOutput = '[{"installable_inside_private_network": false, "name": "essential-0", "price": {"cents": 500}}, ' +
260
- ' {"installable_inside_private_network": false, "name": "essential-1", "price": {"cents": 900}}]';
261
- const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDON_PLANS)
262
- .addFlags({ json: true })
263
- .addPositionalArguments({ service: 'heroku-postgresql' })
264
- .build();
265
- herokuRepl.executeCommand.resolves(expectedOutput);
266
- const result = await toolCallback({ service: 'heroku-postgresql', json: true }, {});
267
- expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
268
- expect(result).to.deep.equal({
269
- content: [{ type: 'text', text: expectedOutput }]
270
- });
271
- });
272
- it('executes command successfully without json flag', async () => {
235
+ it('executes command successfully', async () => {
273
236
  const expectedOutput = ' Slug Name Price Max price \n' +
274
237
  ' ─────── ────────────────────────────── ──────────── ───────────── ──────────── \n' +
275
238
  ' default heroku-postgresql:essential-0 Essential 0 ~$0.007/hour $5/month \n' +