@hubspot/cli 8.5.0 → 8.6.0-beta.0

package/lib/link/prompts.js

@@ -0,0 +1,126 @@
+import { promptUser } from '../prompts/promptUtils.js';
+import { uiAccountDescription } from '../ui/index.js';
+import { uiLogger } from '../ui/logger.js';
+import { commands } from '../../lang/en.js';
+import { buildAccountRow, getNameColumnWidth, buildAccountHeader, sortDefaultFirst, } from './accountTableUtils.js';
+import { Separator } from '@inquirer/prompts';
+function buildColumnarChoices(accounts, localDefaultAccount) {
+    const rows = accounts.map(a => ({
+        ...buildAccountRow(a.accountId, a.accountId === localDefaultAccount),
+        disabled: a.disabled,
+        checked: a.checked,
+        hint: a.hint,
+    }));
+    const nameWidth = getNameColumnWidth(rows);
+    const header = buildAccountHeader(nameWidth);
+    return [
+        new Separator(header),
+        ...rows.map(row => {
+            const label = `${row.name.padEnd(nameWidth)}  ${row.accountId}`;
+            return {
+                name: row.hint ? `${label}  ${row.hint}` : label,
+                short: uiAccountDescription(Number(row.accountId), false),
+                value: Number(row.accountId),
+                disabled: row.disabled,
+                checked: row.checked,
+            };
+        }),
+    ];
+}
+function mapLinkAccountChoices(eligibleAccounts, inEligibleAccounts, accountOverrideId, localDefaultAccount, preselectedAccountId) {
+    const sortedIneligible = sortDefaultFirst(inEligibleAccounts, localDefaultAccount);
+    const accounts = [
+        ...eligibleAccounts.map(a => ({
+            accountId: a.accountId,
+            disabled: false,
+            checked: a.accountId === accountOverrideId ||
+                a.accountId === preselectedAccountId,
+            hint: a.accountId === accountOverrideId
+                ? commands.account.subcommands.link.prompts.fromHsAccount
+                : a.accountId === preselectedAccountId
+                    ? commands.account.subcommands.link.prompts.newlyAuthenticated
+                    : undefined,
+        })),
+        ...sortedIneligible.map(a => ({
+            accountId: a.accountId,
+            disabled: commands.account.subcommands.link.prompts.alreadyLinked,
+            checked: false,
+        })),
+    ];
+    return buildColumnarChoices(accounts, localDefaultAccount);
+}
+export async function promptForAction(state) {
+    const isSettingsEmpty = state.accounts.length === 0 && state.localDefaultAccount === undefined;
+    const { accountEditOption } = await promptUser({
+        type: 'list',
+        name: 'accountEditOption',
+        message: isSettingsEmpty
+            ? commands.account.subcommands.link.prompts.howToProceed
+            : commands.account.subcommands.link.prompts.whatToDo,
+        choices: [
+            {
+                name: commands.account.subcommands.link.prompts.linkExisting,
+                value: 'link',
+            },
+            {
+                name: commands.account.subcommands.link.prompts.authenticateNew,
+                value: 'authenticate',
+            },
+            {
+                name: commands.account.subcommands.link.prompts.cancel,
+                value: 'cancel',
+            },
+        ],
+    });
+    uiLogger.log('');
+    return accountEditOption;
+}
+export async function promptForDefaultAccount(accounts, currentDefaultAccount, prompt = '') {
+    const choiceAccounts = accounts.map(accountId => ({
+        accountId,
+    }));
+    const choices = buildColumnarChoices(choiceAccounts, currentDefaultAccount);
+    const { defaultAccount } = await promptUser({
+        type: 'list',
+        name: 'defaultAccount',
+        pageSize: 20,
+        message: prompt || commands.account.subcommands.link.prompts.selectDefault,
+        choices,
+        default: currentDefaultAccount ?? undefined,
+    });
+    uiLogger.log('');
+    return defaultAccount;
+}
+export async function promptForAccountsToLink(context, eligibleAccounts, inEligibleAccounts, localDefaultAccount) {
+    const { accountsToAdd } = await promptUser({
+        type: 'checkbox',
+        name: 'accountsToAdd',
+        pageSize: 20,
+        message: commands.account.subcommands.link.prompts.selectToLink,
+        choices: mapLinkAccountChoices(eligibleAccounts, inEligibleAccounts, context.accountOverrideId, localDefaultAccount, context.preselectedAccountId),
+        validate: (answer) => {
+            if (answer.length === 0) {
+                return commands.account.subcommands.link.prompts.mustSelectOne;
+            }
+            return true;
+        },
+    });
+    uiLogger.log('');
+    return accountsToAdd;
+}
+export async function promptForAccountsToUnlink(accounts, localDefaultAccount) {
+    const sortedAccounts = sortDefaultFirst(accounts, localDefaultAccount);
+    const choiceAccounts = sortedAccounts.map(accountId => ({
+        accountId,
+    }));
+    const choices = buildColumnarChoices(choiceAccounts, localDefaultAccount);
+    const { accountsToRemove } = await promptUser({
+        type: 'checkbox',
+        name: 'accountsToRemove',
+        pageSize: 20,
+        message: commands.account.subcommands.link.prompts.selectToUnlink,
+        choices,
+    });
+    uiLogger.log('');
+    return accountsToRemove;
+}

