@heroku/mcp-server 0.0.1-alpha.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.
Files changed (42) hide show
  1. package/LICENSE.txt +206 -0
  2. package/README.md +279 -0
  3. package/dist/index.js +86 -0
  4. package/dist/repl/heroku-cli-repl.js +210 -0
  5. package/dist/repl/heroku-cli-repl.spec.js +106 -0
  6. package/dist/services/app-service.js +42 -0
  7. package/dist/services/app-setup-service.js +72 -0
  8. package/dist/services/build-service.js +149 -0
  9. package/dist/services/source-service.js +42 -0
  10. package/dist/tools/addons.js +241 -0
  11. package/dist/tools/addons.spec.js +335 -0
  12. package/dist/tools/apps.js +222 -0
  13. package/dist/tools/apps.spec.js +332 -0
  14. package/dist/tools/data.js +345 -0
  15. package/dist/tools/data.spec.js +300 -0
  16. package/dist/tools/deploy-to-heroku.js +449 -0
  17. package/dist/tools/deploy-to-heroku.spec.js +166 -0
  18. package/dist/tools/logs.js +61 -0
  19. package/dist/tools/logs.spec.js +112 -0
  20. package/dist/tools/maintenance.js +55 -0
  21. package/dist/tools/maintenance.spec.js +115 -0
  22. package/dist/tools/pipelines.js +146 -0
  23. package/dist/tools/pipelines.spec.js +183 -0
  24. package/dist/tools/ps.js +99 -0
  25. package/dist/tools/ps.spec.js +127 -0
  26. package/dist/tools/spaces.js +34 -0
  27. package/dist/tools/spaces.spec.js +71 -0
  28. package/dist/tools/teams.js +37 -0
  29. package/dist/tools/teams.spec.js +69 -0
  30. package/dist/utils/app-json.schema.json +232 -0
  31. package/dist/utils/command-builder.js +61 -0
  32. package/dist/utils/command-builder.spec.js +95 -0
  33. package/dist/utils/generate-request-init.js +18 -0
  34. package/dist/utils/handle-cli-output.js +26 -0
  35. package/dist/utils/handle-cli-output.spec.js +54 -0
  36. package/dist/utils/mcp-tool-response.js +1 -0
  37. package/dist/utils/read-app-json.js +39 -0
  38. package/dist/utils/read-app-json.spec.js +106 -0
  39. package/dist/utils/tarball.js +114 -0
  40. package/dist/utils/tarball.spec.js +98 -0
  41. package/dist/utils/tool-commands.js +47 -0
  42. package/package.json +85 -0
