@trylighthouse/mcp-server 0.2.1 → 0.2.6

package/README.md

@@ -86,7 +86,7 @@ Records support built-in types (`company`, `person`, `deal`) and custom object t
 
 | Tool | Description |
 |------|-------------|
-| `lighthouse_crm_list_lists` | Get all CRM lists |
+| `lighthouse_crm_list_lists` | Get the CRM lists in your workspace, or find one by its name |
 | `lighthouse_crm_create_list` | Create a new list |
 | `lighthouse_crm_get_list` | Get a single list |
 | `lighthouse_crm_update_list` | Update a list |
@@ -201,6 +201,10 @@ Files and folders live in the workspace, not on a record. Linking one to a recor
 | `lighthouse_reports_share_dashboard_with_teams` | Share a dashboard with teams |
 | `lighthouse_reports_revoke_dashboard_from_teams` | Revoke team access to a dashboard |
 
+## Rate limits
+
+A `429` with the code `rate_limit_exceeded` is retried for you, up to 4 times, before the tool reports the `429` exactly as the API sent it. Before each retry the server waits at least the seconds in the `Retry-After` header (1 second if there is none, at most 30). Each retry also draws a random wait that can grow with every attempt: up to 2 seconds before the first retry, then up to 4, 8 and 16 (never more than 30), and the server waits the longer of the two. Calls refused at the same moment therefore spread out instead of all coming back together and being refused again. It never starts a retry more than 40 seconds after the first attempt, so the API still has time to answer within the 60 seconds many MCP clients allow for a tool call. When the next wait would end past those 40 seconds, the tool reports the `429` straight away. A tool call your client cancels stops waiting and is not sent again. The API refuses such a request before running it, so a refused attempt changes nothing and only the attempt it accepts is applied. No other error is retried, `credit_limit_exceeded` included, and neither is a limit set by a connected email or LinkedIn account (`rate_limited`).
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/build/api.d.ts

