@heroku/mcp-server 1.1.0 → 1.2.0-beta.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
@@ -1,7 +1,6 @@
1
1
  # heroku-mcp-server
2
2
 
3
3
  [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=heroku&config=eyJjb21tYW5kIjoibnB4IC15IEBoZXJva3UvbWNwLXNlcnZlciIsImVudiI6eyJIRVJPS1VfQVBJX0tFWSI6IjxZT1VSX0hFUk9LVV9BVVRIX1RPS0VOPiJ9fQ%3D%3D)
4
- [![smithery badge](https://smithery.ai/badge/@heroku/heroku-mcp-server)](https://smithery.ai/server/@heroku/heroku-mcp-server)
5
4
 
6
5
  > The Heroku Platform MCP Server works on Common Runtime, Cedar Private and Shield Spaces, and Fir Private Spaces.
7
6
 
@@ -478,15 +477,6 @@ To set up local debugging with breakpoints:
478
477
 
479
478
  Note: the debugger automatically builds your TypeScript files before launching.
480
479
 
481
- ### Installing via Smithery
482
-
483
- To install Heroku Platform MCP Server for Claude Desktop automatically via
484
- [Smithery](https://smithery.ai/server/@heroku/heroku-mcp-server):
485
-
486
- ```bash
487
- npx -y @smithery/cli install @heroku/heroku-mcp-server --client claude
488
- ```
489
-
490
480
  ## Environment Variables
491
481
 
492
482
  The Heroku Platform MCP Server supports the following environment variables:
package/dist/index.js CHANGED
@@ -15,6 +15,7 @@ import * as logs from './tools/logs.js';
15
15
  import * as ai from './tools/ai.js';
16
16
  import * as devCenterResource from './resources/dev-center-resource.js';
17
17
  import { HerokuREPL } from './repl/heroku-cli-repl.js';
18
+ import { isPluginInstalled } from './utils/plugin-detector.js';
18
19
  const VERSION = pjson.default.version;
19
20
  const server = new McpServer({ name: 'Heroku MCP Server', version: VERSION }, {
20
21
  capabilities: {
@@ -75,10 +76,17 @@ pipelines.registerPipelinesInfoTool(server, herokuRepl);
75
76
  // Deploy-to-Heroku tool
76
77
  deployToHeroku.registerDeployToHerokuTool(server);
77
78
  deployToHeroku.registerDeployOneOffDynoTool(server);
78
- // AI-related tools
79
- ai.registerListAiAvailableModelsTool(server, herokuRepl);
80
- ai.registerProvisionAiModelTool(server, herokuRepl);
81
- ai.registerMakeAiInferenceTool(server, herokuRepl);
79
+ // AI-related tools (only register if plugin is installed)
80
+ const hasAiPlugin = isPluginInstalled('@heroku/plugin-ai');
81
+ if (hasAiPlugin) {
82
+ process.stderr.write('[Plugin Check] @heroku/plugin-ai: INSTALLED - Registering AI tools\n');
83
+ ai.registerListAiAvailableModelsTool(server, herokuRepl);
84
+ ai.registerProvisionAiModelTool(server, herokuRepl);
85
+ ai.registerMakeAiInferenceTool(server, herokuRepl);
86
+ }
87
+ else {
88
+ process.stderr.write('[Plugin Check] @heroku/plugin-ai: NOT INSTALLED - Skipping AI tools\n');
89
+ }
82
90
  // Register the Dev Center resource
83
91
  devCenterResource.registerDevCenterResource(server);
84
92
  /**
@@ -61,7 +61,7 @@ export class HerokuREPL extends EventEmitter {
61
61
  * async iterator that yields the commands being executed
62
62
  *
63
63
  * @returns An async iterator that yields the commands being executed
64
- * @yields the command being executed
64
+ * @yields {Promise<string>} the command being executed
65
65
  */
66
66
  async *[Symbol.asyncIterator]() {
67
67
  while (!this.abortController.signal.aborted) {
@@ -106,13 +106,20 @@ export class HerokuREPL extends EventEmitter {
106
106
  */
107
107
  getHerokuCliCommandAndArgs() {
108
108
  // Check for npx presence
109
- const npxCheck = HerokuREPL.spawnSync('npx', ['--version'], { encoding: 'utf-8' });
109
+ // On Windows, we need to use shell: true to find npx.cmd
110
+ const npxCheck = HerokuREPL.spawnSync('npx', ['--version'], {
111
+ encoding: 'utf-8',
112
+ shell: process.platform === 'win32'
113
+ });
110
114
  if (!npxCheck.error && npxCheck.status === 0) {
111
115
  return { cliCommand: 'npx', cliArgs: ['-y', 'heroku@latest', '--repl'] };
112
116
  }
113
117
  else {
114
118
  // Fallback: check for heroku CLI and version
115
- const herokuCheck = HerokuREPL.spawnSync('heroku', ['version'], { encoding: 'utf-8' });
119
+ const herokuCheck = HerokuREPL.spawnSync('heroku', ['version'], {
120
+ encoding: 'utf-8',
121
+ shell: process.platform === 'win32'
122
+ });
116
123
  if (!herokuCheck.error &&
117
124
  herokuCheck.status === 0 &&
118
125
  typeof herokuCheck.stdout === 'string' &&
@@ -161,6 +168,7 @@ export class HerokuREPL extends EventEmitter {
161
168
  this.process = HerokuREPL.spawn(cliCommand, cliArgs, {
162
169
  stdio: ['pipe', 'pipe', 'pipe'],
163
170
  signal: this.abortController.signal,
171
+ shell: process.platform === 'win32',
164
172
  env: {
165
173
  ...process.env,
166
174
  HEROKU_MCP_MODE: 'true',
@@ -154,7 +154,7 @@ describe('HerokuREPL', () => {
154
154
  spawnSyncStub.restore();
155
155
  });
156
156
  it('should return npx command when npx is available', () => {
157
- spawnSyncStub.withArgs('npx', ['--version'], { encoding: 'utf-8' }).returns({
157
+ spawnSyncStub.withArgs('npx', ['--version'], sinon.match({ encoding: 'utf-8' })).returns({
158
158
  error: null,
159
159
  status: 0,
160
160
  stdout: '9.8.1'
@@ -168,13 +168,13 @@ describe('HerokuREPL', () => {
168
168
  });
169
169
  it('should return heroku command when npx is not available but heroku CLI >= 10.10.0 is available', () => {
170
170
  // npx not available
171
- spawnSyncStub.withArgs('npx', ['--version'], { encoding: 'utf-8' }).returns({
171
+ spawnSyncStub.withArgs('npx', ['--version'], sinon.match({ encoding: 'utf-8' })).returns({
172
172
  error: new Error('npx not found'),
173
173
  status: 1,
174
174
  stdout: ''
175
175
  });
176
176
  // heroku CLI available with version >= 10.10.0
177
- spawnSyncStub.withArgs('heroku', ['version'], { encoding: 'utf-8' }).returns({
177
+ spawnSyncStub.withArgs('heroku', ['version'], sinon.match({ encoding: 'utf-8' })).returns({
178
178
  error: null,
179
179
  status: 0,
180
180
  stdout: 'heroku/10.15.0 (darwin-x64) node-v18.17.0'
@@ -188,13 +188,13 @@ describe('HerokuREPL', () => {
188
188
  });
189
189
  it('should return heroku command when npx is not available but heroku CLI > 10.x is available', () => {
190
190
  // npx not available
191
- spawnSyncStub.withArgs('npx', ['--version'], { encoding: 'utf-8' }).returns({
191
+ spawnSyncStub.withArgs('npx', ['--version'], sinon.match({ encoding: 'utf-8' })).returns({
192
192
  error: new Error('npx not found'),
193
193
  status: 1,
194
194
  stdout: ''
195
195
  });
196
196
  // heroku CLI available with version > 10.x
197
- spawnSyncStub.withArgs('heroku', ['version'], { encoding: 'utf-8' }).returns({
197
+ spawnSyncStub.withArgs('heroku', ['version'], sinon.match({ encoding: 'utf-8' })).returns({
198
198
  error: null,
199
199
  status: 0,
200
200
  stdout: 'heroku/11.0.0 (darwin-x64) node-v18.17.0'
@@ -208,13 +208,13 @@ describe('HerokuREPL', () => {
208
208
  });
209
209
  it('should emit fatalError and return null when npx is not available and heroku CLI < 10.10.0 is available', () => {
210
210
  // npx not available
211
- spawnSyncStub.withArgs('npx', ['--version'], { encoding: 'utf-8' }).returns({
211
+ spawnSyncStub.withArgs('npx', ['--version'], sinon.match({ encoding: 'utf-8' })).returns({
212
212
  error: new Error('npx not found'),
213
213
  status: 1,
214
214
  stdout: ''
215
215
  });
216
216
  // heroku CLI available but version < 10.10.0
217
- spawnSyncStub.withArgs('heroku', ['version'], { encoding: 'utf-8' }).returns({
217
+ spawnSyncStub.withArgs('heroku', ['version'], sinon.match({ encoding: 'utf-8' })).returns({
218
218
  error: null,
219
219
  status: 0,
220
220
  stdout: 'heroku/10.9.0 (darwin-x64) node-v18.17.0'
@@ -228,13 +228,13 @@ describe('HerokuREPL', () => {
228
228
  });
229
229
  it('should emit fatalError and return null when npx is not available and heroku CLI is not available', () => {
230
230
  // npx not available
231
- spawnSyncStub.withArgs('npx', ['--version'], { encoding: 'utf-8' }).returns({
231
+ spawnSyncStub.withArgs('npx', ['--version'], sinon.match({ encoding: 'utf-8' })).returns({
232
232
  error: new Error('npx not found'),
233
233
  status: 1,
234
234
  stdout: ''
235
235
  });
236
236
  // heroku CLI not available
237
- spawnSyncStub.withArgs('heroku', ['version'], { encoding: 'utf-8' }).returns({
237
+ spawnSyncStub.withArgs('heroku', ['version'], sinon.match({ encoding: 'utf-8' })).returns({
238
238
  error: new Error('heroku not found'),
239
239
  status: 1,
240
240
  stdout: ''
@@ -247,13 +247,13 @@ describe('HerokuREPL', () => {
247
247
  });
248
248
  it('should emit fatalError and return null when npx is not available and heroku CLI version format is unexpected', () => {
249
249
  // npx not available
250
- spawnSyncStub.withArgs('npx', ['--version'], { encoding: 'utf-8' }).returns({
250
+ spawnSyncStub.withArgs('npx', ['--version'], sinon.match({ encoding: 'utf-8' })).returns({
251
251
  error: new Error('npx not found'),
252
252
  status: 1,
253
253
  stdout: ''
254
254
  });
255
255
  // heroku CLI available but version format is unexpected
256
- spawnSyncStub.withArgs('heroku', ['version'], { encoding: 'utf-8' }).returns({
256
+ spawnSyncStub.withArgs('heroku', ['version'], sinon.match({ encoding: 'utf-8' })).returns({
257
257
  error: null,
258
258
  status: 0,
259
259
  stdout: 'some unexpected output without version'
@@ -266,13 +266,13 @@ describe('HerokuREPL', () => {
266
266
  });
267
267
  it('should emit fatalError and return null when npx is not available and heroku CLI returns error', () => {
268
268
  // npx not available
269
- spawnSyncStub.withArgs('npx', ['--version'], { encoding: 'utf-8' }).returns({
269
+ spawnSyncStub.withArgs('npx', ['--version'], sinon.match({ encoding: 'utf-8' })).returns({
270
270
  error: new Error('npx not found'),
271
271
  status: 1,
272
272
  stdout: ''
273
273
  });
274
274
  // heroku CLI returns error
275
- spawnSyncStub.withArgs('heroku', ['version'], { encoding: 'utf-8' }).returns({
275
+ spawnSyncStub.withArgs('heroku', ['version'], sinon.match({ encoding: 'utf-8' })).returns({
276
276
  error: new Error('heroku command failed'),
277
277
  status: 1,
278
278
  stdout: ''
@@ -285,13 +285,13 @@ describe('HerokuREPL', () => {
285
285
  });
286
286
  it('should emit fatalError and return null when npx is not available and heroku CLI stdout is not a string', () => {
287
287
  // npx not available
288
- spawnSyncStub.withArgs('npx', ['--version'], { encoding: 'utf-8' }).returns({
288
+ spawnSyncStub.withArgs('npx', ['--version'], sinon.match({ encoding: 'utf-8' })).returns({
289
289
  error: new Error('npx not found'),
290
290
  status: 1,
291
291
  stdout: ''
292
292
  });
293
293
  // heroku CLI available but stdout is not a string
294
- spawnSyncStub.withArgs('heroku', ['version'], { encoding: 'utf-8' }).returns({
294
+ spawnSyncStub.withArgs('heroku', ['version'], sinon.match({ encoding: 'utf-8' })).returns({
295
295
  error: null,
296
296
  status: 0,
297
297
  stdout: Buffer.from('heroku/10.15.0')
@@ -4,6 +4,7 @@
4
4
  *
5
5
  * When the output contains error markers (<<<ERROR>>>...<<<END ERROR>>>), it formats
6
6
  * the error message with a standardized prefix and returns an error response.
7
+ * Detects missing CLI commands/plugins based on oclif v4 error patterns.
7
8
  * Otherwise, it returns the command output as a successful response.
8
9
  *
9
10
  * @param output - The output string from the Heroku REPL command execution
@@ -15,6 +16,21 @@ export function handleCliOutput(output) {
15
16
  if (errorMatch || !output) {
16
17
  const baseMessage = '[Heroku MCP Server Error] Please use available tools to resolve this issue. Ignore any Heroku CLI command ' +
17
18
  'suggestions that may be provided in the command output or error details. ';
19
+ // Check for missing command error (oclif v4 format: "is not a heroku command")
20
+ const missingCommandPattern = /is not a heroku command/i;
21
+ const isMissingCommand = missingCommandPattern.test(output || '');
22
+ if (isMissingCommand) {
23
+ const commandNotFoundMessage = '\n\nThe requested command was not found in your Heroku CLI installation.';
24
+ return {
25
+ isError: true,
26
+ content: [
27
+ {
28
+ type: 'text',
29
+ text: `${baseMessage}Details:\n${output || 'No response from command'}${commandNotFoundMessage}`
30
+ }
31
+ ]
32
+ };
33
+ }
18
34
  return {
19
35
  isError: true,
20
36
  content: [{ type: 'text', text: `${baseMessage}Details:\n${output || 'No response from command'}` }]
@@ -28,6 +28,24 @@ describe('handleCliOutput', () => {
28
28
  content: [{ type: 'text', text: `${baseMessage}Details:\n${output}` }]
29
29
  });
30
30
  });
31
+ it('handles missing command error with appropriate message', () => {
32
+ const output = '<<<ERROR>>>› Warning: ai:models:list is not a heroku command.\nDid you mean container:login? (Y/n)\n› Error: Run heroku help for a list of available commands.<<<END ERROR>>>';
33
+ const result = handleCliOutput(output);
34
+ const commandNotFoundMessage = '\n\nThe requested command was not found in your Heroku CLI installation.';
35
+ expect(result).to.deep.equal({
36
+ isError: true,
37
+ content: [{ type: 'text', text: `${baseMessage}Details:\n${output}${commandNotFoundMessage}` }]
38
+ });
39
+ });
40
+ it('handles missing command error case-insensitively', () => {
41
+ const output = '<<<ERROR>>>somecommand IS NOT A HEROKU COMMAND<<<END ERROR>>>';
42
+ const result = handleCliOutput(output);
43
+ const commandNotFoundMessage = '\n\nThe requested command was not found in your Heroku CLI installation.';
44
+ expect(result).to.deep.equal({
45
+ isError: true,
46
+ content: [{ type: 'text', text: `${baseMessage}Details:\n${output}${commandNotFoundMessage}` }]
47
+ });
48
+ });
31
49
  });
32
50
  describe('success handling', () => {
33
51
  it('handles normal output without error markers', () => {
@@ -0,0 +1,24 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ /**
3
+ * Detects if a Heroku CLI plugin is installed
4
+ *
5
+ * @param pluginName - The name of the plugin to check (e.g., '@heroku/plugin-ai')
6
+ * @param spawnFn - Optional spawn function for testing
7
+ * @returns true if the plugin is installed, false otherwise
8
+ */
9
+ export function isPluginInstalled(pluginName, spawnFn = spawnSync) {
10
+ try {
11
+ // Use plugins:inspect to detect if specific plugin is installed
12
+ const result = spawnFn('heroku', ['plugins:inspect', pluginName], {
13
+ encoding: 'utf-8',
14
+ timeout: 5000
15
+ });
16
+ // If the command succeeds (status 0), the plugin is installed
17
+ // If it fails (non-zero status), the plugin is not installed
18
+ return result.status === 0 && !result.error;
19
+ }
20
+ catch {
21
+ // If any error occurs, assume plugin is not installed
22
+ return false;
23
+ }
24
+ }
@@ -0,0 +1,55 @@
1
+ import { expect } from 'chai';
2
+ import { isPluginInstalled } from './plugin-detector.js';
3
+ describe('isPluginInstalled', () => {
4
+ it('returns true when plugin is installed (plugins:inspect succeeds)', () => {
5
+ const mockSpawn = (cmd, args) => {
6
+ // Verify correct command is called
7
+ expect(cmd).to.equal('heroku');
8
+ expect(args).to.deep.equal(['plugins:inspect', '@heroku/plugin-ai']);
9
+ return {
10
+ status: 0,
11
+ stdout: 'Plugin info...',
12
+ stderr: '',
13
+ error: undefined,
14
+ signal: null,
15
+ output: [null, 'Plugin info...', ''],
16
+ pid: 12345
17
+ };
18
+ };
19
+ const result = isPluginInstalled('@heroku/plugin-ai', mockSpawn);
20
+ expect(result).to.be.true;
21
+ });
22
+ it('returns false when plugin is not installed (plugins:inspect fails)', () => {
23
+ const mockSpawn = () => ({
24
+ status: 1,
25
+ stdout: '',
26
+ stderr: 'Error: Plugin not found',
27
+ error: undefined,
28
+ signal: null,
29
+ output: [null, '', 'Error: Plugin not found'],
30
+ pid: 12345
31
+ });
32
+ const result = isPluginInstalled('@heroku/plugin-ai', mockSpawn);
33
+ expect(result).to.be.false;
34
+ });
35
+ it('returns false when heroku command has an error', () => {
36
+ const mockSpawn = () => ({
37
+ status: 1,
38
+ stdout: '',
39
+ stderr: 'Command failed',
40
+ error: new Error('Command failed'),
41
+ signal: null,
42
+ output: [null, '', 'Command failed'],
43
+ pid: 12345
44
+ });
45
+ const result = isPluginInstalled('@heroku/plugin-ai', mockSpawn);
46
+ expect(result).to.be.false;
47
+ });
48
+ it('returns false when spawnSync throws an exception', () => {
49
+ const mockSpawn = () => {
50
+ throw new Error('Spawn error');
51
+ };
52
+ const result = isPluginInstalled('@heroku/plugin-ai', mockSpawn);
53
+ expect(result).to.be.false;
54
+ });
55
+ });
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@heroku/mcp-server",
3
3
  "description": "Heroku Platform MCP Server",
4
- "version": "1.1.0",
4
+ "version": "1.2.0-beta.0",
5
5
  "author": "Heroku",
6
6
  "bugs": "https://github.com/heroku/heroku-mcp-server/issues",
7
7
  "bin": {
@@ -9,38 +9,38 @@
9
9
  },
10
10
  "type": "module",
11
11
  "dependencies": {
12
- "@heroku/plugin-ai": "^1.0.1",
13
- "@modelcontextprotocol/sdk": "^1.16.0",
14
- "cheerio": "^1.1.0",
12
+ "@heroku-cli/schema": "^2.0.1",
13
+ "@modelcontextprotocol/sdk": "^1.26.0",
14
+ "cheerio": "^1.2.0",
15
15
  "jsonschema": "^1.5.0",
16
16
  "node-fetch": "^3.3.2",
17
17
  "tar-stream": "^3.1.7",
18
- "zod": "^3.24.2",
19
- "zod-to-json-schema": "^3.24.5"
18
+ "zod": "^3.25.76",
19
+ "zod-to-json-schema": "^3.25.1"
20
20
  },
21
21
  "devDependencies": {
22
- "@eslint/eslintrc": "^3.3.1",
23
- "@eslint/js": "^9.23.0",
22
+ "@anthropic-ai/mcpb": "^2.1.2",
23
+ "@eslint/eslintrc": "^3.3.3",
24
+ "@eslint/js": "^9.39.2",
24
25
  "@types/chai": "^5.2.1",
25
26
  "@types/mocha": "^10.0.10",
26
- "@types/node": "^20.x",
27
- "@types/sinon": "^17.0.4",
27
+ "@types/node": "^22.x",
28
+ "@types/sinon": "^21.0.0",
28
29
  "@types/tar-stream": "^3.1.3",
29
- "@typescript-eslint/eslint-plugin": "^8.28.0",
30
- "@typescript-eslint/parser": "^8.28.0",
31
- "chai": "^5.2.0",
32
- "eslint": "^9.23",
30
+ "@typescript-eslint/eslint-plugin": "^8.55.0",
31
+ "@typescript-eslint/parser": "^8.55.0",
32
+ "chai": "^6.2.2",
33
+ "eslint": "^9.39.2",
33
34
  "eslint-config-salesforce-typescript": "^3.4.0",
34
- "eslint-plugin-jsdoc": "^50.6.9",
35
+ "eslint-plugin-jsdoc": "^62.5.4",
35
36
  "husky": "^9.1.7",
36
37
  "mocha": "^11.1.0",
37
38
  "nyc": "^17.1.0",
38
- "prettier": "^3.5.3",
39
+ "prettier": "^3.8.1",
39
40
  "shx": "^0.4.0",
40
- "sinon": "^20.0.0",
41
- "ts-node": "^10.9.2",
42
- "tsx": "^4.19.3",
43
- "typescript": "^5.8.2"
41
+ "sinon": "^21.0.1",
42
+ "tsx": "^4.21.0",
43
+ "typescript": "^5.9.3"
44
44
  },
45
45
  "engines": {
46
46
  "node": ">=20"
@@ -76,15 +76,14 @@
76
76
  "build": "rm -rf dist && tsc -p tsconfig.json && npm run exec-perms",
77
77
  "build:dev": "rm -rf dist && tsc --sourceMap -p tsconfig.json && npm run exec-perms",
78
78
  "build:watch": "tsc --sourceMap -p tsconfig.json -w",
79
- "build:dxt": "npx @anthropic-ai/dxt pack",
80
- "start:dev": "npm run build:dev && npm link && npx @modelcontextprotocol/inspector heroku-mcp-server",
81
- "start": "node dist/index.js",
79
+ "build:mcpb": "mcpb pack",
80
+ "start": "node bin/heroku-mcp-server.mjs",
82
81
  "format": "prettier . --write --config ./.prettier.mjs",
83
82
  "lint": "cd src && eslint ./",
84
83
  "posttest": "npm run lint",
85
84
  "pretest": "npm run build",
86
85
  "type-check": "tsc --noEmit",
87
- "test": "nyc mocha --forbid-only --loader=ts-node/esm",
86
+ "test": "nyc mocha --forbid-only",
88
87
  "exec-perms": "shx chmod +x dist/*.js",
89
88
  "test:watch": "nyc mocha --watch --forbid-only"
90
89
  }