@hubspot/cli 8.2.0-beta.0 → 8.2.0-experimental.1

package/mcp-server/tools/index.js

@@ -18,31 +18,33 @@ import { HsCreateFunctionTool } from './cms/HsCreateFunctionTool.js';
 import { HsListFunctionsTool } from './cms/HsListFunctionsTool.js';
 import { HsFunctionLogsTool } from './cms/HsFunctionLogsTool.js';
 import { CreateTestAccountTool } from './project/CreateTestAccountTool.js';
-export function registerProjectTools(mcpServer) {
+import { FindProjectsTool } from './project/FindProjectsTool.js';
+export function registerProjectTools(mcpServer, logger) {
     return [
-        new UploadProjectTools(mcpServer).register(),
-        new CreateProjectTool(mcpServer).register(),
-        new GuidedWalkthroughTool(mcpServer).register(),
-        new CreateTestAccountTool(mcpServer).register(),
-        new DeployProjectTool(mcpServer).register(),
-        new AddFeatureToProjectTool(mcpServer).register(),
-        new ValidateProjectTool(mcpServer).register(),
-        new GetConfigValuesTool(mcpServer).register(),
-        new DocsSearchTool(mcpServer).register(),
-        new DocFetchTool(mcpServer).register(),
-        new GetApiUsagePatternsByAppIdTool(mcpServer).register(),
-        new GetApplicationInfoTool(mcpServer).register(),
-        new GetBuildLogsTool(mcpServer).register(),
-        new GetBuildStatusTool(mcpServer).register(),
+        new UploadProjectTools(mcpServer, logger).register(),
+        new CreateProjectTool(mcpServer, logger).register(),
+        new GuidedWalkthroughTool(mcpServer, logger).register(),
+        new CreateTestAccountTool(mcpServer, logger).register(),
+        new DeployProjectTool(mcpServer, logger).register(),
+        new AddFeatureToProjectTool(mcpServer, logger).register(),
+        new ValidateProjectTool(mcpServer, logger).register(),
+        new GetConfigValuesTool(mcpServer, logger).register(),
+        new DocsSearchTool(mcpServer, logger).register(),
+        new DocFetchTool(mcpServer, logger).register(),
+        new GetApiUsagePatternsByAppIdTool(mcpServer, logger).register(),
+        new GetApplicationInfoTool(mcpServer, logger).register(),
+        new GetBuildLogsTool(mcpServer, logger).register(),
+        new GetBuildStatusTool(mcpServer, logger).register(),
+        new FindProjectsTool(mcpServer, logger).register(),
     ];
 }
-export function registerCmsTools(mcpServer) {
+export function registerCmsTools(mcpServer, logger) {
     return [
-        new HsListTool(mcpServer).register(),
-        new HsCreateModuleTool(mcpServer).register(),
-        new HsCreateTemplateTool(mcpServer).register(),
-        new HsCreateFunctionTool(mcpServer).register(),
-        new HsListFunctionsTool(mcpServer).register(),
-        new HsFunctionLogsTool(mcpServer).register(),
+        new HsListTool(mcpServer, logger).register(),
+        new HsCreateModuleTool(mcpServer, logger).register(),
+        new HsCreateTemplateTool(mcpServer, logger).register(),
+        new HsCreateFunctionTool(mcpServer, logger).register(),
+        new HsListFunctionsTool(mcpServer, logger).register(),
+        new HsFunctionLogsTool(mcpServer, logger).register(),
     ];
 }

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

@@ -1,5 +1,7 @@
-import { TextContentResponse, Tool } from '../../types.js';
+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<{
     absoluteProjectPath: z.ZodString;
@@ -20,15 +22,16 @@ declare const inputSchemaZodObject: z.ZodObject<{
         "workflow-action-tool": "workflow-action-tool";
         page: "page";
         webhooks: "webhooks";
-        "workflow-action": "workflow-action";
         "app-function": "app-function";
         "app-object": "app-object";
         scim: "scim";
+        "workflow-action": "workflow-action";
+        "app-function-endpoint": "app-function-endpoint";
     }>>>;
 }, z.core.$strip>;
 export type AddFeatureInputSchema = z.infer<typeof inputSchemaZodObject>;
 export declare class AddFeatureToProjectTool extends Tool<AddFeatureInputSchema> {
-    constructor(mcpServer: McpServer);
+    constructor(mcpServer: McpServer, logger: McpLogger);
     handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, distribution, auth, features, addApp, }: AddFeatureInputSchema): Promise<TextContentResponse>;
     register(): RegisteredTool;
 }

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

