@hubspot/cli 7.7.0-experimental.2 → 7.7.1-experimental.0

package/commands/setupMcp.js

@@ -1,229 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const exitCodes_1 = require("../lib/enums/exitCodes");
-const en_1 = require("../lang/en");
-const yargsUtils_1 = require("../lib/yargsUtils");
-const logger_1 = require("@hubspot/local-dev-lib/logger");
-const promptUtils_1 = require("../lib/prompts/promptUtils");
-const fs_extra_1 = __importDefault(require("fs-extra"));
-const path_1 = __importDefault(require("path"));
-const os_1 = __importDefault(require("os"));
-const command = 'setup-mcp';
-const describe = en_1.commands.setupMcp.describe;
-function getCursorMcpConfigPath(global = true) {
-    if (global) {
-        // Global configuration: ~/.cursor/mcp.json
-        const homeDir = os_1.default.homedir();
-        return path_1.default.join(homeDir, '.cursor', 'mcp.json');
-    }
-    else {
-        // Project-specific configuration: .cursor/mcp.json in current directory
-        return path_1.default.join(process.cwd(), '.cursor', 'mcp.json');
-    }
-}
-const MCP_SERVER_COMMAND = 'hsmcp';
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function readCursorConfig(global = true) {
-    const configPath = getCursorMcpConfigPath(global);
-    try {
-        if (await fs_extra_1.default.pathExists(configPath)) {
-            const content = await fs_extra_1.default.readFile(configPath, 'utf8');
-            return JSON.parse(content);
-        }
-    }
-    catch (error) {
-        logger_1.logger.debug(`Error reading Cursor config: ${error}`);
-    }
-    return { mcpServers: {} };
-}
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function writeCursorConfig(config, global = true) {
-    const configPath = getCursorMcpConfigPath(global);
-    const configDir = path_1.default.dirname(configPath);
-    // Ensure the directory exists
-    await fs_extra_1.default.ensureDir(configDir);
-    // Write the config with proper formatting
-    await fs_extra_1.default.writeFile(configPath, JSON.stringify(config, null, 2));
-}
-async function setupMcpServer(global = true) {
-    try {
-        const config = await readCursorConfig(global);
-        // Check if hsmcp command is available
-        try {
-            require('child_process').execSync(`which ${MCP_SERVER_COMMAND} 2>/dev/null`, {
-                encoding: 'utf8',
-            });
-        }
-        catch (error) {
-            logger_1.logger.error(en_1.commands.setupMcp.errors.serverNotFound);
-            logger_1.logger.error(en_1.commands.setupMcp.errors.installHint);
-            return false;
-        }
-        // Check if already configured
-        if (config.mcpServers && config.mcpServers['hubspot-cli-mcp']) {
-            logger_1.logger.info(en_1.commands.setupMcp.warnings.alreadyConfigured);
-            const { shouldOverwrite } = await (0, promptUtils_1.promptUser)([
-                {
-                    type: 'confirm',
-                    name: 'shouldOverwrite',
-                    message: en_1.commands.setupMcp.prompts.overwrite,
-                    default: false,
-                },
-            ]);
-            if (!shouldOverwrite) {
-                return true;
-            }
-        }
-        // Configure the MCP server with the simple global command
-        if (!config.mcpServers) {
-            config.mcpServers = {};
-        }
-        config.mcpServers['hubspot-cli-mcp'] = {
-            command: MCP_SERVER_COMMAND,
-            args: [],
-        };
-        await writeCursorConfig(config, global);
-        const configType = global ? 'global' : 'project-specific';
-        logger_1.logger.success(en_1.commands.setupMcp.success.configured.replace('Claude', `Cursor (${configType})`));
-        logger_1.logger.info(en_1.commands.setupMcp.success.restartCursor);
-        return true;
-    }
-    catch (error) {
-        logger_1.logger.error(`${en_1.commands.setupMcp.errors.configurationFailed}: ${error}`);
-        return false;
-    }
-}
-function displayInstructions(global = true) {
-    const configPath = getCursorMcpConfigPath(global);
-    const configType = global ? 'global' : 'project-specific';
-    logger_1.logger.log(en_1.commands.setupMcp.instructions.title.replace('Claude', `Cursor (${configType})`));
-    logger_1.logger.log('');
-    logger_1.logger.log(en_1.commands.setupMcp.instructions.step1);
-    logger_1.logger.log(`  ${configPath}`);
-    logger_1.logger.log('');
-    logger_1.logger.log(en_1.commands.setupMcp.instructions.step2);
-    logger_1.logger.log('  {');
-    logger_1.logger.log('    "mcpServers": {');
-    logger_1.logger.log('      "hubspot-cli-mcp": {');
-    logger_1.logger.log(`        "command": "${MCP_SERVER_COMMAND}",`);
-    logger_1.logger.log('        "args": []');
-    logger_1.logger.log('      }');
-    logger_1.logger.log('    }');
-    logger_1.logger.log('  }');
-    logger_1.logger.log('');
-    logger_1.logger.log(en_1.commands.setupMcp.instructions.step3.replace('Claude', 'Cursor'));
-    logger_1.logger.log('');
-    logger_1.logger.log(en_1.commands.setupMcp.instructions.documentation);
-}
-async function handler(args) {
-    const useGlobal = args.global !== false; // Default to global unless explicitly set to false
-    if (args.showInstructions) {
-        displayInstructions(useGlobal);
-        process.exit(exitCodes_1.EXIT_CODES.SUCCESS);
-        return;
-    }
-    if (args.autoSetup) {
-        const success = await setupMcpServer(useGlobal);
-        process.exit(success ? exitCodes_1.EXIT_CODES.SUCCESS : exitCodes_1.EXIT_CODES.ERROR);
-        return;
-    }
-    // Interactive mode - determine scope first if not specified
-    let isGlobal = useGlobal;
-    if (args.global === undefined) {
-        const { scope } = await (0, promptUtils_1.promptUser)([
-            {
-                type: 'list',
-                name: 'scope',
-                message: en_1.commands.setupMcp.prompts.selectScope,
-                choices: [
-                    {
-                        name: en_1.commands.setupMcp.choices.global,
-                        value: 'global',
-                    },
-                    {
-                        name: en_1.commands.setupMcp.choices.project,
-                        value: 'project',
-                    },
-                ],
-            },
-        ]);
-        isGlobal = scope === 'global';
-    }
-    // Then ask what action to take
-    const { action } = await (0, promptUtils_1.promptUser)([
-        {
-            type: 'list',
-            name: 'action',
-            message: en_1.commands.setupMcp.prompts.selectAction,
-            choices: [
-                {
-                    name: en_1.commands.setupMcp.choices.autoSetup,
-                    value: 'auto',
-                },
-                {
-                    name: en_1.commands.setupMcp.choices.showInstructions,
-                    value: 'instructions',
-                },
-            ],
-        },
-    ]);
-    if (action === 'auto') {
-        const success = await setupMcpServer(isGlobal);
-        process.exit(success ? exitCodes_1.EXIT_CODES.SUCCESS : exitCodes_1.EXIT_CODES.ERROR);
-    }
-    else {
-        displayInstructions(isGlobal);
-        process.exit(exitCodes_1.EXIT_CODES.SUCCESS);
-    }
-}
-function setupMcpBuilder(yargs) {
-    yargs
-        .options({
-        'auto-setup': {
-            describe: en_1.commands.setupMcp.options.autoSetup.describe,
-            type: 'boolean',
-            default: false,
-        },
-        'show-instructions': {
-            describe: en_1.commands.setupMcp.options.showInstructions.describe,
-            type: 'boolean',
-            default: false,
-        },
-        global: {
-            describe: en_1.commands.setupMcp.options.global.describe,
-            type: 'boolean',
-        },
-    })
-        .example([
-        ['$0 setup-mcp', en_1.commands.setupMcp.examples.default],
-        ['$0 setup-mcp --auto-setup', en_1.commands.setupMcp.examples.autoSetup],
-        [
-            '$0 setup-mcp --auto-setup --global',
-            en_1.commands.setupMcp.examples.autoSetupGlobal,
-        ],
-        [
-            '$0 setup-mcp --auto-setup --no-global',
-            en_1.commands.setupMcp.examples.autoSetupProject,
-        ],
-        [
-            '$0 setup-mcp --show-instructions',
-            en_1.commands.setupMcp.examples.showInstructions,
-        ],
-    ]);
-    return yargs;
-}
-const builder = (0, yargsUtils_1.makeYargsBuilder)(setupMcpBuilder, command, describe, {
-    useGlobalOptions: true,
-});
-const setupMcpCommand = {
-    command,
-    describe,
-    handler,
-    builder,
-};
-exports.default = setupMcpCommand;
-// Legacy export for compatibility
-module.exports = setupMcpCommand;

