@trylighthouse/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# Lighthouse MCP Server
+
+An [MCP](https://modelcontextprotocol.io/) server that connects AI assistants (Claude, Cursor, etc.) to the Lighthouse CRM API.
+
+## Setup
+
+### 1. Get your API key
+
+Go to **Settings → API Keys** in Lighthouse and generate a key (starts with `lgt_live_`).
+
+### 2. Build
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+### 3. Configure your AI client
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "lighthouse": {
+      "command": "node",
+      "args": ["/absolute/path/to/lighthouse/mcp-server/build/index.js"],
+      "env": {
+        "LIGHTHOUSE_API_KEY": "lgt_live_..."
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+```bash
+claude mcp add lighthouse -- node /absolute/path/to/lighthouse/mcp-server/build/index.js
+```
+
+Set the env var: `export LIGHTHOUSE_API_KEY=lgt_live_...`
+
+#### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "lighthouse": {
+      "command": "node",
+      "args": ["/absolute/path/to/lighthouse/mcp-server/build/index.js"],
+      "env": {
+        "LIGHTHOUSE_API_KEY": "lgt_live_..."
+      }
+    }
+  }
+}
+```
+
+### 4. After publishing to npm
+
+```json
+{
+  "mcpServers": {
+    "lighthouse": {
+      "command": "npx",
+      "args": ["-y", "@trylighthouse/mcp-server@latest"],
+      "env": {
+        "LIGHTHOUSE_API_KEY": "lgt_live_..."
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `lighthouse_search_records` | Search/filter companies, people, or deals |
+| `lighthouse_get_record` | Get a single record by ID |
+| `lighthouse_create_record` | Create a new record |
+| `lighthouse_update_record` | Update a record's fields |
+| `lighthouse_delete_record` | Delete a record |
+| `lighthouse_list_lists` | Get all CRM lists |
+| `lighthouse_get_list_records` | Get records in a list |
+| `lighthouse_add_to_list` | Add a record to a list |
+| `lighthouse_remove_from_list` | Remove a record from a list |
+| `lighthouse_list_notes` | Get notes for a record |
+| `lighthouse_create_note` | Create a note on a record |
+| `lighthouse_list_tasks` | Get CRM tasks |
+| `lighthouse_create_task` | Create a task |
+| `lighthouse_update_task` | Update a task |
+| `lighthouse_list_views` | Get saved views |
+| `lighthouse_list_attributes` | List custom field definitions |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `LIGHTHOUSE_API_KEY` | Yes | Your Lighthouse API key (`lgt_live_...`) |
+| `LIGHTHOUSE_API_URL` | No | Override API base URL (default: `https://api.trylighthouse.vc`) |
+
+## Publishing
+
+```bash
+npm login
+npm publish --access public
+```

package/build/api.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Lightweight HTTP client for the Lighthouse API.
+ * Reads LIGHTHOUSE_API_KEY from environment.
+ */
+export declare class LighthouseAPI {
+    private baseUrl;
+    private apiKey;
+    constructor();
+    private request;
+    get(path: string, params?: Record<string, unknown>): Promise<{
+        status: number;
+        data: unknown;
+        error: unknown;
+        meta?: unknown;
+    }>;
+    post(path: string, body?: Record<string, unknown>): Promise<{
+        status: number;
+        data: unknown;
+        error: unknown;
+        meta?: unknown;
+    }>;
+    patch(path: string, body?: Record<string, unknown>): Promise<{
+        status: number;
+        data: unknown;
+        error: unknown;
+        meta?: unknown;
+    }>;
+    delete(path: string, body?: Record<string, unknown>): Promise<{
+        status: number;
+        data: unknown;
+        error: unknown;
+        meta?: unknown;
+    }>;
+}

package/build/api.js

@@ -0,0 +1,51 @@
+/**
+ * Lightweight HTTP client for the Lighthouse API.
+ * Reads LIGHTHOUSE_API_KEY from environment.
+ */
+const DEFAULT_BASE_URL = "https://api.trylighthouse.vc";
+export class LighthouseAPI {
+    baseUrl;
+    apiKey;
+    constructor() {
+        const key = process.env.LIGHTHOUSE_API_KEY;
+        if (!key) {
+            throw new Error("LIGHTHOUSE_API_KEY environment variable is required. " +
+                "Generate one at Settings → API Keys in Lighthouse.");
+        }
+        this.apiKey = key;
+        this.baseUrl = (process.env.LIGHTHOUSE_API_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}/v1${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const json = await res.json();
+        return json;
+    }
+    async get(path, params) {
+        const qs = params
+            ? "?" +
+                Object.entries(params)
+                    .filter(([, v]) => v !== undefined && v !== null)
+                    .map(([k, v]) => `${k}=${encodeURIComponent(typeof v === "object" ? JSON.stringify(v) : String(v))}`)
+                    .join("&")
+            : "";
+        return this.request("GET", path + qs);
+    }
+    async post(path, body) {
+        return this.request("POST", path, body);
+    }
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    async delete(path, body) {
+        return this.request("DELETE", path, body);
+    }
+}

package/build/index.d.ts

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

package/build/index.js

@@ -0,0 +1,957 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { LighthouseAPI } from "./api.js";
+const api = new LighthouseAPI();
+function text(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function err(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+const server = new McpServer({
+    name: "lighthouse",
+    version: "0.1.0",
+});
+// ─────────────────────────────────────────────────────────
+// FILTER FORMAT REFERENCE (used in tool descriptions)
+// ─────────────────────────────────────────────────────────
+//
+// Shared filter structure (CRM & Discovery):
+//   { "operator":"AND"|"OR", "conditions":[...], "groups":[...] }
+//   conditions: [{ "field":"<key>", "operator":"<op>", "value":<val> }]
+//   groups: nested filter blocks with their own operator/conditions/groups
+//
+// Value formats:
+//   - text operators (contains, eq, etc.): string value
+//   - number operators (gt, lt, eq, etc.): numeric value
+//   - CRM between (number): { "from": <num>, "to": <num> } OR [min, max]
+//   - CRM between (date):   { "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }
+//   - Discovery between:    { "min": <num>, "max": <num> }
+//   - contains_any / not_contains_any / contains_all: array of values e.g. ["US","GB"]
+//   - empty / not_empty: no value needed (omit value key)
+//   - boolean eq: true or false
+//   - date (before, after, on): ISO date string "2024-01-15"
+//
+// CRM operators (from FilterBuilder.jsx):
+//   text/url:              contains, not_contains, starts_with, ends_with, eq, neq, empty, not_empty
+//   number/currency/rating: gt, gte, lt, lte, eq, neq, empty, not_empty
+//   date/datetimez:        before, after, on
+//   select/status/user:    contains_any, not_contains_any, empty, not_empty
+//   multi_select/category/multi_user/multi_record: contains_any, not_contains_any, contains_all, empty, not_empty
+//   record:                contains_any, not_contains_any, empty, not_empty
+//   domain/email/phone:    contains_any, not_contains_any, contains_all, empty, not_empty
+//   list_entries:          contains_any, not_contains_any, contains_all
+//
+// Discovery operators (from resourceFilterConfig.js):
+//   short_text:            contains, is
+//   long_text:             contains, not_contains, empty, not_empty
+//   text/url:              contains, not_contains, starts_with, ends_with, eq, neq, empty, not_empty
+//   number/currency:       between, gt, gte, lt, lte, eq, neq, empty, not_empty
+//   range:                 between, gt, lt, empty, not_empty
+//   date:                  after, before
+//   select:                contains_any, not_contains_any, empty, not_empty
+//   multi_select/investor_multi_select/work_experience_multi_select/education_multi_select/signal_select/language_select: contains_any, not_contains_any, contains_all, empty, not_empty
+//   funding_type_multi_select: contains_any, not_contains_any, empty, not_empty
+//   multi_user:            contains_any, not_contains_any, contains_all, empty, not_empty
+//   boolean/checkbox:      eq
+//   json:                  contains, not_contains, empty, not_empty
+// ─────────────────────────────────────────────────────────
+const CRM_FILTER_DESCRIPTION = "CRM filter object. Format: " +
+    '{"operator":"AND","conditions":[{"field":"<key>","operator":"<op>","value":<val>}],"groups":[]}. ' +
+    "IMPORTANT: First call lighthouse_crm_get_attributes to discover available field keys and types. " +
+    "Operators by field type — " +
+    "text/url: contains, not_contains, starts_with, ends_with, eq, neq, empty, not_empty; " +
+    "number/currency/rating: gt, gte, lt, lte, eq, neq, empty, not_empty; " +
+    "date: before, after, on; " +
+    "select/status/user: contains_any, not_contains_any, empty, not_empty; " +
+    "multi_select/category/multi_user/multi_record: contains_any, not_contains_any, contains_all, empty, not_empty; " +
+    "record: contains_any, not_contains_any, empty, not_empty; " +
+    "domain/email/phone: contains_any, not_contains_any, contains_all, empty, not_empty; " +
+    "list_entries: contains_any, not_contains_any, contains_all. " +
+    "Value formats: text ops → string; number ops → number; between (number) → {\"from\": min, \"to\": max}; " +
+    "between (date) → {\"from\": \"YYYY-MM-DD\", \"to\": \"YYYY-MM-DD\"}; " +
+    "contains_any/not_contains_any/contains_all → array of values; " +
+    "empty/not_empty → omit value; date ops → ISO date string. " +
+    "Groups allow nested AND/OR filter blocks with their own operator/conditions/groups. " +
+    "Do NOT use discovery field keys here — CRM fields come from lighthouse_crm_get_attributes.";
+const CRM_SORT_DESCRIPTION = 'CRM sort array. Format: [{"field":"<key>","direction":"asc"|"desc"}]. ' +
+    "Field keys must match a sortable CRM attribute (text, number, date, select, status, currency, rating).";
+const DISCOVERY_FILTER_DESCRIPTION = "Discovery filter object. Format: " +
+    '{"operator":"AND","conditions":[{"field":"<filter_id>","operator":"<op>","value":<val>}],"groups":[]}. ' +
+    "IMPORTANT: First call lighthouse_discovery_get_attributes to discover available filter_id values and types. " +
+    "Fields use prefixed keys (company_name, company_headcount, person_country, etc.). " +
+    "Operators by field type — " +
+    "short_text: contains, is; " +
+    "long_text: contains, not_contains, empty, not_empty; " +
+    "text/url: contains, not_contains, starts_with, ends_with, eq, neq, empty, not_empty; " +
+    "number/currency: between, gt, gte, lt, lte, eq, neq, empty, not_empty; " +
+    "range: between, gt, lt, empty, not_empty; " +
+    "date: after, before; " +
+    "select: contains_any, not_contains_any, empty, not_empty; " +
+    "multi_select/investor_multi_select/work_experience_multi_select/education_multi_select/signal_select/language_select: contains_any, not_contains_any, contains_all, empty, not_empty; " +
+    "funding_type_multi_select: contains_any, not_contains_any, empty, not_empty; " +
+    "multi_user: contains_any, not_contains_any, contains_all, empty, not_empty; " +
+    "boolean/checkbox: eq; " +
+    "json: contains, not_contains, empty, not_empty. " +
+    "Value formats: text ops → string; number ops → number; between → {\"min\": <num>, \"max\": <num>}; " +
+    "contains_any/not_contains_any/contains_all → array of values; empty/not_empty → omit value; boolean eq → true/false. " +
+    "Do NOT use CRM attribute keys here — discovery fields come from lighthouse_discovery_get_attributes.";
+const DISCOVERY_SORT_DESCRIPTION = 'Discovery sort object. Format: {"by":"<field_name>","dir":"asc"|"desc"}. ' +
+    "Common sort fields: founded_on, total_funding_amount_usd, score. Default: score descending.";
+// ─── CRM: Attributes ────────────────────────────────────
+server.registerTool("lighthouse_crm_get_attributes", {
+    title: "Get CRM Attributes",
+    description: "Get custom field definitions for a CRM record type. " +
+        "ALWAYS call this before building filters for search_records, list_records, or creating/updating views. " +
+        "Returns field keys, types, and options needed to construct valid filter conditions. " +
+        "This queries YOUR WORKSPACE's custom fields (CRM data you manage).",
+    inputSchema: {
+        entity_type: z
+            .enum(["company", "person", "deal"])
+            .describe("Record type to get attributes for"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get("/attributes", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_get_attribute", {
+    title: "Get CRM Attribute",
+    description: "Get a single custom field definition by its field_permalink.",
+    inputSchema: {
+        field_permalink: z.string().describe("Field permalink (unique key) of the attribute"),
+        entity_type: z.enum(["company", "person", "deal"]).optional().describe("Record type context"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get(`/attributes/${params.field_permalink}`, {
+            entity_type: params.entity_type,
+        });
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_create_attribute", {
+    title: "Create CRM Attribute",
+    description: "Create a new custom field in your CRM workspace. " +
+        "Common types: short_text, long_text, number, currency, date, select, multi_select, boolean, url, email, phone, rating.",
+    inputSchema: {
+        name: z.string().describe("Display name for the field"),
+        entity_type: z.enum(["company", "person", "deal"]).describe("Record type this field belongs to"),
+        data_type: z.string().describe("Field type (short_text, long_text, number, currency, date, select, multi_select, boolean, url, email, phone, rating)"),
+        options: z
+            .array(z.record(z.unknown()))
+            .optional()
+            .describe("For select/multi_select fields: array of {value, label} option objects"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post("/attributes", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_update_attribute", {
+    title: "Update CRM Attribute",
+    description: "Update a custom field's name or configuration.",
+    inputSchema: {
+        field_permalink: z.string().describe("Field permalink of the attribute to update"),
+        entity_type: z.enum(["company", "person", "deal"]).optional().describe("Record type context"),
+        name: z.string().optional().describe("New display name"),
+    },
+}, async (params) => {
+    try {
+        const { field_permalink, ...body } = params;
+        const res = await api.patch(`/attributes/${field_permalink}`, body);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── CRM: Options (select field values) ─────────────────
+server.registerTool("lighthouse_crm_list_options", {
+    title: "List CRM Field Options",
+    description: "Get select/multi_select field options. " +
+        "Use this to discover available values for select fields before setting them on records.",
+    inputSchema: {
+        field_permalink: z.string().optional().describe("Filter by field permalink"),
+        entity_type: z.enum(["company", "person", "deal"]).optional().describe("Filter by record type"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get("/options", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_create_option", {
+    title: "Create CRM Field Option",
+    description: "Add a new option value to a select/multi_select field.",
+    inputSchema: {
+        field_permalink: z.string().describe("Field permalink of the select/multi_select field"),
+        entity_type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        value: z.string().describe("Option value (stored value)"),
+        label: z.string().describe("Option label (display text)"),
+        color: z.string().optional().describe("Option color (hex code)"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post("/options", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── CRM: Records ────────────────────────────────────────
+server.registerTool("lighthouse_crm_search_records", {
+    title: "Search CRM Records",
+    description: "Search and filter records in YOUR CRM workspace (companies, people, or deals you've added). " +
+        "Supports filters, sorting, pagination, and saved views. " +
+        "NEVER guess field keys — ALWAYS call lighthouse_crm_get_attributes first to get the exact field keys " +
+        "for the entity_type, then use those keys in your filter conditions. " +
+        "NOT for discovering new companies/people — use lighthouse_discovery_* tools for that.",
+    inputSchema: {
+        type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        filters: z
+            .record(z.unknown())
+            .optional()
+            .describe(CRM_FILTER_DESCRIPTION),
+        sort: z
+            .array(z.record(z.unknown()))
+            .optional()
+            .describe(CRM_SORT_DESCRIPTION),
+        limit: z.number().min(1).max(100).default(25).describe("Records per page (max 100)"),
+        offset: z.number().min(0).default(0).describe("Number of records to skip"),
+        view_id: z
+            .string()
+            .uuid()
+            .optional()
+            .describe("Load saved filters/sort from a view. User-provided filters override view filters."),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post(`/records/${params.type}/search`, {
+            filters: params.filters,
+            sort: params.sort,
+            limit: params.limit,
+            offset: params.offset,
+            view_id: params.view_id,
+        });
+        return text(res);
+    }
+    catch (e) {
+        return err(`Search failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_get_record", {
+    title: "Get CRM Record",
+    description: "Get a single CRM record by ID with all fields and relationships.",
+    inputSchema: {
+        type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        id: z.string().uuid().describe("Record ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get(`/records/${params.type}/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_create_record", {
+    title: "Create CRM Record",
+    description: "Create a new CRM record. Required fields: " +
+        "company (name, domain), person (first_name, last_name), deal (name).",
+    inputSchema: {
+        type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        data: z.record(z.unknown()).describe("Record fields (name, domain, first_name, last_name, etc.)"),
+        attributes: z
+            .record(z.unknown())
+            .optional()
+            .describe("Custom field values keyed by field_permalink (from lighthouse_crm_get_attributes)"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post(`/records/${params.type}`, {
+            data: params.data,
+            attributes: params.attributes,
+        });
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_update_record", {
+    title: "Update CRM Record",
+    description: "Update an existing CRM record's fields.",
+    inputSchema: {
+        type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        id: z.string().uuid().describe("Record ID"),
+        data: z.record(z.unknown()).describe("Fields to update"),
+        attributes: z.record(z.unknown()).optional().describe("Custom field values to update (keyed by field_permalink)"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.patch(`/records/${params.type}/${params.id}`, {
+            data: params.data,
+            attributes: params.attributes,
+        });
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_delete_record", {
+    title: "Delete CRM Record",
+    description: "Permanently delete a CRM record.",
+    inputSchema: {
+        type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        id: z.string().uuid().describe("Record ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.delete(`/records/${params.type}/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── CRM: Lists ──────────────────────────────────────────
+server.registerTool("lighthouse_crm_create_list", {
+    title: "Create CRM List",
+    description: "Create a new CRM list to organize records.",
+    inputSchema: {
+        name: z.string().describe("List name"),
+        entity_type: z.enum(["company", "person", "deal"]).describe("Record type for this list"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post("/lists", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_list_lists", {
+    title: "List CRM Lists",
+    description: "Get all CRM lists in your workspace.",
+    inputSchema: {},
+}, async (params) => {
+    try {
+        const res = await api.get("/lists", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_get_list", {
+    title: "Get CRM List",
+    description: "Get a single CRM list by ID with its configuration.",
+    inputSchema: {
+        id: z.string().uuid().describe("List ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get(`/lists/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_update_list", {
+    title: "Update CRM List",
+    description: "Update a CRM list's name or configuration.",
+    inputSchema: {
+        id: z.string().uuid().describe("List ID"),
+        name: z.string().optional().describe("New list name"),
+    },
+}, async (params) => {
+    try {
+        const { id, ...body } = params;
+        const res = await api.patch(`/lists/${id}`, body);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_delete_list", {
+    title: "Delete CRM List",
+    description: "Permanently delete a CRM list.",
+    inputSchema: {
+        id: z.string().uuid().describe("List ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.delete(`/lists/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_get_list_records", {
+    title: "Get List Records",
+    description: "Get records in a CRM list with optional filtering, sorting, and view support. " +
+        "Same filter format as search_records.",
+    inputSchema: {
+        id: z.string().uuid().describe("List ID"),
+        filters: z.record(z.unknown()).optional().describe(CRM_FILTER_DESCRIPTION),
+        sort: z.array(z.record(z.unknown())).optional().describe(CRM_SORT_DESCRIPTION),
+        limit: z.number().min(1).max(100).default(25),
+        offset: z.number().min(0).default(0),
+        view_id: z.string().uuid().optional().describe("Load saved filters/sort from a view. User-provided filters override view filters."),
+    },
+}, async (params) => {
+    try {
+        const { id, ...query } = params;
+        const res = await api.get(`/lists/${id}/records`, query);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_add_to_list", {
+    title: "Add Record to List",
+    description: "Add a CRM record to a list.",
+    inputSchema: {
+        list_id: z.string().uuid().describe("List ID"),
+        record_id: z.string().uuid().describe("Record ID to add"),
+        type: z.enum(["company", "person", "deal"]).describe("Record type"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post(`/lists/${params.list_id}/records`, {
+            record_id: params.record_id,
+            type: params.type,
+        });
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_remove_from_list", {
+    title: "Remove Record from List",
+    description: "Remove a record from a CRM list.",
+    inputSchema: {
+        list_id: z.string().uuid().describe("List ID"),
+        record_id: z.string().uuid().describe("Record ID to remove"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.delete(`/lists/${params.list_id}/records/${params.record_id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── CRM: Notes ──────────────────────────────────────────
+server.registerTool("lighthouse_crm_list_notes", {
+    title: "List Notes",
+    description: "Get notes for a CRM record.",
+    inputSchema: {
+        record_id: z.string().uuid().describe("Record ID to get notes for"),
+        record_type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        limit: z.number().min(1).max(100).default(25),
+        offset: z.number().min(0).default(0),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get("/notes", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_create_note", {
+    title: "Create Note",
+    description: "Create a note on a CRM record. " +
+        "Content is HTML. For plain text, just pass it as-is. " +
+        "To @mention/tag workspace users in the note, you MUST: " +
+        "1) Call lighthouse_workspace_list_users first to find the user's ID, " +
+        "2) Include their user IDs in the tagged_users array, " +
+        "3) Include a mention span in the HTML content: " +
+        '<span data-type="mention" data-id="USER_UUID" data-label="First Last">@First Last</span>. ' +
+        "Tagged users receive an in-app notification.",
+    inputSchema: {
+        record_id: z.string().uuid().describe("Record ID to attach the note to"),
+        record_type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        title: z.string().describe("Note title"),
+        content: z.string().describe("Note content (plain text or HTML). Use <p> tags for paragraphs. For @mentions, include mention spans (see description)."),
+        tagged_users: z
+            .array(z.string().uuid())
+            .optional()
+            .describe("Array of workspace user UUIDs to tag/mention in the note. Must match mention spans in content."),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post("/notes", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_get_note", {
+    title: "Get Note",
+    description: "Get a single note by ID.",
+    inputSchema: {
+        id: z.string().uuid().describe("Note ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get(`/notes/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_delete_note", {
+    title: "Delete Note",
+    description: "Permanently delete a note.",
+    inputSchema: {
+        id: z.string().uuid().describe("Note ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.delete(`/notes/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── CRM: Tasks ──────────────────────────────────────────
+server.registerTool("lighthouse_crm_list_tasks", {
+    title: "List Tasks",
+    description: "List CRM tasks with optional filtering and sorting. " +
+        "The filters object supports: " +
+        'filter (CRM-style): {"operator":"AND","conditions":[{"field":"status","operator":"contains_any","value":["pending"]}]}; ' +
+        'sort: [{"field":"due_date","direction":"asc"}]; ' +
+        "Filterable fields: title, status, priority, due_date, description, assigned_to, records (person/company/deal), plus custom fields.",
+    inputSchema: {
+        filters: z
+            .object({
+            filter: z.record(z.any()).optional().describe("CRM filter object with operator/conditions/groups"),
+            sort: z.array(z.record(z.any())).optional().describe('Sort array: [{"field":"due_date","direction":"asc"}]'),
+        })
+            .optional()
+            .describe("Filter and sort options"),
+        limit: z.number().min(1).max(100).default(25),
+        offset: z.number().min(0).default(0),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get("/tasks", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_get_task", {
+    title: "Get Task",
+    description: "Get a single CRM task by ID.",
+    inputSchema: {
+        id: z.string().uuid().describe("Task ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get(`/tasks/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_create_task", {
+    title: "Create Task",
+    description: "Create a CRM task, optionally linked to records and assigned to users. " +
+        "The SQL expects assigned_to as [{id: uuid}] and records as {company: [{id}], person: [{id}], deal: [{id}]}.",
+    inputSchema: {
+        title: z.string().describe("Task title"),
+        description: z.string().optional().describe("Task description"),
+        status: z.string().optional().describe("Task status (e.g. 'pending', 'in_progress', 'completed')"),
+        priority: z.number().int().optional().describe("Priority as integer (e.g. 1=low, 2=medium, 3=high)"),
+        due_date: z.string().optional().describe("Due date (ISO 8601)"),
+        assigned_to: z
+            .array(z.string().uuid())
+            .optional()
+            .describe("Array of user UUIDs to assign the task to"),
+        records: z
+            .object({
+            company: z.array(z.string().uuid()).optional(),
+            person: z.array(z.string().uuid()).optional(),
+            deal: z.array(z.string().uuid()).optional(),
+        })
+            .optional()
+            .describe("Records to link: {company: [ids], person: [ids], deal: [ids]}"),
+        attributes: z.record(z.any()).optional().describe("Custom task field values as {field_permalink: value}"),
+    },
+}, async (params) => {
+    try {
+        const { attributes, assigned_to, records, ...rest } = params;
+        const data = { ...rest };
+        if (assigned_to)
+            data.assigned_to = assigned_to.map((id) => ({ id }));
+        if (records) {
+            data.records = {
+                company: records.company?.map((id) => ({ id })) || [],
+                person: records.person?.map((id) => ({ id })) || [],
+                deal: records.deal?.map((id) => ({ id })) || [],
+            };
+        }
+        const res = await api.post("/tasks", { data, attributes });
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_update_task", {
+    title: "Update Task",
+    description: "Update a CRM task. Provide only fields you want to change. " +
+        "assigned_to replaces all current assignees. records replaces all linked records.",
+    inputSchema: {
+        id: z.string().uuid().describe("Task ID"),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        status: z.string().optional().describe("Task status (e.g. 'pending', 'in_progress', 'completed')"),
+        priority: z.number().int().optional().describe("Priority as integer (e.g. 1=low, 2=medium, 3=high)"),
+        due_date: z.string().optional(),
+        assigned_to: z
+            .array(z.string().uuid())
+            .optional()
+            .describe("Array of user UUIDs to assign (replaces current assignees)"),
+        records: z
+            .object({
+            company: z.array(z.string().uuid()).optional(),
+            person: z.array(z.string().uuid()).optional(),
+            deal: z.array(z.string().uuid()).optional(),
+        })
+            .optional()
+            .describe("Records to link (replaces current): {company: [ids], person: [ids], deal: [ids]}"),
+        attributes: z.record(z.any()).optional().describe("Custom task field values as {field_permalink: value}"),
+    },
+}, async (params) => {
+    try {
+        const { id, attributes, assigned_to, records, ...rest } = params;
+        const data = { ...rest };
+        if (assigned_to)
+            data.assigned_to = assigned_to.map((id) => ({ id }));
+        if (records) {
+            data.records = {
+                company: records.company?.map((id) => ({ id })) || [],
+                person: records.person?.map((id) => ({ id })) || [],
+                deal: records.deal?.map((id) => ({ id })) || [],
+            };
+        }
+        const res = await api.patch(`/tasks/${id}`, { data, attributes });
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_delete_task", {
+    title: "Delete Task",
+    description: "Permanently delete a CRM task.",
+    inputSchema: {
+        id: z.string().uuid().describe("Task ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.delete(`/tasks/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── CRM: Views ──────────────────────────────────────────
+server.registerTool("lighthouse_crm_list_views", {
+    title: "List CRM Views",
+    description: "Get all saved CRM views. Views store filter/sort configurations that can be loaded in search_records.",
+    inputSchema: {
+        entity_type: z.enum(["company", "person", "deal"]).optional().describe("Filter by record type"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get("/views", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_create_view", {
+    title: "Create CRM View",
+    description: "Create a saved CRM view with filters and sort configuration. " +
+        "Views are for YOUR CRM data only (not discovery). " +
+        "WORKFLOW: 1) Call lighthouse_crm_get_attributes to get field keys, " +
+        "2) Build a filter object using those keys, " +
+        "3) Create the view with the filter. " +
+        "The saved filters will auto-apply when search_records is called with this view_id.",
+    inputSchema: {
+        name: z.string().describe("View name"),
+        entity_type: z.enum(["company", "person", "deal"]).describe("Record type"),
+        filters: z
+            .record(z.unknown())
+            .optional()
+            .describe(CRM_FILTER_DESCRIPTION),
+        sort: z.array(z.record(z.unknown())).optional().describe(CRM_SORT_DESCRIPTION),
+        view_type: z.enum(["table", "kanban"]).default("table").describe("View layout type"),
+        grouped_by: z.string().optional().describe("Field key to group by (required for kanban views)"),
+        sharing: z.enum(["private", "workspace"]).default("private").describe("Visibility"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post("/views", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_update_view", {
+    title: "Update CRM View",
+    description: "Update a saved CRM view's name, filters, sort, or sharing settings. " +
+        "Uses CRM filter format — call lighthouse_crm_get_attributes first if modifying filters.",
+    inputSchema: {
+        id: z.string().uuid().describe("View ID"),
+        name: z.string().optional(),
+        filters: z.record(z.unknown()).optional().describe(CRM_FILTER_DESCRIPTION),
+        sort: z.array(z.record(z.unknown())).optional().describe(CRM_SORT_DESCRIPTION),
+        view_type: z.enum(["table", "kanban"]).optional(),
+        grouped_by: z.string().optional().describe("Field key to group by (required for kanban views)"),
+        sharing: z.enum(["private", "workspace"]).optional(),
+    },
+}, async (params) => {
+    try {
+        const { id, ...body } = params;
+        const res = await api.patch(`/views/${id}`, body);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_get_view", {
+    title: "Get CRM View",
+    description: "Get a single saved CRM view by ID.",
+    inputSchema: {
+        id: z.string().uuid().describe("View ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get(`/views/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_crm_delete_view", {
+    title: "Delete CRM View",
+    description: "Permanently delete a saved CRM view.",
+    inputSchema: {
+        id: z.string().uuid().describe("View ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.delete(`/views/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── Workspace: Users ───────────────────────────────────
+server.registerTool("lighthouse_workspace_me", {
+    title: "Get Current User",
+    description: "Get the current authenticated user's profile (name, email, role, etc.).",
+    inputSchema: {},
+}, async () => {
+    try {
+        const res = await api.get("/users/me");
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_workspace_list_users", {
+    title: "List Workspace Users",
+    description: "List users in the workspace. Use this to find user IDs for task assignment, note tagging, or filtering by user. " +
+        "Supports search by name/email.",
+    inputSchema: {
+        search: z.string().optional().describe("Search by name or email"),
+        team_id: z.string().uuid().optional().describe("Filter by team ID"),
+        role_id: z.string().uuid().optional().describe("Filter by role ID"),
+        limit: z.number().min(1).max(100).default(25),
+        offset: z.number().min(0).default(0),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get("/users", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_workspace_get_user", {
+    title: "Get Workspace User",
+    description: "Get a specific workspace user's profile by ID.",
+    inputSchema: {
+        id: z.string().uuid().describe("User ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get(`/users/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── Workspace: Teams ───────────────────────────────────
+server.registerTool("lighthouse_workspace_list_teams", {
+    title: "List Workspace Teams",
+    description: "List all teams in the workspace.",
+    inputSchema: {
+        limit: z.number().min(1).max(100).default(25),
+        offset: z.number().min(0).default(0),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get("/teams", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_workspace_get_team", {
+    title: "Get Workspace Team",
+    description: "Get a specific team by ID with its members.",
+    inputSchema: {
+        id: z.string().uuid().describe("Team ID"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get(`/teams/${params.id}`);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── Discovery: Attributes ───────────────────────────────
+server.registerTool("lighthouse_discovery_get_attributes", {
+    title: "Get Discovery Attributes",
+    description: "Get available filter fields for Lighthouse's company/people database (discovery). " +
+        "ALWAYS call this before building filters for discovery_search_companies or discovery_search_people. " +
+        "Returns field definitions with filter_id, type, and options. " +
+        "These are NOT your CRM fields — these are Lighthouse's global database fields.",
+    inputSchema: {
+        type: z
+            .enum(["company", "person"])
+            .optional()
+            .describe("Entity type: 'company' or 'person'. If omitted, returns both as { company: [...], person: [...] }."),
+    },
+}, async (params) => {
+    try {
+        const res = await api.get("/discovery/attributes", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── Discovery: Search ───────────────────────────────────
+server.registerTool("lighthouse_discovery_search_companies", {
+    title: "Search Discovery Companies",
+    description: "Search Lighthouse's global company database to DISCOVER new companies. " +
+        "This searches Lighthouse's enriched database (millions of companies), NOT your CRM. " +
+        "NEVER guess field keys — ALWAYS call lighthouse_discovery_get_attributes with type=company first " +
+        "to get the exact filter_id values, then use those in your filter conditions. " +
+        "Common fields: company_name, company_headcount, company_hq_country, company_total_funding, company_categories.",
+    inputSchema: {
+        filters: z
+            .record(z.unknown())
+            .optional()
+            .describe(DISCOVERY_FILTER_DESCRIPTION),
+        sort: z.record(z.unknown()).optional().describe(DISCOVERY_SORT_DESCRIPTION),
+        skip: z.number().min(0).default(0).describe("Number of results to skip"),
+        limit: z.number().min(1).max(100).default(25).describe("Results per page"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post("/database/get-companies", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+server.registerTool("lighthouse_discovery_search_people", {
+    title: "Search Discovery People",
+    description: "Search Lighthouse's global people database to DISCOVER new people. " +
+        "This searches Lighthouse's enriched database, NOT your CRM. " +
+        "NEVER guess field keys — ALWAYS call lighthouse_discovery_get_attributes with type=person first " +
+        "to get the exact filter_id values, then use those in your filter conditions. " +
+        "Common fields: person_name, person_country, person_highlights, person_current_categories.",
+    inputSchema: {
+        filters: z
+            .record(z.unknown())
+            .optional()
+            .describe(DISCOVERY_FILTER_DESCRIPTION),
+        skip: z.number().min(0).default(0).describe("Number of results to skip"),
+        limit: z.number().min(1).max(100).default(25).describe("Results per page"),
+    },
+}, async (params) => {
+    try {
+        const res = await api.post("/database/get-people", params);
+        return text(res);
+    }
+    catch (e) {
+        return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+});
+// ─── Start ───────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Lighthouse MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@trylighthouse/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for the Lighthouse CRM API",
+  "type": "module",
+  "bin": {
+    "lighthouse-mcp": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}