@@ -1,11 +1,10 @@
-import { Tool } from '../../types.js';
+import { Tool } from '../../Tool.js';
 import { z } from 'zod';
 import { APP_AUTH_TYPES, APP_DISTRIBUTION_TYPES, } from '../../../lib/constants.js';
 import { addFlag } from '../../utils/command.js';
 import { absoluteCurrentWorkingDirectory, absoluteProjectPath, features, } from './constants.js';
 import { runCommandInDir } from '../../utils/command.js';
 import { formatTextContents, formatTextContent } from '../../utils/content.js';
-import { trackToolUsage } from '../../utils/toolUsageTracking.js';
 import { setupHubSpotConfig } from '../../utils/config.js';
 import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
 const inputSchema = {
@@ -30,13 +29,12 @@ const inputSchemaZodObject = z.object({
 });
 const toolName = 'add-feature-to-project';
 export class AddFeatureToProjectTool extends Tool {
-    constructor(mcpServer) {
-        super(mcpServer);
+    constructor(mcpServer, logger) {
+        super(mcpServer, logger, toolName);
     }
     async handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, distribution, auth, features, addApp, }) {
         setupHubSpotConfig(absoluteCurrentWorkingDirectory);
         try {
-            await trackToolUsage(toolName);
             let command = `hs project add`;
             const content = [];
             if (distribution) {
@@ -62,6 +60,10 @@ export class AddFeatureToProjectTool extends Tool {
             return formatTextContents(stdout, stderr);
         }
         catch (error) {
+            this.logger.debug(toolName, {
+                message: 'Handler caught error',
+                error: error instanceof Error ? error.message : String(error),
+            });
             return formatTextContents(getErrorMessage(error));
         }
     }
@@ -69,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,
@@ -77,6 +79,6 @@ export class AddFeatureToProjectTool extends Tool {
                 idempotentHint: false,
                 openWorldHint: false,
             },
-        }, this.handler);
+        }, input => this.wrappedHandler(input));
     }
 }

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

@@ -1,5 +1,7 @@
-import { TextContentResponse, Tool } from '../../types.js';
+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<{
     absoluteCurrentWorkingDirectory: z.ZodString;
@@ -24,15 +26,16 @@ declare const inputSchemaZodObject: z.ZodObject<{
         "workflow-action-tool": "workflow-action-tool";
         page: "page";
         webhooks: "webhooks";
-        "workflow-action": "workflow-action";
         "app-function": "app-function";
         "app-object": "app-object";
         scim: "scim";
+        "workflow-action": "workflow-action";
+        "app-function-endpoint": "app-function-endpoint";
     }>>>;
 }, z.core.$strip>;
 export type CreateProjectInputSchema = z.infer<typeof inputSchemaZodObject>;
 export declare class CreateProjectTool extends Tool<CreateProjectInputSchema> {
-    constructor(mcpServer: McpServer);
+    constructor(mcpServer: McpServer, logger: McpLogger);
     handler({ name, destination, projectBase, distribution, auth, features, absoluteCurrentWorkingDirectory, }: CreateProjectInputSchema): Promise<TextContentResponse>;
     register(): RegisteredTool;
 }

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

@@ -1,13 +1,13 @@
-import { Tool } from '../../types.js';
+import { Tool } from '../../Tool.js';
 import { z } from 'zod';
 import { APP_AUTH_TYPES, APP_DISTRIBUTION_TYPES, EMPTY_PROJECT, PROJECT_WITH_APP, } from '../../../lib/constants.js';
 import { addFlag } from '../../utils/command.js';
 import { absoluteCurrentWorkingDirectory, features } from './constants.js';
 import { runCommandInDir } from '../../utils/command.js';
 import { formatTextContents, formatTextContent } from '../../utils/content.js';
-import { trackToolUsage } from '../../utils/toolUsageTracking.js';
 import { setupHubSpotConfig } from '../../utils/config.js';
 import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