@@ -0,0 +1,241 @@
1
+ import { z } from 'zod';
2
+ import { handleCliOutput } from '../utils/handle-cli-output.js';
3
+ import { CommandBuilder } from '../utils/command-builder.js';
4
+ import { TOOL_COMMAND_MAP } from '../utils/tool-commands.js';
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.
8
+ */
9
+ export const listAddonsOptionsSchema = z.object({
10
+ all: z
11
+ .boolean()
12
+ .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.'),
19
+ app: z
20
+ .string()
21
+ .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.')
38
+ });
39
+ /**
40
+ * 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
+ *
44
+ * @param server - The MCP server instance to register the tool with
45
+ * @param herokuRepl - The Heroku REPL instance for executing commands
46
+ */
47
+ 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) => {
51
+ const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDONS)
52
+ .addFlags({
53
+ all: options.all,
54
+ app: options.app,
55
+ json: options.json
56
+ })
57
+ .build();
58
+ const output = await herokuRepl.executeCommand(command);
59
+ return handleCliOutput(output);
60
+ });
61
+ };
62
+ /**
63
+ * Schema for getting information about a specific Heroku add-on.
64
+ */
65
+ 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.'),
77
+ app: z
78
+ .string()
79
+ .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.')
90
+ });
91
+ /**
92
+ * 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
+ *
96
+ * @param server - The MCP server instance to register the tool with
97
+ * @param herokuRepl - The Heroku REPL instance for executing commands
98
+ */
99
+ 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) => {
103
+ const command = new CommandBuilder(TOOL_COMMAND_MAP.GET_ADDON_INFO)
104
+ .addFlags({ app: options.app })
105
+ .addPositionalArguments({ addon: options.addon })
106
+ .build();
107
+ const output = await herokuRepl.executeCommand(command);
108
+ return handleCliOutput(output);
109
+ });
110
+ };
111
+ /**
112
+ * Schema for creating a new Heroku add-on.
113
+ */
114
+ 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.')
147
+ });
148
+ /**
149
+ * 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
+ *
153
+ * @param server - The MCP server instance to register the tool with
154
+ * @param herokuRepl - The Heroku REPL instance for executing commands
155
+ */
156
+ 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) => {
161
+ const command = new CommandBuilder(TOOL_COMMAND_MAP.CREATE_ADDON)
162
+ .addFlags({
163
+ app: options.app,
164
+ as: options.as,
165
+ name: options.name
166
+ })
167
+ .addPositionalArguments({ 'service:plan': options.serviceAndPlan })
168
+ .build();
169
+ const output = await herokuRepl.executeCommand(command);
170
+ return handleCliOutput(output);
171
+ });
172
+ };
173
+ /**
174
+ * Schema for listing available add-on services.
175
+ */
176
+ export const listAddonServicesOptionsSchema = z.object({
177
+ json: z
178
+ .boolean()
179
+ .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.')
183
+ });
184
+ /**
185
+ * 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
+ *
189
+ * @param server - The MCP server instance to register the tool with
190
+ * @param herokuRepl - The Heroku REPL instance for executing commands
191
+ */
192
+ 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) => {
195
+ const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDON_SERVICES)
196
+ .addFlags({
197
+ json: options.json
198
+ })
199
+ .build();
200
+ const output = await herokuRepl.executeCommand(command);
201
+ return handleCliOutput(output);
202
+ });
203
+ };
204
+ /**
205
+ * Schema for listing plans for a specific add-on service.
206
+ */
207
+ 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.')
219
+ });
220
+ /**
221
+ * 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
+ *
225
+ * @param server - The MCP server instance to register the tool with
226
+ * @param herokuRepl - The Heroku REPL instance for executing commands
227
+ */
228
+ 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) => {
232
+ const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDON_PLANS)
233
+ .addFlags({
234
+ json: options.json
235
+ })
236
+ .addPositionalArguments({ service: options.service })
237
+ .build();
238
+ const output = await herokuRepl.executeCommand(command);
239
+ return handleCliOutput(output);
240
+ });
241
+ };
@@ -0,0 +1,335 @@
1
+ import { expect } from 'chai';
2
+ import sinon from 'sinon';
3
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
4
+ import { HerokuREPL } from '../repl/heroku-cli-repl.js';
5
+ import { listAddonsOptionsSchema, getAddonInfoOptionsSchema, createAddonOptionsSchema, listAddonServicesOptionsSchema, listAddonPlansOptionsSchema, registerListAddonsTool, registerGetAddonInfoTool, registerCreateAddonTool, registerListAddonServicesTool, registerListAddonPlansTool } from './addons.js';
6
+ import { CommandBuilder } from '../utils/command-builder.js';
7
+ import { TOOL_COMMAND_MAP } from '../utils/tool-commands.js';
8
+ describe('addons topic tools', () => {
9
+ describe('registerListAddonsTool', () => {
10
+ let server;
11
+ let herokuRepl;
12
+ let toolCallback;
13
+ beforeEach(() => {
14
+ server = sinon.createStubInstance(McpServer);
15
+ herokuRepl = sinon.createStubInstance(HerokuREPL);
16
+ server.tool.callsFake((_name, _description, _schema, callback) => {
17
+ toolCallback = callback;
18
+ return server;
19
+ });
20
+ registerListAddonsTool(server, herokuRepl);
21
+ });
22
+ afterEach(() => {
23
+ sinon.restore();
24
+ });
25
+ it('registers the tool with correct name and schema', () => {
26
+ expect(server.tool.calledOnce).to.be.true;
27
+ const call = server.tool.getCall(0);
28
+ expect(call.args[0]).to.equal('list_addons');
29
+ expect(call.args[2]).to.deep.equal(listAddonsOptionsSchema.shape);
30
+ });
31
+ it('executes command successfully with all flag', async () => {
32
+ const expectedOutput = ' Owning app Add-on Plan Price Max price State \n' +
33
+ ' ────────── ─────────────────────── ───────────────────────────── ──────────── ───────── ─────── \n' +
34
+ ' test-app postgresql-curved-12345 heroku-postgresql:essential-0 ~$0.007/hour $5/month created \n' +
35
+ ' test-app-2 redis-elliptical-12345 heroku-redis:mini ~$0.004/hour $3/month created \n';
36
+ const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDONS).addFlags({ all: true }).build();
37
+ herokuRepl.executeCommand.resolves(expectedOutput);
38
+ const result = await toolCallback({ all: true }, {});
39
+ expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
40
+ expect(result).to.deep.equal({
41
+ content: [{ type: 'text', text: expectedOutput }]
42
+ });
43
+ });
44
+ it('executes command successfully with app flag', async () => {
45
+ const expectedOutput = ' Add-on Plan Price Max price State \n' +
46
+ ' ───────────────────────────────────── ──── ──────────── ───────── ─────── \n' +
47
+ ' heroku-redis (redis-elliptical-12345) mini ~$0.004/hour $3/month created \n' +
48
+ ' └─ as REDIS_TEST_DB \n';
49
+ const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDONS).addFlags({ app: 'test-app-2' }).build();
50
+ herokuRepl.executeCommand.resolves(expectedOutput);
51
+ const result = await toolCallback({ app: 'test-app-2' }, {});
52
+ expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
53
+ expect(result).to.deep.equal({
54
+ content: [{ type: 'text', text: expectedOutput }]
55
+ });
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
+ });
70
+ describe('registerGetAddonInfoTool', () => {
71
+ let server;
72
+ let herokuRepl;
73
+ let toolCallback;
74
+ beforeEach(() => {
75
+ server = sinon.createStubInstance(McpServer);
76
+ herokuRepl = sinon.createStubInstance(HerokuREPL);
77
+ server.tool.callsFake((_name, _description, _schema, callback) => {
78
+ toolCallback = callback;
79
+ return server;
80
+ });
81
+ registerGetAddonInfoTool(server, herokuRepl);
82
+ });
83
+ afterEach(() => {
84
+ sinon.restore();
85
+ });
86
+ it('registers the tool with correct name and schema', () => {
87
+ expect(server.tool.calledOnce).to.be.true;
88
+ const call = server.tool.getCall(0);
89
+ expect(call.args[0]).to.equal('get_addon_info');
90
+ expect(call.args[2]).to.deep.equal(getAddonInfoOptionsSchema.shape);
91
+ });
92
+ it('executes command successfully with add-on name', async () => {
93
+ const expectedOutput = '=== postgresql-curved-12345\n\n' +
94
+ 'Attachments: test-app::DATABASE\n' +
95
+ 'Owning App: test-app\n' +
96
+ 'Plan: heroku-postgresql:essential-0\n';
97
+ const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.GET_ADDON_INFO)
98
+ .addPositionalArguments({ addon: 'postgresql-curved-12345' })
99
+ .build();
100
+ herokuRepl.executeCommand.resolves(expectedOutput);
101
+ const result = await toolCallback({ addon: 'postgresql-curved-12345' }, {});
102
+ expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
103
+ expect(result).to.deep.equal({
104
+ content: [{ type: 'text', text: expectedOutput }]
105
+ });
106
+ });
107
+ it('executes command successfully with app context', async () => {
108
+ const expectedOutput = '=== postgresql-curved-12345\n\n' +
109
+ 'Attachments: test-app::DATABASE\n' +
110
+ 'Owning App: test-app\n' +
111
+ 'Plan: heroku-postgresql:essential-0\n';
112
+ const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.GET_ADDON_INFO)
113
+ .addPositionalArguments({ addon: 'DATABASE' })
114
+ .addFlags({ app: 'test-app' })
115
+ .build();
116
+ herokuRepl.executeCommand.resolves(expectedOutput);
117
+ const result = await toolCallback({ addon: 'DATABASE', app: 'test-app' }, {});
118
+ expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
119
+ expect(result).to.deep.equal({
120
+ content: [{ type: 'text', text: expectedOutput }]
121
+ });
122
+ });
123
+ });
124
+ describe('registerCreateAddonTool', () => {
125
+ let server;
126
+ let herokuRepl;
127
+ let toolCallback;
128
+ beforeEach(() => {
129
+ server = sinon.createStubInstance(McpServer);
130
+ herokuRepl = sinon.createStubInstance(HerokuREPL);
131
+ server.tool.callsFake((_name, _description, _schema, callback) => {
132
+ toolCallback = callback;
133
+ return server;
134
+ });
135
+ registerCreateAddonTool(server, herokuRepl);
136
+ });
137
+ afterEach(() => {
138
+ sinon.restore();
139
+ });
140
+ it('registers the tool with correct name and schema', () => {
141
+ expect(server.tool.calledOnce).to.be.true;
142
+ const call = server.tool.getCall(0);
143
+ expect(call.args[0]).to.equal('create_addon');
144
+ expect(call.args[2]).to.deep.equal(createAddonOptionsSchema.shape);
145
+ });
146
+ it('executes command successfully with all options', async () => {
147
+ const expectedOutput = 'Creating heroku-postgresql:essential-0 on test-app... ~$0.007/hour (max $5/month)\n' +
148
+ 'Database should be available soon\n' +
149
+ 'test-app-primary-db is being created in the background. The app will restart when complete...\n';
150
+ const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.CREATE_ADDON)
151
+ .addFlags({
152
+ app: 'test-app',
153
+ as: 'DATABASE',
154
+ name: 'test-app-primary-db'
155
+ })
156
+ .addPositionalArguments({ 'service:plan': 'heroku-postgresql:essential-0' })
157
+ .build();
158
+ herokuRepl.executeCommand.resolves(expectedOutput);
159
+ const result = await toolCallback({
160
+ app: 'test-app',
161
+ as: 'DATABASE',
162
+ name: 'test-app-primary-db',
163
+ serviceAndPlan: 'heroku-postgresql:essential-0'
164
+ }, {});
165
+ expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
166
+ expect(result).to.deep.equal({
167
+ content: [{ type: 'text', text: expectedOutput }]
168
+ });
169
+ });
170
+ it('executes command successfully with minimal options', async () => {
171
+ const expectedOutput = 'Creating heroku-postgresql:essential-0 on test-app... ~$0.007/hour (max $5/month)\n' +
172
+ 'Database should be available soon\n' +
173
+ 'postgresql-curved-12345 is being created in the background. The app will restart when complete...\n';
174
+ const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.CREATE_ADDON)
175
+ .addFlags({ app: 'test-app' })
176
+ .addPositionalArguments({ 'service:plan': 'heroku-postgresql:essential-0' })
177
+ .build();
178
+ herokuRepl.executeCommand.resolves(expectedOutput);
179
+ const result = await toolCallback({
180
+ app: 'test-app',
181
+ serviceAndPlan: 'heroku-postgresql:essential-0'
182
+ }, {});
183
+ expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
184
+ expect(result).to.deep.equal({
185
+ content: [{ type: 'text', text: expectedOutput }]
186
+ });
187
+ });
188
+ });
189
+ describe('registerListAddonServicesTool', () => {
190
+ let server;
191
+ let herokuRepl;
192
+ let toolCallback;
193
+ beforeEach(() => {
194
+ server = sinon.createStubInstance(McpServer);
195
+ herokuRepl = sinon.createStubInstance(HerokuREPL);
196
+ server.tool.callsFake((_name, _description, _schema, callback) => {
197
+ toolCallback = callback;
198
+ return server;
199
+ });
200
+ registerListAddonServicesTool(server, herokuRepl);
201
+ });
202
+ afterEach(() => {
203
+ sinon.restore();
204
+ });
205
+ it('registers the tool with correct name and schema', () => {
206
+ expect(server.tool.calledOnce).to.be.true;
207
+ const call = server.tool.getCall(0);
208
+ expect(call.args[0]).to.equal('list_addon_services');
209
+ expect(call.args[2]).to.deep.equal(listAddonServicesOptionsSchema.shape);
210
+ });
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 () => {
223
+ const expectedOutput = ' Slug Name State \n' +
224
+ ' ───────────────── ────────────────────── ───── \n' +
225
+ ' heroku-postgresql Heroku PostgreSQL ga \n' +
226
+ ' heroku-redis Heroku Key-Value Store ga \n';
227
+ const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDON_SERVICES).build();
228
+ herokuRepl.executeCommand.resolves(expectedOutput);
229
+ const result = await toolCallback({}, {});
230
+ expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
231
+ expect(result).to.deep.equal({
232
+ content: [{ type: 'text', text: expectedOutput }]
233
+ });
234
+ });
235
+ });
236
+ describe('registerListAddonPlansTool', () => {
237
+ let server;
238
+ let herokuRepl;
239
+ let toolCallback;
240
+ beforeEach(() => {
241
+ server = sinon.createStubInstance(McpServer);
242
+ herokuRepl = sinon.createStubInstance(HerokuREPL);
243
+ server.tool.callsFake((_name, _description, _schema, callback) => {
244
+ toolCallback = callback;
245
+ return server;
246
+ });
247
+ registerListAddonPlansTool(server, herokuRepl);
248
+ });
249
+ afterEach(() => {
250
+ sinon.restore();
251
+ });
252
+ it('registers the tool with correct name and schema', () => {
253
+ expect(server.tool.calledOnce).to.be.true;
254
+ const call = server.tool.getCall(0);
255
+ expect(call.args[0]).to.equal('list_addon_plans');
256
+ expect(call.args[2]).to.deep.equal(listAddonPlansOptionsSchema.shape);
257
+ });
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 () => {
273
+ const expectedOutput = ' Slug Name Price Max price \n' +
274
+ ' ─────── ────────────────────────────── ──────────── ───────────── ──────────── \n' +
275
+ ' default heroku-postgresql:essential-0 Essential 0 ~$0.007/hour $5/month \n' +
276
+ ' heroku-postgresql:essential-1 Essential 1 ~$0.013/hour $9/month \n';
277
+ const expectedCommand = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDON_PLANS)
278
+ .addPositionalArguments({ service: 'heroku-postgresql' })
279
+ .build();
280
+ herokuRepl.executeCommand.resolves(expectedOutput);
281
+ const result = await toolCallback({ service: 'heroku-postgresql' }, {});
282
+ expect(herokuRepl.executeCommand.calledOnceWith(expectedCommand)).to.be.true;
283
+ expect(result).to.deep.equal({
284
+ content: [{ type: 'text', text: expectedOutput }]
285
+ });
286
+ });
287
+ });
288
+ // Common error handling test for all tools
289
+ describe('error handling', () => {
290
+ let server;
291
+ let herokuRepl;
292
+ let toolCallback;
293
+ beforeEach(() => {
294
+ server = sinon.createStubInstance(McpServer);
295
+ herokuRepl = sinon.createStubInstance(HerokuREPL);
296
+ server.tool.callsFake((_name, _description, _schema, callback) => {
297
+ toolCallback = callback;
298
+ return server;
299
+ });
300
+ });
301
+ afterEach(() => {
302
+ sinon.restore();
303
+ });
304
+ it('handles CLI errors properly for all tools', async () => {
305
+ const expectedOutput = '<<<BEGIN RESULTS>>>\n<<<ERROR>>>API error<<<END ERROR>>><<<END RESULTS>>>';
306
+ herokuRepl.executeCommand.resolves(expectedOutput);
307
+ // Test error handling for each tool
308
+ const tools = [
309
+ { register: registerListAddonsTool, options: {} },
310
+ { register: registerGetAddonInfoTool, options: { addon: 'test-addon' } },
311
+ {
312
+ register: registerCreateAddonTool,
313
+ options: { app: 'test-app', serviceAndPlan: 'heroku-postgresql:essential-0' }
314
+ },
315
+ { register: registerListAddonServicesTool, options: {} },
316
+ { register: registerListAddonPlansTool, options: { service: 'heroku-postgresql' } }
317
+ ];
318
+ for (const tool of tools) {
319
+ tool.register(server, herokuRepl);
320
+ const result = await toolCallback(tool.options, {});
321
+ expect(result).to.deep.equal({
322
+ isError: true,
323
+ content: [
324
+ {
325
+ type: 'text',
326
+ text: '[Heroku MCP Server Error] Please use available tools to resolve this issue. ' +
327
+ 'Ignore any Heroku CLI command suggestions that may be provided in the command output or error ' +
328
+ `details. Details:\n${expectedOutput}`
329
+ }
330
+ ]
331
+ });
332
+ }
333
+ });
334
+ });
335
+ });