package/lib/link/renderLinkedAccountsTable.d.ts

@@ -0,0 +1,2 @@
+import { HsSettingsFile } from '@hubspot/local-dev-lib/types/HsSettings';
+export declare function renderLinkedAccountsTable(settings: HsSettingsFile): Promise<void>;

package/lib/link/renderLinkedAccountsTable.js

@@ -0,0 +1,14 @@
+import { commands } from '../../lang/en.js';
+import { renderTable } from '../../ui/render.js';
+import { buildAccountRow, sortDefaultFirst } from './accountTableUtils.js';
+export async function renderLinkedAccountsTable(settings) {
+    const labels = commands.account.subcommands.list.labels;
+    const tableHeader = [labels.name, labels.accountId];
+    const sortedAccounts = sortDefaultFirst(settings.accounts, settings.localDefaultAccount);
+    const tableData = sortedAccounts.map(accountId => {
+        const isDefault = accountId === settings.localDefaultAccount;
+        const row = buildAccountRow(accountId, isDefault);
+        return [row.name, row.accountId];
+    });
+    await renderTable(tableHeader, tableData, true);
+}

package/lib/link/warnIfLinkedDirectory.d.ts

@@ -0,0 +1 @@
+export declare function warnIfLinkedDirectory(args: (string | number)[]): void;

package/lib/link/warnIfLinkedDirectory.js

@@ -0,0 +1,9 @@
+import { getHsSettingsFilePath } from '@hubspot/local-dev-lib/config/hsSettings';
+import { uiLogger } from '../ui/logger.js';
+import { lib } from '../../lang/en.js';
+export function warnIfLinkedDirectory(args) {
+    if (getHsSettingsFilePath() === null) {
+        return;
+    }
+    uiLogger.warn(lib.linkedDirectory.warning(`hs ${args.join(' ')}`, getHsSettingsFilePath()));
+}

package/lib/projects/localDev/DevServerManager_DEPRECATED.d.ts

@@ -21,12 +21,13 @@ declare class DevServerManager_DEPRECATED {
         [key: string]: Component;
     }) => Promise<void>): Promise<void>;
     arrangeComponentsByType(components: Component[]): ComponentsByType;