+import { PLATFORM_VERSIONS } from '@hubspot/project-parsing-lib/constants';
 const inputSchema = {
     absoluteCurrentWorkingDirectory,
     name: z
@@ -34,13 +34,12 @@ const inputSchema = {
 const inputSchemaZodObject = z.object({ ...inputSchema });
 const toolName = 'create-project';
 export class CreateProjectTool extends Tool {
-    constructor(mcpServer) {
-        super(mcpServer);
+    constructor(mcpServer, logger) {
+        super(mcpServer, logger, toolName);
     }
     async handler({ name, destination, projectBase, distribution, auth, features, absoluteCurrentWorkingDirectory, }) {
         setupHubSpotConfig(absoluteCurrentWorkingDirectory);
-        await trackToolUsage(toolName);
-        let command = addFlag('hs project create', 'platform-version', '2025.2');
+        let command = addFlag('hs project create', 'platform-version', PLATFORM_VERSIONS.v2026_03);
         const content = [];
         if (name) {
             command = addFlag(command, 'name', name);
@@ -78,6 +77,10 @@ export class CreateProjectTool extends Tool {
             return formatTextContents(stdout, stderr);
         }
         catch (error) {
+            this.logger.debug(toolName, {
+                message: 'Handler caught error',
+                error: error instanceof Error ? error.message : String(error),
+            });
             return formatTextContents(getErrorMessage(error));
         }
     }
@@ -92,6 +95,6 @@ export class CreateProjectTool extends Tool {
                 idempotentHint: false,
                 openWorldHint: false,
             },
-        }, this.handler);
+        }, input => this.wrappedHandler(input));
     }
 }

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

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { TextContentResponse, Tool } from '../../types.js';
+import { McpLogger } from '../../utils/logger.js';
+import { TextContentResponse } from '../../types.js';
+import { Tool } from '../../Tool.js';
 declare const createTestAccountInputSchema: z.ZodObject<{
     absoluteCurrentWorkingDirectory: z.ZodString;
     configPath: z.ZodOptional<z.ZodString>;
@@ -44,7 +46,7 @@ declare const createTestAccountInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type CreateTestAccountInputSchema = z.infer<typeof createTestAccountInputSchema>;
 export declare class CreateTestAccountTool extends Tool<CreateTestAccountInputSchema> {
-    constructor(mcpServer: McpServer);
+    constructor(mcpServer: McpServer, logger: McpLogger);
     handler({ absoluteCurrentWorkingDirectory, name, description, marketingLevel, opsLevel, serviceLevel, salesLevel, contentLevel, commerceLevel, configPath, }: CreateTestAccountInputSchema): Promise<TextContentResponse>;
     register(): RegisteredTool;
 }

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

@@ -1,11 +1,10 @@
 import { z } from 'zod';
 import fs from 'fs';
-import { trackToolUsage } from '../../utils/toolUsageTracking.js';
 import { formatTextContents, formatTextContent } from '../../utils/content.js';
 import { addFlag } from '../../utils/command.js';
 import { runCommandInDir } from '../../utils/command.js';
 import { ACCOUNT_LEVELS, ACCOUNT_LEVEL_CHOICES, } from '../../../lib/constants.js';
-import { Tool } from '../../types.js';
+import { Tool } from '../../Tool.js';
 import { absoluteCurrentWorkingDirectory } from './constants.js';
 import { getConfigAccountByName } from '@hubspot/local-dev-lib/config';
 import { setupHubSpotConfig } from '../../utils/config.js';
@@ -58,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()
@@ -68,12 +67,11 @@ const inputSchema = {
 const createTestAccountInputSchema = z.object({ ...inputSchema });
 const toolName = 'create-test-account';
 export class CreateTestAccountTool extends Tool {
-    constructor(mcpServer) {
-        super(mcpServer);
+    constructor(mcpServer, logger) {
+        super(mcpServer, logger, toolName);
     }
     async handler({ absoluteCurrentWorkingDirectory, name, description, marketingLevel, opsLevel, serviceLevel, salesLevel, contentLevel, commerceLevel, configPath, }) {
         setupHubSpotConfig(absoluteCurrentWorkingDirectory);
-        await trackToolUsage(toolName);
         let command = 'hs test-account create';
         const content = [];
         // Use config file if provided (LLM should check for config first)
@@ -84,6 +82,10 @@ export class CreateTestAccountTool extends Tool {
                 configJson = JSON.parse(config);
             }
             catch (error) {
+                this.logger.debug(toolName, {
+                    message: 'Handler caught error reading config file',
+                    error: error instanceof Error ? error.message : String(error),
+                });
                 return {
                     content: [
                         formatTextContent(`Failed to read or parse config file at "${configPath}": ${getErrorMessage(error)}. Please ensure the file exists and contains valid JSON.`),
@@ -97,7 +99,10 @@ export class CreateTestAccountTool extends Tool {
                     }
                 }
                 catch (error) {
-                    // nothing to do here
+                    this.logger.debug(toolName, {
+                        message: 'Handler caught error checking account by config name',
+                        error: error instanceof Error ? error.message : String(error),
+                    });
                 }
             }
             command = addFlag(command, 'config-path', configPath);
@@ -110,7 +115,10 @@ export class CreateTestAccountTool extends Tool {
                 }
             }
             catch (e) {
-                // nothing to do here
+                this.logger.debug(toolName, {
+                    message: 'Handler caught error checking account by name',
+                    error: e instanceof Error ? e.message : String(e),
+                });
             }
             command = addFlag(command, 'name', name);
             command = addFlag(command, 'description', description || name);
@@ -135,6 +143,10 @@ export class CreateTestAccountTool extends Tool {
             return formatTextContents(absoluteCurrentWorkingDirectory, stdout, stderr);
         }
         catch (error) {
+            this.logger.debug(toolName, {
+                message: 'Handler caught error',
+                error: error instanceof Error ? error.message : String(error),
+            });
             return formatTextContents(absoluteCurrentWorkingDirectory, getErrorMessage(error));
         }
     }
@@ -165,6 +177,6 @@ export class CreateTestAccountTool extends Tool {
                 idempotentHint: false,
                 openWorldHint: true,
             },
-        }, this.handler);
+        }, input => this.wrappedHandler(input));
     }
 }

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

