@hubspot/cli 8.15.0 → 8.16.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.
Files changed (125) hide show
  1. package/api/releases.d.ts +4 -1
  2. package/bin/cli.js +2 -0
  3. package/commands/account/auth.d.ts +3 -2
  4. package/commands/account/auth.js +21 -10
  5. package/commands/project/add.d.ts +3 -2
  6. package/commands/project/add.js +10 -8
  7. package/commands/project/appInstallStatus.d.ts +2 -2
  8. package/commands/project/appInstallStatus.js +2 -2
  9. package/commands/project/create.d.ts +4 -2
  10. package/commands/project/create.js +16 -4
  11. package/commands/project/deploy.d.ts +2 -2
  12. package/commands/project/deploy.js +2 -2
  13. package/commands/project/download.d.ts +2 -2
  14. package/commands/project/download.js +2 -2
  15. package/commands/project/info.d.ts +1 -1
  16. package/commands/project/info.js +1 -1
  17. package/commands/project/installApp.d.ts +2 -2
  18. package/commands/project/installApp.js +2 -2
  19. package/commands/project/listBuilds.d.ts +2 -2
  20. package/commands/project/listBuilds.js +2 -2
  21. package/commands/project/release/create.d.ts +2 -2
  22. package/commands/project/release/create.js +7 -3
  23. package/commands/project/release/info.d.ts +2 -2
  24. package/commands/project/release/info.js +2 -2
  25. package/commands/project/release/list.d.ts +2 -2
  26. package/commands/project/release/list.js +2 -2
  27. package/commands/project/release/preview.d.ts +9 -0
  28. package/commands/project/release/preview.js +167 -0
  29. package/commands/project/release.js +7 -1
  30. package/commands/project/upload.d.ts +2 -2
  31. package/commands/project/upload.js +2 -2
  32. package/commands/project/validate.d.ts +2 -2
  33. package/commands/project/validate.js +2 -2
  34. package/commands/testAccount/create.d.ts +2 -2
  35. package/commands/testAccount/create.js +2 -2
  36. package/lang/en.d.ts +25 -0
  37. package/lang/en.js +27 -2
  38. package/lib/app/urls.d.ts +0 -1
  39. package/lib/app/urls.js +0 -4
  40. package/lib/constants.d.ts +5 -0
  41. package/lib/constants.js +9 -0
  42. package/lib/jsonOutput/accountAuth.d.ts +7 -0
  43. package/lib/jsonOutput/accountAuth.js +6 -0
  44. package/lib/jsonOutput/projectAdd.d.ts +9 -0
  45. package/lib/jsonOutput/projectAdd.js +10 -0
  46. package/lib/jsonOutput/{appInstallStatus.d.ts → projectAppInstallStatus.d.ts} +2 -2
  47. package/lib/jsonOutput/{appInstallStatus.js → projectAppInstallStatus.js} +1 -1
  48. package/lib/jsonOutput/projectCreate.d.ts +8 -0
  49. package/lib/jsonOutput/projectCreate.js +7 -0
  50. package/lib/jsonOutput/projectDeploy.d.ts +5 -0
  51. package/lib/jsonOutput/{deploy.js → projectDeploy.js} +1 -1
  52. package/lib/jsonOutput/projectDownload.d.ts +7 -0
  53. package/lib/jsonOutput/{download.js → projectDownload.js} +1 -1
  54. package/lib/jsonOutput/{installApp.d.ts → projectInstallApp.d.ts} +2 -2
  55. package/lib/jsonOutput/{installApp.js → projectInstallApp.js} +1 -1
  56. package/lib/jsonOutput/{listBuilds.d.ts → projectListBuilds.d.ts} +2 -2
  57. package/lib/jsonOutput/{listBuilds.js → projectListBuilds.js} +1 -1
  58. package/lib/jsonOutput/{release.d.ts → projectRelease.d.ts} +15 -8
  59. package/lib/jsonOutput/{release.js → projectRelease.js} +11 -4
  60. package/lib/jsonOutput/{upload.d.ts → projectUpload.d.ts} +2 -2
  61. package/lib/jsonOutput/{upload.js → projectUpload.js} +1 -1
  62. package/lib/jsonOutput/{validate.d.ts → projectValidate.d.ts} +2 -2
  63. package/lib/jsonOutput/{validate.js → projectValidate.js} +1 -1
  64. package/lib/jsonOutput/{createTestAccount.d.ts → testAccountCreate.d.ts} +2 -2
  65. package/lib/jsonOutput/{createTestAccount.js → testAccountCreate.js} +1 -1
  66. package/lib/middleware/deprecationWarningMiddleware.d.ts +1 -0
  67. package/lib/middleware/deprecationWarningMiddleware.js +57 -0
  68. package/lib/projects/add/legacyAddComponent.d.ts +2 -1
  69. package/lib/projects/add/legacyAddComponent.js +3 -0
  70. package/lib/projects/add/v2AddComponent.d.ts +2 -1
  71. package/lib/projects/add/v2AddComponent.js +7 -1
  72. package/lib/projects/localDev/LocalDevWatcher.js +1 -1
  73. package/lib/projects/release.d.ts +2 -2
  74. package/lib/projects/validate.d.ts +1 -1
  75. package/mcp-server/Tool.d.ts +6 -1
  76. package/mcp-server/Tool.js +6 -4
  77. package/mcp-server/server.js +26 -4
  78. package/mcp-server/tools/cms/HsCreateFunctionTool.js +1 -1
  79. package/mcp-server/tools/cms/HsFunctionLogsTool.d.ts +1 -1
  80. package/mcp-server/tools/cms/HsFunctionLogsTool.js +59 -5
  81. package/mcp-server/tools/cms/HsListFunctionsTool.js +1 -1
  82. package/mcp-server/tools/index.js +2 -0
  83. package/mcp-server/tools/project/AddFeatureToProjectTool.js +31 -31
  84. package/mcp-server/tools/project/AuthAccountTool.js +12 -2
  85. package/mcp-server/tools/project/CreateProjectTool.js +13 -3
  86. package/mcp-server/tools/project/CreateTestAccountTool.js +13 -13
  87. package/mcp-server/tools/project/DeployProjectTool.js +9 -1
  88. package/mcp-server/tools/project/DocFetchTool.js +1 -1
  89. package/mcp-server/tools/project/DocsSearchTool.d.ts +4 -1
  90. package/mcp-server/tools/project/DocsSearchTool.js +18 -9
  91. package/mcp-server/tools/project/FindProjectsTool.js +12 -0
  92. package/mcp-server/tools/project/GetApiUsagePatternsByAppIdTool.d.ts +3 -2
  93. package/mcp-server/tools/project/GetApiUsagePatternsByAppIdTool.js +38 -10
  94. package/mcp-server/tools/project/GetApplicationInfoTool.d.ts +2 -1
  95. package/mcp-server/tools/project/GetApplicationInfoTool.js +13 -14
  96. package/mcp-server/tools/project/GetBuildLogsTool.d.ts +2 -1
  97. package/mcp-server/tools/project/GetBuildLogsTool.js +12 -9
  98. package/mcp-server/tools/project/GetBuildStatusTool.d.ts +2 -1
  99. package/mcp-server/tools/project/GetBuildStatusTool.js +12 -9
  100. package/mcp-server/tools/project/GetConfigValuesTool.d.ts +2 -1
  101. package/mcp-server/tools/project/GetConfigValuesTool.js +11 -8
  102. package/mcp-server/tools/project/KnowledgeSearchTool.d.ts +29 -0
  103. package/mcp-server/tools/project/KnowledgeSearchTool.js +82 -0
  104. package/mcp-server/tools/project/UploadProjectTools.js +3 -3
  105. package/mcp-server/tools/project/ValidateProjectTool.js +23 -7
  106. package/mcp-server/tools/project/apps.d.ts +8 -0
  107. package/mcp-server/tools/project/apps.js +7 -0
  108. package/mcp-server/tools/project/constants.d.ts +2 -0
  109. package/mcp-server/tools/project/constants.js +8 -1
  110. package/mcp-server/tools/project/resolveAccount.d.ts +15 -0
  111. package/mcp-server/tools/project/resolveAccount.js +60 -0
  112. package/mcp-server/utils/command.d.ts +1 -0
  113. package/mcp-server/utils/command.js +8 -0
  114. package/mcp-server/utils/content.d.ts +1 -0
  115. package/mcp-server/utils/content.js +5 -0
  116. package/mcp-server/utils/elicitSelection.d.ts +11 -0
  117. package/mcp-server/utils/elicitSelection.js +25 -0
  118. package/mcp-server/utils/elicitation.d.ts +9 -0
  119. package/mcp-server/utils/elicitation.js +35 -0
  120. package/package.json +23 -22
  121. package/ui/components/Table.d.ts +8 -8
  122. package/lib/jsonOutput/deploy.d.ts +0 -5
  123. package/lib/jsonOutput/download.d.ts +0 -7
  124. /package/lib/jsonOutput/{info.d.ts → projectInfo.d.ts} +0 -0
  125. /package/lib/jsonOutput/{info.js → projectInfo.js} +0 -0
