@hubspot/cli 7.6.0-beta.7 → 7.6.0-beta.8

package/mcp-server/tools/index.js

@@ -5,6 +5,8 @@ import { DeployProjectTool } from './project/DeployProjectTool.js';
 import { AddFeatureToProjectTool } from './project/AddFeatureToProjectTool.js';
 import { ValidateProjectTool } from './project/ValidateProjectTool.js';
 import { GetConfigValuesTool } from './project/GetConfigValuesTool.js';
+import { DocsSearchTool } from './project/DocsSearchTool.js';
+import { DocFetchTool } from './project/DocFetchTool.js';
 export function registerProjectTools(mcpServer) {
     return [
         new UploadProjectTools(mcpServer).register(),
@@ -14,5 +16,7 @@ export function registerProjectTools(mcpServer) {
         new AddFeatureToProjectTool(mcpServer).register(),
         new ValidateProjectTool(mcpServer).register(),
         new GetConfigValuesTool(mcpServer).register(),
+        new DocsSearchTool(mcpServer).register(),
+        new DocFetchTool(mcpServer).register(),
     ];
 }

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

@@ -0,0 +1,17 @@
+import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import z from 'zod';
+import { TextContentResponse, Tool } from '../../types.js';
+declare const inputSchemaZodObject: z.ZodObject<{
+    docUrl: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    docUrl: string;
+}, {
+    docUrl: string;
+}>;
+type InputSchemaType = z.infer<typeof inputSchemaZodObject>;
+export declare class DocFetchTool extends Tool<InputSchemaType> {
+    constructor(mcpServer: McpServer);
+    handler({ docUrl }: InputSchemaType): Promise<TextContentResponse>;
+    register(): RegisteredTool;
+}
+export {};

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

@@ -0,0 +1,49 @@
+import z from 'zod';
+import { Tool } from '../../types.js';
+import { formatTextContents } from '../../utils/content.js';
+import { trackToolUsage } from '../../utils/toolUsageTracking.js';
+import { docUrl } from './constants.js';
+import { http } from '@hubspot/local-dev-lib/http/unauthed';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+const inputSchema = {
+    docUrl,
+};
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const inputSchemaZodObject = z.object({
+    ...inputSchema,
+});
+const toolName = 'fetch-hubspot-doc';
+export class DocFetchTool extends Tool {
+    constructor(mcpServer) {
+        super(mcpServer);
+    }
+    async handler({ docUrl }) {
+        await trackToolUsage(toolName);
+        try {
+            // Append .md extension to the URL
+            const markdownUrl = `${docUrl}.md`;
+            const response = await http.get({
+                url: markdownUrl,
+            });
+            const content = response.data;
+            if (!content || content.trim().length === 0) {
+                return formatTextContents('Document is empty or contains no content.');
+            }
+            return formatTextContents(content);
+        }
+        catch (error) {
+            if (isHubSpotHttpError(error)) {
+                return formatTextContents(error.toString());
+            }
+            const errorMessage = `Error fetching documentation: ${error instanceof Error ? error.message : String(error)}`;
+            return formatTextContents(errorMessage);
+        }
+    }
+    register() {
+        return this.mcpServer.registerTool(toolName, {
+            title: 'Fetch a single HubSpot Developer Documentation file',
+            description: 'Fetch a single HubSpot Developer Documentation file by URL. Call after search-hubspot-docs.',
+            inputSchema,
+        }, this.handler);
+    }
+}

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

@@ -0,0 +1,26 @@
+import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import z from 'zod';
+import { TextContentResponse, Tool } from '../../types.js';
+declare const inputSchemaZodObject: z.ZodObject<{
+    docsSearchQuery: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    docsSearchQuery: string;
+}, {
+    docsSearchQuery: string;
+}>;
+export interface DocsSearchResponse {
+    results: {
+        title: string;
+        content: string;
+        description: string;
+        url: string;
+        score: number;
+    }[];
+}
+type InputSchemaType = z.infer<typeof inputSchemaZodObject>;
+export declare class DocsSearchTool extends Tool<InputSchemaType> {
+    constructor(mcpServer: McpServer);
+    handler({ docsSearchQuery, }: InputSchemaType): Promise<TextContentResponse>;
+    register(): RegisteredTool;
+}
+export {};

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

@@ -0,0 +1,62 @@
+import { http } from '@hubspot/local-dev-lib/http';
+import z from 'zod';
+import { Tool } from '../../types.js';
+import { formatTextContents } from '../../utils/content.js';
+import { trackToolUsage } from '../../utils/toolUsageTracking.js';
+import { docsSearchQuery } from './constants.js';
+import { getAccountId, getConfigPath, loadConfig, } from '@hubspot/local-dev-lib/config';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+const inputSchema = {
+    docsSearchQuery,
+};
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const inputSchemaZodObject = z.object({
+    ...inputSchema,
+});
+const toolName = 'search-hubspot-docs';
+export class DocsSearchTool extends Tool {
+    constructor(mcpServer) {
+        super(mcpServer);
+    }
+    async handler({ docsSearchQuery, }) {
+        await trackToolUsage(toolName, { mode: docsSearchQuery });
+        loadConfig(getConfigPath());
+        const accountId = getAccountId();
+        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>\``;
+            return formatTextContents(authErrorMessage);
+        }
+        try {
+            const response = await http.post(accountId, {
+                url: 'dev/docs/llms/v1/docs-search',
+                data: {
+                    query: docsSearchQuery,
+                },
+            });
+            const results = response.data.results;
+            if (!results || results.length === 0) {
+                return formatTextContents('No documentation found for your query.');
+            }
+            const formattedResults = results
+                .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}`;
+            return formatTextContents(successMessage);
+        }
+        catch (error) {
+            if (isHubSpotHttpError(error)) {
+                // Handle different status codes
+                return formatTextContents(error.toString());
+            }
+            const errorMessage = `Error searching documentation: ${error instanceof Error ? error.message : String(error)}`;
+            return formatTextContents(errorMessage);
+        }
+    }
+    register() {
+        return this.mcpServer.registerTool(toolName, {
+            title: 'Search the HubSpot docs',
+            description: 'Search the HubSpot docs for information. This will return results that include a url to be used in fetch-hubspot-doc.',
+            inputSchema,
+        }, this.handler);
+    }
+}

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

@@ -2,7 +2,7 @@ import { Tool } from '../../types.js';
 import { z } from 'zod';
 import { formatTextContents } from '../../utils/content.js';
 import { getIntermediateRepresentationSchema, mapToInternalType, } from '@hubspot/project-parsing-lib';
-import { getAccountId } from '@hubspot/local-dev-lib/config';
+import { getAccountId, getConfigPath, loadConfig, } from '@hubspot/local-dev-lib/config';
 import { useV3Api } from '../../../lib/projects/buildAndDeploy.js';
 const inputSchema = {
     platformVersion: z
@@ -16,7 +16,7 @@ const inputSchema = {
 const inputSchemaZodObject = z.object({
     ...inputSchema,
 });
-const toolName = 'get-hubspot-project-feature-config-schema';
+const toolName = 'get-hubspot-feature-config-schema';
 export class GetConfigValuesTool extends Tool {
     constructor(mcpServer) {
         super(mcpServer);
@@ -26,6 +26,7 @@ export class GetConfigValuesTool extends Tool {
             if (!useV3Api(platformVersion)) {
                 return formatTextContents(`Can only be used on projects with a minimum platformVersion of 2025.2`);
             }
+            loadConfig(getConfigPath());
             const schema = await getIntermediateRepresentationSchema({
                 platformVersion,
                 projectSourceDir: '',

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,117 @@
+import { DocFetchTool } from '../DocFetchTool.js';
+import { http } from '@hubspot/local-dev-lib/http/unauthed';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js');
+vi.mock('@hubspot/local-dev-lib/http/unauthed');
+vi.mock('@hubspot/local-dev-lib/errors/index');
+vi.mock('../../utils/toolUsageTracking');
+const mockHttp = http;
+const mockIsHubSpotHttpError = vi.mocked(isHubSpotHttpError);
+describe('mcp-server/tools/project/DocFetchTool', () => {
+    let mockMcpServer;
+    let tool;
+    let mockRegisteredTool;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // @ts-expect-error Not mocking whole server
+        mockMcpServer = {
+            registerTool: vi.fn(),
+        };
+        mockRegisteredTool = {};
+        mockMcpServer.registerTool.mockReturnValue(mockRegisteredTool);
+        tool = new DocFetchTool(mockMcpServer);
+    });
+    describe('register', () => {
+        it('should register tool with correct parameters', () => {
+            const result = tool.register();
+            expect(mockMcpServer.registerTool).toHaveBeenCalledWith('fetch-hubspot-doc', {
+                title: 'Fetch a single HubSpot Developer Documentation file',
+                description: 'Fetch a single HubSpot Developer Documentation file by URL. Call after search-hubspot-docs.',
+                inputSchema: expect.any(Object),
+            }, tool.handler);
+            expect(result).toBe(mockRegisteredTool);
+        });
+    });
+    describe('handler', () => {
+        const mockInput = {
+            docUrl: 'https://example.com/docs/test-doc',
+        };
+        it('should successfully fetch and return markdown content', async () => {
+            const mockContent = '# Test Document\n\nThis is a test markdown document.';
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.get.mockResolvedValue({
+                data: mockContent,
+            });
+            const result = await tool.handler(mockInput);
+            expect(mockHttp.get).toHaveBeenCalledWith({
+                url: 'https://example.com/docs/test-doc.md',
+            });
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: mockContent,
+                    },
+                ],
+            });
+        });
+        it('should handle HubSpot HTTP errors', async () => {
+            const mockError = {
+                toString: () => 'HubSpotHttpError: \n- message: The request was not found.\n- status: 404\n- statusText: Not Found\n- method: get\n- code: ERR_BAD_REQUEST\n- derivedContext: {\n  "request": "https://example.com/docs/test-doc.md"\n}',
+            };
+            mockHttp.get.mockRejectedValue(mockError);
+            mockIsHubSpotHttpError.mockReturnValue(true);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'HubSpotHttpError: \n- message: The request was not found.\n- status: 404\n- statusText: Not Found\n- method: get\n- code: ERR_BAD_REQUEST\n- derivedContext: {\n  "request": "https://example.com/docs/test-doc.md"\n}',
+                    },
+                ],
+            });
+        });
+        it('should handle empty content', async () => {
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.get.mockResolvedValue({
+                data: '   ',
+            });
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Document is empty or contains no content.',
+                    },
+                ],
+            });
+        });
+        it('should handle generic errors', async () => {
+            const mockError = new Error('Network error');
+            mockHttp.get.mockRejectedValue(mockError);
+            mockIsHubSpotHttpError.mockReturnValue(false);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error fetching documentation: Network error',
+                    },
+                ],
+            });
+        });
+        it('should handle non-Error rejections', async () => {
+            mockHttp.get.mockRejectedValue('String error');
+            mockIsHubSpotHttpError.mockReturnValue(false);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error fetching documentation: String error',
+                    },
+                ],
+            });
+        });
+    });
+});

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,190 @@
+import { DocsSearchTool } from '../DocsSearchTool.js';
+import { http } from '@hubspot/local-dev-lib/http';
+import { getAccountId } from '@hubspot/local-dev-lib/config';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js');
+vi.mock('@hubspot/local-dev-lib/http');
+vi.mock('@hubspot/local-dev-lib/config');
+vi.mock('@hubspot/local-dev-lib/errors/index');
+vi.mock('../../../utils/toolUsageTracking');
+const mockHttp = http;
+const mockGetAccountId = getAccountId;
+const mockIsHubSpotHttpError = vi.mocked(isHubSpotHttpError);
+describe('mcp-server/tools/project/DocsSearchTool', () => {
+    let mockMcpServer;
+    let tool;
+    let mockRegisteredTool;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // @ts-expect-error Not mocking whole server
+        mockMcpServer = {
+            registerTool: vi.fn(),
+        };
+        mockRegisteredTool = {};
+        mockMcpServer.registerTool.mockReturnValue(mockRegisteredTool);
+        tool = new DocsSearchTool(mockMcpServer);
+    });
+    describe('register', () => {
+        it('should register tool with correct parameters', () => {
+            const result = tool.register();
+            expect(mockMcpServer.registerTool).toHaveBeenCalledWith('search-hubspot-docs', {
+                title: 'Search the HubSpot docs',
+                description: 'Search the HubSpot docs for information. This will return results that include a url to be used in fetch-hubspot-doc.',
+                inputSchema: expect.any(Object),
+            }, tool.handler);
+            expect(result).toBe(mockRegisteredTool);
+        });
+    });
+    describe('handler', () => {
+        const mockInput = {
+            docsSearchQuery: 'test query',
+        };
+        it('should return auth error message when no account ID is found', async () => {
+            mockGetAccountId.mockReturnValue(null);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No account ID found. Please run `hs account auth` to configure an account, or set a default account with `hs account use <account>`',
+                    },
+                ],
+            });
+        });
+        it('should return successful results when docs are found', async () => {
+            mockGetAccountId.mockReturnValue(12345);
+            const mockResponse = {
+                results: [
+                    {
+                        title: 'Test Doc 1',
+                        content: 'Test content 1',
+                        description: 'Test description 1',
+                        url: 'https://example.com/doc1',
+                        score: 0.9,
+                    },
+                    {
+                        title: 'Test Doc 2',
+                        content: 'Test content 2',
+                        description: 'Test description 2',
+                        url: 'https://example.com/doc2',
+                        score: 0.8,
+                    },
+                ],
+            };
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.post.mockResolvedValue({
+                data: mockResponse,
+            });
+            const result = await tool.handler(mockInput);
+            expect(mockHttp.post).toHaveBeenCalledWith(12345, {
+                url: 'dev/docs/llms/v1/docs-search',
+                data: {
+                    query: 'test query',
+                },
+            });
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: expect.stringContaining('Found 2 documentation results:'),
+                    },
+                ],
+            });
+            const resultText = result.content[0].text;
+            expect(resultText).toContain('**Test Doc 1**');
+            expect(resultText).toContain('Test description 1');
+            expect(resultText).toContain('https://example.com/doc1');
+            expect(resultText).toContain('Score: 0.9');
+            expect(resultText).toContain('Test content 1');
+            expect(resultText).toContain('**Test Doc 2**');
+            expect(resultText).toContain('Test description 2');
+            expect(resultText).toContain('https://example.com/doc2');
+            expect(resultText).toContain('Score: 0.8');
+            expect(resultText).toContain('Test content 2');
+        });
+        it('should return no results message when no documentation is found', async () => {
+            mockGetAccountId.mockReturnValue(12345);
+            const mockResponse = {
+                results: [],
+            };
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.post.mockResolvedValue({
+                data: mockResponse,
+            });
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No documentation found for your query.',
+                    },
+                ],
+            });
+        });
+        it('should return no results message when results is null', async () => {
+            mockGetAccountId.mockReturnValue(12345);
+            const mockResponse = {
+                results: null,
+            };
+            // @ts-expect-error - Mocking axios response structure
+            mockHttp.post.mockResolvedValue({
+                data: mockResponse,
+            });
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No documentation found for your query.',
+                    },
+                ],
+            });
+        });
+        it('should handle HubSpot HTTP errors', async () => {
+            mockGetAccountId.mockReturnValue(12345);
+            const mockError = {
+                toString: () => 'HubSpot API Error: 404 Not Found',
+            };
+            mockHttp.post.mockRejectedValue(mockError);
+            mockIsHubSpotHttpError.mockReturnValue(true);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'HubSpot API Error: 404 Not Found',
+                    },
+                ],
+            });
+        });
+        it('should handle generic errors', async () => {
+            mockGetAccountId.mockReturnValue(12345);
+            const mockError = new Error('Network error');
+            mockHttp.post.mockRejectedValue(mockError);
+            mockIsHubSpotHttpError.mockReturnValue(false);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error searching documentation: Network error',
+                    },
+                ],
+            });
+        });
+        it('should handle non-Error rejections', async () => {
+            mockGetAccountId.mockReturnValue(12345);
+            mockHttp.post.mockRejectedValue('String error');
+            mockIsHubSpotHttpError.mockReturnValue(false);
+            const result = await tool.handler(mockInput);
+            expect(result).toEqual({
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error searching documentation: String error',
+                    },
+                ],
+            });
+        });
+    });
+});

package/mcp-server/tools/project/__tests__/GetConfigValuesTool.test.js

@@ -25,7 +25,7 @@ describe('mcp-server/tools/project/GetConfigValuesTool', () => {
     describe('register', () => {
         it('should register tool with correct parameters', () => {
             const result = tool.register();
-            expect(mockMcpServer.registerTool).toHaveBeenCalledWith('get-hubspot-project-feature-config-schema', {
+            expect(mockMcpServer.registerTool).toHaveBeenCalledWith('get-hubspot-feature-config-schema', {
                 title: 'Fetch the JSON Schema for component',
                 description: expect.stringContaining('Fetches and returns the JSON schema for the provided feature'),
                 inputSchema: expect.objectContaining({

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

@@ -2,3 +2,5 @@ import z from 'zod';
 export declare const absoluteProjectPath: z.ZodString;
 export declare const absoluteCurrentWorkingDirectory: z.ZodString;
 export declare const features: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodLiteral<"card">, z.ZodLiteral<"settings">, z.ZodLiteral<"app-function">, z.ZodLiteral<"webhooks">, z.ZodLiteral<"workflow-action">]>, "many">>;
+export declare const docsSearchQuery: z.ZodString;
+export declare const docUrl: z.ZodString;

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

@@ -16,3 +16,9 @@ export const features = z
 ])
     .describe('The features to include in the project, multiple options can be selected'))
     .optional();
+export const docsSearchQuery = z
+    .string()
+    .describe('The query to search the HubSpot Developer Documentation for.');
+export const docUrl = z
+    .string()
+    .describe('The URL of the HubSpot Developer Documentation to fetch.');

package/mcp-server/utils/toolUsageTracking.d.ts

@@ -1 +1,3 @@
-export declare function trackToolUsage(toolName: string): Promise<void>;
+export declare function trackToolUsage(toolName: string, meta?: {
+    [key: string]: string;
+}): Promise<void>;

package/mcp-server/utils/toolUsageTracking.js

@@ -2,7 +2,7 @@ import { trackUsage } from '@hubspot/local-dev-lib/trackUsage';
 import { logger } from '@hubspot/local-dev-lib/logger';
 import { EventClass, getNodeVersionData, getPlatform, } from '../../lib/usageTracking.js';
 import { getAccountId, isTrackingAllowed } from '@hubspot/local-dev-lib/config';
-export async function trackToolUsage(toolName) {
+export async function trackToolUsage(toolName, meta) {
     if (!isTrackingAllowed()) {
         return;
     }
@@ -12,6 +12,7 @@ export async function trackToolUsage(toolName) {
         ...getNodeVersionData(),
         command: toolName,
         type: process.env.HUBSPOT_MCP_AI_AGENT,
+        ...meta,
     };
     const accountId = getAccountId() || undefined;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/cli",
-    "version": "7.6.0-beta.7",
+    "version": "7.6.0-beta.8",
     "description": "The official CLI for developing on HubSpot",
     "license": "Apache-2.0",
     "repository": "https://github.com/HubSpot/hubspot-cli",