package/mcp-server/index.d.ts

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

package/mcp-server/index.js

@@ -1,17 +0,0 @@
-import { MCPServer } from 'mcp-framework';
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-// Calculate the correct base path for tools
-// ToolLoader does: dirname(basePath) + "/tools"
-// We want it to look in dist/mcp-server/tools
-// So basePath should be dist/mcp-server/anything
-// __filename is dist/mcp-server/index.js, so dirname is dist/mcp-server
-// We need to provide a path like dist/mcp-server/main.js
-const basePath = join(__dirname, 'main.js');
-console.log('Debug: basePath:', basePath);
-const server = new MCPServer({
-    basePath: basePath,
-});
-server.start();

package/mcp-server/mcpLoader.d.ts

@@ -1,5 +0,0 @@
-export declare function getMCPServer(): Promise<any>;
-export declare function getMCPTool(): Promise<any>;
-export declare class MCPToolBase {
-    static create(): Promise<any>;
-}

package/mcp-server/mcpLoader.js

@@ -1,24 +0,0 @@
-// Dynamic import loader for mcp-framework to handle ESM/CommonJS compatibility
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let mcpFramework = null;
-async function loadMCPFramework() {
-    if (!mcpFramework) {
-        mcpFramework = await import('mcp-framework');
-    }
-    return mcpFramework;
-}
-export async function getMCPServer() {
-    const framework = await loadMCPFramework();
-    return framework.MCPServer;
-}
-export async function getMCPTool() {
-    const framework = await loadMCPFramework();
-    return framework.MCPTool;
-}
-// Export a ready-to-use MCPTool base class
-export class MCPToolBase {
-    static async create() {
-        const MCPTool = await getMCPTool();
-        return MCPTool;
-    }
-}