@@ -1,9 +1,34 @@
+export declare const RATE_LIMIT_RETRY: Readonly<{
+    retriesMax: 4;
+    fallbackWaitMs: 1000;
+    waitMaxMs: 30000;
+    backoffBaseMs: 1000;
+    retryWindowMs: 40000;
+}>;
+export declare const RATE_LIMIT_CODE = "rate_limit_exceeded";
+export interface RateLimitRetryOptions {
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    random?: () => number;
+    now?: () => number;
+    signal?: AbortSignal;
+}
+export declare function withCallSignal<T>(signal: AbortSignal | undefined, run: () => T): T;
+export declare function callSignalOf(args: unknown[]): AbortSignal | undefined;
+export declare function retryAfterMs(header: string | null | undefined, now?: number): number;
+export declare function backoffCeilingMs(retry: number): number;
+export declare function rateLimitWaitMs(header: string | null | undefined, retry: number, random?: () => number, now?: number): number;
+export declare function isRateLimitRefusal(res: Response): Promise<boolean>;
+export declare function fetchWithRateLimitRetry(send: () => Promise<Response>, options?: RateLimitRetryOptions): Promise<Response>;
 export declare class LighthouseAPI {
     private baseUrl;
     private apiKey;
     private currentTool;
     constructor(apiKey?: string);
     setCurrentTool(toolName: string | null): void;
+    private url;
+    private headers;
+    private query;
+    private send;
     private request;
     get(path: string, params?: Record<string, unknown>): Promise<{
         status: number;
@@ -11,6 +36,15 @@ export declare class LighthouseAPI {
         error: unknown;
         meta?: unknown;
     }>;
+    download(path: string, params: Record<string, unknown> | undefined, maxBytes: number): Promise<{
+        bytes: Buffer<ArrayBuffer>;
+        contentType: string;
+    } | null>;
+    downloadSigned(url: string, maxBytes: number): Promise<{
+        bytes: Buffer<ArrayBuffer>;
+        contentType: string;
+    } | null>;
+    private fetchBytes;
     post(path: string, body?: Record<string, unknown>): Promise<{
         status: number;
         data: unknown;

package/build/api.js

@@ -1,4 +1,103 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 const DEFAULT_BASE_URL = "https://api.trylighthouse.vc";
+export const RATE_LIMIT_RETRY = Object.freeze({
+    retriesMax: 4,
+    fallbackWaitMs: 1_000,
+    waitMaxMs: 30_000,
+    backoffBaseMs: 1_000,
+    retryWindowMs: 40_000,
+});
+export const RATE_LIMIT_CODE = "rate_limit_exceeded";
+const toolCall = new AsyncLocalStorage();
+export function withCallSignal(signal, run) {
+    return toolCall.run({ signal }, run);
+}
+export function callSignalOf(args) {
+    for (let i = args.length - 1; i >= 0; i -= 1) {
+        const arg = args[i];
+        const signal = arg != null && typeof arg === "object" ? arg.signal : undefined;
+        if (signal instanceof AbortSignal)
+            return signal;
+    }
+    return undefined;
+}
+const pause = (ms, signal) => new Promise((resolve) => {
+    if (signal?.aborted)
+        return resolve();
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+});
+function cancelled(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        return reason;
+    const error = new Error("The tool call was cancelled.");
+    error.name = "AbortError";
+    return error;
+}
+export function retryAfterMs(header, now = Date.now()) {
+    const value = typeof header === "string" ? header.trim() : "";
+    if (/^\d+(\.\d+)?$/.test(value))
+        return Number(value) * 1000;
+    if (/[a-z]/i.test(value)) {
+        const at = Date.parse(value);
+        if (Number.isFinite(at))
+            return Math.max(0, at - now);
+    }
+    return RATE_LIMIT_RETRY.fallbackWaitMs;
+}
+export function backoffCeilingMs(retry) {
+    return Math.min(RATE_LIMIT_RETRY.waitMaxMs, RATE_LIMIT_RETRY.backoffBaseMs * 2 ** retry);
+}
+export function rateLimitWaitMs(header, retry, random = Math.random, now = Date.now()) {
+    const floor = Math.min(retryAfterMs(header, now), RATE_LIMIT_RETRY.waitMaxMs);
+    const draw = Number(random());
+    const spread = Number.isFinite(draw) ? Math.min(Math.max(draw, 0), 1) : 0;
+    return Math.ceil(Math.max(floor, spread * backoffCeilingMs(retry)));
+}
+export async function isRateLimitRefusal(res) {
+    if (res.status !== 429)
+        return false;
+    try {
+        const body = (await res.clone().json());
+        if (body == null || typeof body !== "object")
+            return false;
+        const error = body.error;
+        const code = error != null && typeof error === "object" ? error.code : undefined;
+        return (typeof code === "string" ? code : body.error_code) === RATE_LIMIT_CODE;
+    }
+    catch {
+        return false;
+    }
+}
+export async function fetchWithRateLimitRetry(send, options = {}) {
+    const sleep = options.sleep ?? pause;
+    const random = options.random ?? Math.random;
+    const now = options.now ?? Date.now;
+    const signal = options.signal;
+    const startedAt = now();
+    let res = await send();
+    for (let retry = 1; retry <= RATE_LIMIT_RETRY.retriesMax; retry += 1) {
+        if (signal?.aborted)
+            return res;
+        if (!(await isRateLimitRefusal(res)))
+            return res;
+        const wait = rateLimitWaitMs(res.headers.get("retry-after"), retry, random, now());
+        if (now() - startedAt + wait > RATE_LIMIT_RETRY.retryWindowMs)
+            return res;
+        await res.body?.cancel().catch(() => undefined);
+        await sleep(wait, signal);
+        if (signal?.aborted)
+            throw cancelled(signal);
+        res = await send();
+    }
+    return res;
+}
 export class LighthouseAPI {
     baseUrl;
     apiKey;
@@ -15,9 +114,11 @@ export class LighthouseAPI {
     setCurrentTool(toolName) {
         this.currentTool = toolName;
     }
-    async request(method, path, body) {
+    url(path) {
         const versioned = (/^\/v\d+\//.test(path) || path.startsWith("/mcp/")) ? path : `/v1${path}`;
-        const url = `${this.baseUrl}${versioned}`;
+        return `${this.baseUrl}${versioned}`;
+    }
+    headers() {
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
@@ -26,23 +127,56 @@ export class LighthouseAPI {
         if (this.currentTool) {
             headers["X-Lighthouse-MCP-Tool"] = this.currentTool;
         }
-        const res = await fetch(url, {
-            method,
-            headers,
-            body: body ? JSON.stringify(body) : undefined,
-        });
-        const json = await res.json();
-        return json;
+        return headers;
     }
-    async get(path, params) {
-        const qs = params
+    query(params) {
+        return 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);
+    }
+    send(url, init) {
+        const signal = toolCall.getStore()?.signal;
+        const request = signal ? { ...init, signal } : init;
+        return fetchWithRateLimitRetry(() => fetch(url, request), { signal });
+    }
+    async request(method, path, body) {
+        const res = await this.send(this.url(path), {
+            method,
+            headers: this.headers(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const json = await res.json();
+        return json;
+    }
+    async get(path, params) {
+        return this.request("GET", path + this.query(params));
+    }
+    async download(path, params, maxBytes) {
+        return this.fetchBytes(this.url(path) + this.query(params), this.headers(), maxBytes);
+    }
+    async downloadSigned(url, maxBytes) {
+        return this.fetchBytes(url, {}, maxBytes);
+    }
+    async fetchBytes(url, headers, maxBytes) {
+        try {
+            const res = await this.send(url, { headers });
+            if (!res.ok)
+                return null;
+            const declared = Number(res.headers.get("content-length"));
+            if (Number.isFinite(declared) && declared > maxBytes)
+                return null;
+            const bytes = Buffer.from(await res.arrayBuffer());
+            if (bytes.length > maxBytes)
+                return null;
+            return { bytes, contentType: (res.headers.get("content-type") || "").split(";")[0].trim().toLowerCase() };
+        }
+        catch {
+            return null;
+        }
     }
     async post(path, body) {
         return this.request("POST", path, body);

package/build/server.d.ts

@@ -1,2 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function createServer(apiKey?: string): McpServer;
+export interface CreateServerOptions {
+    privateEquity?: boolean;
+}
+export declare function createServer(apiKey?: string, options?: CreateServerOptions): McpServer;

package/build/server.js

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { LighthouseAPI } from "./api.js";
+import { LighthouseAPI, callSignalOf, withCallSignal } from "./api.js";
 import { leanDiscovery } from "./leanDiscovery.js";
 function text(data) {
     const failed = data != null && typeof data === "object" && data.error != null;
@@ -29,6 +29,44 @@ function profileSection(res, keys) {
     return { ...envelope, data: section };
 }
 const TRANSCRIPT_WINDOW_CHARS = 40_000;
+const FILE_CONTENT_WINDOW_CHARS = TRANSCRIPT_WINDOW_CHARS;
+const IMAGE_BYTES_MAX = 5 * 1024 * 1024;
+const IMAGE_CONTENT_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+const IMAGE_LIMIT_WORDS = `${IMAGE_BYTES_MAX / (1024 * 1024)} MB`;
+function viewableImageType(res, pick) {
+    if (res == null || typeof res !== "object")
+        return null;
+    const envelope = res;
+    if (envelope.error != null || envelope.data == null || typeof envelope.data !== "object")
+        return null;
+    const data = envelope.data;
+    if (data.kind !== "image")
+        return null;
+    const { contentType, size } = pick(data);
+    const type = typeof contentType === "string" ? contentType.toLowerCase() : "";
+    if (!IMAGE_CONTENT_TYPES.has(type))
+        return null;
+    if (typeof size === "number" && size > IMAGE_BYTES_MAX)
+        return null;
+    return type;
+}
+function textWithImage(res, image, declaredType) {
+    const base = text(res);
+    if (!image)
+        return base;
+    const mimeType = IMAGE_CONTENT_TYPES.has(image.contentType) ? image.contentType : declaredType;
+    return { ...base, content: [...base.content, { type: "image", data: image.bytes.toString("base64"), mimeType }] };
+}
+const FILE_CONTENT_RULES = "kind is pdf, document, spreadsheet, presentation, html, csv, markdown, text or image (null for a kind that cannot be read); pages_total is a PDF's pages or a presentation's slides. " +
+    "A spreadsheet reads as one \"Sheet: <name>\" block per sheet, a row per line with its cells tab separated (a date shows as its stored serial number); a presentation as one \"Slide <n>\" block per slide. " +
+    `A long file comes back in windows of max_chars (default ${FILE_CONTENT_WINDOW_CHARS}): meta.has_more true means the file continues, so pass meta.next_offset_chars as offset_chars to read on, and never treat a window with has_more as the end of the file. ` +
+    "meta.complete false means the file is longer than can be read here and the text stops before its end. " +
+    "When text is null, reason says why (unsupported_type, image, too_large, no_text for a scan or an empty file, unreadable for a damaged or password protected one, timed_out) and note says it in words: relay the note, never guess the content. " +
+    `An image (PNG, JPEG, GIF or WebP up to ${IMAGE_LIMIT_WORDS}) comes back as the image itself after the JSON, so you can look at it. ` +
+    "Older .doc, .xls and .ppt files, archives, audio and video cannot be read.";
+const MEETING_ACCESS_RULE = "The API key's user may read a recorded meeting (its notes and transcript) when they recorded it, were invited to it (as a guest, declined included, or as its organizer), or a teammate who recorded it shares their meeting notes with them; each occurrence of a recurring meeting is judged on its own.";
+const MEETING_KEY_SOURCES = "from a lighthouse_inbox_calendar_meetings row, or from the meeting object of a meeting note read with lighthouse_crm_get_note, lighthouse_crm_list_notes or lighthouse_crm_search_notes";
+const NOTE_MEETING_KEY_RULE = "meeting.meeting_key is the recorded meeting's handle, the same one a lighthouse_inbox_calendar_meetings row carries: when meeting.has_transcript is true, pass it to lighthouse_inbox_calendar_meeting_transcript for what was actually said. meeting.has_transcript and meeting.has_recording are answered for the API key's user: each is true only when that transcript or recording belongs to this note's occurrence and they may read it, which needs no access to the recorder's calendar (their role permitting). A recurring meeting shares one key and keeps only the transcript of its latest recorded occurrence, so the note of an earlier occurrence says false. lighthouse_inbox_calendar_meeting describes that same latest occurrence, so it answers for the key when either flag is true; lighthouse_inbox_calendar_meeting_notes returns the newest notes of that meeting the user may read. The API returns no recording, only whether one exists.";
 const THREAD_MESSAGES_PAGE_DEFAULT = 15;
 const RETIRED_INPUTS = {
     email: "email is no longer a parameter. Use emails, a comma separated list of email addresses.",
@@ -43,18 +81,18 @@ const ADDRESS_INPUT = z.union([
     }),
 ]);
 const RECIPIENTS = z.union([ADDRESS_INPUT, z.array(ADDRESS_INPUT)]);
-export function createServer(apiKey) {
+export function createServer(apiKey, options = {}) {
     const api = new LighthouseAPI(apiKey);
     const server = new McpServer({
         name: "lighthouse",
-        version: "0.2.1",
+        version: "0.2.6",
     });
     const originalRegister = server.registerTool.bind(server);
     server.registerTool = (name, schemaOrConfig, handler) => {
         const wrappedHandler = async (...args) => {
             api.setCurrentTool(name);
             try {
-                return await handler(...args);
+                return await withCallSignal(callSignalOf(args), () => handler(...args));
             }
             finally {
                 api.setCurrentTool(null);
@@ -78,7 +116,7 @@ export function createServer(apiKey) {
         "investors (a company's investors, a read-only multi_record of the GLOBAL DATABASE's companies and people): contains_any, not_contains_any, contains_all, empty, not_empty; the value is a list of investor ids from lighthouse_discovery_search_entities with record_type 'investor', never CRM record ids; " +
         "experience / education (a person's work history and schools, read-only multi_records of the GLOBAL DATABASE's companies and schools): contains_any, not_contains_any, contains_all, empty, not_empty; the value is a list of ids from lighthouse_discovery_search_entities with record_type 'company' (record_type 'school' for education), never CRM record ids; " +
         "domain/email/phone: contains_any, not_contains_any, contains_all, empty, not_empty; " +
-        "list_entries (the record's list memberships; the value is an array of list ids from lighthouse_crm_list_lists, and the list's record_type must be this record type): contains_any, not_contains_any, contains_all, empty, not_empty (empty = in no list, not_empty = in at least one list; both take no value). A custom field can belong to ONE list: lighthouse_crm_list_attributes leaves it out unless you pass that list's list_id, its value sits inside that list's entry under the record's list_entries rather than at the top level, and naming it in a condition or a sort answers 'List not found' when you cannot open the list. A question about the records IN a list with further conditions or an order (\"companies in list X created this month, newest first\") is ONE call: either lighthouse_crm_list_list_records with the same filters and sort, or this search with a list_entries contains_any condition on that list's id beside the other conditions; never read the whole list and narrow it by hand; " +
+        "list_entries (the record's list memberships; the value is an array of list ids from lighthouse_crm_list_lists, and the list's record_type must be the type of the record the condition is on: this record type, or the linked record's type on a dotted path): contains_any, not_contains_any, contains_all, empty, not_empty (empty = in no list, not_empty = in at least one list; both take no value). On a dotted path it filters by the linked records' lists, quantified like every dotted field: associated_people.list_entries contains_any [<people list id>] on a company = the companies with at least one person in that list, associated_people.list_entries empty = the companies none of whose people is in a list, companies with no people included; a custom record-link field works the same way (<link field>.list_entries, the lists of the record type it links to). A custom field can belong to ONE list: lighthouse_crm_list_attributes gives it that list's list_id, it can be set only on a record already in that list, its value sits inside that list's entry under the record's list_entries rather than at the top level, and naming it in a condition or a sort answers 'List not found' when you cannot open the list. A question about the records IN a list with further conditions or an order (\"companies in list X created this month, newest first\") is ONE call: either lighthouse_crm_list_list_records with the same filters and sort, or this search with a list_entries contains_any condition on that list's id beside the other conditions; never read the whole list and narrow it by hand; " +
         "checkbox: eq (value is true or false); " +
         "interaction (first/last email & linkedin interaction, overall interaction-with): eq, neq, empty, not_empty; " +
         "interaction-type (first/last interaction type): contains_any, not_contains_any, empty, not_empty. " +
@@ -109,7 +147,7 @@ export function createServer(apiKey) {
         "Multiple entries sort by the first, then tie-break by the next. " +
         "NOT every field is sortable. A field is sortable ONLY when its type (the `data_type` returned by lighthouse_crm_list_attributes) is one of: " +
         "text, url, number, currency, percentage, rating, date, datetime, datetimez, select, status, user, checkbox, " +
-        "record, record_company_name, record_person_name, record_deal_name, growth, note, duration. " +
+        "record, record_company_name, record_person_name, record_deal_name, record_custom_object_name, growth, note, duration. " +
         "growth (headcount_growth) sorts by ONE window: add \"timeframe\":\"1m\"|\"3m\"|\"6m\"|\"1y\" to the sort item ({\"field\":\"headcount_growth\",\"direction\":\"desc\",\"timeframe\":\"6m\"}; 3m when omitted; an unknown window comes back in invalid_sort_fields). " +
         "note (the notes field) orders by the newest note's date, records without notes last. " +
         "duration (time_in_stage, time_in_status, every time_in_<status field> twin) orders by the time in the current status: asc = fewest days first, records whose status is empty last; the sort item is the plain {\"field\",\"direction\"} with no extra key. " +
@@ -146,8 +184,8 @@ export function createServer(apiKey) {
         "json: contains, not_contains, empty, not_empty. " +
         "SPECIAL COMPOUND TYPES, " +
         "signal_select (company_signals): operators contains_any/not_contains_any/contains_all, value is array of signal strings e.g. [\"new_funding_round\",\"growth_headcount\"]; " +
-        "signal_select (person_signals): operators contains_any/not_contains_any/contains_all, value is {\"signals\":[\"company_registration\",...],\"registration_countries\":[\"US\",\"DE\",...],\"signal_dates\":{\"stealth\":\"2024-03-01\"},\"stealth_predicted_areas\":[\"fintech\",...]} " +
-        "(every key besides signals is optional: registration_countries only filters the company_registration signal by country; " +
+        "signal_select (person_signals): operators contains_any/not_contains_any/contains_all, value is {\"signals\":[\"company_registration\",...],\"registration_countries\":[\"DE\",\"GB\",...],\"signal_dates\":{\"stealth\":\"2024-03-01\"},\"stealth_predicted_areas\":[\"fintech\",...]} " +
+        "(every key besides signals is optional: registration_countries only filters the company_registration signal by country, as UPPERCASE ISO codes, and the country is where the company was registered, and registrations exist only for the countries whose company registers we read, which lighthouse_discovery_list_locations returns as `registration_countries`, so any other country returns no people; " +
         "signal_dates maps a signal to a 'started on/after' ISO date and applies to stealth / out_of_stealth / founded_new_company; " +
         "stealth_predicted_areas refines the stealth signal by predicted category group, same values as person_stealth_predicted_area); " +
         "language_select: operators contains_any/not_contains_any/contains_all, value is {\"languages\":[<ISO 639-1 two-letter codes, e.g. \"en\",\"de\",\"fr\">],\"proficiency\":[<one or more of exactly \"NATIVE_BILINGUAL\",\"EXPERT\",\"ADVANCED\",\"INTERMEDIATE\",\"BASIC\">]} " +
@@ -182,7 +220,7 @@ export function createServer(apiKey) {
         "Socials: company_linkedin, company_twitter, company_facebook, company_github, company_producthunt (url; matches the profile handle/permalink with text operators). " +
         "Investors (who invested IN this company): company_investor (investor_multi_select; ids from lighthouse_discovery_search_entities record_type 'investor'), company_investor_country (multi_select; list_locations countries), company_investor_region (multi_select; list_locations regions). " +
         "Investments (the company AS an investor; the investments_top_* keys match the investor's TOP-RANKED preference only, e.g. their #1 country, not every investment they ever made): company_is_investor (checkbox; eq true = the company is itself an investor such as a fund or CVC, eq false = exclude investors), company_num_investments (number; total recorded investments), company_investments_top_category (multi_select; list_industries categories), company_investments_top_sdg (multi_select; list_industries sdg_categories), company_investments_top_country (multi_select; list_locations countries), company_investments_top_region (multi_select; list_locations regions), company_investments_top_stage (funding_type_multi_select; lighthouse_discovery_list_funding_types `value`, no_funding not applicable). " +
-        "Team: company_team_past_companies (work_experience_multi_select; ids from lighthouse_discovery_search_entities record_type 'company'), company_team_education (education_multi_select; ids from lighthouse_discovery_search_entities record_type 'school'), company_team_experience (multi_select; same values as company_tags), company_team_language (language_select), company_team_language_proficiency (multi_select; use with company_team_language to require a proficiency level), company_team_name_origin (multi_select; list_locations countries), company_team_location_country, company_team_location_region, company_team_work_country, company_team_work_region, company_team_edu_country, company_team_edu_region (multi_select; list_locations). " +
+        "Team: company_team_past_companies (work_experience_multi_select; ids from lighthouse_discovery_search_entities record_type 'company'), company_team_education (education_multi_select; ids from lighthouse_discovery_search_entities record_type 'school'), company_team_tags (multi_select; same values as person_tags; matches a company whose current founders or executives carry the tags, and contains_all may be met by different members), company_team_language (language_select), company_team_language_proficiency (multi_select; use with company_team_language to require a proficiency level), company_team_name_origin (multi_select; list_locations countries), company_team_location_country, company_team_location_region, company_team_work_country, company_team_work_region, company_team_edu_country, company_team_edu_region (multi_select; list_locations). " +
         "CRM (filter the global database by YOUR workspace CRM): company_internal_crm_status (checkbox; eq true = already in your CRM, false = not), company_crm_list_entries (multi_select; companies that are in specific CRM company lists, list ids from lighthouse_crm_list_lists), company_crm_deals_list_entries (multi_select; companies whose deals are in specific deal lists), company_crm_team_network (multi_user; companies whose team members are connected to specific workspace users, ids from lighthouse_workspace_list_users), company_crm_team_list_entries (multi_select; companies whose team members are in specific people lists), company_external_crm_status (checkbox; needs a connected external CRM), company_external_crm_lists (multi_select; needs a connected external CRM). " +
         'NESTED-GROUP EXAMPLE for "headcount 10-50 AND (HQ in US or UK) AND raised Series A": ' +
         '{"operator":"AND","conditions":[{"field":"company_headcount","operator":"between","value":{"min":10,"max":50}},{"field":"company_last_funding_type","operator":"contains_any","value":["series_a"]}],"groups":[{"operator":"OR","conditions":[{"field":"company_hq_country","operator":"contains_any","value":["US","GB"]}],"groups":[]}]} ' +
@@ -191,8 +229,8 @@ export function createServer(apiKey) {
         "Basics: person_name (short_text), person_created_at (date). " +
         "Investments (the person AS an investor, e.g. an angel; the investments_top_* keys match the investor's TOP-RANKED preference only, e.g. their #1 country, not every investment they ever made): person_is_investor (checkbox; eq true = only investors, eq false = exclude investors), person_num_investments (number; total recorded investments), person_investments_top_category (multi_select; list_industries categories), person_investments_top_sdg (multi_select; list_industries sdg_categories), person_investments_top_country (multi_select; list_locations countries), person_investments_top_region (multi_select; list_locations regions), person_investments_top_stage (funding_type_multi_select; lighthouse_discovery_list_funding_types `value`, no_funding not applicable). " +
         "Industry: person_current_categories, person_past_categories (multi_select; values from lighthouse_discovery_list_industries → categories), person_current_sdg_impact, person_past_sdg_impact (multi_select; list_industries → sdg_categories). " +
-        "Signals: person_signals (signal_select; value {\"signals\":[...],\"registration_countries\"?:[...],\"signal_dates\"?:{<signal>:\"YYYY-MM-DD\"},\"stealth_predicted_areas\"?:[...]}), person_registration_country (multi_select; filters company_registration signals by country, list_locations countries). " +
-        "Tags: person_tags (multi_select; values: phd_doctorate, 2nd_time_founder, serial_founder, has_exit, raised_funding, sales_exp, co_exp, eng_exp, ai_and_data_exp, product_exp, hr_exp). " +
+        "Signals: person_signals (signal_select; value {\"signals\":[...],\"registration_countries\"?:[...],\"signal_dates\"?:{<signal>:\"YYYY-MM-DD\"},\"stealth_predicted_areas\"?:[...]}), person_registration_country (multi_select; filters company_registration signals by country, values from lighthouse_discovery_list_locations → registration_countries, the countries whose company registers we read; the country is where the company was registered, so any other country returns no people). " +
+        "Tags: person_tags (multi_select; values: phd_doctorate, master, bachelor, technical, 2nd_time_founder, serial_founder, has_exit, raised_funding, sales_exp, co_exp, eng_exp, ai_and_data_exp, product_exp, hr_exp). " +
         "Language & origin: person_language (language_select), person_language_proficiency (multi_select; use with person_language to require a proficiency level), person_name_origin (multi_select; list_locations countries). " +
         "Current location: person_country (multi_select; UPPERCASE ISO alpha-2 codes e.g. \"US\", \"GB\" from lighthouse_discovery_list_locations → countries), person_region (multi_select; list_locations → regions), person_german_state (multi_select; German federal states). " +
         "Experience: person_past_companies (work_experience_multi_select; ids from lighthouse_discovery_search_entities record_type 'company'), person_education (education_multi_select; ids from lighthouse_discovery_search_entities record_type 'school'), person_experience_start_date, person_experience_end_date (date; matches people with at least one work experience whose start/end date passes the bound, independent of the other experience conditions), person_work_country, person_work_region, person_edu_country, person_edu_region (multi_select; list_locations). " +
@@ -204,13 +242,13 @@ export function createServer(apiKey) {
         "(an outer AND of two OR groups; country codes from list_locations).";
     server.registerTool("lighthouse_crm_list_attributes", {
         title: "List CRM Attributes",
-        description: "Get a lightweight catalog of the fields for a CRM record type: each field's permalink, label, data_type, links_to, read_only, is_custom, has_options, and source_field. " +
+        description: "Get a lightweight catalog of the fields for a CRM record type: each field's permalink, label, data_type, links_to, read_only, is_custom, has_options, source_field and list_id. " +
             "`source_field` names the status attribute a `duration` attribute is derived from (null on every other attribute); such attributes (time_in_stage on deals, time_in_status on tasks, time_in_<status> beside a custom status field) are read-only and computed, never written. " +
             "ALWAYS call this before building filters for search_records / list_records or creating/updating views. Use the exact permalinks it returns. " +
             "To keep the response small it does NOT include select/multi_select option values: when a field has has_options=true, call lighthouse_crm_list_options with that permalink to get its allowed values before filtering or setting it. " +
             "Supports built-in types (company, person, deal, task) and custom objects (use the object's permalink, e.g. 'lp', 'project'). " +
             "When called without record_type, returns all types including custom objects as top-level keys. " +
-            "A custom field that belongs to a single list is left out unless you pass that list's list_id, and a list you cannot open answers 'List not found'. Filtering or sorting on such a field without access to its list answers the same way.",
+            "A custom field that belongs to a single list carries that list's list_id: it can be set only on a record already in that list (add the record with lighthouse_crm_add_to_list first), and its value sits in that list's entry under the record's list_entries. Without list_id every list's fields are listed; passing list_id keeps the fields of every record plus that list's own. A list you cannot open answers 'List not found', and so does filtering or sorting on a field of such a list.",
         inputSchema: {
             record_type: z
                 .string()
@@ -518,7 +556,7 @@ export function createServer(apiKey) {
         description: "The AI reports generated on one CRM record (any record type: company, person, deal, or a custom object permalink), newest first: the memos, SWOTs, teardowns, pass memos and briefs a member generated from the record's AI Reports tab in Lighthouse. " +
             "WHEN TO USE: the user asks whether a memo or report already exists on a record, what the last one said, wants to compare or build on an earlier report, or asks about a company's \"memo\" / \"analysis\" / \"write-up\" (check here before writing one from scratch). Not for dashboards or charts (those are lighthouse_reports_*), and nothing here generates a report: that happens in the app. " +
             "Each row: id, name, status (processing / success / error), depth (short / standard / extensive), template, partial (true when the run hit a cap), summary (one paragraph of the report's own prose), created_by ({ id, first_name, last_name, full_name, avatar_url, email }, the same member object every other row carries), created_at, completed_at. Only a success report has a document: read it with lighthouse_crm_get_ai_report. " +
-            "A report quoting a mailbox, calendar, LinkedIn account or file the API key's user cannot read is left out of the list (its author always sees it).",
+            "A report quoting a mailbox, calendar, meeting notes, LinkedIn account or file the API key's user cannot read is left out of the list (its author always sees it).",
         inputSchema: {
             record_type: z.string().describe("Record type: company, person, deal, or a custom object permalink"),
             record_id: z.string().uuid().optional().describe("Record ID whose reports to list"),
@@ -540,7 +578,7 @@ export function createServer(apiKey) {
         title: "Get AI Report",
         description: "One AI report by id (from lighthouse_crm_list_ai_reports): the same metadata plus record_type / record_id and content, the full document as Markdown with its section headings (citation markers removed). " +
             "WHEN TO USE: the user wants what an earlier memo or report actually says (a section, a number, a recommendation), or a comparison with it. A report can be long: quote or summarise the part the question is about rather than echoing it whole. " +
-            "content is null while the report is still processing or failed. Answers 403 naming the channel when the report draws on a shared mailbox, calendar, LinkedIn account or document the API key's user cannot read, and 404 for an unknown id.",
+            "content is null while the report is still processing or failed. Answers 403 naming the channel when the report draws on a shared mailbox, calendar, meeting notes, LinkedIn account or document the API key's user cannot read, and 404 for an unknown id.",
         inputSchema: {
             id: z.string().uuid().describe("Report ID from lighthouse_crm_list_ai_reports"),
         },
@@ -790,14 +828,17 @@ export function createServer(apiKey) {
     server.registerTool("lighthouse_crm_list_lists", {
         title: "List CRM Lists",
         description: "Get all CRM lists in your workspace. Each list's record_type is 'company', 'person', 'deal', or a custom object permalink (e.g. 'lp', 'project'), and that is the record type of everything in it. " +
-            "Each row carries owner (the member who created it) and is_owner (true when that member is the API key's user), so 'my lists' and 'lists shared with me' can be told apart without a second call.",
+            "Each row carries owner (the member who created it) and is_owner (true when that member is the API key's user), so 'my lists' and 'lists shared with me' can be told apart without a second call. " +
+            "WHEN TO USE: to find a list someone names (\"the Deals Reviewed list\"), pass search with the words of its name and read the id off the matching row, instead of paging through every list; leave search out to page through all of them. meta.total counts the lists that matched.",
         inputSchema: {
+            search: z.string().optional().describe("Only lists whose name contains every one of these words, in any case. A list with a similar name is a different list."),
+            query: z.string().optional().describe("Same as search. Either name works; search wins when both are sent."),
             limit: z.number().min(1).max(100).default(25),
             offset: z.number().min(0).default(0),
         },
     }, async (params) => {
         try {
-            const res = await api.get("/lists", params);
+            const res = await api.post("/lists/search", params);
             return text(res);
         }
         catch (e) {
@@ -1016,7 +1057,7 @@ export function createServer(apiKey) {
         title: "List Notes",
         description: "Get notes for a CRM record. Each note in the response includes a `records` map, every record (company/person/deal/custom object) the note is currently linked to, plus a `tags` array of any workspace tags attached to the note (each with id, label, color). " +
             "`tagged_users` is the teammates the note MENTIONS, each the member object this API answers for a person ({ id, first_name, last_name, full_name, avatar_url, email }), and [] when it mentions nobody. It is read from the mention spans in `content`, not from the ids a write sent, so a note written with tagged_users ids and no mention span reads back []: always write both, as lighthouse_crm_create_note and lighthouse_crm_update_note say. " +
-            "Every note also carries `type` ('standard' for a note a member wrote, 'meeting' for meeting notes written from a recorded meeting) and `meeting` (null on a standard note; on a meeting note { title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording }, where attendees is [{ email, name }] with name possibly null, call_type is a short category from a fixed list such as 'First founder call' or 'Internal discussion', and duration_seconds / ical_uid / attendees are omitted when unknown). Meeting notes are included only when the API key's user can open the meeting's recording.",
+            "Every note also carries `type` ('standard' for a note a member wrote, 'meeting' for meeting notes written from a recorded meeting) and `meeting` (null on a standard note; on a meeting note { meeting_key, title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording }, where attendees is [{ email, name }] with name possibly null, call_type is a short category from a fixed list such as 'First founder call' or 'Internal discussion', duration_seconds and ical_uid are null when unknown and attendees is [] when there are none). " + NOTE_MEETING_KEY_RULE + " Meeting notes are included only when the API key's user may read the meeting. " + MEETING_ACCESS_RULE,
         inputSchema: {
             record_id: z.string().uuid().describe("Record ID to list notes for"),
             limit: z.number().min(1).max(100).default(25),
@@ -1043,7 +1084,7 @@ export function createServer(apiKey) {
             "type (select: contains_any / not_contains_any ONLY, with an array of \"standard\" and / or \"meeting\"; [\"meeting\"] selects meeting notes written from a recorded meeting, [\"standard\"] the notes members wrote; any other value is rejected). " +
             "An unknown field or invalid operator is rejected with a clear error naming it. " +
             "`tagged_users` is the teammates the note MENTIONS, each the member object this API answers for a person ({ id, first_name, last_name, full_name, avatar_url, email }), and [] when it mentions nobody. It is read from the mention spans in `content`, not from the ids a write sent, so a note written with tagged_users ids and no mention span reads back []: always write both, as lighthouse_crm_create_note and lighthouse_crm_update_note say. " +
-            "Every returned note carries `type` ('standard' | 'meeting') and `meeting` (null on a standard note; on a meeting note { title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording }; attendees is [{ email, name }] with name possibly null; duration_seconds, ical_uid and attendees are omitted when unknown). Meeting notes are included only when the API key's user can open the meeting's recording.",
+            "Every returned note carries `type` ('standard' | 'meeting') and `meeting` (null on a standard note; on a meeting note { meeting_key, title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording }; attendees is [{ email, name }] with name possibly null; duration_seconds and ical_uid are null when unknown and attendees is [] when there are none). " + NOTE_MEETING_KEY_RULE + " Meeting notes are included only when the API key's user may read the meeting. " + MEETING_ACCESS_RULE,
         inputSchema: {
             search: z.string().optional().describe("Free-text search on the note title"),
             filters: z.record(z.any()).optional().describe("CRM-style filter object for notes (see tool description for fields + operators)"),
@@ -1103,7 +1144,7 @@ export function createServer(apiKey) {
         title: "Get Note",
         description: "Get a single note by ID. Response includes a `records` object keyed by record type (or custom object permalink) with every linked record, plus a `tags` array of any workspace tags attached to the note (each with permalink, label, color). " +
             "`tagged_users` is the teammates the note MENTIONS, each the member object this API answers for a person ({ id, first_name, last_name, full_name, avatar_url, email }), and [] when it mentions nobody. It is read from the mention spans in `content`, not from the ids a write sent, so a note written with tagged_users ids and no mention span reads back []: always write both, as lighthouse_crm_create_note and lighthouse_crm_update_note say. " +
-            "`type` is 'standard' for a note a member wrote and 'meeting' for meeting notes written from a recorded meeting; `meeting` is null on a standard note and { title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording } on a meeting note: title and occurred_at come from the meeting itself, attendees is [{ email, name }] with name possibly null, call_type is one of 'First founder call', 'Follow-up founder call', 'Diligence call', 'Re-engagement', 'Portfolio check-in', 'Board meeting', 'Investment committee', 'LP meeting', 'Fundraising call', 'Co-investor or syndication call', 'Internal discussion', 'Hiring or reference call', 'Partnership or vendor call' or 'Other', and duration_seconds / ical_uid / attendees are omitted when unknown. A meeting note is returned only when the API key's user can open the meeting's recording; otherwise it is reported as not found.",
+            "`type` is 'standard' for a note a member wrote and 'meeting' for meeting notes written from a recorded meeting; `meeting` is null on a standard note and { meeting_key, title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording } on a meeting note: title and occurred_at come from the meeting itself, attendees is [{ email, name }] with name possibly null, call_type is one of 'First founder call', 'Follow-up founder call', 'Diligence call', 'Re-engagement', 'Portfolio check-in', 'Board meeting', 'Investment committee', 'LP meeting', 'Fundraising call', 'Co-investor or syndication call', 'Internal discussion', 'Hiring or reference call', 'Partnership or vendor call' or 'Other', duration_seconds and ical_uid are null when unknown, and attendees is [] when there are none. " + NOTE_MEETING_KEY_RULE + " A meeting note is returned only when the API key's user may read the meeting; otherwise it is reported as not found. " + MEETING_ACCESS_RULE,
         inputSchema: {
             note_id: z.string().uuid().optional().describe("Note ID"),
             id: z.string().uuid().optional().describe("Same as note_id, the name this tool has always taken. Send either one."),
@@ -1575,7 +1616,7 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_documents_get_file", {
         title: "Get File",
-        description: "Get file metadata. Response includes my_role ('owner' | 'editor' | 'viewer'), is_owner, owner (the member who owns it: { id, first_name, last_name, full_name, avatar_url, email }), sharing ('private' or 'workspace'), linked_records_count, linked_records[] and shared_with_teams[] (each entry has { team_id, team_name, role, granted_at }). Pass download_url=true to also receive a short-lived signed read URL (expires in 15 minutes).",
+        description: "Get file metadata. Response includes my_role ('owner' | 'editor' | 'viewer'), is_owner, owner (the member who owns it: { id, first_name, last_name, full_name, avatar_url, email }), sharing ('private' or 'workspace'), linked_records_count, linked_records[] and shared_with_teams[] (each entry has { team_id, team_name, role, granted_at }). Pass download_url=true to also receive a short-lived signed read URL (expires in 15 minutes). To read what the file SAYS, use lighthouse_documents_get_file_content.",
         inputSchema: {
             file_id: z.string().uuid().describe("File UUID"),
             download_url: z.boolean().optional().describe("Include a short-lived signed download URL"),
@@ -1590,6 +1631,39 @@ export function createServer(apiKey) {
             return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     });
+    server.registerTool("lighthouse_documents_get_file_content", {
+        title: "Read File",
+        description: "What one stored file SAYS, as text: PDFs, Word, Excel and PowerPoint files (and their OpenDocument versions), text, CSV and HTML. " +
+            "WHEN TO USE: the answer is inside a document the workspace keeps (\"what are the conditions in the term sheet\", \"summarise the memo on this deal\", \"what does the deck say about revenue\"). " +
+            "Take the file id from lighthouse_documents_list or lighthouse_documents_list_for_record. " +
+            "Returns the file's row (the one lighthouse_documents_get_file returns: id, name, folder_id, size_bytes, content_type, sharing, owner, ...) followed by kind, pages_total, text, reason and note. " +
+            FILE_CONTENT_RULES +
+            " A file the user may not open answers forbidden, one that does not exist not found.",
+        inputSchema: {
+            file_id: z.string().uuid().optional().describe("File UUID. The name every other file tool takes."),
+            id: z.string().uuid().optional().describe("Same as file_id. Send either one."),
+            offset_chars: z.number().min(0).default(0).describe("Character offset to start from (meta.next_offset_chars of the previous window)"),
+            max_chars: z.number().min(1).default(FILE_CONTENT_WINDOW_CHARS).describe("Characters per window"),
+        },
+    }, async (params) => {
+        try {
+            const fileId = requireId(params.file_id, params.id, "file_id");
+            const res = await api.get(`/v1/documents/files/${fileId}/content`, {
+                offset_chars: params.offset_chars,
+                max_chars: params.max_chars,
+            });
+            const imageType = viewableImageType(res, (data) => ({ contentType: data.content_type, size: data.size_bytes }));
+            if (!imageType)
+                return text(res);
+            const signed = await api.get(`/v1/documents/files/${fileId}`, { download_url: "1" });
+            const url = signed?.data?.download_url;
+            const image = typeof url === "string" ? await api.downloadSigned(url, IMAGE_BYTES_MAX) : null;
+            return textWithImage(res, image, imageType);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     server.registerTool("lighthouse_documents_update_file", {
         title: "Update File",
         description: "Rename, move, or change sharing on a file. Editors can rename/move-between-folders and delete; only the owner can move to root, change sharing, or grant team access. " +
@@ -2150,9 +2224,11 @@ export function createServer(apiKey) {
         description: "Get available location options (countries and regions) for discovery filters. " +
             "ALWAYS call this to get valid country/region values before filtering by location fields " +
             "(company_hq_country, company_hq_region, person_country, person_region, company_investor_country, etc.). " +
-            "Returns {countries: [{name, value, flag}], regions: [{name, value, flag}]}. " +
+            "Returns {countries: [{name, value, flag}], regions: [{name, value, flag}], registration_countries: [{name, value, flag}]}. " +
             "Use 'value' (alpha-2 codes for countries e.g. 'DE' for Germany, IDs for regions) " +
-            "in filter conditions with contains_any/not_contains_any operators.",
+            "in filter conditions with contains_any/not_contains_any operators. " +
+            "registration_countries are the countries whose company registers we read: the only values that can match person_registration_country " +
+            "and the registration_countries of the company_registration person signal, so any other country returns no people.",
         inputSchema: {},
     }, async () => {
         try {
@@ -2868,7 +2944,7 @@ export function createServer(apiKey) {
             "body (the full HTML, null when there is none), reply_to_message_id (the message this one answers, when the mailbox states it), " +
             "is_read, is_starred, attachments [{ id, message_id, type (image | video | audio | file | other), filename, content_type, size }], " +
             "inline_images (the files embedded in the body: the same keys plus cid), account { id, name, email, is_owner } }. Every key is always present. " +
-            "Read text when you need what was said and body only when the markup matters. " +
+            "Read text when you need what was said and body only when the markup matters. To read what an attached file SAYS, pass its id, its message_id and the message's account.id to lighthouse_inbox_email_attachment. " +
             "When the user can see only the metadata of that account, text and body are null, both file lists are empty and data.has_limited_access is true (false otherwise). Thread ids are " +
             "account-specific: BOTH thread_id AND account_id (the thread row's account.id from " +
             "lighthouse_inbox_email_threads) are required. " +
@@ -2899,6 +2975,38 @@ export function createServer(apiKey) {
             return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     });
+    server.registerTool("lighthouse_inbox_email_attachment", {
+        title: "Read Email Attachment",
+        description: "What one email attachment SAYS, as text: PDFs, Word, Excel and PowerPoint files (and their OpenDocument versions), text, CSV and HTML. " +
+            "WHEN TO USE: the user asks what an attached file contains (\"summarise the report Jane sent\", \"what are the numbers in the attached model\", \"check the attachment on that email\"). " +
+            "Find the message first: lighthouse_inbox_email_threads (a subject, a sender, a date), then lighthouse_inbox_email_thread, whose messages carry attachments [{ id, message_id, filename, ... }] and account { id }. Pass that attachment's id as attachment_id, its message_id, and the message's account.id as account_id. " +
+            "Returns { attachment { id, message_id, type, filename, content_type, size }, message { id, thread_id, subject }, account { id, name, email, is_owner }, kind, pages_total, text, reason, note }. " +
+            FILE_CONTENT_RULES +
+            " An attachment in an account the user may see only the metadata of answers not found.",
+        inputSchema: {
+            message_id: z.string().describe("The message_id on the attachment (the message that carries it)"),
+            attachment_id: z.string().describe("The attachment's id, from a message's attachments (or inline_images) in lighthouse_inbox_email_thread"),
+            account_id: z.string().uuid().describe("Required: the account.id of that message (attachment ids belong to one account)"),
+            offset_chars: z.number().min(0).default(0).describe("Character offset to start from (meta.next_offset_chars of the previous window)"),
+            max_chars: z.number().min(1).default(FILE_CONTENT_WINDOW_CHARS).describe("Characters per window"),
+        },
+    }, async ({ message_id, attachment_id, account_id, offset_chars, max_chars }) => {
+        try {
+            const path = `/inbox/email/messages/${encodeURIComponent(message_id)}/attachments/${encodeURIComponent(attachment_id)}`;
+            const res = await api.get(`${path}/content`, { account_id, offset_chars, max_chars });
+            const imageType = viewableImageType(res, (data) => {
+                const attachment = (data.attachment ?? {});
+                return { contentType: attachment.content_type, size: attachment.size };
+            });
+            if (!imageType)
+                return text(res);
+            const image = await api.download(path, { account_id }, IMAGE_BYTES_MAX);
+            return textWithImage(res, image, imageType);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     server.registerTool("lighthouse_inbox_email_create_draft", {
         title: "Create Email Draft",
         description: "Save an email draft in one of the user's mailboxes. The draft is NOT sent: it lands in the mailbox for the " +
@@ -3022,8 +3130,8 @@ export function createServer(apiKey) {
         description: "Calendars the API key's user can read: their own connected calendar (is_owner true) and colleagues' calendars shared with them. " +
             "The same account object the email and LinkedIn channels return: { id, name, email, is_owner, provider (google | microsoft | other), " +
             "status (connected | pending | disconnected), status_reason (credentials | error | stopped | other; null unless disconnected), " +
-            "owner, permissions { calendar_view }, created_at }. " +
-            "A calendar is the same connected account as a mailbox, behind its own sharing switch, so a mailbox shared for mail only is NOT listed here. " +
+            "owner, permissions { calendar_view, meeting_notes_view }, created_at }: calendar_view reads the calendar's meetings, meeting_notes_view reads the notes and transcripts of the meetings its owner recorded, including meetings the user was not invited to. " +
+            "A calendar is the same connected account as a mailbox, behind its own sharing switch, so a mailbox shared for mail only is NOT listed here, and neither is a calendar shared for meeting notes only: those notes come through the note tools, and each one's meeting.meeting_key opens its transcript. " +
             "Use scope 'me' to get only the user's own calendar: the SAME object, or null. " +
             "Use it to know whose meetings lighthouse_inbox_calendar_meetings can see, or to get an account_id to narrow that tool to one calendar. Returns [] when no calendar is connected.",
         inputSchema: {
@@ -3044,7 +3152,7 @@ export function createServer(apiKey) {
         description: "Calendar meetings across every calendar the API key's user can read (their own, plus colleagues' calendars shared with them), read live from the calendar. PAST meetings newest first by default (the last 6 months; pass months up to 36, or after / before, to move the window), or the SCHEDULED ones soonest first with upcoming=true (90 days ahead by default; an explicit before reaches further). " +
             "Narrow by CRM record (record_id + record_type, company or person: the record's addresses and domains are matched), by emails / domains lists (comma separated), by words in the meeting TITLE (query; never the notes), or by one calendar (account_id from lighthouse_inbox_calendar_accounts). No filter lists the user's whole calendar over the window. " +
             "WHEN TO USE: \"when did we last meet X\", \"what meetings do I have next week\", \"have we talked to anyone at acme.com\", \"which calls with this company were recorded\". To find what was DISCUSSED about a topic, list the meetings and read the notes of the likely ones. " +
-            "Each row: { id, meeting_key (only when the meeting was recorded), ical_uid, title, description, location, start, end, is_all_day, is_recurring (a recurring meeting appears once per occurrence), status (confirmed | tentative | cancelled | null), meeting_url (the video link), organizer { name, email }, attendees [{ name, email, response_status }] (everyone invited, the calendar's own account included; response_status is accepted | declined | tentative | needs_action, where needs_action means that attendee has not answered yet; a missing title, description, location, name or email is null, never an empty string), account { id, name, email, is_owner } (the calendar it was read from), recording: null when not recorded, else { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by }, the same object lighthouse_inbox_calendar_meeting returns (recorded_by is the recorder as a workspace member { id, first_name, last_name, full_name, avatar_url, email }, or null; has_notes is true only when notes are ready and the user may view notes) }. " +
+            "Each row: { id, meeting_key (only when the meeting was recorded), ical_uid, title, description, location, start, end, is_all_day, is_recurring (a recurring meeting appears once per occurrence), status (confirmed | tentative | cancelled | null), meeting_url (the video link), organizer { name, email }, attendees [{ name, email, response_status }] (everyone invited, the calendar's own account included; response_status is accepted | declined | tentative | needs_action, where needs_action means that attendee has not answered yet; a missing title, description, location, name or email is null, never an empty string), account { id, name, email, is_owner } (the calendar it was read from), recording: null when not recorded, else { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by }, the same object lighthouse_inbox_calendar_meeting returns (recorded_by is the recorder as a workspace member { id, first_name, last_name, full_name, avatar_url, email }, or null; has_notes is true only when notes are ready and the user may read them) }. " +
             "A row with meeting_key is a recorded meeting: pass it to lighthouse_inbox_calendar_meeting_notes for what was discussed and decided, or lighthouse_inbox_calendar_meeting_transcript for what was said. " +
             "Paged with a CURSOR: pass meta.next_cursor as cursor (same filters) while meta.has_more is true; the window is walked from its near end in 30-day steps, so the first page always holds the newest (or soonest) meetings. A date-only before includes that whole day. meta.window { after, before } is the window that was read. meta.accounts lists every calendar the user can see, one entry of { id, name, email, is_owner, ok, error, count } (a calendar that could not be read is ok false with its error code while the others are still read). meta.complete false means a step could not be fully scanned in time or a calendar failed: filter by record, emails or domains, or narrow the window. meta.note explains an empty or partial result (no calendar connected, a record with no addresses, a calendar that could not be read).",
         inputSchema: {
@@ -3074,10 +3182,10 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting", {
         title: "Get Recorded Meeting",
-        description: "One recorded meeting's metadata by meeting_key (from a row of lighthouse_inbox_calendar_meetings; a meeting note's meeting object carries no meeting_key): { meeting_key, ical_uid, title, occurred_at, meeting_url (the video link), recording { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by } (the same object the meetings list carries; recorded_by is the recorder as a workspace member, or null), notes { id, status, created_at }: the note lighthouse_inbox_calendar_meeting_notes returns, or null when there is none the user may read }. The title and the time are the same here as on the meetings list and inside the notes. " +
-            "WHEN TO USE: to check whether a transcript or notes exist before reading them, or to answer how long a call lasted. It never returns the transcript or the notes themselves. Not found when the meeting was not recorded or the API key's user cannot open its recording.",
+        description: "One recorded meeting's metadata by meeting_key (" + MEETING_KEY_SOURCES + "): { meeting_key, ical_uid, title, occurred_at, meeting_url (the video link), recording { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by } (the same object the meetings list carries; recorded_by is the recorder as a workspace member, or null), notes { id, status, created_at }: the note lighthouse_inbox_calendar_meeting_notes returns, or null when there is none the user may read }. The title and the time are the same here as on the meetings list and inside the notes. " +
+            "WHEN TO USE: to check whether a transcript or notes exist before reading them, or to answer how long a call lasted. It never returns the transcript or the notes themselves, and the API never returns the recording itself. Not found when the meeting was not recorded or the API key's user may not read it. A recurring meeting keeps the recording of its most recently recorded occurrence. " + MEETING_ACCESS_RULE,
         inputSchema: {
-            meeting_key: z.string().describe("The meeting_key of a recorded meeting"),
+            meeting_key: z.string().describe("The meeting_key of a recorded meeting, " + MEETING_KEY_SOURCES),
         },
     }, async (params) => {
         try {
@@ -3090,11 +3198,11 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting_notes", {
         title: "Get Meeting Notes",
-        description: "The meeting notes written from one recorded meeting, by meeting_key: the note in the same shape as lighthouse_crm_get_note (type 'meeting', with the meeting object and the records it is linked to), plus content_markdown (what was generated: Meeting Context first, then the sections) and is_edited (true when a member changed the note since, in which case content is the version to trust). " +
+        description: "The meeting notes written from one recorded meeting, by meeting_key (" + MEETING_KEY_SOURCES + "): the note in the same shape as lighthouse_crm_get_note (type 'meeting', with the meeting object and the records it is linked to), plus content_markdown (what was generated: Meeting Context first, then the sections) and is_edited (true when a member changed the note since, in which case content is the version to trust). " +
             "WHEN TO USE: the user asks what was discussed, decided or agreed in a specific meeting, the next steps from a call, or who attended. Lighter than the transcript: prefer it unless the answer depends on exactly what was said. " +
-            "Not found when the meeting has no notes yet (see has_notes on the meeting) or the API key's user cannot open its recording.",
+            "Not found when the meeting has no notes yet (see has_notes on the meeting) or the API key's user may not read them; for a recurring meeting the newest occurrence the user may read is returned. " + MEETING_ACCESS_RULE,
         inputSchema: {
-            meeting_key: z.string().describe("The meeting_key of a recorded meeting"),
+            meeting_key: z.string().describe("The meeting_key of a recorded meeting, " + MEETING_KEY_SOURCES),
         },
     }, async (params) => {
         try {
@@ -3107,12 +3215,12 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting_transcript", {
         title: "Get Meeting Transcript",
-        description: "The transcript of one recorded meeting by meeting_key, as text: one \"Speaker: text\" line per utterance, in order. " +
+        description: "The transcript of one recorded meeting by meeting_key (" + MEETING_KEY_SOURCES + "), as text: one \"Speaker: text\" line per utterance, in order. A note's meeting_key opens this transcript when that note's meeting.has_transcript is true. " +
             "WHEN TO USE: only when the answer depends on what was actually SAID (an exact quote, a number, who said what, a nuance the notes would flatten). For what was discussed or decided, lighthouse_inbox_calendar_meeting_notes is enough and far smaller. " +
             `A long meeting comes back in windows of max_chars (default ${TRANSCRIPT_WINDOW_CHARS}): meta.has_more true means the meeting continues past this window, so pass meta.next_offset_chars as offset_chars to read on, and never treat a window with has_more as the end of the meeting. ` +
-            "Not found when the meeting has no transcript or the API key's user cannot open its recording.",
+            "Not found when the meeting has no transcript or the API key's user may not read it. " + MEETING_ACCESS_RULE,
         inputSchema: {
-            meeting_key: z.string().describe("The meeting_key of a recorded meeting"),
+            meeting_key: z.string().describe("The meeting_key of a recorded meeting, " + MEETING_KEY_SOURCES),
             offset_chars: z.number().min(0).default(0).describe("Character offset to start from (meta.next_offset_chars of the previous window)"),
             max_chars: z.number().min(1).default(TRANSCRIPT_WINDOW_CHARS).describe("Characters per window"),
         },
@@ -3125,5 +3233,68 @@ export function createServer(apiKey) {
             return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     });
+    if (options.privateEquity !== true)
+        return server;
+    server.registerTool("lighthouse_private_equity_list_saved_searches", {
+        title: "List Private Equity Saved Searches",
+        description: "List the Private Equity saved searches the user can see in this workspace (their own, the ones shared with the workspace, and the ones shared with one of their teams), ordered by name. " +
+            "Each search carries id, name, sharing (private | workspace), shared_with_teams, is_owner, owner, created_at, updated_at, last_run_at and last_run: the stored run its results come from ({ id, created_at, last_fetched_at, result_count, match_count, created_by }, where result_count is how many companies are stored and match_count how many the search matched in the company database, or null), or null when it never ran. The search's filters are not returned. " +
+            "READ ONLY: this reads what the workspace already stored. It never runs a search, never fetches new companies and never spends credits; a Private Equity search is run, and paid for, only in the Lighthouse app. " +
+            "WHEN TO USE: the user asks which Private Equity searches exist, or names one whose results they want; pass its id to lighthouse_private_equity_list_saved_search_results. " +
+            "These are separate from the Discovery saved searches (lighthouse_discovery_list_saved_searches), which search a different database.",
+        inputSchema: {
+            offset: z.number().int().min(0).optional().describe("Number of saved searches to skip (default 0)"),
+            limit: z.number().int().min(1).max(100).optional().describe("Saved searches per page, 1 to 100 (default 25)"),
+        },
+    }, async ({ offset, limit }) => {
+        try {
+            const res = await api.get("/private-equity/saved-searches", { offset, limit });
+            return text(res);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.registerTool("lighthouse_private_equity_list_saved_search_results", {
+        title: "List Private Equity Saved Search Results",
+        description: "Read one page of the companies a Private Equity saved search's LAST run stored, in the order that run returned them. " +
+            "Each row is a stored company: id, name, domain, website_url, linkedin_url, short_description, avatar_url, hq ({ country, country_code, region, city }) and hq_label, industry, category, sector, naics ({ code, label }), business_models, employees and revenue_usd ({ value, estimated }), founded_year, company_type, num_locations, crm_id (the id of this workspace's CRM company for it, or null), lighthouse_company (the matching company in Lighthouse's own data, or null), from_lighthouse (the keys whose value was filled from Lighthouse's own data), fetched_at, profile_updated_at, and match ({ snippets, headline }: why a keyword or product search matched it, or null). " +
+            "meta carries total, limit, offset, has_more, has_results and run (the stored run the page is read from). A search that never ran, or whose last run is no longer stored, answers an empty page with meta.has_results false. " +
+            "READ ONLY: the rows are exactly what the search stored when someone last ran it in the app, even if its filters were edited since. This never runs the search again, never fetches more companies and never spends credits; for newer results, ask the user to run the search in the Lighthouse app. " +
+            "WHEN TO USE: the user asks what a Private Equity search found. Page with offset while meta.has_more is true. For one company's full stored profile use lighthouse_private_equity_get_company; when crm_id is set, lighthouse_crm_get_record (record_type 'company') opens the CRM company. " +
+            "Not found when the saved search does not exist or the user cannot see it.",
+        inputSchema: {
+            search_id: z.string().uuid().describe("Private Equity saved search ID (from lighthouse_private_equity_list_saved_searches)"),
+            offset: z.number().int().min(0).optional().describe("Number of companies to skip (default 0)"),
+            limit: z.number().int().min(1).max(100).optional().describe("Companies per page, 1 to 100 (default 25)"),
+        },
+    }, async ({ search_id, offset, limit }) => {
+        try {
+            const res = await api.get(`/private-equity/saved-searches/${encodeURIComponent(search_id)}/results`, { offset, limit });
+            return text(res);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.registerTool("lighthouse_private_equity_get_company", {
+        title: "Get Private Equity Company",
+        description: "Read one company's stored Private Equity profile by company_id: the id of a row returned by lighthouse_private_equity_list_saved_search_results (a text id, not a UUID, and not a Discovery or CRM id). " +
+            "Returns the keys of a results row (without match) plus the full profile: legal_names, commercial_names, long_description, long_description_extracted, locations, classification ({ naics_secondary, nace, sic, isic }), target_markets, core_offerings, technology_focus, certification_focus, supply_chain_focus, business_tags, technologies and technologies_total, contact ({ primary_phone, phone_numbers, primary_email, emails }), socials, website_language, profile_created_at, is_fresh and run_count. " +
+            "READ ONLY: the profile as a Private Equity search of this workspace stored it, never refreshed. It never fetches the company again and never spends credits. " +
+            "WHEN TO USE: the user asks for details on one company from a Private Equity search's results. When crm_id is set, lighthouse_crm_get_record (record_type 'company') opens the CRM company. " +
+            "Not found when none of this workspace's Private Equity searches returned that company.",
+        inputSchema: {
+            company_id: z.string().min(1).describe("The company's id, as a row of lighthouse_private_equity_list_saved_search_results gives it"),
+        },
+    }, async ({ company_id }) => {
+        try {
+            const res = await api.get(`/private-equity/companies/${encodeURIComponent(company_id)}`);
+            return text(res);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylighthouse/mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.6",
   "description": "MCP server for the Lighthouse CRM API",
   "homepage": "https://trylighthouse.vc",
   "type": "module",
@@ -20,6 +20,7 @@
   "scripts": {
     "build": "rm -rf build && tsc && chmod 755 build/index.js && node scripts/check-no-comments.mjs",
     "dev": "tsc --watch",
+    "test": "node --test test/*.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {