daeda-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daeda Technologies PTE Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# Daeda MCP
+
+An MCP server that syncs your HubSpot CRM to a local encrypted database, enabling AI assistants to query your contacts, companies, and deals instantly.
+
+## Why Daeda?
+
+Querying HubSpot through the API is slow and rate-limited. Daeda solves this by:
+
+- **Syncing your entire CRM locally** - Contacts, companies, deals, and all associations
+- **Encrypted storage** - Your data is encrypted at rest using your HubSpot token
+- **Instant queries** - AI assistants can run SQL queries against your local database
+- **Works offline** - Once synced, no internet required for queries
+
+## Features
+
+- **Full CRM Sync** - Exports all contacts, companies, and deals with all properties
+- **Association Support** - Contact-company, deal-contact, and deal-company relationships
+- **Smart Seeding** - Quick preview of ~1,000 recent deals available in seconds while full sync runs
+- **Resumable Sync** - Interrupted syncs resume automatically on restart
+- **Read-Only Queries** - AI can only SELECT data, never modify your CRM
+
+## Use Cases
+
+- "Show me all deals closing this month over $50k"
+- "Find contacts at companies in the healthcare industry"
+- "Which deals have no associated contacts?"
+- "List all contacts with a @gmail.com email"
+- "What's the total pipeline value by deal stage?"
+
+## Prerequisites
+
+### HubSpot Private App Setup
+
+1. Go to your HubSpot account → Settings → Integrations → Private Apps
+2. Create a new private app
+3. Under "Scopes", enable these permissions:
+   - `crm.export` (required for bulk data export)
+   - `crm.objects.contacts.read`
+   - `crm.objects.companies.read`
+   - `crm.objects.deals.read`
+4. Create the app and copy your access token (starts with `pat-`)
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g daeda-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/daeda-tech/daeda-mcp.git
+cd daeda-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "daeda": {
+      "command": "npx",
+      "args": ["-y", "daeda-mcp"],
+      "env": {
+        "HS_PRIVATE_TOKEN": "pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (from source)
+
+```json
+{
+  "mcpServers": {
+    "daeda": {
+      "command": "node",
+      "args": ["/path/to/daeda-mcp/dist/index.js"],
+      "env": {
+        "HS_PRIVATE_TOKEN": "pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json` in your project or global config):
+
+```json
+{
+  "mcpServers": {
+    "daeda": {
+      "command": "npx",
+      "args": ["-y", "daeda-mcp"],
+      "env": {
+        "HS_PRIVATE_TOKEN": "pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf MCP config (`~/.windsurf/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "daeda": {
+      "command": "npx",
+      "args": ["-y", "daeda-mcp"],
+      "env": {
+        "HS_PRIVATE_TOKEN": "pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### VS Code with MCP Extension
+
+Add to your VS Code settings or MCP extension config:
+
+```json
+{
+  "mcp.servers": {
+    "daeda": {
+      "command": "npx",
+      "args": ["-y", "daeda-mcp"],
+      "env": {
+        "HS_PRIVATE_TOKEN": "pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Cline
+
+Add to your Cline MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "daeda": {
+      "command": "npx",
+      "args": ["-y", "daeda-mcp"],
+      "env": {
+        "HS_PRIVATE_TOKEN": "pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Using with Bun (development)
+
+If you prefer Bun for faster startup:
+
+```json
+{
+  "mcpServers": {
+    "daeda": {
+      "command": "bun",
+      "args": ["run", "/path/to/daeda-mcp/src/index.ts"],
+      "env": {
+        "HS_PRIVATE_TOKEN": "pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+## How It Works
+
+1. **First Launch** - Daeda requests bulk exports from HubSpot's Export API
+2. **Quick Seed** - While exports process, ~1,000 recent deals are fetched via Search API for immediate use
+3. **Full Sync** - Export CSVs are downloaded and streamed into an encrypted SQLite database
+4. **Ready** - AI assistants can now query your full CRM instantly
+
+The **quick seed completes in 2-5 minutes**, giving you immediate access to your 1,000 most recent deals and their associated contacts and companies.
+
+The **full sync** runs in the background and duration depends on your CRM size:
+- Small CRM (10k records): ~5-10 minutes
+- Medium CRM (100k records): ~30-60 minutes  
+- Large CRM (1M+ records): up to 5 hours
+
+Progress is shown via the `db_status` tool. You can start querying immediately after the quick seed completes.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `db_status` | Check sync progress and database health |
+| `get_raw_sql` | Execute SELECT queries against your CRM data |
+
+## Database Schema
+
+The local database contains:
+
+- **contacts** - All contacts with email and full properties as JSON
+- **companies** - All companies with domain and full properties as JSON
+- **deals** - All deals with name and full properties as JSON
+- **contact_company** - Contact to company associations
+- **deal_contact** - Deal to contact associations
+- **deal_company** - Deal to company associations
+
+Query any HubSpot property using `json_extract()`:
+
+```sql
+SELECT 
+  json_extract(properties, '$.firstname') as first_name,
+  json_extract(properties, '$.lastname') as last_name,
+  email
+FROM contacts
+WHERE json_extract(properties, '$.lifecyclestage') = 'customer'
+LIMIT 10
+```
+
+## Data Storage
+
+Your CRM data is stored locally at:
+- **macOS/Linux**: `~/.daeda-mcp/data/`
+- **Windows**: `%APPDATA%\daeda-mcp\data\`
+
+The database is encrypted using your HubSpot token as the encryption key. If you change tokens, the database will be re-initialized automatically.
+
+## Security
+
+- All data stays on your machine
+- Database is encrypted at rest
+- Only SELECT queries are allowed
+- Dangerous SQL keywords are blocked
+- Your HubSpot token is never stored (only used for encryption)
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.

package/dist/db/config.d.ts

@@ -0,0 +1,12 @@
+export interface PortalConfig {
+    portalId: string;
+    accessToken: string;
+    name?: string;
+    createdAt: string;
+    lastSyncAt?: string;
+}
+export declare function getPortal(portalId: string): PortalConfig | null;
+export declare function listPortals(): PortalConfig[];
+export declare function setPortal(portal: PortalConfig): void;
+export declare function updatePortalLastSync(portalId: string): void;
+export declare function deletePortal(portalId: string): boolean;

package/dist/db/config.js

@@ -0,0 +1,53 @@
+// Portal configuration storage
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = join(__dirname, '../../data');
+const CONFIG_FILE = join(DATA_DIR, 'config.json');
+function ensureDataDir() {
+    if (!existsSync(DATA_DIR)) {
+        mkdirSync(DATA_DIR, { recursive: true });
+    }
+}
+function loadConfig() {
+    ensureDataDir();
+    if (!existsSync(CONFIG_FILE)) {
+        return { portals: {} };
+    }
+    const content = readFileSync(CONFIG_FILE, 'utf-8');
+    return JSON.parse(content);
+}
+function saveConfig(config) {
+    ensureDataDir();
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+export function getPortal(portalId) {
+    const config = loadConfig();
+    return config.portals[portalId] || null;
+}
+export function listPortals() {
+    const config = loadConfig();
+    return Object.values(config.portals);
+}
+export function setPortal(portal) {
+    const config = loadConfig();
+    config.portals[portal.portalId] = portal;
+    saveConfig(config);
+}
+export function updatePortalLastSync(portalId) {
+    const config = loadConfig();
+    if (config.portals[portalId]) {
+        config.portals[portalId].lastSyncAt = new Date().toISOString();
+        saveConfig(config);
+    }
+}
+export function deletePortal(portalId) {
+    const config = loadConfig();
+    if (config.portals[portalId]) {
+        delete config.portals[portalId];
+        saveConfig(config);
+        return true;
+    }
+    return false;
+}

package/dist/db/keychain.d.ts

@@ -0,0 +1,2 @@
+export declare function getHubSpotToken(): string | null;
+export declare function getDbEncryptionKey(): Promise<string>;

package/dist/db/keychain.js

@@ -0,0 +1,11 @@
+const ENV_VAR_NAME = "HS_PRIVATE_TOKEN";
+export function getHubSpotToken() {
+    return process.env[ENV_VAR_NAME] || null;
+}
+export async function getDbEncryptionKey() {
+    const key = process.env[ENV_VAR_NAME];
+    if (!key) {
+        throw new Error(`${ENV_VAR_NAME} environment variable is required for database encryption.`);
+    }
+    return key;
+}

package/dist/db/schema.d.ts

@@ -0,0 +1,10 @@
+export declare const SCHEMA_SQL = "\n-- Contacts table (id, human-readable identifier, last_synced, all properties as JSON)\nCREATE TABLE IF NOT EXISTS contacts (\n  id TEXT PRIMARY KEY,\n  email TEXT,\n  last_synced TEXT,\n  properties TEXT\n);\n\nCREATE INDEX IF NOT EXISTS idx_contacts_email ON contacts(email);\n\n-- Companies table\nCREATE TABLE IF NOT EXISTS companies (\n  id TEXT PRIMARY KEY,\n  domain TEXT,\n  last_synced TEXT,\n  properties TEXT\n);\n\nCREATE INDEX IF NOT EXISTS idx_companies_domain ON companies(domain);\n\n-- Deals table\nCREATE TABLE IF NOT EXISTS deals (\n  id TEXT PRIMARY KEY,\n  dealname TEXT,\n  last_synced TEXT,\n  properties TEXT\n);\n\nCREATE INDEX IF NOT EXISTS idx_deals_dealname ON deals(dealname);\n\n-- Association tables\nCREATE TABLE IF NOT EXISTS contact_company (\n  contact_id TEXT,\n  company_id TEXT,\n  PRIMARY KEY (contact_id, company_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_cc_contact ON contact_company(contact_id);\nCREATE INDEX IF NOT EXISTS idx_cc_company ON contact_company(company_id);\n\nCREATE TABLE IF NOT EXISTS deal_contact (\n  deal_id TEXT,\n  contact_id TEXT,\n  PRIMARY KEY (deal_id, contact_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_dc_deal ON deal_contact(deal_id);\nCREATE INDEX IF NOT EXISTS idx_dc_contact ON deal_contact(contact_id);\n\nCREATE TABLE IF NOT EXISTS deal_company (\n  deal_id TEXT,\n  company_id TEXT,\n  PRIMARY KEY (deal_id, company_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_dco_deal ON deal_company(deal_id);\nCREATE INDEX IF NOT EXISTS idx_dco_company ON deal_company(company_id);\n\n-- Sync metadata table\nCREATE TABLE IF NOT EXISTS sync_metadata (\n  key TEXT PRIMARY KEY,\n  value TEXT\n);\n";
+export type ObjectType = "contacts" | "companies" | "deals";
+export type AssociationType = "contact_company" | "deal_contact" | "deal_company";
+export interface SyncMetadata {
+    initialized_at: string;
+    last_synced: string;
+    contacts_count: number;
+    companies_count: number;
+    deals_count: number;
+}

package/dist/db/schema.js

@@ -0,0 +1,65 @@
+export const SCHEMA_SQL = `
+-- Contacts table (id, human-readable identifier, last_synced, all properties as JSON)
+CREATE TABLE IF NOT EXISTS contacts (
+  id TEXT PRIMARY KEY,
+  email TEXT,
+  last_synced TEXT,
+  properties TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_contacts_email ON contacts(email);
+
+-- Companies table
+CREATE TABLE IF NOT EXISTS companies (
+  id TEXT PRIMARY KEY,
+  domain TEXT,
+  last_synced TEXT,
+  properties TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_companies_domain ON companies(domain);
+
+-- Deals table
+CREATE TABLE IF NOT EXISTS deals (
+  id TEXT PRIMARY KEY,
+  dealname TEXT,
+  last_synced TEXT,
+  properties TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_deals_dealname ON deals(dealname);
+
+-- Association tables
+CREATE TABLE IF NOT EXISTS contact_company (
+  contact_id TEXT,
+  company_id TEXT,
+  PRIMARY KEY (contact_id, company_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cc_contact ON contact_company(contact_id);
+CREATE INDEX IF NOT EXISTS idx_cc_company ON contact_company(company_id);
+
+CREATE TABLE IF NOT EXISTS deal_contact (
+  deal_id TEXT,
+  contact_id TEXT,
+  PRIMARY KEY (deal_id, contact_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_dc_deal ON deal_contact(deal_id);
+CREATE INDEX IF NOT EXISTS idx_dc_contact ON deal_contact(contact_id);
+
+CREATE TABLE IF NOT EXISTS deal_company (
+  deal_id TEXT,
+  company_id TEXT,
+  PRIMARY KEY (deal_id, company_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_dco_deal ON deal_company(deal_id);
+CREATE INDEX IF NOT EXISTS idx_dco_company ON deal_company(company_id);
+
+-- Sync metadata table
+CREATE TABLE IF NOT EXISTS sync_metadata (
+  key TEXT PRIMARY KEY,
+  value TEXT
+);
+`;

package/dist/db/sqlite.d.ts

@@ -0,0 +1,43 @@
+import { type Client } from "@libsql/client";
+import { type ObjectType, type AssociationType } from "./schema.js";
+export declare function getDbPath(): string;
+export declare function dbExists(): Promise<boolean>;
+export declare function isDbHealthy(): Promise<boolean>;
+export declare function getDb(): Promise<Client>;
+export declare function closeDb(): Promise<void>;
+export declare function clearTable(table: ObjectType | AssociationType): Promise<void>;
+export declare function insertContact(id: string, email: string | null, properties: Record<string, unknown>): Promise<void>;
+export declare function insertCompany(id: string, domain: string | null, properties: Record<string, unknown>): Promise<void>;
+export declare function insertDeal(id: string, dealname: string | null, properties: Record<string, unknown>): Promise<void>;
+export declare function insertAssociation(associationType: AssociationType, fromId: string, toId: string): Promise<void>;
+export declare function setMetadata(key: string, value: string): Promise<void>;
+export interface ContactRow {
+    id: string;
+    email: string | null;
+    properties: Record<string, unknown>;
+}
+export interface CompanyRow {
+    id: string;
+    domain: string | null;
+    properties: Record<string, unknown>;
+}
+export interface DealRow {
+    id: string;
+    dealname: string | null;
+    properties: Record<string, unknown>;
+}
+export interface AssociationRow {
+    fromId: string;
+    toId: string;
+}
+export declare function batchInsertContacts(rows: ContactRow[]): Promise<void>;
+export declare function batchInsertCompanies(rows: CompanyRow[]): Promise<void>;
+export declare function batchInsertDeals(rows: DealRow[]): Promise<void>;
+export declare function batchInsertAssociations(associationType: AssociationType, rows: AssociationRow[]): Promise<void>;
+export declare function getMetadata(key: string): Promise<string | null>;
+export declare function getAllMetadata(): Promise<Record<string, string>>;
+export declare function getRecordCount(objectType: ObjectType): Promise<number>;
+export declare function executeQuery(sql: string): Promise<{
+    columns: string[];
+    rows: Record<string, unknown>[];
+}>;