@@ -1,5 +1,7 @@
-import { TextContentResponse, Tool } from '../../types.js';
+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<{
     absoluteProjectPath: z.ZodString;
@@ -8,7 +10,7 @@ declare const inputSchemaZodObject: z.ZodObject<{
 }, z.core.$strip>;
 type InputSchemaType = z.infer<typeof inputSchemaZodObject>;
 export declare class DeployProjectTool extends Tool<InputSchemaType> {
-    constructor(mcpServer: McpServer);
+    constructor(mcpServer: McpServer, logger: McpLogger);
     handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, buildNumber, }: InputSchemaType): Promise<TextContentResponse>;
     register(): RegisteredTool;
 }

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

@@ -1,10 +1,9 @@
-import { Tool } from '../../types.js';
+import { Tool } from '../../Tool.js';
 import { z } from 'zod';
 import { addFlag } from '../../utils/command.js';
 import { absoluteCurrentWorkingDirectory, absoluteProjectPath, } from './constants.js';
 import { runCommandInDir } from '../../utils/command.js';
 import { formatTextContents, formatTextContent } from '../../utils/content.js';
-import { trackToolUsage } from '../../utils/toolUsageTracking.js';
 import { setupHubSpotConfig } from '../../utils/config.js';
 const inputSchema = {
     absoluteProjectPath,
@@ -19,12 +18,11 @@ const inputSchemaZodObject = z.object({
 });
 const toolName = 'deploy-project';
 export class DeployProjectTool extends Tool {
-    constructor(mcpServer) {
-        super(mcpServer);
+    constructor(mcpServer, logger) {
+        super(mcpServer, logger, toolName);
     }
     async handler({ absoluteProjectPath, absoluteCurrentWorkingDirectory, buildNumber, }) {
         setupHubSpotConfig(absoluteCurrentWorkingDirectory);
-        await trackToolUsage(toolName);
         let command = `hs project deploy`;
         const content = [];
         if (!buildNumber) {
@@ -45,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,
@@ -53,6 +51,6 @@ export class DeployProjectTool extends Tool {
                 idempotentHint: true,
                 openWorldHint: true,
             },
-        }, this.handler);
+        }, input => this.wrappedHandler(input));
     }
 }

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

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

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

@@ -1,7 +1,6 @@
 import z from 'zod';
-import { Tool } from '../../types.js';
+import { Tool } from '../../Tool.js';
 import { formatTextContents } from '../../utils/content.js';
-import { trackToolUsage } from '../../utils/toolUsageTracking.js';
 import { absoluteCurrentWorkingDirectory, docUrl } from './constants.js';
 import { http } from '@hubspot/local-dev-lib/http/unauthed';
 import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
