USAGE

HubSpot Integration Usage Guide

Complete guide for using HubSpot integration with Linear tickets and natural language queries in Cursor.

Quick Start

1. Set Up HubSpot MCP (Read Operations)

Follow the MCP Setup Guide to configure HubSpot MCP server for natural language queries.

2. Set Up HubSpot API Service (Write Operations)

cd api-service
npm install
cp .env.example .env
# Edit .env with your HUBSPOT_ACCESS_TOKEN

3. Start Using

You can now:

• Query HubSpot via natural language in Cursor
• Enrich Linear tickets with HubSpot context
• Update HubSpot deals from Cursor

Natural Language Queries (via MCP)

Read Operations

Query deals:

• “Show me all deals for Inteleos”
• “What deals are in the ‘Qualified To Buy’ stage?”
• “List all deals created this month”
• “What’s the status of deal SAL-649?”

Query contacts:

• “Get contact details for Juan Sanchez”
• “Find contacts at Inteleos Foundation”
• “Show me all contacts with email domain @inteleos.org”

Query companies:

• “Get company information for Inteleos Foundation”
• “List all companies in the nonprofit industry”
• “Show me companies with more than 100 employees”

Association queries:

• “Who are the contacts on the Inteleos deal?”
• “What company is associated with deal X?”
• “Show me all deals for Inteleos Foundation”

Write Operations (via API Service)

Create deals:

• “Create a deal for Inteleos Foundation with amount $15K”
• “Create a deal: Inteleos - Data Leadership, $15K/month, close date March 1”

Update deals:

• “Move Inteleos deal to ‘Qualified To Buy’ stage”
• “Update deal close date to March 1, 2026”
• “Change deal amount to $20K”

Add notes:

• “Add note to Inteleos deal: ‘SOW sent, awaiting NDA signature’”
• “Add note: ‘Meeting scheduled for Feb 5’”

Link tickets:

• “Link this Linear ticket to HubSpot deal X”
• “Link SAL-649 to the Inteleos deal”

Enriching Linear Tickets

Manual Enrichment

When working on a sales ticket in Cursor:

1. Identify the deal:

   "What HubSpot deal is associated with Inteleos?"
   

2. Enrich the ticket:

   import { fetchHubSpotContext } from './enrichment/enrich-ticket.js';
   import { formatHubSpotContext } from './enrichment/format-context.js';
    
   const context = await fetchHubSpotContext({
     companyName: 'Inteleos Foundation'
   });
    
   const markdown = formatHubSpotContext(context);
   // Add markdown to Linear ticket description or comment

3. Link the ticket:

   import { linkTicketToDeal } from './enrichment/link-ticket.js';
    
   await linkTicketToDeal(
     'deal-id-123',
     'SAL-649',
     'https://linear.app/brainforge/issue/SAL-649/...'
   );

Auto-Suggest Enrichment

When opening a sales ticket, the system can:

1. Extract ticket title: “Inteleos Foundation - Interim Data Leadership”
2. Infer matching HubSpot deal
3. Suggest: “Would you like to enrich this ticket with HubSpot context?”
4. If confirmed, fetch and add context automatically

Natural Language Commands

• “Enrich this ticket with HubSpot context”
• “Link this ticket to the Inteleos deal”
• “Show me the full HubSpot context for this lead”
• “What’s the HubSpot deal status for this ticket?”

Pipeline Selection

When creating or updating deals, the system can infer the pipeline:

Automatic Inference

The system infers pipeline from:

• Deal properties (industry, deal type)
• Ticket labels (e.g., “enterprise”, “nonprofit”)
• Ticket context (client type, engagement type)

Manual Selection

If inference is uncertain, you’ll be prompted:

"Which pipeline should this deal go in?"
- Sales Pipeline (default)
- Enterprise Pipeline
- Nonprofit Pipeline

Association Traversal

Get full context by traversing associations:

import { traverseDealAssociations } from './api-service/src/associations.js';
 
const context = await traverseDealAssociations('deal-id-123');
 
// Returns:
// - Deal information
// - Associated contacts
// - Associated company
// - Company's contacts (if any)

Natural language:

• “Show me everything about the Inteleos opportunity”
• “Get full context for deal X”
• “Who are all the people involved in this deal?”

Workflow Examples

Example 1: New Sales Ticket

1. Create Linear ticket: “Inteleos Foundation - Data Leadership”
2. In Cursor: “Enrich this ticket with HubSpot context”
3. System finds matching deal (or creates one)
4. Adds formatted context to ticket
5. Links ticket to deal

Example 2: Update Deal Stage

1. In Cursor: “Move Inteleos deal to ‘Qualified To Buy’ stage”
2. System confirms: “Update deal SAL-649 to ‘Qualified To Buy’?”
3. You confirm
4. Deal updated in HubSpot
5. Optionally update Linear ticket status

Example 3: Add Meeting Notes

1. After a meeting: “Add note to Inteleos deal: ‘Discussed Phase 1 timeline, awaiting NDA’”
2. Note added to HubSpot deal
3. Optionally add to Linear ticket as comment

Confirmation Flow

For write operations, the system shows a preview and asks for confirmation:

Proposed change:
- Deal: Inteleos Foundation - Data Leadership
- Action: Update stage to "Qualified To Buy"
- Pipeline: Sales Pipeline

Confirm? (yes/no)

Error Handling

Deal Not Found

If a deal isn’t found:

"No matching HubSpot deal found. Would you like to create one?"

Multiple Matches

If multiple deals match:

"Found 3 matching deals:
1. Inteleos Foundation - Data Leadership (SAL-649)
2. Inteleos Foundation - AI Strategy (SAL-650)
3. Inteleos Foundation - Platform (SAL-651)

Which one should I use?"

Rate Limiting

If rate limited:

"HubSpot rate limit reached. Retrying in 10 seconds..."

Best Practices

1. Link tickets early: Link Linear tickets to HubSpot deals when created
2. Use consistent naming: Match ticket titles to deal names
3. Enrich before meetings: Enrich tickets before client calls for context
4. Update both systems: Keep Linear and HubSpot in sync manually
5. Use associations: Leverage contact and company associations for full context

Troubleshooting

”No matching deal found”

• Check company name spelling
• Try searching by deal name instead
• Create deal manually if needed

”Access token expired”

• Regenerate HubSpot Private App token
• Update HUBSPOT_ACCESS_TOKEN in .env

”Rate limit exceeded”

• Wait 10 seconds and retry
• The API service has automatic retry logic

Next Steps

• Set up HubSpot MCP: See setup.md
• Configure API service: See README.md
• Learn enrichment: See README.md