@hubspot/cli 7.6.0-experimental.0 → 7.7.0-experimental.1

package/mcp-server/tools/ExplainProjectStructureTool.js

@@ -0,0 +1,266 @@
+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

@@ -0,0 +1,99 @@
+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;

package/mcp-server/tools/GenerateAppComponentTool.js

@@ -0,0 +1,193 @@
+import { MCPTool } from 'mcp-framework';
+import { z } from 'zod';
+class GenerateAppComponentTool extends MCPTool {
+    name = 'generateAppComponent';
+    description = 'Generates an app component (top-level) with proper folder structure and hsmeta.json configuration file. Apps provide OAuth authentication that sub-components depend on.';
+    schema = {
+        appName: {
+            type: z.string(),
+            description: 'Name of the app (used for file naming and default display name)',
+        },
+        uid: {
+            type: z.string(),
+            description: 'Unique identifier for the app component (must be unique per-project)',
+        },
+        description: {
+            type: z.string().optional(),
+            description: "Description of the app. Defaults to 'A public app'",
+        },
+        displayName: {
+            type: z.string().optional(),
+            description: 'Display name of the app. Defaults to the appName',
+        },
+        distribution: {
+            type: z.string().optional(),
+            description: "Distribution type (one of 'marketplace' or 'private'). Defaults to 'marketplace'",
+        },
+        supportEmail: {
+            type: z.string().optional(),
+            description: "Support email address. Defaults to 'support@example.com'",
+        },
+        documentationUrl: {
+            type: z.string().optional(),
+            description: "Documentation URL. Defaults to 'https://example.com/docs'",
+        },
+        supportUrl: {
+            type: z.string().optional(),
+            description: "Support URL. Defaults to 'https://example.com/support'",
+        },
+        supportPhone: {
+            type: z.string().optional(),
+            description: "Support phone number. Defaults to '+18005555555'",
+        },
+        redirectUrls: {
+            type: z.array(z.string()).optional(),
+            description: "OAuth redirect URLs. Defaults to ['http://localhost:3000/oauth-callback']",
+        },
+        requiredScopes: {
+            type: z.array(z.string()).optional(),
+            description: 'Required OAuth scopes. Consider what sub-components you plan to add. Defaults to basic CRM contact scopes',
+        },
+        optionalScopes: {
+            type: z.array(z.string()).optional(),
+            description: 'Optional OAuth scopes. Defaults to empty array',
+        },
+        permittedFetchUrls: {
+            type: z.array(z.string()).optional(),
+            description: "URLs permitted for fetch requests. Defaults to ['https://api.example.com']",
+        },
+        plannedFeatures: {
+            type: z.array(z.string()).optional(),
+            description: "List of planned sub-components/features (e.g., 'cards', 'functions', 'webhooks'). Used to suggest appropriate OAuth scopes",
+        },
+    };
+    async execute(input) {
+        const { appName, uid, description = 'A public app', displayName = appName, distribution = 'marketplace', supportEmail = 'support@example.com', documentationUrl = 'https://example.com/docs', supportUrl = 'https://example.com/support', supportPhone = '+18005555555', redirectUrls = ['http://localhost:3000/oauth-callback'], requiredScopes = [
+            'crm.objects.contacts.read',
+            'crm.objects.contacts.write',
+        ], optionalScopes = [], permittedFetchUrls = ['https://api.example.com'], plannedFeatures = [], } = input;
+        // Generate the sanitized app name for file naming
+        const sanitizedAppName = appName.toLowerCase().replace(/\s+/g, '-');
+        const fileName = `${sanitizedAppName}-hsmeta.json`;
+        const folderPath = 'src/app';
+        const appConfig = {
+            uid: uid,
+            type: 'app',
+            config: {
+                description: description,
+                name: displayName,
+                distribution: distribution,
+                auth: {
+                    type: 'oauth',
+                    redirectUrls: redirectUrls,
+                    requiredScopes: requiredScopes,
+                    optionalScopes: optionalScopes,
+                    conditionallyRequiredScopes: [],
+                },
+                permittedUrls: {
+                    fetch: permittedFetchUrls,
+                    iframe: [],
+                    img: [],
+                },
+                support: {
+                    supportEmail: supportEmail,
+                    documentationUrl: documentationUrl,
+                    supportUrl: supportUrl,
+                    supportPhone: supportPhone,
+                },
+            },
+        };
+        // Generate scope recommendations based on planned features
+        const scopeRecommendations = this.generateScopeRecommendations(plannedFeatures);
+        // Generate next steps guidance
+        const nextSteps = this.generateNextSteps(plannedFeatures, folderPath);
+        return {
+            message: `Generated app component configuration for "${displayName}"`,
+            config: JSON.stringify(appConfig, null, 2),
+            folderPath: folderPath,
+            fileName: fileName,
+            fullPath: `${folderPath}/${fileName}`,
+            architecture: {
+                componentType: 'top-level',
+                role: 'authentication-provider',
+                singularComponent: true,
+                dependents: "All sub-components (cards, functions, settings, etc.) will depend on this app's authentication",
+            },
+            scopeRecommendations: scopeRecommendations,
+            nextSteps: nextSteps,
+            instructions: [
+                `Create the directory structure: ${folderPath}/`,
+                `Place the configuration file at: ${folderPath}/${fileName}`,
+                `This is a TOP-LEVEL component that provides OAuth authentication`,
+                `Sub-components (features) will live within ${folderPath}/ and depend on this app's authentication`,
+                `The app component uid: ${uid} must be unique within your project`,
+                'Consider what sub-components you plan to add and ensure sufficient OAuth scopes',
+                'Typically there is one app component per project (singular component)',
+            ],
+        };
+    }
+    generateScopeRecommendations(plannedFeatures) {
+        const recommendations = [];
+        if (plannedFeatures.length === 0) {
+            return [
+                'Consider what sub-components you plan to add to determine required OAuth scopes',
+                'Cards typically need CRM object read access',
+                'Functions may need broader API access depending on functionality',
+                'Webhooks may need specific event subscription scopes',
+            ];
+        }
+        const scopeMap = {
+            cards: [
+                'Cards typically need: crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read',
+            ],
+            functions: [
+                'Functions may need: broader API access depending on functionality',
+                'Consider: crm.objects.*.read, crm.objects.*.write if manipulating CRM data',
+            ],
+            webhooks: [
+                'Webhooks may need: specific event subscription scopes',
+                'Consider: webhooks scope and relevant object scopes for events you want to receive',
+            ],
+            settings: [
+                'Settings typically need: minimal scopes, may inherit from other components',
+            ],
+            'marketing-events': [
+                'Marketing events may need: marketing event creation and management scopes',
+            ],
+            'timeline-events': [
+                'Timeline events may need: timeline read/write scopes for the relevant objects',
+            ],
+            'workflow-actions': [
+                'Workflow actions may need: workflow and automation related scopes',
+            ],
+        };
+        plannedFeatures.forEach(feature => {
+            if (scopeMap[feature]) {
+                recommendations.push(`For ${feature}: ${scopeMap[feature].join(', ')}`);
+            }
+        });
+        return recommendations;
+    }
+    generateNextSteps(plannedFeatures, appPath) {
+        const steps = [
+            '1. Create the app component configuration file and directory structure',
+            '2. Test OAuth flow and ensure authentication works correctly',
+            '3. Add sub-components within the app directory as needed:',
+        ];
+        if (plannedFeatures.length > 0) {
+            plannedFeatures.forEach(feature => {
+                steps.push(`   - ${appPath}/${feature}/`);
+            });
+        }
+        else {
+            steps.push(`   - ${appPath}/cards/ (for UI cards)`);
+            steps.push(`   - ${appPath}/functions/ (for serverless functions)`);
+            steps.push(`   - ${appPath}/settings/ (for configuration UI)`);
+            steps.push(`   - ${appPath}/webhooks/ (for event handling)`);
+        }
+        steps.push("4. Ensure all sub-components can access required APIs with the app's OAuth scopes");
+        steps.push('5. Test the complete application with all components integrated');
+        return steps;
+    }
+}
+export default GenerateAppComponentTool;

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