@@ -3,8 +3,10 @@ import { Tool } from '../../Tool.js';
3
3
  import { formatTextContents } from '../../utils/content.js';
4
4
  import { HubSpotCommand } from '../../utils/command.js';
5
5
  import { setupHubSpotConfig } from '../../utils/config.js';
6
+ import { parseCommandJsonOutput } from '../../utils/json.js';
6
7
  import { absoluteCurrentWorkingDirectory } from './constants.js';
7
8
  import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
9
+ import { AccountAuthSchema } from '../../../lib/jsonOutput/accountAuth.js';
8
10
  const inputSchema = {
9
11
  absoluteCurrentWorkingDirectory,
10
12
  accountId: z
@@ -29,7 +31,9 @@ export class AuthAccountTool extends Tool {
29
31
  }
30
32
  async handler({ absoluteCurrentWorkingDirectory, accountId, name, setAsDefault, }, extra) {
31
33
  setupHubSpotConfig(absoluteCurrentWorkingDirectory);
32
- const command = new HubSpotCommand('account auth');
34
+ const command = new HubSpotCommand('account auth', [
35
+ { name: 'json', value: true },
36
+ ]);
33
37
  if (name) {
34
38
  command.addFlag('name', name);
35
39
  }
@@ -42,7 +46,12 @@ export class AuthAccountTool extends Tool {
42
46
  command.addFlag('default', setAsDefault === false ? 'false' : 'true');
43
47
  try {
44
48
  const { stdout, stderr } = await this.runCommand(absoluteCurrentWorkingDirectory, command, extra);
45
- return formatTextContents(stdout, stderr);
49
+ const structuredContent = parseCommandJsonOutput(stdout, AccountAuthSchema, this.logger, toolName);
50
+ const response = await formatTextContents(stdout, stderr);
51
+ if (structuredContent) {
52
+ response.structuredContent = structuredContent;
53
+ }
54
+ return response;
46
55
  }
47
56
  catch (error) {
48
57
  this.logger.debug(toolName, {
@@ -67,6 +76,7 @@ export class AuthAccountTool extends Tool {
67
76
  '4. Retry any operation that was blocked by missing auth\n\n' +
68
77
  'setAsDefault defaults to true. Pass setAsDefault: false to keep an existing default account.',
69
78
  inputSchema,
79
+ outputSchema: AccountAuthSchema.shape,
70
80
  annotations: {
71
81
  readOnlyHint: false,
72
82
  destructiveHint: false,
@@ -7,6 +7,8 @@ import { formatTextContents, formatTextContent } from '../../utils/content.js';
7
7
  import { setupHubSpotConfig } from '../../utils/config.js';
8
8
  import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
9
9
  import { PLATFORM_VERSIONS } from '@hubspot/project-parsing-lib/constants';
10
+ import { parseCommandJsonOutput } from '../../utils/json.js';
11
+ import { ProjectCreateSchema } from '../../../lib/jsonOutput/projectCreate.js';
10
12
  const inputSchema = {
11
13
  absoluteCurrentWorkingDirectory,
12
14
  name: z
@@ -40,6 +42,7 @@ export class CreateProjectTool extends Tool {
40
42
  setupHubSpotConfig(absoluteCurrentWorkingDirectory);
41
43
  const command = new HubSpotCommand('project create', [
42
44
  { name: 'platform-version', value: PLATFORM_VERSIONS.v2026_03 },
45
+ { name: 'json', value: true },
43
46
  ]);
44
47
  const content = [];
45
48
  if (name) {
@@ -69,20 +72,26 @@ export class CreateProjectTool extends Tool {
69
72
  if (content.length > 0) {
70
73
  return {
71
74
  content,
75
+ structuredContent: {},
72
76
  };
73
77
  }
74
78
  // Always pass features, even if it is an empty array to bypass the prompts
75
79
  command.addFlag('features', features || []);
76
80
  try {
77
81
  const { stdout, stderr } = await this.runCommand(absoluteCurrentWorkingDirectory, command, extra);
78
- return formatTextContents(stdout, stderr);
82
+ const response = await formatTextContents(stdout, stderr);
83
+ response.structuredContent =
84
+ parseCommandJsonOutput(stdout, ProjectCreateSchema, this.logger, toolName) ?? {};
85
+ return response;
79
86
  }
80
87
  catch (error) {
81
88
  this.logger.debug(toolName, {
82
89
  message: 'Handler caught error',
83
- error: error instanceof Error ? error.message : String(error),
90
+ error: getErrorMessage(error),
84
91
  });
85
- return formatTextContents(getErrorMessage(error));
92
+ const errorResponse = await formatTextContents(getErrorMessage(error));
93
+ errorResponse.isError = true;
94
+ return errorResponse;
86
95
  }
87
96
  }
88
97
  register() {
@@ -90,6 +99,7 @@ export class CreateProjectTool extends Tool {
90
99
  title: 'Create HubSpot Project',
91
100
  description: 'Creates a HubSpot project with the provided name and outputs it in the provided destination',
92
101
  inputSchema,
102
+ outputSchema: ProjectCreateSchema.shape,
93
103
  annotations: {
94
104
  readOnlyHint: false,
95
105
  destructiveHint: false,
@@ -2,12 +2,14 @@ import { z } from 'zod';
2
2
  import fs from 'fs';
3
3
  import { formatTextContents, formatTextContent } from '../../utils/content.js';
4
4
  import { HubSpotCommand } from '../../utils/command.js';
5
+ import { parseCommandJsonOutput } from '../../utils/json.js';
5
6
  import { ACCOUNT_LEVELS, ACCOUNT_LEVEL_CHOICES, } from '../../../lib/constants.js';
6
7
  import { Tool } from '../../Tool.js';
7
8
  import { absoluteCurrentWorkingDirectory } from './constants.js';
8
9
  import { getConfigAccountByName } from '@hubspot/local-dev-lib/config';
9
10
  import { setupHubSpotConfig } from '../../utils/config.js';
10
11
  import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
12
+ import { TestAccountCreateSchema } from '../../../lib/jsonOutput/testAccountCreate.js';
11
13
  const ACCOUNT_LEVEL_CHOICES_WITHOUT_STARTER = [
12
14
  ACCOUNT_LEVELS.FREE,
13
15
  ACCOUNT_LEVELS.PROFESSIONAL,
@@ -71,7 +73,9 @@ export class CreateTestAccountTool extends Tool {
71
73
  }
72
74
  async handler({ absoluteCurrentWorkingDirectory, name, description, marketingLevel, opsLevel, serviceLevel, salesLevel, contentLevel, commerceLevel, configPath, }, extra) {
73
75
  setupHubSpotConfig(absoluteCurrentWorkingDirectory);
74
- const command = new HubSpotCommand('test-account create');
76
+ const command = new HubSpotCommand('test-account create', [
77
+ { name: 'json', value: true },
78
+ ]);
75
79
  const content = [];
76
80
  // Use config file if provided (LLM should check for config first)
77
81
  if (configPath) {
@@ -89,6 +93,7 @@ export class CreateTestAccountTool extends Tool {
89
93
  content: [
90
94
  formatTextContent(`Failed to read or parse config file at "${configPath}": ${getErrorMessage(error)}. Please ensure the file exists and contains valid JSON.`),
91
95
  ],
96
+ structuredContent: {},
92
97
  };
93
98
  }
94
99
  if (configJson.accountName) {
@@ -134,20 +139,14 @@ export class CreateTestAccountTool extends Tool {
134
139
  if (content.length > 0) {
135
140
  return {
136
141
  content,
142
+ structuredContent: {},
137
143
  };
138
144
  }
139
- // No flags or config - command will prompt user interactively
140
- try {
141
- const { stdout, stderr } = await this.runCommand(absoluteCurrentWorkingDirectory, command, extra);
142
- return formatTextContents(absoluteCurrentWorkingDirectory, stdout, stderr);
143
- }
144
- catch (error) {
145
- this.logger.debug(toolName, {
146
- message: 'Handler caught error',
147
- error: error instanceof Error ? error.message : String(error),
148
- });
149
- return formatTextContents(absoluteCurrentWorkingDirectory, getErrorMessage(error));
150
- }
145
+ const { stdout, stderr } = await this.runCommand(absoluteCurrentWorkingDirectory, command, extra);
146
+ const response = await formatTextContents(stdout, stderr);
147
+ response.structuredContent =
148
+ parseCommandJsonOutput(stdout, TestAccountCreateSchema, this.logger, toolName) ?? {};
149
+ return response;
151
150
  }
152
151
  register() {
153
152
  return this.mcpServer.registerTool(toolName, {
@@ -170,6 +169,7 @@ export class CreateTestAccountTool extends Tool {
170
169
  'Available Hub Tier Levels: FREE, STARTER, PROFESSIONAL, ENTERPRISE\n' +
171
170
  'Available Hubs: Marketing (marketingLevel), Sales (salesLevel), Service (serviceLevel), Operations (opsLevel), CMS (contentLevel), Commerce (commerceLevel)',
172
171
  inputSchema,
172
+ outputSchema: TestAccountCreateSchema.shape,
173
173
  annotations: {
174
174
  readOnlyHint: false,
175
175
  destructiveHint: false,
@@ -4,6 +4,8 @@ import { HubSpotCommand } from '../../utils/command.js';
4
4
  import { absoluteCurrentWorkingDirectory, absoluteProjectPath, } from './constants.js';
5
5
  import { formatTextContents, formatTextContent } from '../../utils/content.js';
6
6
  import { setupHubSpotConfig } from '../../utils/config.js';
7
+ import { parseCommandJsonOutput } from '../../utils/json.js';
8
+ import { ProjectDeploySchema } from '../../../lib/jsonOutput/projectDeploy.js';
7
9
  const inputSchema = {
8
10
  absoluteProjectPath,
9
11
  absoluteCurrentWorkingDirectory,
@@ -32,19 +34,25 @@ export class DeployProjectTool extends Tool {
32
34
  if (content.length) {
33
35
  return {
34
36
  content,
37
+ structuredContent: {},
35
38
  };
36
39
  }
37
40
  const command = new HubSpotCommand('project deploy', [
38
41
  { name: 'build', value: buildNumber },
42
+ { name: 'json', value: true },
39
43
  ]);
40
44
  const { stdout, stderr } = await this.runCommand(absoluteProjectPath, command, extra);
41
- return formatTextContents(stdout, stderr);
45
+ const response = await formatTextContents(stdout, stderr);
46
+ response.structuredContent =
47
+ parseCommandJsonOutput(stdout, ProjectDeploySchema, this.logger, toolName) ?? {};
48
+ return response;
42
49
  }
43
50
  register() {
44
51
  return this.mcpServer.registerTool(toolName, {
45
52
  title: 'Deploy a build of HubSpot Project',
46
53
  description: 'Takes a build number and a project name and deploys that build of the project. DO NOT run this tool unless the user specifies they would like to deploy the project. If you do not know the project path, use the find-projects tool first to locate HubSpot projects in the workspace.',
47
54
  inputSchema,
55
+ outputSchema: ProjectDeploySchema.shape,
48
56
  annotations: {
49
57
  readOnlyHint: false,
50
58
  destructiveHint: true,
@@ -48,7 +48,7 @@ export class DocFetchTool extends Tool {
48
48
  register() {
49
49
  return this.mcpServer.registerTool(toolName, {
50
50
  title: 'Fetch HubSpot Developer Documentation (single file)',
51
- description: 'Always use this immediately after `search-docs` and before creating a plan, writing code, or answering technical questions. This tool retrieves the full, authoritative content of a HubSpot Developer Documentation page from its URL, ensuring responses are accurate, up-to-date, and grounded in the official docs.',
51
+ description: 'Always use this immediately after `search-docs` and before creating a plan, writing code, or answering technical questions. This tool retrieves the full, authoritative content of a HubSpot Developer Documentation page from its URL, ensuring responses are accurate, up-to-date, and grounded in the official docs. Some pages include a "Supported products" section (a `<SupportedProducts .../>` tag) listing the products and subscription tiers a feature requires. Read it to tell the user whether a feature is available on their plan, stated plainly (for example "requires Content Hub Enterprise") rather than by quoting raw spec fields.',
52
52
  inputSchema,
53
53
  annotations: {
54
54
  readOnlyHint: true,
@@ -5,8 +5,10 @@ import { McpToolResponse } from '../../types.js';
5
5
  import { Tool } from '../../Tool.js';
6
6
  declare const inputSchemaZodObject: z.ZodObject<{
7
7
  absoluteCurrentWorkingDirectory: z.ZodString;
8
+ account: z.ZodOptional<z.ZodString>;
8
9
  docsSearchQuery: z.ZodString;
9
10
  docsSearchLimit: z.ZodDefault<z.ZodNumber>;
11
+ docsSearchVersion: z.ZodDefault<z.ZodString>;
10
12
  }, z.z.core.$strip>;
11
13
  export interface DocsSearchResponse {
12
14
  results: {
@@ -15,6 +17,7 @@ export interface DocsSearchResponse {
15
17
  description: string;
16
18
  url: string;
17
19
  score: number;
20
+ version?: string;
18
21
  }[];
19
22
  }
20
23
  type InputSchemaType = z.infer<typeof inputSchemaZodObject>;
@@ -23,7 +26,7 @@ export declare class DocsSearchTool extends Tool<InputSchemaType> {
23
26
  protected getTrackingMeta({ docsSearchQuery, }: InputSchemaType): {
24
27
  [key: string]: string;
25
28
  } | undefined;
26
- handler({ docsSearchQuery, docsSearchLimit, absoluteCurrentWorkingDirectory, }: InputSchemaType): Promise<McpToolResponse>;
29
+ handler({ docsSearchQuery, docsSearchLimit, docsSearchVersion, account, absoluteCurrentWorkingDirectory, }: InputSchemaType): Promise<McpToolResponse>;
27
30
  register(): RegisteredTool;
28
31
  }
29
32
  export {};
@@ -2,10 +2,10 @@ import { http } from '@hubspot/local-dev-lib/http';
2
2
  import z from 'zod';
3
3
  import { Tool } from '../../Tool.js';
4
4
  import { formatTextContents } from '../../utils/content.js';
5
- import { absoluteCurrentWorkingDirectory, docsSearchQuery, } from './constants.js';
5
+ import { absoluteCurrentWorkingDirectory, account, docsSearchQuery, } from './constants.js';
6
6
  import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
7
7
  import { setupHubSpotConfig } from '../../utils/config.js';
8
- import { discoverAccountTargets } from '../../../lib/accountTargetDiscovery.js';
8
+ import { resolveAccountId } from './resolveAccount.js';
9
9
  import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
10
10
  const docsSearchLimit = z
11
11
  .number()
@@ -14,10 +14,16 @@ const docsSearchLimit = z
14
14
  .max(20)
15
15
  .default(5)
16
16
  .describe('Maximum number of results to return.');
17
+ const docsSearchVersion = z
18
+ .string()
19
+ .default('latest')
20
+ .describe('API documentation version to search. Defaults to "latest" for current docs, which is almost always what you want. Only override when the user explicitly asks about a specific or legacy version, using a date-based version like "2026-03" or "legacy". Versionless docs such as guides and CMS pages are always included regardless of this value.');
17
21
  const inputSchema = {
18
22
  absoluteCurrentWorkingDirectory,
23
+ account,
19
24
  docsSearchQuery,
20
25
  docsSearchLimit,
26
+ docsSearchVersion,
21
27
  };
22
28
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
23
29
  const inputSchemaZodObject = z.object({
@@ -31,19 +37,22 @@ export class DocsSearchTool extends Tool {
31
37
  getTrackingMeta({ docsSearchQuery, }) {
32
38
  return { mode: docsSearchQuery };
33
39
  }
34
- async handler({ docsSearchQuery, docsSearchLimit, absoluteCurrentWorkingDirectory, }) {
40
+ async handler({ docsSearchQuery, docsSearchLimit, docsSearchVersion, account, absoluteCurrentWorkingDirectory, }) {
35
41
  setupHubSpotConfig(absoluteCurrentWorkingDirectory);
36
42
  try {
37
- const { recommended } = await discoverAccountTargets();
38
- const accountId = recommended?.accountId;
39
- if (!accountId) {
40
- const authErrorMessage = `No account ID found. Call the auth-account tool to authenticate a HubSpot account.`;
41
- return formatTextContents(authErrorMessage);
43
+ const resolved = await resolveAccountId(this.mcpServer, this.logger, {
44
+ toolName,
45
+ account,
46
+ });
47
+ if ('response' in resolved) {
48
+ return resolved.response;
42
49
  }
50
+ const { accountId } = resolved;
43
51
  const response = await http.post(accountId, {
44
52
  url: 'dev/docs/llms/v1/docs-search',
45
53
  data: {
46
54
  query: docsSearchQuery,
55
+ version: docsSearchVersion,
47
56
  },
48
57
  });
49
58
  const results = response.data.results;
@@ -82,7 +91,7 @@ export class DocsSearchTool extends Tool {
82
91
  register() {
83
92
  return this.mcpServer.registerTool(toolName, {
84
93
  title: 'Search HubSpot Developer Documentation',
85
- description: 'Use this first whenever you need details about HubSpot APIs, SDKs, integrations, or developer platform features. This searches the official HubSpot Developer Documentation and returns the most relevant pages, each with a URL for use in `fetch-doc`. Always follow this with a fetch to get the full, authoritative content before making plans or writing answers.',
94
+ description: 'Use this first for any HubSpot developer question, including whether an API or feature is available on a subscription tier or plan (for example "is the content audit API available on Content Hub Professional"). The doc you fetch next states the required product and tier; report it in plain terms (for example "requires Content Hub Enterprise") rather than quoting raw spec fields. This searches the official HubSpot Developer Documentation and returns the most relevant pages, each with a URL for use in `fetch-doc`. Always follow this with a fetch to get the full, authoritative content before making plans or writing answers.',
86
95
  inputSchema,
87
96
  annotations: {
88
97
  readOnlyHint: true,
@@ -4,6 +4,7 @@ import { formatTextContents } from '../../utils/content.js';
4
4
  import { walk } from '@hubspot/local-dev-lib/fs';
5
5
  import path from 'path';
6
6
  import { PROJECT_CONFIG_FILE } from '../../../lib/constants.js';
7
+ import { elicitSelection } from '../../utils/elicitSelection.js';
7
8
  const TOOL_NAME = 'find-projects';
8
9
  const IGNORE_DIRS = ['node_modules', '.git', '.vite'];
9
10
  const inputSchema = {
@@ -25,6 +26,17 @@ export class FindProjectsTool extends Tool {
25
26
  return formatTextContents(`No ${PROJECT_CONFIG_FILE} files found under ${absoluteDirectory}.`);
26
27
  }
27
28
  const projectDirs = projectFiles.map(file => path.dirname(file));
29
+ if (projectDirs.length > 1) {
30
+ const selected = await elicitSelection(this.mcpServer, this.logger, {
31
+ message: 'Select the HubSpot project to use.',
32
+ title: 'HubSpot project',
33
+ options: projectDirs.map(dir => ({ value: dir, label: dir })),
34
+ });
35
+ if (selected) {
36
+ return formatTextContents(`Selected project: ${selected}`);
37
+ }
38
+ return formatTextContents(`Several projects are available. Ask the user which to use, then call ${TOOL_NAME} again with absoluteDirectory narrowed to one of: ${projectDirs.join(', ')}.`);
39
+ }
28
40
  const output = [
29
41
  `Found ${projectFiles.length} project(s):`,
30
42
  '',
@@ -6,14 +6,15 @@ import { z } from 'zod';
6
6
  declare const inputSchemaZodObject: z.ZodObject<{
7
7
  absoluteCurrentWorkingDirectory: z.ZodString;
8
8
  absoluteProjectPath: z.ZodOptional<z.ZodString>;
9
- appId: z.ZodString;
9
+ account: z.ZodOptional<z.ZodString>;
10
+ appId: z.ZodOptional<z.ZodString>;
10
11
  startDate: z.ZodOptional<z.ZodString>;
11
12
  endDate: z.ZodOptional<z.ZodString>;
12
13
  }, z.core.$strip>;
13
14
  export type GetApiUsagePatternsByAppIdInputSchema = z.infer<typeof inputSchemaZodObject>;
14
15
  export declare class GetApiUsagePatternsByAppIdTool extends Tool<GetApiUsagePatternsByAppIdInputSchema> {
15
16
  constructor(mcpServer: McpServer, logger: McpLogger);
16
- handler({ appId, startDate, endDate, absoluteCurrentWorkingDirectory, absoluteProjectPath, }: GetApiUsagePatternsByAppIdInputSchema): Promise<McpToolResponse>;
17
+ handler({ appId, startDate, endDate, account, absoluteCurrentWorkingDirectory, absoluteProjectPath, }: GetApiUsagePatternsByAppIdInputSchema): Promise<McpToolResponse>;
17
18
  register(): RegisteredTool;
18
19
  }
19
20
  export {};
@@ -3,16 +3,20 @@ import { z } from 'zod';
3
3
  import { http } from '@hubspot/local-dev-lib/http';
4
4
  import { formatTextContents } from '../../utils/content.js';
5
5
  import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
6
- import { absoluteCurrentWorkingDirectory, absoluteProjectPath, } from './constants.js';
6
+ import { absoluteCurrentWorkingDirectory, absoluteProjectPath, account, } from './constants.js';
7
7
  import { setupHubSpotConfig } from '../../utils/config.js';
8
- import { discoverAccountTargets } from '../../../lib/accountTargetDiscovery.js';
8
+ import { resolveAccountId } from './resolveAccount.js';
9
9
  import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
10
+ import { elicitSelection } from '../../utils/elicitSelection.js';
11
+ import { getApps } from './apps.js';
10
12
  const inputSchema = {
11
13
  absoluteCurrentWorkingDirectory,
12
14
  absoluteProjectPath: absoluteProjectPath.optional(),
15
+ account,
13
16
  appId: z
14
17
  .string()
15
- .describe('The numeric app ID as a string (e.g., "3003909"). Must contain only digits. Use get-apps-info to find available app IDs.'),
18
+ .describe('The numeric app ID as a string (e.g., "3003909"). Must contain only digits. If omitted and the account has several apps, you will be asked to choose one.')
19
+ .optional(),
16
20
  startDate: z
17
21
  .string()
18
22
  .describe('Start date for the usage patterns query in YYYY-MM-DD format (e.g., 2025-01-01).')
@@ -29,17 +33,41 @@ export class GetApiUsagePatternsByAppIdTool extends Tool {
29
33
  constructor(mcpServer, logger) {
30
34
  super(mcpServer, logger, toolName);
31
35
  }
32
- async handler({ appId, startDate, endDate, absoluteCurrentWorkingDirectory, absoluteProjectPath, }) {
36
+ async handler({ appId, startDate, endDate, account, absoluteCurrentWorkingDirectory, absoluteProjectPath, }) {
33
37
  setupHubSpotConfig(absoluteProjectPath ?? absoluteCurrentWorkingDirectory);
34
38
  try {
35
- const { recommended } = await discoverAccountTargets();
36
- const accountId = recommended?.accountId;
37
- if (!accountId) {
38
- const authErrorMessage = `No account ID found. Call the auth-account tool to authenticate a HubSpot account.`;
39
- return formatTextContents(authErrorMessage);
39
+ const resolved = await resolveAccountId(this.mcpServer, this.logger, {
40
+ toolName,
41
+ account,
42
+ });
43
+ if ('response' in resolved) {
44
+ return resolved.response;
45
+ }
46
+ const { accountId } = resolved;
47
+ let resolvedAppId = appId;
48
+ if (!resolvedAppId) {
49
+ const { applications } = await getApps(accountId);
50
+ const apps = applications ?? [];
51
+ if (apps.length === 0) {
52
+ return formatTextContents('No apps found for this account. Nothing to inspect.');
53
+ }
54
+ const selected = await elicitSelection(this.mcpServer, this.logger, {
55
+ message: 'Select the app to inspect usage patterns for.',
56
+ title: 'HubSpot app',
57
+ options: apps.map(app => ({
58
+ value: String(app.appId),
59
+ label: `${app.appName} (${app.appId})`,
60
+ })),
61
+ });
62
+ if (!selected) {
63
+ return formatTextContents(`Several apps are available. Ask the user which to use, then call ${toolName} again with the appId argument set to one of: ${apps
64
+ .map(app => `${app.appName} (appId ${app.appId})`)
65
+ .join(', ')}.`);
66
+ }
67
+ resolvedAppId = selected;
40
68
  }
41
69
  const response = await http.get(accountId, {
42
- url: `app/feature/utilization/public/v3/insights/app/${appId}/usage-patterns`,
70
+ url: `app/feature/utilization/public/v3/insights/app/${resolvedAppId}/usage-patterns`,
43
71
  params: {
44
72
  ...(startDate && { startDate }),
45
73
  ...(endDate && { endDate }),
@@ -6,11 +6,12 @@ import { z } from 'zod';
6
6
  declare const inputSchemaZodObject: z.ZodObject<{
7
7
  absoluteCurrentWorkingDirectory: z.ZodString;
8
8
  absoluteProjectPath: z.ZodOptional<z.ZodString>;
9
+ account: z.ZodOptional<z.ZodString>;
9
10
  }, z.core.$strip>;
10
11
  export type GetApplicationInfoInputSchema = z.infer<typeof inputSchemaZodObject>;
11
12
  export declare class GetApplicationInfoTool extends Tool<GetApplicationInfoInputSchema> {
12
13
  constructor(mcpServer: McpServer, logger: McpLogger);
13
- handler({ absoluteCurrentWorkingDirectory, absoluteProjectPath, }: GetApplicationInfoInputSchema): Promise<McpToolResponse>;
14
+ handler({ account, absoluteCurrentWorkingDirectory, absoluteProjectPath, }: GetApplicationInfoInputSchema): Promise<McpToolResponse>;
14
15
  register(): RegisteredTool;
15
16
  }
16
17
  export {};
@@ -1,15 +1,16 @@
1
1
  import { Tool } from '../../Tool.js';
2
2
  import { z } from 'zod';
3
- import { http } from '@hubspot/local-dev-lib/http';
4
3
  import { formatTextContents } from '../../utils/content.js';
5
4
  import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
6
- import { absoluteCurrentWorkingDirectory, absoluteProjectPath, } from './constants.js';
5
+ import { absoluteCurrentWorkingDirectory, absoluteProjectPath, account, } from './constants.js';
7
6
  import { setupHubSpotConfig } from '../../utils/config.js';
8
- import { discoverAccountTargets } from '../../../lib/accountTargetDiscovery.js';
7
+ import { resolveAccountId } from './resolveAccount.js';
9
8
  import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
9
+ import { getApps } from './apps.js';
10
10
  const inputSchema = {
11
11
  absoluteCurrentWorkingDirectory,
12
12
  absoluteProjectPath: absoluteProjectPath.optional(),
13
+ account,
13
14
  };
14
15
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
15
16
  const inputSchemaZodObject = z.object({ ...inputSchema });
@@ -18,20 +19,18 @@ export class GetApplicationInfoTool extends Tool {
18
19
  constructor(mcpServer, logger) {
19
20
  super(mcpServer, logger, toolName);
20
21
  }
21
- async handler({ absoluteCurrentWorkingDirectory, absoluteProjectPath, }) {
22
+ async handler({ account, absoluteCurrentWorkingDirectory, absoluteProjectPath, }) {
22
23
  setupHubSpotConfig(absoluteProjectPath ?? absoluteCurrentWorkingDirectory);
23
24
  try {
24
- const { recommended } = await discoverAccountTargets();
25
- const accountId = recommended?.accountId;
26
- if (!accountId) {
27
- const authErrorMessage = `No account ID found. Call the auth-account tool to authenticate a HubSpot account.`;
28
- return formatTextContents(authErrorMessage);
29
- }
30
- const response = await http.get(accountId, {
31
- url: `app/feature/utilization/public/v3/insights/apps`,
25
+ const resolved = await resolveAccountId(this.mcpServer, this.logger, {
26
+ toolName,
27
+ account,
32
28
  });
33
- // Format the response for display
34
- const { data } = response;
29
+ if ('response' in resolved) {
30
+ return resolved.response;
31
+ }
32
+ const { accountId } = resolved;
33
+ const data = await getApps(accountId);
35
34
  const formattedResult = JSON.stringify(data, null, 2);
36
35
  return formatTextContents(formattedResult);
37
36
  }
@@ -6,6 +6,7 @@ import { z } from 'zod';
6
6
  declare const inputSchemaZodObject: z.ZodObject<{
7
7
  absoluteProjectPath: z.ZodString;
8
8
  absoluteCurrentWorkingDirectory: z.ZodString;
9
+ account: z.ZodOptional<z.ZodString>;
9
10
  buildId: z.ZodNumber;
10
11
  logLevel: z.ZodOptional<z.ZodEnum<{
11
12
  ERROR: "ERROR";
@@ -17,7 +18,7 @@ declare const inputSchemaZodObject: z.ZodObject<{
17
18
  export type GetBuildLogsInputSchema = z.infer<typeof inputSchemaZodObject>;
18
19
  export declare class GetBuildLogsTool extends Tool<GetBuildLogsInputSchema> {
19
20
  constructor(mcpServer: McpServer, logger: McpLogger);
20
- handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, buildId, logLevel, }: GetBuildLogsInputSchema): Promise<McpToolResponse>;
21
+ handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, account, buildId, logLevel, }: GetBuildLogsInputSchema): Promise<McpToolResponse>;
21
22
  register(): RegisteredTool;
22
23
  }
23
24
  export {};
@@ -4,14 +4,15 @@ import { formatTextContents } from '../../utils/content.js';
4
4
  import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
5
5
  import { http } from '@hubspot/local-dev-lib/http';
6
6
  import { getProjectConfig } from '../../../lib/projects/config.js';
7
- import { absoluteCurrentWorkingDirectory, absoluteProjectPath, } from './constants.js';
7
+ import { absoluteCurrentWorkingDirectory, absoluteProjectPath, account, } from './constants.js';
8
8
  import { setupHubSpotConfig } from '../../utils/config.js';
9
- import { discoverAccountTargets } from '../../../lib/accountTargetDiscovery.js';
9
+ import { resolveAccountId } from './resolveAccount.js';
10
10
  const TOOL_NAME = 'get-build-logs';
11
11
  const PROJECTS_LOGS_API_PATH = 'dfs/logging/v1';
12
12
  const inputSchema = {
13
13
  absoluteProjectPath,
14
14
  absoluteCurrentWorkingDirectory,
15
+ account,
15
16
  buildId: z
16
17
  .number()
17
18
  .describe('Build ID to fetch logs for. Use get-build-status to find recent build IDs.'),
@@ -61,18 +62,20 @@ export class GetBuildLogsTool extends Tool {
61
62
  constructor(mcpServer, logger) {
62
63
  super(mcpServer, logger, TOOL_NAME);
63
64
  }
64
- async handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, buildId, logLevel, }) {
65
+ async handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, account, buildId, logLevel, }) {
65
66
  setupHubSpotConfig(absoluteProjectPath);
66
67
  try {
67
68
  const { projectConfig, projectDir } = getProjectConfig(absoluteProjectPath);
68
- const { recommended } = await discoverAccountTargets({
69
- projectDir,
70
- projectConfig,
69
+ const resolved = await resolveAccountId(this.mcpServer, this.logger, {
70
+ toolName: TOOL_NAME,
71
+ absoluteCurrentWorkingDirectory,
72
+ account,
73
+ discoverOptions: { projectDir, projectConfig },
71
74
  });
72
- const accountId = recommended?.accountId;
73
- if (!accountId) {
74
- return formatTextContents(absoluteCurrentWorkingDirectory, 'No account ID found. Call the auth-account tool to authenticate a HubSpot account.');
75
+ if ('response' in resolved) {
76
+ return resolved.response;
75
77
  }
78
+ const { accountId } = resolved;
76
79
  const projectName = projectConfig.name;
77
80
  const response = await http.get(accountId, {
78
81
  url: `${PROJECTS_LOGS_API_PATH}/logs/projects/${encodeURIComponent(projectName)}/builds/${buildId}`,
@@ -6,13 +6,14 @@ import { z } from 'zod';
6
6
  declare const inputSchemaZodObject: z.ZodObject<{
7
7
  absoluteProjectPath: z.ZodString;
8
8
  absoluteCurrentWorkingDirectory: z.ZodString;
9
+ account: z.ZodOptional<z.ZodString>;
9
10
  buildId: z.ZodOptional<z.ZodNumber>;
10
11
  limit: z.ZodOptional<z.ZodNumber>;
11
12
  }, z.core.$strip>;
12
13
  export type GetBuildStatusInputSchema = z.infer<typeof inputSchemaZodObject>;
13
14
  export declare class GetBuildStatusTool extends Tool<GetBuildStatusInputSchema> {
14
15
  constructor(mcpServer: McpServer, logger: McpLogger);
15
- handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, buildId, limit, }: GetBuildStatusInputSchema): Promise<McpToolResponse>;
16
+ handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, account, buildId, limit, }: GetBuildStatusInputSchema): Promise<McpToolResponse>;
16
17
  register(): RegisteredTool;
17
18
  }
18
19
  export {};
@@ -5,13 +5,14 @@ import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
5
5
  import { fetchProjectBuilds, getBuildStatus, } from '@hubspot/local-dev-lib/api/projects';
6
6
  import { getProjectConfig } from '../../../lib/projects/config.js';
7
7
  import moment from 'moment';
8
- import { absoluteCurrentWorkingDirectory, absoluteProjectPath, } from './constants.js';
8
+ import { absoluteCurrentWorkingDirectory, absoluteProjectPath, account, } from './constants.js';
9
9
  import { setupHubSpotConfig } from '../../utils/config.js';
10
- import { discoverAccountTargets } from '../../../lib/accountTargetDiscovery.js';
10
+ import { resolveAccountId } from './resolveAccount.js';
11
11
  const TOOL_NAME = 'get-build-status';
12
12
  const inputSchema = {
13
13
  absoluteProjectPath,
14
14
  absoluteCurrentWorkingDirectory,
15
+ account,
15
16
  buildId: z
16
17
  .number()
17
18
  .optional()
@@ -106,18 +107,20 @@ export class GetBuildStatusTool extends Tool {
106
107
  constructor(mcpServer, logger) {
107
108
  super(mcpServer, logger, TOOL_NAME);
108
109
  }
109
- async handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, buildId, limit, }) {
110
+ async handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, account, buildId, limit, }) {
110
111
  setupHubSpotConfig(absoluteProjectPath);
111
112
  try {
112
113
  const { projectConfig, projectDir } = getProjectConfig(absoluteProjectPath);
113
- const { recommended } = await discoverAccountTargets({
114
- projectDir,
115
- projectConfig,
114
+ const resolved = await resolveAccountId(this.mcpServer, this.logger, {
115
+ toolName: TOOL_NAME,
116
+ absoluteCurrentWorkingDirectory,
117
+ account,
118
+ discoverOptions: { projectDir, projectConfig },
116
119
  });
117
- const accountId = recommended?.accountId;
118
- if (!accountId) {
119
- return formatTextContents(absoluteCurrentWorkingDirectory, 'No account ID found. Call the auth-account tool to authenticate a HubSpot account.');
120
+ if ('response' in resolved) {
121
+ return resolved.response;
120
122
  }
123
+ const { accountId } = resolved;
121
124
  const projectName = projectConfig.name;
122
125
  let output;
123
126
  if (buildId) {
@@ -6,13 +6,14 @@ import { z } from 'zod';
6
6
  declare const inputSchemaZodObject: z.ZodObject<{
7
7
  absoluteCurrentWorkingDirectory: z.ZodString;
8
8
  absoluteProjectPath: z.ZodOptional<z.ZodString>;
9
+ account: z.ZodOptional<z.ZodString>;
9
10
  platformVersion: z.ZodString;
10
11
  featureType: z.ZodString;
11
12
  }, z.core.$strip>;
12
13
  type InputSchemaType = z.infer<typeof inputSchemaZodObject>;
13
14
  export declare class GetConfigValuesTool extends Tool<InputSchemaType> {
14
15
  constructor(mcpServer: McpServer, logger: McpLogger);
15
- handler({ platformVersion, featureType, absoluteCurrentWorkingDirectory, absoluteProjectPath, }: InputSchemaType): Promise<McpToolResponse>;
16
+ handler({ platformVersion, featureType, account, absoluteCurrentWorkingDirectory, absoluteProjectPath, }: InputSchemaType): Promise<McpToolResponse>;
16
17
  register(): RegisteredTool;
17
18
  }
18
19
  export {};