package/mcp-server/tools/ExplainProjectStructureTool.d.ts

@@ -1,33 +0,0 @@
-import { MCPTool } from "mcp-framework";
-import { z } from "zod";
-interface ExplainProjectStructureInput {
-    section?: string;
-}
-declare class ExplainProjectStructureTool extends MCPTool<ExplainProjectStructureInput> {
-    name: string;
-    description: string;
-    schema: {
-        section: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-    };
-    execute(input: ExplainProjectStructureInput): Promise<{
-        section: string;
-        title: string;
-        content: string;
-        message?: undefined;
-        sections?: undefined;
-    } | {
-        message: string;
-        sections: {
-            section: string;
-            title: string;
-            content: string;
-        }[];
-        section?: undefined;
-        title?: undefined;
-        content?: undefined;
-    }>;
-}
-export default ExplainProjectStructureTool;

package/mcp-server/tools/ExplainProjectStructureTool.js

@@ -1,266 +0,0 @@
-import { MCPTool } from "mcp-framework";
-import { z } from "zod";
-class ExplainProjectStructureTool extends MCPTool {
-    name = "explainProjectStructure";
-    description = "Explains the developer projects platform structure, conventions, and best practices";
-    schema = {
-        section: {
-            type: z.string().optional(),
-            description: "Specific section to explain (overview, projectFiles, components, hierarchy, fileNaming, bestPractices, envelope). If not provided, returns complete explanation",
-        },
-    };
-    async execute(input) {
-        const { section } = input;
-        const explanation = {
-            overview: {
-                title: "Developer Projects Platform Overview",
-                content: `
-The developer projects platform allows users to build applications using a hierarchical component-based architecture with consistency and predictability as core principles.
-
-Key Concepts:
-- Projects are defined by hsproject.json files in the root directory
-- Components follow a hierarchical structure with top-level and sub-components
-- Apps are the primary top-level components that provide authentication
-- Sub-components (features) live within apps and depend on app authentication
-- All components live in the src directory with dedicated folders
-- Component instances are declared via *-hsmeta.json files
-- 1:1 relationship between components and their configuration files
-- Envelope layer (uid, type) provides meta information about components
-        `,
-            },
-            projectFiles: {
-                title: "Project Configuration Files",
-                content: `
-hsproject.json (Project Root):
-- Designates a folder as a developer project
-- Contains project metadata including name, source directory, and platform version
-- Required fields:
-  * name: Project name (e.g., "North Star Project")
-  * srcDir: Source code directory (typically "src")
-  * platformVersion: Platform version (e.g., "2025.1", defaults to "2025.2")
-
-Example:
-{
-  "name": "North Star Project",
-  "srcDir": "src",
-  "platformVersion": "2025.1"
-}
-        `,
-            },
-            components: {
-                title: "Component Architecture",
-                content: `
-Components follow a structured, predictable architecture with two main categories:
-
-**Top-Level Components:**
-- Stand-alone components that provide core functionality
-- Currently: Apps (and Themes)
-- Located directly in src/[component-type]/
-- Provide authentication and foundational services
-
-**Sub-Components (Features):**
-- Live within top-level components (primarily apps)
-- Depend on parent component's authentication
-- Located in src/app/[feature-type]/
-- Include: cards, functions, settings, webhooks, marketing-events, timeline-events, etc.
-
-Standard Component Structure (Envelope Layer):
-{
-  "uid": "unique-component-id",      // Unique identifier
-  "type": "component-type",          // Component type
-  "config": {                        // Component-specific configuration
-    // Configuration details here
-  }
-}
-
-Component Characteristics:
-- Each component has a dedicated folder and *-hsmeta.json file (1:1 relationship)
-- Some components are singular (only one per app): settings, webhooks, calling
-- Others can have multiple instances: cards, functions, marketing-events
-- All follow the envelope layer structure for consistency
-        `,
-            },
-            hierarchy: {
-                title: "Component Hierarchy & Authentication",
-                content: `
-The platform uses a hierarchical architecture where authentication flows from top-level components to sub-components.
-
-**Top-Level Components:**
-- App: Primary component providing OAuth authentication
-- Theme: Styling and branding (top-level but may depend on app context)
-
-**Sub-Components within Apps:**
-Sub-components rely on their parent app's authentication and include:
-
-- App Objects: Custom CRM objects
-- App Object Associations: Relationships between objects  
-- Cards: UI cards displayed in HubSpot
-- Functions: Serverless functions
-- Settings: Configuration interfaces
-- Marketing Events: Custom marketing event types
-- Timeline Events: Custom timeline activities
-- Webhooks: Event notification endpoints
-- Workflow Actions: Custom workflow steps
-- Calling: Phone/communication features
-- Video Conferencing: Meeting integrations
-- Media Bridge: Media handling capabilities
-
-**Authentication Flow:**
-1. App component defines OAuth scopes and authentication
-2. Sub-components inherit and utilize app authentication
-3. Sub-components cannot exist without a parent app
-4. All API calls from sub-components use app credentials
-        `,
-            },
-            fileNaming: {
-                title: "File Naming Conventions & Structure",
-                content: `
-Component Configuration Files (*-hsmeta.json):
-- Must end with "-hsmeta.json"
-- Prefix can be anything meaningful to the user
-- Recommended: use component name as prefix for clarity
-- Examples: "my-app-hsmeta.json", "contact-card-hsmeta.json"
-- Maintain 1:1 relationship between components and configuration files
-
-Complete Directory Structure:
-my-project/
-├── hsproject.json              # Project configuration
-└── src/                        # Source code directory
-    ├── app/                    # App component directory (top-level)
-    │   ├── my-app-hsmeta.json  # App component configuration
-    │   ├── cards/              # Cards sub-components
-    │   │   ├── contact-card-hsmeta.json
-    │   │   └── deal-card-hsmeta.json
-    │   ├── functions/          # Function sub-components
-    │   │   ├── data-sync-hsmeta.json
-    │   │   └── email-validator-hsmeta.json
-    │   ├── settings/           # Settings sub-component (singular)
-    │   │   └── app-settings-hsmeta.json
-    │   ├── webhooks/           # Webhooks sub-component (singular)
-    │   │   └── event-handler-hsmeta.json
-    │   └── [other-features]/   # Other sub-component directories
-    └── theme/                  # Theme component (if applicable)
-        └── brand-theme-hsmeta.json
-
-UIDs (Unique Identifiers):
-- Must be unique within each project
-- Use descriptive, kebab-case naming
-- Examples: "my-unified-app", "contact-summary-card", "lead-scoring-function"
-- Should clearly identify the component's purpose and type
-        `,
-            },
-            envelope: {
-                title: "Envelope Layer Architecture",
-                content: `
-The envelope layer provides a consistent structure for all components, enabling the system to derive meta information automatically.
-
-Envelope Structure:
-{
-  "uid": "component-identifier",     // Unique ID for component identification
-  "type": "component-type",          // Type determines component behavior
-  "config": {                       // Component-specific configuration
-    // All component-specific settings go here
-  }
-}
-
-Benefits of Envelope Layer:
-- Consistent metadata extraction across all component types
-- Predictable structure for tooling and validation
-- Clear separation between component identity (uid, type) and configuration
-- Enables automatic component discovery and management
-- Supports hierarchical relationships between components
-
-Example App Component (Top-Level):
-{
-  "uid": "my-unified-app",
-  "type": "app",
-  "config": {
-    "description": "An example to demonstrate how to build a public app with developer projects.",
-    "name": "My unified app",
-    "logo": "./app-logo.png",
-    "distribution": "A public app",
-    "auth": {
-      "type": "oauth",
-      "redirectUrls": ["http://localhost:3000/oauth-callback"],
-      "requiredScopes": ["crm.objects.contacts.read"]
-    }
-  }
-}
-
-Example Sub-Component (Card):
-{
-  "uid": "contact-summary-card",
-  "type": "cards",
-  "config": {
-    "title": "Contact Summary",
-    "description": "Displays key contact information",
-    "displayOptions": {
-      "width": "medium",
-      "height": "auto"
-    }
-  }
-}
-        `,
-            },
-            bestPractices: {
-                title: "Best Practices & Guidelines",
-                content: `
-1. Hierarchy and Authentication:
-   - Always create an app component first (provides authentication)
-   - Sub-components must live within the app directory structure
-   - Ensure app has sufficient OAuth scopes for all sub-components
-   - Consider authentication requirements when planning components
-
-2. Consistency and Predictability:
-   - Follow established folder structures exactly
-   - Maintain 1:1 relationship between components and configuration files
-   - Use consistent naming conventions across all components
-   - Ensure each component has a dedicated folder
-
-3. Project Organization:
-   - Keep hsproject.json in project root
-   - Organize sub-components in their dedicated directories within src/app/
-   - Group related functionality (e.g., all cards in cards/ directory)
-   - Follow the hierarchical structure religiously
-
-4. Component Configuration:
-   - Keep configurations clear and concise
-   - Focus on the rules established by the schema
-   - Use the envelope layer (uid, type, config) consistently
-   - Ensure UIDs are unique and descriptive across all component types
-
-5. File Management:
-   - Use meaningful -hsmeta.json file names that reflect component purpose
-   - Place sub-component files in appropriate feature directories
-   - Include necessary assets (like logos) in component directories
-   - Follow kebab-case for consistency
-
-6. Component Development:
-   - Start with app component to establish authentication foundation
-   - Plan OAuth scopes to cover all intended sub-components
-   - Consider component relationships and dependencies
-   - Validate component configurations against the schema
-   - Remember some components are singular (settings, webhooks) vs. multiple instances (cards, functions)
-        `,
-            },
-        };
-        if (section && explanation[section]) {
-            const selectedSection = explanation[section];
-            return {
-                section: section,
-                title: selectedSection.title,
-                content: selectedSection.content.trim(),
-            };
-        }
-        // Return complete explanation
-        return {
-            message: "Complete Developer Projects Platform Structure Guide",
-            sections: Object.entries(explanation).map(([key, value]) => ({
-                section: key,
-                title: value.title,
-                content: value.content.trim(),
-            })),
-        };
-    }
-}
-export default ExplainProjectStructureTool;