@@ -0,0 +1,74 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+interface GenerateCardComponentInput {
+    cardName: string;
+    uid: string;
+    displayName?: string;
+    location?: string;
+    objectTypes?: string[];
+    componentFileName?: string;
+}
+declare class GenerateCardComponentTool extends MCPTool<GenerateCardComponentInput> {
+    name: string;
+    description: string;
+    schema: {
+        cardName: {
+            type: z.ZodString;
+            description: string;
+        };
+        uid: {
+            type: z.ZodString;
+            description: string;
+        };
+        displayName: {
+            type: z.ZodOptional<z.ZodString>;
+            description: string;
+        };
+        location: {
+            type: z.ZodOptional<z.ZodString>;
+            description: string;
+        };
+        objectTypes: {
+            type: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            description: string;
+        };
+        componentFileName: {
+            type: z.ZodOptional<z.ZodString>;
+            description: string;
+        };
+    };
+    execute(input: GenerateCardComponentInput): Promise<{
+        message: string;
+        files: {
+            configuration: {
+                path: string;
+                content: string;
+                description: string;
+            };
+            packageJson: {
+                path: string;
+                content: string;
+                description: string;
+            };
+            reactComponent: {
+                path: string;
+                content: string;
+                description: string;
+            };
+        };
+        folderPath: string;
+        architecture: {
+            componentType: string;
+            parentComponent: string;
+            category: string;
+            authenticationDependency: string;
+            allowMultiple: boolean;
+            technology: string;
+        };
+        instructions: string[];
+        nextSteps: string[];
+        developmentNotes: string[];
+    }>;
+    private toPascalCase;
+}
+export default GenerateCardComponentTool;