@mindstone-engineering/mcp-server-fathom 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Fathom authentication module.
+ *
+ * Manages the API key lifecycle — env var on startup, runtime update via
+ * configure tool, and bridge integration for host-app credential management.
+ */
+/**
+ * Returns the current API key.
+ */
+export declare function getApiKey(): string;
+/**
+ * Returns true if an API key is configured.
+ */
+export declare function isConfigured(): boolean;
+/**
+ * Update the API key at runtime (e.g. after configure_fathom_api_key).
+ */
+export declare function setApiKey(key: string): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,26 @@
+/**
+ * Fathom authentication module.
+ *
+ * Manages the API key lifecycle — env var on startup, runtime update via
+ * configure tool, and bridge integration for host-app credential management.
+ */
+let apiKey = process.env.FATHOM_API_KEY || '';
+/**
+ * Returns the current API key.
+ */
+export function getApiKey() {
+    return apiKey;
+}
+/**
+ * Returns true if an API key is configured.
+ */
+export function isConfigured() {
+    return apiKey.length > 0;
+}
+/**
+ * Update the API key at runtime (e.g. after configure_fathom_api_key).
+ */
+export function setApiKey(key) {
+    apiKey = key;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fathom API HTTP client.
+ *
+ * Centralises X-Api-Key header injection, error handling, and rate-limit
+ * messaging for all Fathom API calls.
+ */
+/**
+ * Make an authenticated request to the Fathom API.
+ *
+ * @param path  API path relative to base, e.g. `/meetings`
+ * @param options  Additional fetch options
+ * @returns Parsed JSON response
+ */
+export declare function fathomFetch<T>(path: string, options?: RequestInit): Promise<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,57 @@
+/**
+ * Fathom API HTTP client.
+ *
+ * Centralises X-Api-Key header injection, error handling, and rate-limit
+ * messaging for all Fathom API calls.
+ */
+import { getApiKey } from './auth.js';
+import { FathomError, FATHOM_API_BASE, REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Make an authenticated request to the Fathom API.
+ *
+ * @param path  API path relative to base, e.g. `/meetings`
+ * @param options  Additional fetch options
+ * @returns Parsed JSON response
+ */
+export async function fathomFetch(path, options = {}) {
+    const key = getApiKey();
+    if (!key) {
+        throw new FathomError('Fathom API key not configured', 'AUTH_REQUIRED', 'Use configure_fathom_api_key to set your API key first.');
+    }
+    const url = `${FATHOM_API_BASE}${path}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                'X-Api-Key': key,
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new FathomError('Request to Fathom API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Fathom API is available.');
+        }
+        throw error;
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new FathomError('Authentication failed', 'AUTH_FAILED', 'Your Fathom API key is invalid or revoked. Use configure_fathom_api_key to set a new key.');
+    }
+    if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        const waitTime = retryAfter ? `${retryAfter} seconds` : 'a moment';
+        throw new FathomError(`Rate limited by Fathom API. Please wait ${waitTime} before retrying.`, 'RATE_LIMITED', `Wait ${waitTime} and try again. Fathom limits API requests to 60 calls per minute.`);
+    }
+    if (response.status === 404) {
+        throw new FathomError('Resource not found', 'NOT_FOUND', 'The requested resource does not exist or you do not have permission to access it.');
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'Unknown error');
+        throw new FathomError(`Fathom API error (${response.status}): ${errorText}`, 'API_ERROR', 'Check the request parameters and try again.');
+    }
+    return response.json();
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Fathom MCP Server
+ *
+ * Provides Fathom AI meeting transcription integration via Model Context Protocol.
+ *
+ * Environment variables:
+ * - FATHOM_API_KEY: User's Fathom API key — required for all operations
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * Fathom MCP Server
+ *
+ * Provides Fathom AI meeting transcription integration via Model Context Protocol.
+ *
+ * Environment variables:
+ * - FATHOM_API_KEY: User's Fathom API key — required for all operations
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Fathom MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerMeetingTools, registerTeamTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'fathom-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerMeetingTools(server);
+    registerTeamTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { setApiKey } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { FathomError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_fathom_api_key', {
+        description: 'Configure the Fathom API key. Call this tool when the user provides their Fathom API key. ' +
+            'Get your API key from https://fathom.video/customize#api-access-header — ' +
+            'click "Add +", select "Generate API Key", name it "Mindstone Rebel".',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('The Fathom API key'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const trimmedKey = args.api_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/fathom/configure', { apiKey: trimmedKey });
+                if (result.success) {
+                    setApiKey(trimmedKey);
+                    const message = result.warning
+                        ? `Fathom API key configured successfully. Note: ${result.warning}`
+                        : 'Fathom API key configured successfully! You can now use list_fathom_meetings to access your meeting transcripts.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new FathomError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof FathomError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new FathomError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge configured — configure in-memory only
+        setApiKey(trimmedKey);
+        return JSON.stringify({
+            ok: true,
+            message: 'Fathom API key configured successfully! You can now use list_fathom_meetings to access your meeting transcripts.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerMeetingTools } from './meetings.js';
+export { registerTeamTools } from './teams.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerMeetingTools } from './meetings.js';
+export { registerTeamTools } from './teams.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/meetings.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerMeetingTools(server: McpServer): void;
+//# sourceMappingURL=meetings.d.ts.map

package/dist/tools/meetings.js

@@ -0,0 +1,283 @@
+import { z } from 'zod';
+import { fathomFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+import { FathomError, } from '../types.js';
+function noApiKeyError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Fathom API key not configured',
+        resolution: 'To use Fathom, you need to configure an API key first.',
+        next_step: {
+            action: 'Ask the user for their Fathom API key, then call configure_fathom_api_key',
+            tool_to_call: 'configure_fathom_api_key',
+            tool_parameters: { api_key: '<user_provided_key>' },
+            get_key_from: 'https://fathom.video/customize#api-access-header',
+        },
+    });
+}
+/**
+ * Find a meeting by its recording ID by scanning through list pages.
+ * Fathom API does not have a GET /meetings/{id} endpoint.
+ */
+async function findMeetingByRecordingId(recordingId, maxPages = 10) {
+    let cursor;
+    let pageCount = 0;
+    do {
+        const path = cursor
+            ? `/meetings?cursor=${encodeURIComponent(cursor)}`
+            : '/meetings';
+        const response = await fathomFetch(path);
+        pageCount++;
+        const found = response.items.find((item) => item.recording_id === recordingId);
+        if (found)
+            return found;
+        cursor = response.next_cursor || undefined;
+    } while (cursor && pageCount < maxPages);
+    return null;
+}
+function formatTimestamp(entry) {
+    if (entry.timestamp)
+        return entry.timestamp;
+    if (entry.start_time !== undefined) {
+        const totalSeconds = Math.floor(entry.start_time);
+        const hours = Math.floor(totalSeconds / 3600);
+        const minutes = Math.floor((totalSeconds % 3600) / 60);
+        const seconds = totalSeconds % 60;
+        return `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
+    }
+    return '00:00:00';
+}
+function getSpeakerName(entry) {
+    const speaker = entry.speaker;
+    if (!speaker)
+        return 'Unknown';
+    return speaker.display_name || speaker.name || speaker.matched_calendar_invitee_email || speaker.email || 'Unknown';
+}
+export function registerMeetingTools(server) {
+    server.registerTool('list_fathom_meetings', {
+        description: `List meetings from Fathom with server-side filtering.
+
+Returns meeting metadata including:
+- recording_id: Primary identifier for get_fathom_meeting and get_fathom_transcript
+- title, scheduled_start_time, duration
+- calendar_invitees: Array of attendees with name/email
+- teams: Teams the meeting belongs to
+
+Server-side filters (use these to narrow results efficiently):
+- teams: Filter by team names
+- recorded_by: Filter by recorder email addresses  
+- calendar_invitees_domains: Filter by attendee email domains (e.g., find all meetings with acme.com)
+- meeting_type: 'internal' (same org) or 'external' (with outsiders)
+- created_after/created_before: Date range filters (ISO format)
+
+NOTE: Fathom does NOT have server-side keyword search. To find meetings by keyword, list meetings with filters then examine results yourself, or use get_fathom_transcript to search transcript content.
+
+Pagination: Returns up to 'limit' results (default 25). hasMore=true indicates more pages exist.
+Rate limit: Fathom allows ~60 API calls/minute.`,
+        inputSchema: z.object({
+            teams: z.array(z.string()).optional().describe('Filter by team names (e.g., ["Sales", "Engineering"])'),
+            recorded_by: z.array(z.string()).optional().describe('Filter by email addresses of recorders'),
+            calendar_invitees_domains: z.array(z.string()).optional().describe('Filter by attendee email domains'),
+            meeting_type: z.enum(['all', 'internal', 'external']).optional().describe('Filter by meeting type'),
+            created_after: z.string().optional().describe('ISO date string — only return meetings created after this date'),
+            created_before: z.string().optional().describe('ISO date string — only return meetings created before this date'),
+            limit: z.number().min(1).max(100).default(25).describe('Maximum number of results per page'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const limit = args.limit;
+        const meetings = [];
+        let stoppedEarly = false;
+        // Build query string from filters
+        const params = new URLSearchParams();
+        if (args.teams)
+            args.teams.forEach((t) => params.append('teams[]', t));
+        if (args.recorded_by)
+            args.recorded_by.forEach((r) => params.append('recorded_by[]', r));
+        if (args.calendar_invitees_domains) {
+            args.calendar_invitees_domains.forEach((d) => params.append('calendar_invitees_domains[]', d));
+        }
+        if (args.meeting_type)
+            params.set('meeting_type', args.meeting_type);
+        if (args.created_after)
+            params.set('created_after', args.created_after);
+        if (args.created_before)
+            params.set('created_before', args.created_before);
+        let cursor;
+        do {
+            if (cursor)
+                params.set('cursor', cursor);
+            const qs = params.toString();
+            const path = qs ? `/meetings?${qs}` : '/meetings';
+            const response = await fathomFetch(path);
+            meetings.push(...response.items);
+            cursor = response.next_cursor || undefined;
+            if (meetings.length > limit) {
+                stoppedEarly = true;
+                break;
+            }
+        } while (cursor);
+        const trimmedMeetings = meetings.slice(0, limit);
+        const hasMore = stoppedEarly || meetings.length > limit;
+        return JSON.stringify({
+            ok: true,
+            meetings: trimmedMeetings,
+            count: trimmedMeetings.length,
+            hasMore,
+            ...(hasMore ? { hint: `Showing first ${limit} results. Increase limit parameter for more.` } : {}),
+        });
+    }));
+    server.registerTool('get_fathom_meeting', {
+        description: `Get details for a single Fathom meeting by its recording_id.
+
+Finds the meeting in your recent history and fetches its AI-generated summary.
+
+Returns:
+- Meeting title, scheduled times, duration
+- Recording URL and shareable link
+- Calendar invitees with names/emails
+- AI-generated summary (if available)
+
+Note: Searches through up to 10 pages of recent meetings. For older meetings,
+use list_fathom_meetings with created_after/created_before date filters first.
+
+For transcript content, use get_fathom_transcript separately.
+Rate limit: May use 1-11 API calls depending on meeting position in history.`,
+        inputSchema: z.object({
+            recording_id: z.number().int().positive().describe('The recording ID of the meeting (from list_fathom_meetings)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const recordingId = args.recording_id;
+        const meeting = await findMeetingByRecordingId(recordingId);
+        if (!meeting) {
+            return JSON.stringify({
+                ok: false,
+                error: 'Meeting not found',
+                recordingId,
+                resolution: 'The meeting may not exist, may not be accessible, or may be older than the search limit. ' +
+                    'Try list_fathom_meetings with created_after/created_before date filters to find older meetings.',
+            });
+        }
+        // Fetch summary via dedicated endpoint
+        let summary = meeting.default_summary || null;
+        if (!summary) {
+            try {
+                const summaryResponse = await fathomFetch(`/recordings/${recordingId}/summary`);
+                if (summaryResponse?.summary) {
+                    summary = {
+                        template_name: summaryResponse.summary.template_name,
+                        markdown_formatted: summaryResponse.summary.markdown_formatted,
+                    };
+                }
+            }
+            catch (err) {
+                // Re-throw rate limit errors; swallow not-found (summary may not exist yet)
+                if (err instanceof FathomError && err.code === 'RATE_LIMITED')
+                    throw err;
+                summary = null;
+            }
+        }
+        return JSON.stringify({
+            ok: true,
+            meeting: {
+                title: meeting.title,
+                meeting_title: meeting.meeting_title,
+                recording_id: meeting.recording_id,
+                url: meeting.url,
+                share_url: meeting.share_url,
+                created_at: meeting.created_at,
+                scheduled_start_time: meeting.scheduled_start_time,
+                scheduled_end_time: meeting.scheduled_end_time,
+                recording_start_time: meeting.recording_start_time,
+                recording_end_time: meeting.recording_end_time,
+                calendar_invitees: meeting.calendar_invitees,
+                recorded_by: meeting.recorded_by,
+                summary,
+            },
+        });
+    }));
+    server.registerTool('get_fathom_transcript', {
+        description: `Get the transcript for a Fathom meeting by its recording_id.
+
+Output formats (use 'format' parameter):
+- "text" (default): Human-readable format: "[HH:MM:SS] Speaker Name: What they said"
+- "json": Compact JSON array with full metadata (speaker object, timestamps, text)
+
+Filtering options to reduce output size:
+- search_query: Case-insensitive search — returns only matching lines plus context
+- max_entries: Limit number of transcript entries returned
+- start_entry: Skip first N entries (for pagination)
+
+For large transcripts, use search_query to find relevant sections rather than fetching everything.
+Rate limit: Counts as 1 API call (Fathom allows ~60/minute).
+Use list_fathom_meetings first to find the recording_id.`,
+        inputSchema: z.object({
+            recording_id: z.number().int().positive().describe('The recording ID of the meeting (from list_fathom_meetings)'),
+            format: z.enum(['text', 'json']).default('text').describe('Output format: "text" (default) or "json"'),
+            search_query: z.string().optional().describe('Case-insensitive search query — returns only matching entries plus context'),
+            max_entries: z.number().int().positive().optional().describe('Maximum number of transcript entries to return'),
+            start_entry: z.number().int().min(0).default(0).describe('Skip first N entries (0-indexed)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const response = await fathomFetch(`/recordings/${args.recording_id}/transcript`);
+        let entries = response.transcript || [];
+        const totalCount = entries.length;
+        // Apply search filter if provided
+        let matchedIndices = null;
+        let directMatchCount = 0;
+        if (args.search_query) {
+            const query = args.search_query.toLowerCase();
+            matchedIndices = new Set();
+            entries.forEach((entry, idx) => {
+                if (entry.text.toLowerCase().includes(query)) {
+                    directMatchCount++;
+                    for (let i = Math.max(0, idx - 2); i <= Math.min(entries.length - 1, idx + 2); i++) {
+                        matchedIndices.add(i);
+                    }
+                }
+            });
+            entries = entries.filter((_, idx) => matchedIndices.has(idx));
+        }
+        // Apply pagination
+        if (args.start_entry > 0) {
+            entries = entries.slice(args.start_entry);
+        }
+        if (args.max_entries !== undefined) {
+            entries = entries.slice(0, args.max_entries);
+        }
+        const hasMore = args.start_entry + entries.length < (matchedIndices ? matchedIndices.size : totalCount);
+        if (args.format === 'json') {
+            return JSON.stringify({
+                ok: true,
+                transcript: entries,
+                count: entries.length,
+                totalCount,
+                hasMore,
+                ...(args.search_query
+                    ? { searchQuery: args.search_query, directMatches: directMatchCount, entriesWithContext: matchedIndices?.size || 0 }
+                    : {}),
+            });
+        }
+        // Text format (default)
+        const lines = entries.map((entry) => {
+            const timestamp = formatTimestamp(entry);
+            const speaker = getSpeakerName(entry);
+            const text = entry.text.replace(/[\r\n]+/g, ' ');
+            return `[${timestamp}] ${speaker}: ${text}`;
+        });
+        const header = args.search_query
+            ? `Transcript: ${directMatchCount} matches for "${args.search_query}" (showing ${entries.length} entries with context, ${totalCount} total in transcript)`
+            : `Transcript (${entries.length} of ${totalCount} entries)`;
+        return `${header}${hasMore ? ' - more available with start_entry parameter' : ''}\n\n${lines.join('\n')}`;
+    }));
+}
+//# sourceMappingURL=meetings.js.map

package/dist/tools/teams.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTeamTools(server: McpServer): void;
+//# sourceMappingURL=teams.d.ts.map

package/dist/tools/teams.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { fathomFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function noApiKeyError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Fathom API key not configured',
+        resolution: 'Use configure_fathom_api_key to set your API key first.',
+    });
+}
+export function registerTeamTools(server) {
+    server.registerTool('list_fathom_teams', {
+        description: `List all teams accessible to the user in Fathom.
+
+Returns teams with:
+- name: Team name (use for filtering meetings or listing members)
+- created_at: When the team was created (if available)
+
+Use this to find team names for filtering meetings with list_fathom_meetings or listing team members with list_fathom_team_members.`,
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const allTeams = [];
+        let cursor;
+        do {
+            const path = cursor ? `/teams?cursor=${encodeURIComponent(cursor)}` : '/teams';
+            const response = await fathomFetch(path);
+            const items = response.items || [];
+            for (const item of items) {
+                if (typeof item === 'string') {
+                    allTeams.push({ name: item });
+                }
+                else {
+                    allTeams.push(item);
+                }
+            }
+            cursor = response.next_cursor || undefined;
+        } while (cursor);
+        return JSON.stringify({ ok: true, teams: allTeams, count: allTeams.length });
+    }));
+    server.registerTool('list_fathom_team_members', {
+        description: `List members of a specific team in Fathom.
+
+Returns team members with:
+- User ID and email
+- Name and role
+- Join date
+
+Use list_fathom_teams first to get available team names.`,
+        inputSchema: z.object({
+            team: z.string().min(1).describe('Team name to list members for (from list_fathom_teams)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const members = [];
+        let cursor;
+        do {
+            const teamParam = encodeURIComponent(args.team);
+            const cursorParam = cursor ? `&cursor=${encodeURIComponent(cursor)}` : '';
+            const path = `/team_members?team=${teamParam}${cursorParam}`;
+            const response = await fathomFetch(path);
+            members.push(...(response.items || []));
+            cursor = response.next_cursor || undefined;
+        } while (cursor);
+        return JSON.stringify({ ok: true, teamMembers: members, count: members.length });
+    }));
+}
+//# sourceMappingURL=teams.js.map

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const FATHOM_API_BASE = "https://api.fathom.ai/external/v1";
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class FathomError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export interface TranscriptEntry {
+    speaker: {
+        name?: string;
+        display_name?: string;
+        email?: string;
+        matched_calendar_invitee_email?: string;
+    };
+    start_time?: number;
+    end_time?: number;
+    timestamp?: string;
+    text: string;
+}
+export interface TranscriptResponse {
+    transcript: TranscriptEntry[];
+}
+export interface MeetingItem {
+    title: string;
+    meeting_title: string | null;
+    recording_id: number;
+    url: string;
+    share_url: string;
+    created_at: string;
+    scheduled_start_time: string;
+    scheduled_end_time: string;
+    recording_start_time: string;
+    recording_end_time: string;
+    calendar_invitees_domains_type: string;
+    transcript_language: string;
+    calendar_invitees: Array<{
+        name?: string;
+        email: string;
+        email_domain?: string;
+        is_external?: boolean;
+    }>;
+    recorded_by: {
+        name?: string;
+        email: string;
+        email_domain?: string;
+        team?: string | null;
+    };
+    default_summary?: {
+        template_name?: string;
+        markdown_formatted?: string;
+    } | null;
+    action_items?: Array<{
+        description: string;
+        user_generated?: boolean;
+        completed?: boolean;
+        recording_timestamp?: string;
+        assignee?: {
+            name?: string;
+            email?: string;
+        };
+    }> | null;
+}
+export interface MeetingsListResponse {
+    limit: number;
+    next_cursor: string | null;
+    items: MeetingItem[];
+}
+export interface TeamItem {
+    name: string;
+    created_at?: string | null;
+}
+export interface TeamsResponse {
+    limit: number;
+    next_cursor: string | null;
+    items: (TeamItem | string)[];
+}
+export interface TeamMembersResponse {
+    limit: number;
+    next_cursor: string | null;
+    items: Array<{
+        id?: string;
+        email?: string;
+        name?: string;
+        role?: string;
+        joined_at?: string;
+    }>;
+}
+export interface SummaryResponse {
+    summary: {
+        template_name?: string;
+        markdown_formatted?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,13 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const FATHOM_API_BASE = 'https://api.fathom.ai/external/v1';
+export class FathomError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'FathomError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On FathomError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { FathomError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On FathomError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof FathomError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mindstone-engineering/mcp-server-fathom",
+  "version": "0.1.0",
+  "description": "Fathom AI meeting transcription MCP server for Model Context Protocol hosts",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-fathom": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/fathom"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/fathom",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "fathom-typescript": "^0.0.37",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}