headlight-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# headlight-mcp-server
+
+MCP server for head·light CRM - connect Claude to your contacts, touchpoints, and reminders.
+
+## Setup
+
+1. Generate an API key in head·light Settings → Integrations → AI Integration
+2. Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "headlight": {
+      "command": "npx",
+      "args": ["-y", "headlight-mcp-server"],
+      "env": {
+        "HEADLIGHT_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_today_summary` | Quick overview of today's due items |
+| `search_people` | Find contacts by name, journey, or status |
+| `get_person` | Full contact details |
+| `add_note` | Add a note to a contact |
+| `list_touchpoints` | View due/overdue tasks |
+| `complete_touchpoint` | Mark a touchpoint done |
+| `list_reminders` | View personal reminders |
+| `create_reminder` | Create a reminder |
+| `complete_reminder` | Mark a reminder done |
+| `list_journeys` | See available journeys |
+| `get_journey` | Journey details and steps |
+| `assign_journey` | Put a contact on a journey |
+
+## Example Prompts
+
+- "What's on my head·light agenda today?"
+- "Find all my contacts with overdue touchpoints"
+- "Add a note to John Smith: Had a great call, interested in the Oak Street listing"
+- "Complete the touchpoint for Sarah about the welcome email"
+- "Remind me to follow up on the Johnson contract tomorrow"
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Test locally
+HEADLIGHT_API_KEY=your-key HEADLIGHT_API_URL=http://localhost:3000 node dist/index.js
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+const API_KEY = process.env.HEADLIGHT_API_KEY;
+const API_URL = process.env.HEADLIGHT_API_URL || 'https://headlight.homes';
+if (!API_KEY) {
+    console.error('HEADLIGHT_API_KEY environment variable is required');
+    process.exit(1);
+}
+async function apiCall(method, path, body) {
+    const url = `${API_URL}/api/mcp${path}`;
+    const response = await fetch(url, {
+        method,
+        headers: {
+            'Authorization': `Bearer ${API_KEY}`,
+            'Content-Type': 'application/json',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: response.statusText }));
+        throw new Error(error.error || `API error: ${response.status}`);
+    }
+    return response.json();
+}
+const server = new Server({
+    name: 'headlight',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Define all available tools
+const tools = [
+    {
+        name: 'get_today_summary',
+        description: 'Get a quick overview of today\'s touchpoints and reminders due, plus overdue items',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'search_people',
+        description: 'Search for contacts by name, workflow/journey, status, or find those with overdue touchpoints',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search by name' },
+                workflow: { type: 'string', description: 'Filter by journey/workflow name' },
+                status: { type: 'string', enum: ['active', 'inactive', 'archived'], description: 'Filter by status' },
+                hasOverdue: { type: 'boolean', description: 'Only show people with overdue touchpoints' },
+                limit: { type: 'number', description: 'Max results (default 10)' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'get_person',
+        description: 'Get full details about a person including phones, emails, notes, upcoming touchpoints, relationships, and important dates',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                personId: { type: 'string', description: 'The person\'s ID' },
+            },
+            required: ['personId'],
+        },
+    },
+    {
+        name: 'add_note',
+        description: 'Add a note to a person\'s profile',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                personId: { type: 'string', description: 'The person\'s ID' },
+                note: { type: 'string', description: 'The note content' },
+            },
+            required: ['personId', 'note'],
+        },
+    },
+    {
+        name: 'list_touchpoints',
+        description: 'List touchpoints (tasks) with optional filters. Use to see what\'s due, overdue, or upcoming.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                personId: { type: 'string', description: 'Filter by person' },
+                status: { type: 'string', enum: ['upcoming', 'completed', 'overdue'], description: 'Filter by status (default: upcoming)' },
+                channel: { type: 'string', enum: ['email', 'call', 'text', 'meeting', 'content', 'other'], description: 'Filter by channel' },
+                dateFrom: { type: 'string', description: 'Start date (ISO format)' },
+                dateTo: { type: 'string', description: 'End date (ISO format)' },
+                limit: { type: 'number', description: 'Max results (default 10)' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'complete_touchpoint',
+        description: 'Mark a touchpoint as done. Returns info about the next touchpoint in the journey.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                touchpointId: { type: 'string', description: 'The touchpoint ID to complete' },
+            },
+            required: ['touchpointId'],
+        },
+    },
+    {
+        name: 'list_reminders',
+        description: 'List personal reminders (not tied to contacts)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: { type: 'string', enum: ['active', 'completed', 'all'], description: 'Filter by status (default: active)' },
+                dateFrom: { type: 'string', description: 'Start date (ISO format)' },
+                dateTo: { type: 'string', description: 'End date (ISO format)' },
+                limit: { type: 'number', description: 'Max results (default 10)' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'create_reminder',
+        description: 'Create a personal reminder. Defaults to tomorrow at 9am if no date specified.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Reminder title' },
+                text: { type: 'string', description: 'Additional details (optional)' },
+                dueAt: { type: 'string', description: 'Due date/time (ISO format, optional)' },
+                isAllDay: { type: 'boolean', description: 'All-day reminder (default false)' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'complete_reminder',
+        description: 'Mark a reminder as done',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                reminderId: { type: 'string', description: 'The reminder ID to complete' },
+            },
+            required: ['reminderId'],
+        },
+    },
+    {
+        name: 'list_journeys',
+        description: 'List available journeys (workflows) with task and contact counts',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                includeInactive: { type: 'boolean', description: 'Include inactive journeys (default false)' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'get_journey',
+        description: 'Get journey details including all task templates',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                journeyId: { type: 'string', description: 'The journey ID' },
+            },
+            required: ['journeyId'],
+        },
+    },
+    {
+        name: 'assign_journey',
+        description: 'Assign a person to a journey. Creates touchpoints based on the journey\'s task templates.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                personId: { type: 'string', description: 'The person\'s ID (or use personName)' },
+                personName: { type: 'string', description: 'Search for person by name (or use personId)' },
+                journeyId: { type: 'string', description: 'The journey ID (or use journeyName)' },
+                journeyName: { type: 'string', description: 'Search for journey by name (or use journeyId)' },
+            },
+            required: [],
+        },
+    },
+];
+// Handle list tools request
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case 'get_today_summary':
+                result = await apiCall('GET', '/summary');
+                break;
+            case 'search_people':
+                result = await apiCall('POST', '/people/search', args);
+                break;
+            case 'get_person':
+                result = await apiCall('GET', `/people/${args.personId}`);
+                break;
+            case 'add_note':
+                result = await apiCall('POST', `/people/${args.personId}/notes`, {
+                    note: args.note,
+                });
+                break;
+            case 'list_touchpoints': {
+                const params = new URLSearchParams();
+                const typedArgs = args;
+                if (typedArgs.personId)
+                    params.set('personId', String(typedArgs.personId));
+                if (typedArgs.status)
+                    params.set('status', String(typedArgs.status));
+                if (typedArgs.channel)
+                    params.set('channel', String(typedArgs.channel));
+                if (typedArgs.dateFrom)
+                    params.set('dateFrom', String(typedArgs.dateFrom));
+                if (typedArgs.dateTo)
+                    params.set('dateTo', String(typedArgs.dateTo));
+                if (typedArgs.limit)
+                    params.set('limit', String(typedArgs.limit));
+                const query = params.toString();
+                result = await apiCall('GET', `/touchpoints${query ? `?${query}` : ''}`);
+                break;
+            }
+            case 'complete_touchpoint':
+                result = await apiCall('POST', `/touchpoints/${args.touchpointId}/complete`);
+                break;
+            case 'list_reminders': {
+                const params = new URLSearchParams();
+                const typedArgs = args;
+                if (typedArgs.status)
+                    params.set('status', String(typedArgs.status));
+                if (typedArgs.dateFrom)
+                    params.set('dateFrom', String(typedArgs.dateFrom));
+                if (typedArgs.dateTo)
+                    params.set('dateTo', String(typedArgs.dateTo));
+                if (typedArgs.limit)
+                    params.set('limit', String(typedArgs.limit));
+                const query = params.toString();
+                result = await apiCall('GET', `/reminders${query ? `?${query}` : ''}`);
+                break;
+            }
+            case 'create_reminder':
+                result = await apiCall('POST', '/reminders', args);
+                break;
+            case 'complete_reminder':
+                result = await apiCall('POST', `/reminders/${args.reminderId}/complete`);
+                break;
+            case 'list_journeys': {
+                const params = new URLSearchParams();
+                if (args.includeInactive) {
+                    params.set('includeInactive', 'true');
+                }
+                const query = params.toString();
+                result = await apiCall('GET', `/journeys${query ? `?${query}` : ''}`);
+                break;
+            }
+            case 'get_journey':
+                result = await apiCall('GET', `/journeys/${args.journeyId}`);
+                break;
+            case 'assign_journey':
+                result = await apiCall('POST', '/journeys/assign', args);
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('head·light MCP server running');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "headlight-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for head·light CRM - connect Claude to your contacts, touchpoints, and reminders",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "headlight-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "headlight",
+    "crm"
+  ],
+  "author": "Hoffman Tools",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+"publishConfig": {}
+}