-    setup({ components, onUploadRequired, accountId, setActiveApp, exit, }: {
+    setup({ components, onUploadRequired, accountId, setActiveApp, exit, port, }: {
         components: Component[];
         onUploadRequired: () => void;
         accountId: number;
         setActiveApp: (appUid: string | undefined) => Promise<void>;
         exit: ExitFunction;
+        port?: number;
     }): Promise<void>;
     start({ accountId, projectConfig, }: {
         accountId: number;

package/lib/projects/localDev/DevServerManager_DEPRECATED.js

@@ -57,7 +57,7 @@ class DevServerManager_DEPRECATED {
             return acc;
         }, {});
     }
-    async setup({ components, onUploadRequired, accountId, setActiveApp, exit, }) {
+    async setup({ components, onUploadRequired, accountId, setActiveApp, exit, port, }) {
         this.componentsByType = this.arrangeComponentsByType(components);
         let env;
         const accountConfig = getConfigAccountById(accountId);
@@ -65,7 +65,7 @@ class DevServerManager_DEPRECATED {
             env = accountConfig.env;
         }
         try {
-            await startPortManagerServer();
+            await startPortManagerServer(port);
         }
         catch (e) {
             logError(e);

package/lib/projects/localDev/LocalDevManager_DEPRECATED.d.ts

@@ -16,6 +16,7 @@ type LocalDevManagerConstructorOptions = {
     runnableComponents: Component[];
     env: Environment;
     exit: ExitFunction;
+    port?: number;
 };
 declare class LocalDevManager_DEPRECATED {
     targetAccountId: number;
@@ -39,6 +40,7 @@ declare class LocalDevManager_DEPRECATED {
     mostRecentUploadWarning: string | null;
     private devSessionManager;
     private exit;
+    private port?;
     constructor(options: LocalDevManagerConstructorOptions);
     setActiveApp(appUid?: string): Promise<void>;
     setActivePublicAppData(): Promise<void>;

package/lib/projects/localDev/LocalDevManager_DEPRECATED.js

@@ -48,6 +48,7 @@ class LocalDevManager_DEPRECATED {
     mostRecentUploadWarning;
     devSessionManager;
     exit;
+    port;
     constructor(options) {
         this.targetAccountId = options.targetAccountId;
         // The account that the project exists in. This is not always the targetAccountId
@@ -67,6 +68,7 @@ class LocalDevManager_DEPRECATED {
         this.publicAppActiveInstalls = null;
         this.mostRecentUploadWarning = null;
         this.exit = options.exit;
+        this.port = options.port;
         this.projectSourceDir = path.join(this.projectDir, this.projectConfig.srcDir);
         if (!this.targetAccountId || !this.projectConfig || !this.projectDir) {
             uiLogger.error(lib.LocalDevManager.failedToInitialize);
@@ -337,6 +339,7 @@ class LocalDevManager_DEPRECATED {
                 accountId: this.targetAccountId,
                 setActiveApp: this.setActiveApp.bind(this),
                 exit: this.exit,
+                port: this.port,
             });
             return true;
         }

package/lib/projects/uieLinting.d.ts

@@ -1,10 +1,19 @@
 export declare const REQUIRED_PACKAGES_AND_MIN_VERSIONS: {
     readonly eslint: "9.0.0";
-    readonly '@typescript-eslint/eslint-plugin': "8.46.4";
-    readonly '@typescript-eslint/parser': "8.46.4";
+    readonly '@eslint/js': "9.0.0";
     readonly 'typescript-eslint': "8.46.4";
+    readonly '@hubspot/eslint-config-ui-extensions': "1.0.0";
+    readonly 'eslint-config-prettier': "10.0.0";
+    readonly 'eslint-plugin-react': "7.0.0";
+    readonly 'eslint-plugin-react-hooks': "7.0.0";
+    readonly 'eslint-plugin-unused-imports': "4.0.0";
+    readonly prettier: "3.0.0";
     readonly jiti: "2.6.1";
 };
+export declare const LINT_SCRIPTS: {
+    readonly lint: "eslint .";
+    readonly 'lint:fix': "eslint . --fix";
+};
 export declare function isEslintInstalled(directory: string): boolean;
 export declare function areAllLintPackagesInstalled(directory: string): boolean;
 export declare function getMissingLintPackages(directory: string): {
@@ -13,7 +22,7 @@ export declare function getMissingLintPackages(directory: string): {
 export declare function hasEslintConfig(directory: string): boolean;
 export declare function hasDeprecatedEslintConfig(directory: string): boolean;
 export declare function getDeprecatedEslintConfigFiles(directory: string): string[];
-export declare function createEslintConfig(directory: string): string;
+export declare function createEslintConfig(directory: string, platformVersion?: string | null): Promise<string>;
 export declare function lintPackagesInDirectory(directory: string, projectDir?: string): Promise<{
     success: boolean;
     output: string;
@@ -31,3 +40,8 @@ export declare function displayLintResults(results: Array<{
     success: boolean;
     output: string;
 }>): void;
+export declare function getMissingLintScripts(directory: string): string[];
+export declare function addLintScriptsToPackageJson(directory: string): {
+    added: string[];
+    relativePath: string;
+};

package/lib/projects/uieLinting.js

@@ -3,17 +3,27 @@ import path from 'path';
 import util from 'util';
 import semver from 'semver';
 import { exec as execAsync } from 'node:child_process';
+import { fetchRepoFile } from '@hubspot/local-dev-lib/api/github';
 import { getProjectPackageJsonLocations, isPackageInstalled, } from '../dependencyManagement.js';
 import { commands } from '../../lang/en.js';
 import { uiLogger } from '../ui/logger.js';
-import { safeGetPackageJsonCached } from '../npm/packageJson.js';
+import { clearPackageJsonCache, safeGetPackageJsonCached, } from '../npm/packageJson.js';
+import { debugError } from '../errorHandlers/index.js';
+import { isLegacyProject } from '@hubspot/project-parsing-lib/projects';
+import { HUBSPOT_PROJECT_COMPONENTS_GITHUB_PATH, DEFAULT_PROJECT_TEMPLATE_BRANCH, } from '../constants.js';
 export const REQUIRED_PACKAGES_AND_MIN_VERSIONS = {
     eslint: '9.0.0',
-    '@typescript-eslint/eslint-plugin': '8.46.4',
-    '@typescript-eslint/parser': '8.46.4',
+    '@eslint/js': '9.0.0',
     'typescript-eslint': '8.46.4',
+    '@hubspot/eslint-config-ui-extensions': '1.0.0',
+    'eslint-config-prettier': '10.0.0',
+    'eslint-plugin-react': '7.0.0',
+    'eslint-plugin-react-hooks': '7.0.0',
+    'eslint-plugin-unused-imports': '4.0.0',
+    prettier: '3.0.0',
     jiti: '2.6.1',
 };
+const UIE_ESLINT_CONFIG_PATH_IN_REPO = 'components/cards/src/app/cards/eslint.config.js';
 const ESLINT_CONFIG_FILES = [
     'eslint.config.mts',
     'eslint.config.ts',
@@ -30,28 +40,10 @@ const DEPRECATED_ESLINT_CONFIG_FILES = [
     '.eslintrc.json',
     '.eslintrc',
 ];
-const ESLINT_CONFIG_TEMPLATE = `import { defineConfig } from "eslint/config";
-import tsParser from "@typescript-eslint/parser";
-
-export default defineConfig([
-  {
-    files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
-    languageOptions: {
-      parser: tsParser,
-      parserOptions: {
-        ecmaVersion: "latest",
-        sourceType: "module",
-        ecmaFeatures: {
-          jsx: true
-        }
-      }
-    },
-    rules: {
-      "no-console": ["warn", { allow: ["warn", "error"] }]
-    }
-  },
-]);
-`;
+export const LINT_SCRIPTS = {
+    lint: 'eslint .',
+    'lint:fix': 'eslint . --fix',
+};
 function getPackageVersionFromPackageJson(directory, packageName) {
     const packageJsonPath = path.join(directory, 'package.json');
     const packageJson = safeGetPackageJsonCached(packageJsonPath);
@@ -127,10 +119,43 @@ export function getDeprecatedEslintConfigFiles(directory) {
         return fs.existsSync(configPath);
     });
 }
-export function createEslintConfig(directory) {
-    const configPath = path.join(directory, 'eslint.config.mts');
+function repoFileDataToString(data) {
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (Buffer.isBuffer(data)) {
+        return data.toString('utf-8');
+    }
+    return String(data);
+}
+export async function createEslintConfig(directory, platformVersion) {
+    const versionForRemote = platformVersion && !isLegacyProject(platformVersion)
+        ? platformVersion
+        : null;
+    if (versionForRemote === null) {
+        const message = commands.project.lint.createEslintConfigRequiresV2Platform(platformVersion);
+        uiLogger.error(message);
+        throw new Error(message);
+    }
+    let fetchedContent = null;
     try {
-        fs.writeFileSync(configPath, ESLINT_CONFIG_TEMPLATE, 'utf-8');
+        const { data } = await fetchRepoFile(HUBSPOT_PROJECT_COMPONENTS_GITHUB_PATH, `${versionForRemote}/${UIE_ESLINT_CONFIG_PATH_IN_REPO}`, DEFAULT_PROJECT_TEMPLATE_BRANCH);
+        const content = repoFileDataToString(data);
+        if (content.trim().length > 0) {
+            fetchedContent = content;
+        }
+    }
+    catch (error) {
+        debugError(error);
+    }
+    if (fetchedContent === null) {
+        const message = commands.project.lint.failedToFetchRemoteEslintConfig(versionForRemote);
+        uiLogger.error(message);
+        throw new Error(message);
+    }
+    const configPath = path.join(directory, 'eslint.config.js');
+    try {
+        fs.writeFileSync(configPath, fetchedContent, 'utf-8');
         return path.relative(process.cwd(), configPath);
     }
     catch (error) {
@@ -218,3 +243,43 @@ export function displayLintResults(results) {
         });
     }
 }
+export function getMissingLintScripts(directory) {
+    const packageJsonPath = path.join(directory, 'package.json');
+    const packageJson = safeGetPackageJsonCached(packageJsonPath);
+    if (!packageJson) {
+        return [];
+    }
+    return Object.keys(LINT_SCRIPTS).filter(scriptName => !packageJson.scripts?.[scriptName]);
+}
+export function addLintScriptsToPackageJson(directory) {
+    const packageJsonPath = path.join(directory, 'package.json');
+    try {
+        const rawContent = fs.readFileSync(packageJsonPath, 'utf-8');
+        const packageJson = JSON.parse(rawContent);
+        if (!packageJson.scripts) {
+            packageJson.scripts = {};
+        }
+        const added = [];
+        for (const [scriptName, scriptValue] of Object.entries(LINT_SCRIPTS)) {
+            if (!packageJson.scripts[scriptName]) {
+                packageJson.scripts[scriptName] = scriptValue;
+                added.push(scriptName);
+            }
+        }
+        if (added.length > 0) {
+            fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf-8');
+            clearPackageJsonCache();
+        }
+        return {
+            added,
+            relativePath: path.relative(process.cwd(), packageJsonPath),
+        };
+    }
+    catch {
+        uiLogger.warn(commands.project.lint.failedToAddLintScripts(packageJsonPath));
+        return {
+            added: [],
+            relativePath: path.relative(process.cwd(), packageJsonPath),
+        };
+    }
+}

package/lib/prompts/promptUtils.js

@@ -42,6 +42,7 @@ function mapPromptChoicesToChoices(choices) {
         return {
             value: choice.value,
             name: choice.name,
+            short: choice.short,
             disabled: choice.disabled,
             checked: choice.checked,
         };

package/lib/ui/accountTable.d.ts

@@ -0,0 +1,8 @@
+import { HubSpotConfigAccount } from '@hubspot/local-dev-lib/types/Accounts';
+export declare function sortAndMapAccounts(accounts: HubSpotConfigAccount[]): {
+    [key: string]: HubSpotConfigAccount[];
+};
+export declare function getAccountData(mappedAccountData: {
+    [key: string]: HubSpotConfigAccount[];
+}): string[][];
+export declare function renderAccountTable(showAllLabel?: boolean): void;

package/lib/ui/accountTable.js

@@ -0,0 +1,67 @@
+import { HUBSPOT_ACCOUNT_TYPES, HUBSPOT_ACCOUNT_TYPE_STRINGS, } from '@hubspot/local-dev-lib/constants/config';
+import { isSandbox, isDeveloperTestAccount } from '../accountTypes.js';
+import { getAllConfigAccounts } from '@hubspot/local-dev-lib/config';
+import { commands } from '../../lang/en.js';
+import { renderTable } from '../../ui/render.js';
+import { uiLogger } from './logger.js';
+export function sortAndMapAccounts(accounts) {
+    const mappedAccountData = {};
+    // Standard and app developer accounts
+    accounts
+        .filter(p => p.accountType &&
+        (p.accountType === HUBSPOT_ACCOUNT_TYPES.STANDARD ||
+            p.accountType === HUBSPOT_ACCOUNT_TYPES.APP_DEVELOPER))
+        .forEach(account => {
+        mappedAccountData[account.accountId] = [account];
+    });
+    // Non-standard accounts (sandbox, developer test account)
+    accounts
+        .filter(p => p.accountType && (isSandbox(p) || isDeveloperTestAccount(p)))
+        .forEach(p => {
+        if (p.parentAccountId) {
+            mappedAccountData[p.parentAccountId] = [
+                ...(mappedAccountData[p.parentAccountId] || []),
+                p,
+            ];
+        }
+        else {
+            mappedAccountData[p.accountId] = [p];
+        }
+    });
+    return mappedAccountData;
+}
+export function getAccountData(mappedAccountData) {
+    const accountData = [];
+    Object.entries(mappedAccountData).forEach(([key, set]) => {
+        const hasParentAccount = set.filter(p => p.accountId === parseInt(key, 10))[0];
+        set.forEach(account => {
+            let name = `${account.name} [${HUBSPOT_ACCOUNT_TYPE_STRINGS[account.accountType]}]`;
+            if (isSandbox(account)) {
+                if (hasParentAccount && set.length > 1) {
+                    name = `↳ ${name}`;
+                }
+            }
+            else if (isDeveloperTestAccount(account)) {
+                if (hasParentAccount && set.length > 1) {
+                    name = `↳ ${name}`;
+                }
+            }
+            accountData.push([name, String(account.accountId), account.authType]);
+        });
+    });
+    return accountData;
+}
+export function renderAccountTable(showAllLabel = false) {
+    const accountsList = getAllConfigAccounts();
+    const mappedAccountData = sortAndMapAccounts(accountsList);
+    const accountData = getAccountData(mappedAccountData);
+    const tableHeader = [
+        commands.account.subcommands.list.labels.name,
+        commands.account.subcommands.list.labels.accountId,
+        commands.account.subcommands.list.labels.authType,
+    ];
+    uiLogger.log(showAllLabel
+        ? commands.account.subcommands.list.allAccounts
+        : commands.account.subcommands.list.accounts);
+    renderTable(tableHeader, accountData, true);
+}

package/mcp-server/server.js

@@ -2,11 +2,49 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerProjectTools, registerCmsTools } from './tools/index.js';
 import { McpLogger } from './utils/logger.js';
+const instructions = `
+This server exposes the HubSpot CLI (\`hs\`) for local development of HubSpot
+projects, apps, and CMS assets. Prefer these tools over running \`hs\`,
+\`npx hs\`, or HubSpot HTTP APIs directly via shell — they handle config
+loading, auth, platform-version flags, and structured output for you.
+
+WHEN TO USE THIS SERVER
+- The user is working in a HubSpot project directory (has an hsproject.json
+  or *-hsmeta.json files), or wants to scaffold one.
+- The user asks about HubSpot apps, CMS modules/templates/serverless
+  functions, project builds, deploys, or developer test accounts.
+- The user asks a HubSpot platform/API question — answer it from the docs
+  via \`search-docs\` + \`fetch-doc\` rather than from prior knowledge.
+
+REQUIRED WORKFLOWS
+1. Documentation lookup: always call \`search-docs\` first, then
+   \`fetch-doc\` on the most relevant result(s) before planning, writing
+   code, or answering platform/API questions. Do not answer from memory.
+2. Locating a HubSpot project: when the current working directory is not
+   a HubSpot project (no \`hsproject.json\`) or you need to determine
+   whether a directory contains one, call \`find-projects\` before
+   running any tool that requires a project path.
+3. Editing \`*-hsmeta.json\`: call \`get-feature-config-schema\` for that
+   feature type first to learn the allowed fields and values.
+4. Debugging a failed build: start with \`get-build-status\` to surface
+   error messages, and only reach for \`get-build-logs\` for deeper
+   troubleshooting or warnings.
+5. Reading serverless function logs: call \`list-cms-serverless-functions\`
+   first to discover the endpoint path, then
+   \`get-cms-serverless-function-logs\`.
+6. App analytics: call \`get-apps-info\` to discover \`appId\` values
+   before \`get-api-usage-patterns-by-app-id\`.
+
+OUTPUT
+Tool results contain the relevant \`hs\` stdout/stderr or structured data.
+Surface error text from results to the user verbatim when troubleshooting,
+rather than paraphrasing.
+`.trim();
 const server = new McpServer({
     name: 'HubSpot CLI MCP Server',
     version: '0.0.1',
     description: 'Helps perform tasks for local development of HubSpot projects.',
-}, { capabilities: { logging: {} } });
+}, { capabilities: { logging: {} }, instructions });
 const logger = new McpLogger(server);
 registerProjectTools(server, logger);
 registerCmsTools(server, logger);

package/mcp-server/tools/index.js

@@ -18,6 +18,7 @@ import { HsCreateFunctionTool } from './cms/HsCreateFunctionTool.js';
 import { HsListFunctionsTool } from './cms/HsListFunctionsTool.js';
 import { HsFunctionLogsTool } from './cms/HsFunctionLogsTool.js';
 import { CreateTestAccountTool } from './project/CreateTestAccountTool.js';
+import { FindProjectsTool } from './project/FindProjectsTool.js';
 export function registerProjectTools(mcpServer, logger) {
     return [
         new UploadProjectTools(mcpServer, logger).register(),
@@ -34,6 +35,7 @@ export function registerProjectTools(mcpServer, logger) {
         new GetApplicationInfoTool(mcpServer, logger).register(),
         new GetBuildLogsTool(mcpServer, logger).register(),
         new GetBuildStatusTool(mcpServer, logger).register(),
+        new FindProjectsTool(mcpServer, logger).register(),
     ];
 }
 export function registerCmsTools(mcpServer, logger) {

package/mcp-server/tools/project/AddFeatureToProjectTool.js

@@ -71,7 +71,7 @@ export class AddFeatureToProjectTool extends Tool {
         return this.mcpServer.registerTool(toolName, {
             title: 'Add feature to HubSpot Project',
             description: `Adds a feature to an existing HubSpot project.
-          Only works for projects with platformVersion '2025.2' and beyond`,
+          Only works for projects with platformVersion '2025.2' and beyond. If you do not know the project path, use the find-projects tool first to locate HubSpot projects in the workspace.`,
             inputSchema,
             annotations: {
                 readOnlyHint: false,

package/mcp-server/tools/project/CreateTestAccountTool.js

@@ -57,7 +57,7 @@ const inputSchema = {
     contentLevel: z
         .enum(ACCOUNT_LEVEL_CHOICES)
         .optional()
-        .describe(`CMS Hub tier level. Options: ${ACCOUNT_LEVEL_CHOICES.join(', ')}. Defaults to ENTERPRISE if not specified.`),
+        .describe(`Content Hub tier level. Options: ${ACCOUNT_LEVEL_CHOICES.join(', ')}. Defaults to ENTERPRISE if not specified.`),
     commerceLevel: z
         .enum(ACCOUNT_LEVEL_CHOICES_WITHOUT_STARTER)
         .optional()

package/mcp-server/tools/project/DeployProjectTool.js

@@ -43,7 +43,7 @@ export class DeployProjectTool extends Tool {
     register() {
         return this.mcpServer.registerTool(toolName, {
             title: 'Deploy a build of HubSpot Project',
-            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.',
+            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.',
             inputSchema,
             annotations: {
                 readOnlyHint: false,

package/mcp-server/tools/project/FindProjectsTool.d.ts

@@ -0,0 +1,15 @@
+import { TextContentResponse } from '../../types.js';
+import { Tool } from '../../Tool.js';
+import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpLogger } from '../../utils/logger.js';
+import { z } from 'zod';
+declare const inputSchemaZodObject: z.ZodObject<{
+    absoluteDirectory: z.ZodString;
+}, z.core.$strip>;
+export type FindProjectsInputSchema = z.infer<typeof inputSchemaZodObject>;
+export declare class FindProjectsTool extends Tool<FindProjectsInputSchema> {
+    constructor(mcpServer: McpServer, logger: McpLogger);
+    handler({ absoluteDirectory, }: FindProjectsInputSchema): Promise<TextContentResponse>;
+    register(): RegisteredTool;
+}
+export {};