@heroku/mcp-server 1.0.6 → 1.0.7-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.
package/README.md CHANGED
@@ -4,6 +4,11 @@
4
4
 
5
5
  > The Heroku Platform MCP Server works on Common Runtime, Cedar Private and Shield Spaces, and Fir Private Spaces.
6
6
 
7
+ ## Prerequisites
8
+
9
+ - **Heroku CLI** must be installed globally on your system, version **10.8.1 or higher**.
10
+ - [Install or upgrade the Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)
11
+
7
12
  ## Deploy on Heroku
8
13
 
9
14
  [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://www.heroku.com/deploy?template=https://github.com/heroku/heroku-mcp-server)
@@ -24,6 +29,9 @@ Note: The Heroku Platform MCP Server is currently in early development. As we co
24
29
  implementation, the available functionality and tools may evolve. We welcome feedback and contributions to help shape
25
30
  the future of this project.
26
31
 
32
+ > **Note:** The Heroku Platform MCP Server requires the Heroku CLI to be installed globally (v10.8.1+). Ensure you have
33
+ > the correct version by running `heroku --version`.
34
+
27
35
  ## Authentication
28
36
 
29
37
  Generate a Heroku authorization token with one of these methods:
@@ -0,0 +1,9 @@
1
+ /* global process */
2
+ try {
3
+ const { runServer } = await import('../dist/index.js');
4
+ await runServer();
5
+ } catch (error) {
6
+ const { message } = error;
7
+ process.stderr.write(`Fatal error in main(): ${message}`);
8
+ process.exit(1);
9
+ }
package/dist/index.js CHANGED
@@ -16,7 +16,15 @@ import * as ai from './tools/ai.js';
16
16
  import { HerokuREPL } from './repl/heroku-cli-repl.js';
17
17
  const VERSION = pjson.default.version;
18
18
  const server = new McpServer({ name: 'Heroku MCP Server', version: VERSION });
19
- const herokuRepl = new HerokuREPL(isNaN(Number(process.env.MCP_SERVER_REQUEST_TIMEOUT)) ? 15_000 : Number(process.env.MCP_SERVER_REQUEST_TIMEOUT));
19
+ const requestTimeout = isNaN(Number(process.env.MCP_SERVER_REQUEST_TIMEOUT))
20
+ ? 15_000
21
+ : Number(process.env.MCP_SERVER_REQUEST_TIMEOUT);
22
+ const herokuRepl = new HerokuREPL(requestTimeout);
23
+ // Listen for MCP-formatted fatal startup errors
24
+ herokuRepl.on('fatalError', (mcpError) => {
25
+ process.stderr.write(JSON.stringify(mcpError) + '\n');
26
+ process.exit(1);
27
+ });
20
28
  // App-related tools
21
29
  apps.registerListAppsTool(server, herokuRepl);
22
30
  apps.registerGetAppInfoTool(server, herokuRepl);
@@ -68,25 +76,17 @@ ai.registerMakeAiInferenceTool(server, herokuRepl);
68
76
  /**
69
77
  * Run the server
70
78
  */
71
- async function runServer() {
79
+ export const runServer = async () => {
72
80
  const transport = new StdioServerTransport();
73
81
  await server.connect(transport);
74
82
  process.stderr.write('Heroku MCP Server running on stdio');
75
- }
76
- try {
77
- await runServer();
78
- }
79
- catch (error) {
80
- const { message } = error;
81
- process.stderr.write(`Fatal error in main():, ${message}`);
82
- process.exit(1);
83
- }
84
- /**
85
- * Hook to intercept all command results before they are
86
- * sent back to the LLM. This is useful for logging
87
- * or modifying command results (not-implemented).
88
- */
89
- // eslint-disable-next-line @typescript-eslint/no-unused-vars
90
- for await (const command of herokuRepl) {
91
- // do nothing until logger is implemented
92
- }
83
+ /**
84
+ * Hook to intercept all command results before they are
85
+ * sent back to the LLM. This is useful for logging
86
+ * or modifying command results (not-implemented).
87
+ */
88
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars
89
+ for await (const command of herokuRepl) {
90
+ // do nothing until logger is implemented
91
+ }
92
+ };
@@ -1,9 +1,7 @@
1
1
  import { spawn } from 'node:child_process';
2
- import path from 'node:path';
3
- import { fileURLToPath } from 'node:url';
2
+ import { EventEmitter } from 'node:events';
4
3
  import * as pjson from '../../package.json' with { type: 'json' };
5
- const heroku = path.parse(path.relative(process.cwd(), fileURLToPath(import.meta.resolve('heroku', import.meta.url))));
6
- const herokuRunPath = path.join(heroku.dir, '..', 'bin', 'run');
4
+ import { handleCliOutput } from '../utils/handle-cli-output.js';
7
5
  const COMMAND_END_RESULTS_MESSAGE = '<<<END RESULTS>>>';
8
6
  const READY_MESSAGE = 'heroku >';
9
7
  const VERSION = pjson.default.version;
@@ -27,7 +25,7 @@ const VERSION = pjson.default.version;
27
25
  *
28
26
  * This maintains a single Heroku CLI process.
29
27
  */
30
- export class HerokuREPL {
28
+ export class HerokuREPL extends EventEmitter {
31
29
  static spawn = spawn;
32
30
  isProcessingCommand = false;
33
31
  isReady = false;
@@ -46,6 +44,7 @@ export class HerokuREPL {
46
44
  * @param commandTimeout the timeout for command execution
47
45
  */
48
46
  constructor(commandTimeout = 15_000) {
47
+ super();
49
48
  this.commandTimeout = commandTimeout;
50
49
  this.pauseQueue();
51
50
  void this.initializeProcess();
@@ -116,20 +115,35 @@ export class HerokuREPL {
116
115
  this.process.kill();
117
116
  this.process = undefined;
118
117
  }
119
- this.process = HerokuREPL.spawn(herokuRunPath, [], {
120
- stdio: ['pipe', 'pipe', 'pipe'],
121
- signal: this.abortController.signal,
122
- env: {
123
- ...process.env,
124
- HEROKU_MCP_MODE: 'true',
125
- HEROKU_MCP_SERVER_VERSION: VERSION,
126
- HEROKU_HEADERS: JSON.stringify({
127
- 'User-Agent': this.userAgent
128
- })
129
- }
118
+ try {
119
+ this.process = HerokuREPL.spawn('heroku', ['--repl'], {
120
+ stdio: ['pipe', 'pipe', 'pipe'],
121
+ signal: this.abortController.signal,
122
+ env: {
123
+ ...process.env,
124
+ HEROKU_MCP_MODE: 'true',
125
+ HEROKU_MCP_SERVER_VERSION: VERSION,
126
+ HEROKU_HEADERS: JSON.stringify({
127
+ 'User-Agent': this.userAgent
128
+ })
129
+ }
130
+ });
131
+ }
132
+ catch (err) {
133
+ // Emit MCP error and abort
134
+ this.emit('fatalError', handleCliOutput(`Startup error: ${err.message}`));
135
+ return;
136
+ }
137
+ this.process.once('error', (err) => {
138
+ this.emit('fatalError', handleCliOutput(`Startup error: ${err.message}`));
130
139
  });
131
140
  this.process.stdout?.on('data', (data) => {
132
141
  const output = data.toString();
142
+ // Detect old CLI warning and emit MCP error
143
+ if (output.includes('Warning: --repl is not a heroku command.')) {
144
+ this.emit('fatalError', handleCliOutput('Startup error: Your Heroku CLI version does not support --repl mode. Please upgrade to the latest Heroku CLI.'));
145
+ return;
146
+ }
133
147
  if (output.includes(READY_MESSAGE)) {
134
148
  this.isReady = true;
135
149
  this.pauseIteratorResolver?.();
@@ -109,4 +109,37 @@ describe('HerokuREPL', () => {
109
109
  expect(repl['abortController'].signal.aborted).to.be.true;
110
110
  });
111
111
  });
112
+ describe('MCP startup error handling', () => {
113
+ it('should emit fatalError if spawn throws', () => {
114
+ spawnStub.restore();
115
+ const error = new Error('spawn failed');
116
+ const badSpawn = sinon.stub(HerokuREPL, 'spawn').throws(error);
117
+ const fatalSpy = sinon.spy();
118
+ const replWithError = new HerokuREPL(500);
119
+ replWithError.on('fatalError', fatalSpy);
120
+ // Force re-init to trigger error
121
+ replWithError['initializeProcess']();
122
+ expect(fatalSpy.called).to.be.true;
123
+ const mcpError = fatalSpy.firstCall.args[0];
124
+ expect(mcpError.content[0].text).to.include('Startup error: spawn failed');
125
+ badSpawn.restore();
126
+ });
127
+ it('should emit fatalError if process emits error', () => {
128
+ const fatalSpy = sinon.spy();
129
+ repl.on('fatalError', fatalSpy);
130
+ const error = new Error('process error');
131
+ mockProcess.emit('error', error);
132
+ expect(fatalSpy.called).to.be.true;
133
+ const mcpError = fatalSpy.firstCall.args[0];
134
+ expect(mcpError.content[0].text).to.include('Startup error: process error');
135
+ });
136
+ it('should emit fatalError if CLI outputs old version warning', () => {
137
+ const fatalSpy = sinon.spy();
138
+ repl.on('fatalError', fatalSpy);
139
+ mockProcess.stdout.emit('data', 'Warning: --repl is not a heroku command.');
140
+ expect(fatalSpy.called).to.be.true;
141
+ const mcpError = fatalSpy.firstCall.args[0];
142
+ expect(mcpError.content[0].text).to.include('Your Heroku CLI version does not support --repl mode');
143
+ });
144
+ });
112
145
  });
package/package.json CHANGED
@@ -1,17 +1,16 @@
1
1
  {
2
2
  "name": "@heroku/mcp-server",
3
3
  "description": "Heroku Platform MCP Server",
4
- "version": "1.0.6",
4
+ "version": "1.0.7-alpha.0",
5
5
  "author": "Heroku",
6
6
  "bugs": "https://github.com/heroku/heroku-mcp-server/issues",
7
7
  "bin": {
8
- "heroku-mcp-server": "./dist/index.js"
8
+ "heroku-mcp-server": "bin/heroku-mcp-server.mjs"
9
9
  },
10
10
  "type": "module",
11
11
  "dependencies": {
12
12
  "@heroku/plugin-ai": "^1.0.1",
13
13
  "@modelcontextprotocol/sdk": "^1.8.0",
14
- "heroku": "10.8.0-alpha.0",
15
14
  "jsonschema": "^1.5.0",
16
15
  "tar-stream": "^3.1.7",
17
16
  "zod": "^3.24.2",
@@ -60,7 +59,8 @@
60
59
  }
61
60
  },
62
61
  "files": [
63
- "dist"
62
+ "dist",
63
+ "bin"
64
64
  ],
65
65
  "homepage": "https://github.com/heroku/heroku-mcp-server",
66
66
  "keywords": [
@@ -68,7 +68,10 @@
68
68
  "mcp"
69
69
  ],
70
70
  "license": "Apache-2.0",
71
- "repository": "heroku/heroku-mcp-server",
71
+ "repository": {
72
+ "type": "git",
73
+ "url": "git+https://github.com/heroku/heroku-mcp-server.git"
74
+ },
72
75
  "scripts": {
73
76
  "build": "rm -rf dist && tsc -p tsconfig.json && npm run exec-perms",
74
77
  "build:dev": "rm -rf dist && tsc --sourceMap -p tsconfig.json && npm run exec-perms",