Heroku MCP server

Instructions

Implementation Reference

• src/tools/deploy-to-heroku.ts:611-639 (handler)

  The handler function registered for the 'deploy_to_heroku' tool. It processes input parameters, instantiates DeployToHeroku class, executes the deployment, and returns MCP tool response.

  async (options: DeployToHerokuParams): Promise<McpToolResponse> => {
    const deployToHeroku = new DeployToHeroku();
    const result = await deployToHeroku.run({
      rootUri: options.rootUri,
      tarballUri: options.tarballUri,
      name: options.name,
      teamId: options.teamId,
      spaceId: options.spaceId,
      internalRouting: options.internalRouting,
      env: options.env as EnvironmentVariables,
      appJson: options.appJson ? new TextEncoder().encode(options.appJson) : undefined
    });
  
    if (result?.errorMessage) {
      return {
        success: false,
        message: result.errorMessage,
        content: [{ type: 'text', text: result.errorMessage }]
      };
    }
  
    const successMessage = `Successfully deployed to ${result?.name ?? 'Heroku'}`;
    return {
      success: true,
      message: successMessage,
      content: [{ type: 'text', text: successMessage }],
      data: result
    };
  }

• src/tools/deploy-to-heroku.ts:580-593 (schema)

  Zod schema defining the input parameters for the deploy_to_heroku tool, including app name, workspace path, tarball URI, team/space IDs, routing, env vars, and app.json config.

  export const deployToHerokuSchema = z
    .object({
      name: z.string().min(5).max(30).describe('App name for deployment. Creates new app if not exists.'),
      rootUri: z.string().min(1).describe('Workspace root directory path.'),
      tarballUri: z.string().optional().describe('URL of deployment tarball. Creates from rootUri if not provided.'),
      teamId: z.string().optional().describe('Team ID for team deployments.'),
      spaceId: z.string().optional().describe('Private space ID for space deployments.'),
      internalRouting: z.boolean().optional().describe('Enable internal routing in private spaces.'),
      env: z.record(z.string(), z.any()).optional().describe('Environment variables overriding app.json values'),
      appJson: z
        .string()
        .describe(`App.json config for deployment. Must follow schema: ${JSON.stringify(appJsonSchema, null, 0)}`)
    })
    .strict();

• src/tools/deploy-to-heroku.ts:605-641 (registration)

  Registration function for the deploy_to_heroku tool that calls server.tool() with name, description, schema, and handler.

  export const registerDeployToHerokuTool = (server: McpServer): void => {
    server.tool(
      'deploy_to_heroku',
      'Use for all deployments. Deploys new/existing apps, with or without teams/spaces, and env vars to Heroku. ' +
        'Ask for app name if missing. Requires valid app.json via appJson param.',
      deployToHerokuSchema.shape,
      async (options: DeployToHerokuParams): Promise<McpToolResponse> => {
        const deployToHeroku = new DeployToHeroku();
        const result = await deployToHeroku.run({
          rootUri: options.rootUri,
          tarballUri: options.tarballUri,
          name: options.name,
          teamId: options.teamId,
          spaceId: options.spaceId,
          internalRouting: options.internalRouting,
          env: options.env as EnvironmentVariables,
          appJson: options.appJson ? new TextEncoder().encode(options.appJson) : undefined
        });
  
        if (result?.errorMessage) {
          return {
            success: false,
            message: result.errorMessage,
            content: [{ type: 'text', text: result.errorMessage }]
          };
        }
  
        const successMessage = `Successfully deployed to ${result?.name ?? 'Heroku'}`;
        return {
          success: true,
          message: successMessage,
          content: [{ type: 'text', text: successMessage }],
          data: result
        };
      }
    );
  };

• src/index.ts:99-99 (registration)

  Invocation of the registerDeployToHerokuTool function to register the tool with the main MCP server.

  deployToHeroku.registerDeployToHerokuTool(server);

• src/tools/deploy-to-heroku.ts:249-298 (handler)

  Core handler method in DeployToHeroku class that performs the actual Heroku deployment: tarball handling, app setup/build creation, git remote addition.

  protected async deployToHeroku(): Promise<(Build & { name: string }) | null> {
    const { tarballUri, rootUri, appJson } = this.deploymentOptions;
  
    let blobUrl = tarballUri?.toString();
  
    // Create and use an amazon s3 bucket and
    // then upload the newly created tarball
    // from the local sources if no tarballUri was provided.
    if (!blobUrl) {
      const generatedAppJson = appJson ? [{ relativePath: './app.json', contents: appJson }] : [];
      const tarball = await packSources(rootUri!, generatedAppJson);
      const { source_blob: sourceBlob } = await this.sourcesService.create(this.requestInit);
      blobUrl = sourceBlob!.get_url!;
      try {
        const response = await fetch(sourceBlob!.put_url!, {
          method: 'PUT',
          body: tarball
        });
  
        if (!response.ok) {
          const uploadErrorMessage = `Error uploading tarball to S3 bucket. The server responded with: ${response.status} - ${response.statusText}`;
          throw new Error(uploadErrorMessage);
        }
      } catch (error) {
        throw new DeploymentError((error as Error).message);
      }
    }
    // The user has right-clicked on a
    // Procfile or app.json or has used
    // the deploy to heroku decorator button
    // and we have apps in the remote. Ask
    // the user where to deploy.
  
    const result = this.isExistingDeployment
      ? await this.createNewBuildForExistingApp(blobUrl, this.deploymentOptions.name ?? '')
      : await this.setupNewApp(blobUrl);
  
    // This is a new app setup and needs a git remote
    // added to the workspace.
    if (!this.isExistingDeployment && result) {
      // Add the new remote to the workspace
      const app = await this.appService.info(result.name, this.requestInit);
      try {
        execSync(`git remote add heroku-${result.name} ${app.git_url!}`, { cwd: rootUri! });
      } catch {
        // Ignore
      }
    }
    return result;
  }