fellow-mcp 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,228 @@
+# Fellow MCP Server
+
+A local MCP (Model Context Protocol) server that wraps the Fellow.ai API, providing tools to access meeting data, transcripts, summaries, action items, and participants.
+
+**Features:**
+- Local SQLite database for caching meeting data
+- Automatic incremental sync to keep action items fresh
+- Full-text search across cached notes
+- Find meetings by participant
+
+## Installation
+
+### Option 1: Install from npm (Recommended)
+
+```bash
+npm install -g fellow-mcp
+```
+
+### Option 2: Install from source
+
+```bash
+git clone https://github.com/liba2k/fellow-mcp.git
+cd fellow-mcp
+npm install
+npm run build
+```
+
+## Setup
+
+### 1. Get your Fellow API credentials
+
+1. Log into your Fellow account
+2. Navigate to Developer API settings in your User settings
+3. Generate a new API key
+4. Note your workspace subdomain (the part before `.fellow.app` in your URL)
+
+### 2. Configure your MCP client
+
+#### If installed via npm:
+
+Add the following to your MCP client configuration (e.g., `~/.config/opencode/opencode.json`):
+
+```json
+{
+  "mcp": {
+    "fellow": {
+      "type": "local",
+      "command": ["fellow-mcp"],
+      "env": {
+        "FELLOW_API_KEY": "your-api-key-here",
+        "FELLOW_SUBDOMAIN": "your-subdomain"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+#### If installed from source:
+
+Option A: Use the run.sh script with .env file:
+
+1. Copy the example env file and fill in your credentials:
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env` with your credentials:
+```
+FELLOW_API_KEY=your-api-key-here
+FELLOW_SUBDOMAIN=your-subdomain
+```
+
+3. Configure your MCP client:
+```json
+{
+  "mcp": {
+    "fellow": {
+      "type": "local",
+      "command": ["/path/to/fellow-mcp/run.sh"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Option B: Pass environment variables directly:
+```json
+{
+  "mcp": {
+    "fellow": {
+      "type": "local",
+      "command": ["node", "/path/to/fellow-mcp/dist/index.js"],
+      "env": {
+        "FELLOW_API_KEY": "your-api-key-here",
+        "FELLOW_SUBDOMAIN": "your-subdomain"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+## Available Tools
+
+### API Tools (Direct Fellow API calls)
+
+#### `search_meetings`
+Search for meetings/recordings in Fellow.
+
+**Parameters:**
+- `title` (optional): Filter by meeting title (case-insensitive partial match)
+- `created_at_start` (optional): Filter meetings created after this date (ISO format)
+- `created_at_end` (optional): Filter meetings created before this date (ISO format)
+- `limit` (optional): Maximum number of results (1-50, default 20)
+
+#### `get_meeting_transcript`
+Get the full transcript of a meeting recording with speaker labels and timestamps.
+
+**Parameters:**
+- `recording_id` (optional): The ID of the recording
+- `meeting_title` (optional): Search by meeting title
+
+#### `get_meeting_summary`
+Get the meeting summary/notes content including agenda items, discussion topics, and decisions.
+
+**Parameters:**
+- `note_id` (optional): The ID of the note
+- `recording_id` (optional): Get the summary for a recording's associated note
+- `meeting_title` (optional): Search by meeting title
+
+#### `get_action_items`
+Extract action items from a single meeting's notes.
+
+**Parameters:**
+- `note_id` (optional): The ID of the note
+- `meeting_title` (optional): Search by meeting title
+
+#### `get_meeting_participants`
+Get the list of participants/attendees for a meeting.
+
+**Parameters:**
+- `note_id` (optional): The ID of the note
+- `meeting_title` (optional): Search by meeting title
+
+### Database Tools (Local SQLite cache)
+
+#### `sync_meetings`
+Sync meetings from Fellow API to local database.
+
+**Parameters:**
+- `force` (optional, default: false): If true, performs full re-sync. Otherwise does incremental sync (only new/updated since last sync)
+- `include_transcripts` (optional, default: false): If true, also fetches and stores transcripts (slower)
+
+#### `get_all_action_items`
+Get all action items from the local database. **Automatically performs incremental sync first** to ensure data is fresh.
+
+**Parameters:**
+- `assignee` (optional): Filter by assignee name (partial match)
+- `show_completed` (optional, default: false): If true, includes completed action items
+- `since` (optional): Only return action items from meetings on or after this date (ISO format: YYYY-MM-DD)
+
+#### `get_meetings_by_participants`
+Find meetings that included specific participants.
+
+**Parameters:**
+- `emails` (required): List of email addresses to search for
+- `require_all` (optional, default: false): If true, only return meetings where ALL specified participants attended
+
+#### `search_cached_notes`
+Full-text search across all cached meeting notes (titles and content).
+
+**Parameters:**
+- `query` (required): Search query
+
+#### `get_sync_status`
+Get the current sync status and database statistics.
+
+## Local Database
+
+Meeting data is cached in a local SQLite database at `~/.fellow-mcp/fellow.db`. This enables:
+
+- Fast local searches
+- Querying across all action items
+- Finding meetings by participant
+- Offline access to cached data
+
+The database stores:
+- Notes (meeting summaries, agendas, content)
+- Recordings (with optional transcripts)
+- Action items (parsed from notes with assignee/due date extraction)
+- Participants (email addresses)
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FELLOW_API_KEY` | Yes | Your Fellow API key |
+| `FELLOW_SUBDOMAIN` | Yes | Your Fellow workspace subdomain |
+
+## Development
+
+```bash
+# Watch mode for development
+npm run dev
+
+# Build
+npm run build
+
+# Test the server
+node dist/index.js --test
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- A Fellow.ai account with API access
+
+## License
+
+MIT
+
+## API Reference
+
+This MCP server wraps the [Fellow Developer API](https://developers.fellow.ai/reference/introduction). The API uses:
+- `X-API-KEY` header for authentication
+- POST requests for list operations (with JSON body for filters/pagination)
+- GET requests for retrieving individual resources

package/dist/database.d.ts

@@ -0,0 +1,76 @@
+export interface StoredNote {
+    id: string;
+    title: string;
+    created_at: string;
+    updated_at: string;
+    event_start: string | null;
+    event_end: string | null;
+    event_guid: string | null;
+    call_url: string | null;
+    content_markdown: string | null;
+    synced_at: string;
+}
+export interface StoredRecording {
+    id: string;
+    note_id: string;
+    title: string;
+    created_at: string;
+    updated_at: string;
+    event_start: string | null;
+    event_end: string | null;
+    recording_start: string | null;
+    recording_end: string | null;
+    event_guid: string | null;
+    call_url: string | null;
+    transcript_json: string | null;
+    synced_at: string;
+}
+export interface StoredActionItem {
+    id: number;
+    note_id: string;
+    content: string;
+    assignee: string | null;
+    due_date: string | null;
+    is_completed: boolean;
+    created_at: string;
+}
+export interface StoredParticipant {
+    id: number;
+    note_id: string;
+    email: string;
+}
+export declare class FellowDatabase {
+    private db;
+    constructor(dbPath?: string);
+    private initSchema;
+    upsertNote(note: Omit<StoredNote, "synced_at">): void;
+    getNote(id: string): StoredNote | null;
+    getAllNotes(): StoredNote[];
+    searchNotes(query: string): StoredNote[];
+    upsertRecording(recording: Omit<StoredRecording, "synced_at">): void;
+    getRecording(id: string): StoredRecording | null;
+    clearActionItemsForNote(noteId: string): void;
+    insertActionItem(item: Omit<StoredActionItem, "id">): void;
+    getAllActionItems(filters?: {
+        assignee?: string;
+        is_completed?: boolean;
+        since?: string;
+    }): (StoredActionItem & {
+        note_title: string;
+        event_start: string | null;
+    })[];
+    clearParticipantsForNote(noteId: string): void;
+    insertParticipant(noteId: string, email: string): void;
+    getMeetingsByParticipants(emails: string[]): StoredNote[];
+    getMeetingsWithAllParticipants(emails: string[]): StoredNote[];
+    getParticipantsForNote(noteId: string): string[];
+    getLastSyncTime(): string | null;
+    setLastSyncTime(time: string): void;
+    getStats(): {
+        notes: number;
+        recordings: number;
+        action_items: number;
+        participants: number;
+    };
+    close(): void;
+}

package/dist/database.js

@@ -0,0 +1,244 @@
+import Database from "better-sqlite3";
+import path from "path";
+import os from "os";
+import fs from "fs";
+export class FellowDatabase {
+    db;
+    constructor(dbPath) {
+        const defaultPath = path.join(os.homedir(), ".fellow-mcp", "fellow.db");
+        const finalPath = dbPath ?? defaultPath;
+        // Ensure directory exists
+        const dir = path.dirname(finalPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        this.db = new Database(finalPath);
+        this.db.pragma("journal_mode = WAL");
+        this.initSchema();
+    }
+    initSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS notes (
+        id TEXT PRIMARY KEY,
+        title TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        event_start TEXT,
+        event_end TEXT,
+        event_guid TEXT,
+        call_url TEXT,
+        content_markdown TEXT,
+        synced_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS recordings (
+        id TEXT PRIMARY KEY,
+        note_id TEXT,
+        title TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        event_start TEXT,
+        event_end TEXT,
+        recording_start TEXT,
+        recording_end TEXT,
+        event_guid TEXT,
+        call_url TEXT,
+        transcript_json TEXT,
+        synced_at TEXT NOT NULL,
+        FOREIGN KEY (note_id) REFERENCES notes(id)
+      );
+
+      CREATE TABLE IF NOT EXISTS action_items (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        note_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        assignee TEXT,
+        due_date TEXT,
+        is_completed INTEGER DEFAULT 0,
+        created_at TEXT NOT NULL,
+        FOREIGN KEY (note_id) REFERENCES notes(id)
+      );
+
+      CREATE TABLE IF NOT EXISTS participants (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        note_id TEXT NOT NULL,
+        email TEXT NOT NULL,
+        FOREIGN KEY (note_id) REFERENCES notes(id),
+        UNIQUE(note_id, email)
+      );
+
+      CREATE TABLE IF NOT EXISTS sync_status (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_notes_event_start ON notes(event_start);
+      CREATE INDEX IF NOT EXISTS idx_notes_title ON notes(title);
+      CREATE INDEX IF NOT EXISTS idx_recordings_note_id ON recordings(note_id);
+      CREATE INDEX IF NOT EXISTS idx_action_items_note_id ON action_items(note_id);
+      CREATE INDEX IF NOT EXISTS idx_action_items_assignee ON action_items(assignee);
+      CREATE INDEX IF NOT EXISTS idx_participants_note_id ON participants(note_id);
+      CREATE INDEX IF NOT EXISTS idx_participants_email ON participants(email);
+    `);
+    }
+    // Notes
+    upsertNote(note) {
+        const stmt = this.db.prepare(`
+      INSERT INTO notes (id, title, created_at, updated_at, event_start, event_end, event_guid, call_url, content_markdown, synced_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        title = excluded.title,
+        updated_at = excluded.updated_at,
+        event_start = excluded.event_start,
+        event_end = excluded.event_end,
+        event_guid = excluded.event_guid,
+        call_url = excluded.call_url,
+        content_markdown = COALESCE(excluded.content_markdown, content_markdown),
+        synced_at = excluded.synced_at
+    `);
+        stmt.run(note.id, note.title, note.created_at, note.updated_at, note.event_start, note.event_end, note.event_guid, note.call_url, note.content_markdown, new Date().toISOString());
+    }
+    getNote(id) {
+        const stmt = this.db.prepare("SELECT * FROM notes WHERE id = ?");
+        return stmt.get(id);
+    }
+    getAllNotes() {
+        const stmt = this.db.prepare("SELECT * FROM notes ORDER BY event_start DESC");
+        return stmt.all();
+    }
+    searchNotes(query) {
+        const stmt = this.db.prepare(`
+      SELECT * FROM notes 
+      WHERE title LIKE ? OR content_markdown LIKE ?
+      ORDER BY event_start DESC
+    `);
+        const pattern = `%${query}%`;
+        return stmt.all(pattern, pattern);
+    }
+    // Recordings
+    upsertRecording(recording) {
+        const stmt = this.db.prepare(`
+      INSERT INTO recordings (id, note_id, title, created_at, updated_at, event_start, event_end, recording_start, recording_end, event_guid, call_url, transcript_json, synced_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        note_id = excluded.note_id,
+        title = excluded.title,
+        updated_at = excluded.updated_at,
+        event_start = excluded.event_start,
+        event_end = excluded.event_end,
+        recording_start = excluded.recording_start,
+        recording_end = excluded.recording_end,
+        event_guid = excluded.event_guid,
+        call_url = excluded.call_url,
+        transcript_json = COALESCE(excluded.transcript_json, transcript_json),
+        synced_at = excluded.synced_at
+    `);
+        stmt.run(recording.id, recording.note_id, recording.title, recording.created_at, recording.updated_at, recording.event_start, recording.event_end, recording.recording_start, recording.recording_end, recording.event_guid, recording.call_url, recording.transcript_json, new Date().toISOString());
+    }
+    getRecording(id) {
+        const stmt = this.db.prepare("SELECT * FROM recordings WHERE id = ?");
+        return stmt.get(id);
+    }
+    // Action Items
+    clearActionItemsForNote(noteId) {
+        const stmt = this.db.prepare("DELETE FROM action_items WHERE note_id = ?");
+        stmt.run(noteId);
+    }
+    insertActionItem(item) {
+        const stmt = this.db.prepare(`
+      INSERT INTO action_items (note_id, content, assignee, due_date, is_completed, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(item.note_id, item.content, item.assignee, item.due_date, item.is_completed ? 1 : 0, item.created_at);
+    }
+    getAllActionItems(filters) {
+        let query = `
+      SELECT a.*, n.title as note_title, n.event_start
+      FROM action_items a
+      JOIN notes n ON a.note_id = n.id
+      WHERE 1=1
+    `;
+        const params = [];
+        if (filters?.assignee) {
+            query += " AND a.assignee LIKE ?";
+            params.push(`%${filters.assignee}%`);
+        }
+        if (filters?.is_completed !== undefined) {
+            query += " AND a.is_completed = ?";
+            params.push(filters.is_completed ? 1 : 0);
+        }
+        if (filters?.since) {
+            query += " AND n.event_start >= ?";
+            params.push(filters.since);
+        }
+        query += " ORDER BY n.event_start DESC";
+        const stmt = this.db.prepare(query);
+        return stmt.all(...params);
+    }
+    // Participants
+    clearParticipantsForNote(noteId) {
+        const stmt = this.db.prepare("DELETE FROM participants WHERE note_id = ?");
+        stmt.run(noteId);
+    }
+    insertParticipant(noteId, email) {
+        const stmt = this.db.prepare(`
+      INSERT OR IGNORE INTO participants (note_id, email) VALUES (?, ?)
+    `);
+        stmt.run(noteId, email);
+    }
+    getMeetingsByParticipants(emails) {
+        if (emails.length === 0)
+            return [];
+        const placeholders = emails.map(() => "?").join(",");
+        const stmt = this.db.prepare(`
+      SELECT DISTINCT n.* FROM notes n
+      JOIN participants p ON n.id = p.note_id
+      WHERE p.email IN (${placeholders})
+      ORDER BY n.event_start DESC
+    `);
+        return stmt.all(...emails);
+    }
+    getMeetingsWithAllParticipants(emails) {
+        if (emails.length === 0)
+            return [];
+        const placeholders = emails.map(() => "?").join(",");
+        const stmt = this.db.prepare(`
+      SELECT n.* FROM notes n
+      WHERE (
+        SELECT COUNT(DISTINCT p.email) FROM participants p 
+        WHERE p.note_id = n.id AND p.email IN (${placeholders})
+      ) = ?
+      ORDER BY n.event_start DESC
+    `);
+        return stmt.all(...emails, emails.length);
+    }
+    getParticipantsForNote(noteId) {
+        const stmt = this.db.prepare("SELECT email FROM participants WHERE note_id = ?");
+        const rows = stmt.all(noteId);
+        return rows.map((r) => r.email);
+    }
+    // Sync status
+    getLastSyncTime() {
+        const stmt = this.db.prepare("SELECT value FROM sync_status WHERE key = 'last_sync'");
+        const row = stmt.get();
+        return row?.value ?? null;
+    }
+    setLastSyncTime(time) {
+        const stmt = this.db.prepare(`
+      INSERT INTO sync_status (key, value) VALUES ('last_sync', ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `);
+        stmt.run(time);
+    }
+    // Stats
+    getStats() {
+        const notes = this.db.prepare("SELECT COUNT(*) as count FROM notes").get().count;
+        const recordings = this.db.prepare("SELECT COUNT(*) as count FROM recordings").get().count;
+        const action_items = this.db.prepare("SELECT COUNT(*) as count FROM action_items").get().count;
+        const participants = this.db.prepare("SELECT COUNT(DISTINCT email) as count FROM participants").get().count;
+        return { notes, recordings, action_items, participants };
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/index.d.ts

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