package/mcp-server/tools/GenerateAppComponentTool.d.ts

@@ -1,99 +0,0 @@
-import { MCPTool } from 'mcp-framework';
-import { z } from 'zod';
-interface GenerateAppComponentInput {
-    appName: string;
-    uid: string;
-    description?: string;
-    displayName?: string;
-    distribution?: string;
-    supportEmail?: string;
-    documentationUrl?: string;
-    supportUrl?: string;
-    supportPhone?: string;
-    redirectUrls?: string[];
-    requiredScopes?: string[];
-    optionalScopes?: string[];
-    permittedFetchUrls?: string[];
-    plannedFeatures?: string[];
-}
-declare class GenerateAppComponentTool extends MCPTool<GenerateAppComponentInput> {
-    name: string;
-    description: string;
-    schema: {
-        appName: {
-            type: z.ZodString;
-            description: string;
-        };
-        uid: {
-            type: z.ZodString;
-            description: string;
-        };
-        description: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        displayName: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        distribution: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        supportEmail: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        documentationUrl: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        supportUrl: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        supportPhone: {
-            type: z.ZodOptional<z.ZodString>;
-            description: string;
-        };
-        redirectUrls: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        requiredScopes: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        optionalScopes: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        permittedFetchUrls: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-        plannedFeatures: {
-            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            description: string;
-        };
-    };
-    execute(input: GenerateAppComponentInput): Promise<{
-        message: string;
-        config: string;
-        folderPath: string;
-        fileName: string;
-        fullPath: string;
-        architecture: {
-            componentType: string;
-            role: string;
-            singularComponent: boolean;
-            dependents: string;
-        };
-        scopeRecommendations: string[];
-        nextSteps: string[];
-        instructions: string[];
-    }>;
-    private generateScopeRecommendations;
-    private generateNextSteps;
-}
-export default GenerateAppComponentTool;