@@ -17,12 +16,11 @@ const inputSchemaZodObject = z.object({
 });
 const toolName = 'fetch-doc';
 export class DocFetchTool extends Tool {
-    constructor(mcpServer) {
-        super(mcpServer);
+    constructor(mcpServer, logger) {
+        super(mcpServer, logger, toolName);
     }
     async handler({ docUrl, absoluteCurrentWorkingDirectory, }) {
         setupHubSpotConfig(absoluteCurrentWorkingDirectory);
-        await trackToolUsage(toolName);
         try {
             // Append .md extension to the URL
             const markdownUrl = `${docUrl}.md`;
@@ -36,6 +34,10 @@ export class DocFetchTool extends Tool {
             return formatTextContents(content);
         }
         catch (error) {
+            this.logger.debug(toolName, {
+                message: 'Handler caught error',
+                error: error instanceof Error ? error.message : String(error),
+            });
             if (isHubSpotHttpError(error)) {
                 return formatTextContents(error.toString());
             }
@@ -52,6 +54,6 @@ export class DocFetchTool extends Tool {
                 readOnlyHint: true,
                 openWorldHint: true,
             },
-        }, this.handler);
+        }, input => this.wrappedHandler(input));
     }
 }

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

@@ -1,9 +1,12 @@
 import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpLogger } from '../../utils/logger.js';
 import z from 'zod';
