[![License: Source Available](https://img.shields.io/badge/License-Source%20Available-blue.svg)](https://github.com/calypsoCodex/hubspot-mcp-extended/blob/main/LICENSE) ![Version](https://img.shields.io/badge/version-1.4.0-blue.svg) ![CI/CD](https://github.com/calypsoCodex/hubspot-mcp-extended/actions/workflows/ci.yml/badge.svg) ![CodeQL](https://github.com/calypsoCodex/hubspot-mcp-extended/actions/workflows/codeql.yml/badge.svg) ![codecov](https://codecov.io/gh/calypsoCodex/hubspot-mcp-extended/branch/main/graph/badge.svg)

> **Note**: Coverage reporting will be available after setting up Codecov token and app integration.

# HubSpot MCP Extended

Independent MCP server built directly from HubSpot's public OpenAPI specifications, providing comprehensive CRM automation with 106 tools including advanced workflows for invoices and line items.

> **Note**: This is an independent, community-driven implementation and not affiliated with or endorsed by HubSpot. Built using HubSpot's official public OpenAPI specifications.

## 📜 Licensing

This software is **source available** with dual licensing:

- **Free for non-commercial use** (personal, educational, research, open source projects)
- **Commercial license required** for business/production use by for-profit organizations

See [LICENSE](LICENSE) for full terms and [LICENSING.md](LICENSING.md) for details on obtaining a commercial license.

## 🆕 Recent Improvements (v1.4.0)

- ✅ **Dual Licensing Model**: MIT for open source + Commercial license option for enterprise support
- ✅ **Claude Desktop Parameter Compatibility**: Fixed parameter name mismatch causing "Unable to infer object type" errors
- ✅ **Line Items API Support**: Added 11 new tools for complete invoice workflow functionality (95→106 tools)
- ✅ **Smart Parameter Mapping**: Automatic normalization of shortened parameter names (objtype/objectType, objid/objectId)
- ✅ **Fixed macOS Compatibility**: Deployment script now works natively on macOS without requiring GNU coreutils
- ✅ **Docker Compose Integration**: Optimized for persistent container with `docker exec` access
- ✅ **Enhanced Deployment Verification**: Automatic validation of tool count and JSON response integrity
- ✅ **Cross-Platform Support**: Works on macOS, Linux, and Windows with consistent behavior

### 🔮 Planned Enhancements

- 🔄 **Rate Limit Handling**: Automatic throttling and exponential backoff for HubSpot API limits (planned for v1.5.0)

## 🚀 Features

- **106 HubSpot Tools** - Complete CRM functionality including contacts, companies, deals, tickets, quotes, invoices, and line items
- **Docker Support** - Containerized deployment for consistent environments
- **Security First** - Environment variable-based configuration, no hardcoded secrets, token redaction in logs
- **Production Ready** - Comprehensive error handling, secure logging, and testing
- **TypeScript** - Fully typed for reliability and developer experience

## 📋 Prerequisites

### Essential (Required)

- **Node.js** (v20 or higher)
- **npm** (for dependency management)
- **HubSpot Private App or Connected App** with appropriate scopes and access token
- **Claude Desktop** or compatible MCP client

### Optional (For Full Deployment)

- **Docker and Docker Compose** (only needed for `./deploy.sh`)
- **macOS/Linux/Windows** (deployment script optimized for macOS)

💡 **First time?** You can skip Docker and use `./deploy-local.sh` for quick testing!

## 🔄 Updating to Latest Version

### For Existing Users

If you already have HubSpot MCP Extended installed and want to update to the latest version:

#### Option 1: Git Update (Recommended)

```bash
# Navigate to your project directory
cd hubspot-mcp-extended

# Pull the latest changes
git pull origin main

# Rebuild the project
npm install
npm run build

# If using Docker, rebuild the image
docker compose down
docker compose up -d --build
```

#### Option 2: Fresh Installation

```bash
# Backup your .env file first
cp .env .env.backup

# Remove old installation
rm -rf hubspot-mcp-extended

# Fresh clone and setup
git clone https://github.com/calypsoCodex/hubspot-mcp-extended.git
cd hubspot-mcp-extended
cp .env.backup .env
./deploy-local.sh  # or ./deploy.sh for Docker
```

### Current Version: v1.4.0

**Latest improvements:**

- 106 tools (added 11 Line Items API tools)
- Enhanced parameter compatibility (objtype/objectType auto-mapping)
- Fixed macOS deployment script (no longer requires GNU coreutils)
- Improved Docker integration with persistent container

## 🚀 Quick Start

### 1. Clone Repository

```bash
git clone https://github.com/calypsoCodex/hubspot-mcp-extended.git
cd hubspot-mcp-extended
```

### 2. Configure Environment

```bash
# Copy environment template
cp .env.example .env

# Edit .env and add your HubSpot API token
# Make sure the variable name is exactly: HUBSPOT_ACCESS_TOKEN
vim .env  # or use your preferred editor
```

### 3. Deploy

#### Option A: Local Development (No Docker)

```bash
./deploy-local.sh
```

**What this does:**

- Installs dependencies
- Builds TypeScript
- Validates deployment (checks for 106 tools)
- No Docker required!

#### Option B: Docker Deployment (Production-Ready)

```bash
./deploy.sh
```

**What this does:**

- Builds Docker image
- Starts container with docker compose
- Validates deployment automatically
- Persistent container for quick `docker exec` access

### 4. Configure Claude Desktop

Update your Claude Desktop config at:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

#### For Local Deployment:

```json
{
  "mcpServers": {
    "hubspot-mcp-extended": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/hubspot-mcp-extended/build/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}
```

#### For Docker Deployment:

```json
{
  "mcpServers": {
    "hubspot-mcp-extended": {
      "command": "docker",
      "args": ["exec", "-i", "hubspot-mcp-extended", "node", "build/index.js", "--stdio"]
    }
  }
}
```

**Important:** Restart Claude Desktop after configuration changes.

### 5. Verify Installation

#### Quick Validation Commands

```bash
# 1. Verify deployment (no API key needed)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js --stdio | jq '.result.tools | length'
# Expected output: 106

# 2. Test tool execution (requires API key in .env)
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_v3_obj", "arguments": {"objectType": "contacts", "limit": "1"}}}' | node build/index.js --stdio
# Expected: Contact data or authentication error
```

### After Successful Deployment

You should see:

- ✅ 106 tools available in Claude Desktop
- ✅ Tools appear in Claude's MCP tools list
- ✅ All HubSpot operations accessible through natural language

#### Docker-Specific Verification

```bash
# Verify the container is running (should show "Up" status)
docker compose ps

# Check logs (should show "106 tools")
docker compose logs

# Test the MCP server through Docker exec
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | docker exec -i hubspot-mcp-extended node build/index.js --stdio
```

## 💡 Usage Examples

### Example 1: Search Contacts by Email

```
"Find all contacts with email domain @acme.com"
```

Claude will:

1. Use `post-crm-v3-objects-objtype-search_search` tool
2. Construct search with:
   - `objectType: "contacts"` (or `objtype: "contacts"` - both work!)
   - `filterGroups` with email filter

### Example 2: Create an Invoice with Line Items

```
"Create an invoice for Acme Corp with:
- Item 1: Consulting Services - $500
- Item 2: Software License - $1,200
Total: $1,700"
```

Claude will:

1. Use `post-crm-v3-objects-invoices_invoices` to create invoice
2. Use `post-crm-v3-objects-line_items-batch-create_create` to add line items
3. Associate line items with invoice

### Example 3: Batch Update Deals

```
"Update all deals in stage 'negotiation' to set close_date to end of month"
```

Claude will:

1. Search deals with `post-crm-v3-objects-objtype-search_search`
2. Batch update with `post-crm-v3-objects-objtype-batch-update_update`

### Parameter Compatibility Note

**Tools work with both parameter naming conventions:**

- ✅ Short names: `objtype`, `objid` (from tool names)
- ✅ Full names: `objectType`, `objectId` (from schemas)

The server automatically maps between them, so Claude can use either form.

## 🛠️ Development

### Project Structure

```
hubspot-mcp-extended/
├── src/              # TypeScript source code
│   ├── index.ts      # Main MCP server entry point
│   ├── tools/        # Tool implementations
│   └── schemas/      # OpenAPI schemas
├── scripts/          # Build and deployment scripts
├── docs/             # Documentation
│   └── specs/        # OpenAPI specification files
├── build/            # Compiled JavaScript (generated)
└── tests/            # Test files
```

### Building from Source

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode with auto-reload
npm run dev

# Verify tool count
node -e "const tools = require('./build/index.js'); console.log('Tools:', tools.hubspotTools?.length || 'Not available');"
```

### Testing

```bash
# Run unit tests
npm test

# Run integration tests
npm run test:integration

# Test tool listing (works without API key - shows 106 tools)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js --stdio

# Test actual tool execution (requires valid API key in .env)
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_v3_obj", "arguments": {"objectType": "contacts", "limit": "5"}}}' | node build/index.js --stdio

# Test Docker deployment
./scripts/verify-docker-project.sh

# Automated Docker setup validation (NEW!)
./scripts/validate-docker-setup.sh
```

### Environment Variables

- `HUBSPOT_ACCESS_TOKEN` (required): Your HubSpot API access token
- `LOG_LEVEL` (optional): Set logging verbosity (default: info)

## 🔄 Tool Regeneration

This server's tools are automatically generated from HubSpot's official OpenAPI specifications. To regenerate tools when HubSpot updates their APIs:

### Quick Regeneration

```bash
npm run regenerate:all
```

### Manual Step-by-Step

```bash
# 1. Ensure HubSpot specs are at known-good version (CRITICAL)
./scripts/ensure-hubspot-version.sh

# 2. Generate tools
npm run regenerate:specs
npm run regenerate:tools

# 3. Test and verify
npm run test:tools
./deploy.sh --allow-non-main

# 4. Update documentation
npm run regenerate:manifest
```

### Current Status

- **Tools**: 106 (includes Line Items API - updated 2025-01-13)
- **Source**: HubSpot official OpenAPI specs
- **Compatibility**: Claude Desktop (names < 64 chars, parameter normalization)

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- Create an [Issue](https://github.com/calypsoCodex/hubspot-mcp-extended/issues) for bug reports
- Submit a [Feature Request](https://github.com/calypsoCodex/hubspot-mcp-extended/issues) for enhancements
- Check [Documentation](docs) for detailed guides

Built with ❤️ for the AI and automation community