-import { TextContentResponse, Tool } from '../../types.js';
+import { TextContentResponse } from '../../types.js';
+import { Tool } from '../../Tool.js';
 declare const inputSchemaZodObject: z.ZodObject<{
     absoluteCurrentWorkingDirectory: z.ZodString;
     docsSearchQuery: z.ZodString;
+    docsSearchLimit: z.ZodDefault<z.ZodNumber>;
 }, z.z.core.$strip>;
 export interface DocsSearchResponse {
     results: {
@@ -16,8 +19,11 @@ export interface DocsSearchResponse {
 }
 type InputSchemaType = z.infer<typeof inputSchemaZodObject>;
 export declare class DocsSearchTool extends Tool<InputSchemaType> {
-    constructor(mcpServer: McpServer);
-    handler({ docsSearchQuery, absoluteCurrentWorkingDirectory, }: InputSchemaType): Promise<TextContentResponse>;
+    constructor(mcpServer: McpServer, logger: McpLogger);
+    protected getTrackingMeta({ docsSearchQuery, }: InputSchemaType): {
+        [key: string]: string;
+    } | undefined;
+    handler({ docsSearchQuery, docsSearchLimit, absoluteCurrentWorkingDirectory, }: InputSchemaType): Promise<TextContentResponse>;
     register(): RegisteredTool;
 }
 export {};

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

@@ -1,16 +1,23 @@
 import { http } from '@hubspot/local-dev-lib/http';
 import z from 'zod';
-import { Tool } from '../../types.js';
+import { Tool } from '../../Tool.js';
 import { formatTextContents } from '../../utils/content.js';
-import { trackToolUsage } from '../../utils/toolUsageTracking.js';
 import { absoluteCurrentWorkingDirectory, docsSearchQuery, } from './constants.js';
 import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
 import { getConfigDefaultAccountIfExists } from '@hubspot/local-dev-lib/config';
 import { setupHubSpotConfig } from '../../utils/config.js';
 import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
+const docsSearchLimit = z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .default(5)
+    .describe('Maximum number of results to return.');
 const inputSchema = {
     absoluteCurrentWorkingDirectory,
     docsSearchQuery,
+    docsSearchLimit,
 };
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const inputSchemaZodObject = z.object({
@@ -18,12 +25,14 @@ const inputSchemaZodObject = z.object({
 });
 const toolName = 'search-docs';
 export class DocsSearchTool extends Tool {
-    constructor(mcpServer) {
-        super(mcpServer);
+    constructor(mcpServer, logger) {
+        super(mcpServer, logger, toolName);
     }
-    async handler({ docsSearchQuery, absoluteCurrentWorkingDirectory, }) {
+    getTrackingMeta({ docsSearchQuery, }) {
+        return { mode: docsSearchQuery };
+    }
+    async handler({ docsSearchQuery, docsSearchLimit, absoluteCurrentWorkingDirectory, }) {
         setupHubSpotConfig(absoluteCurrentWorkingDirectory);
-        await trackToolUsage(toolName, { mode: docsSearchQuery });
         const accountId = getConfigDefaultAccountIfExists()?.accountId;
         if (!accountId) {
             const authErrorMessage = `No account ID found. Please run \`hs account auth\` to configure an account, or set a default account with \`hs account use <account>\``;
@@ -40,13 +49,27 @@ export class DocsSearchTool extends Tool {
             if (!results || results.length === 0) {
                 return formatTextContents('No documentation found for your query.');
             }
-            const formattedResults = results
+            // The docs-search API returns duplicate URLs; dedupe to avoid wasting the result limit on repeats
+            const seen = new Set();
+            const dedupedResults = results.filter(result => {
+                if (seen.has(result.url)) {
+                    return false;
+                }
+                seen.add(result.url);
+                return true;
+            });
+            const limitedResults = dedupedResults.slice(0, docsSearchLimit);
+            const formattedResults = limitedResults
                 .map(result => `**${result.title}**\n${result.description}\nURL: ${result.url}\nScore: ${result.score}\n\n${result.content}\n---\n`)
                 .join('\n');
-            const successMessage = `Found ${results.length} documentation results:\n\n${formattedResults}`;
+            const successMessage = `Found ${dedupedResults.length} results, showing top ${limitedResults.length}:\n\n${formattedResults}`;
             return formatTextContents(successMessage);
         }
         catch (error) {
+            this.logger.debug(toolName, {
+                message: 'Handler caught error',
+                error: error instanceof Error ? error.message : String(error),
+            });
             if (isHubSpotHttpError(error)) {
                 // Handle different status codes
                 return formatTextContents(error.toString());
@@ -64,6 +87,6 @@ export class DocsSearchTool extends Tool {
                 readOnlyHint: true,
                 openWorldHint: true,
             },
-        }, this.handler);
+        }, input => this.wrappedHandler(input));
     }
 }

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 {};

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

@@ -0,0 +1,60 @@
+import { Tool } from '../../Tool.js';
+import { z } from 'zod';
+import { formatTextContents } from '../../utils/content.js';
+import { walk } from '@hubspot/local-dev-lib/fs';
+import path from 'path';
+import { PROJECT_CONFIG_FILE } from '../../../lib/constants.js';
+const TOOL_NAME = 'find-projects';
+const IGNORE_DIRS = ['node_modules', '.git', '.vite'];
+const inputSchema = {
+    absoluteDirectory: z
+        .string()
+        .describe('The absolute path to the directory to search for HubSpot projects in.'),
+};
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const inputSchemaZodObject = z.object({ ...inputSchema });
+export class FindProjectsTool extends Tool {
+    constructor(mcpServer, logger) {
+        super(mcpServer, logger, TOOL_NAME);
+    }
+    async handler({ absoluteDirectory, }) {
+        try {
+            const allFiles = await walk(absoluteDirectory, IGNORE_DIRS);
+            const projectFiles = allFiles.filter(file => path.basename(file) === PROJECT_CONFIG_FILE);
+            if (projectFiles.length === 0) {
+                return formatTextContents(`No ${PROJECT_CONFIG_FILE} files found under ${absoluteDirectory}.`);
+            }
+            const projectDirs = projectFiles.map(file => path.dirname(file));
+            const output = [
+                `Found ${projectFiles.length} project(s):`,
+                '',
+                ...projectDirs.map(dir => `  ${dir}`),
+            ].join('\n');
+            return formatTextContents(output);
+        }
+        catch (error) {
+            this.logger.debug(TOOL_NAME, {
+                message: 'Handler caught error',
+                error: error instanceof Error ? error.message : String(error),
+            });
+            const cause = error instanceof Error ? error.cause : undefined;
+            const causeMessage = cause instanceof Error ? `: ${cause.message}` : '';
+            const errorMessage = error instanceof Error
+                ? error.message || `FileSystemError${causeMessage}`
+                : String(error);
+            return formatTextContents(`Error searching for projects: ${errorMessage}`);
+        }
+    }
+    register() {
+        return this.mcpServer.registerTool(TOOL_NAME, {
+            title: 'Find HubSpot Projects',
+            description: 'Use this tool to locate HubSpot projects. Traverses child directories of the given directory to find hsproject.json files, returning the paths of all discovered HubSpot projects.',
+            inputSchema,
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+                idempotentHint: true,
+            },
+        }, input => this.wrappedHandler(input));
+    }
+}