exponential-mcp 0.4.0 → 0.6.0

package/README.md

@@ -106,6 +106,8 @@ exponential-mcp serve
 |------|-------------|
 | `get_workspaces` | List all workspaces |
 | `get_projects` | List projects (optionally by workspace) |
+| `get_project` | One project in full: linked objectives & key results, DRI, team, dates |
+| `update_project` | Rename, change status/priority, set dates, re-link to OKRs |
 | `get_actions` | List actions/tasks (filter by project or status; no date filtering) |
 | `get_todays_actions` | **What's on your plate now** — overdue / today / inbox, across all workspaces |
 | `get_overdue_triage` | Why the overdue pile is that size: bulk-created cohorts vs real debt |
@@ -114,7 +116,13 @@ exponential-mcp serve
 | `defer_actions` | Amnesty: clear dates, back to the project backlog untimed |
 | `reschedule_actions` | Move actions to a new do-date |
 | `complete_action` | Mark an action as done |
-| `get_goals` | List OKRs with progress |
+| `get_goals` | List objectives, flat or as the annual → quarterly tree |
+| `get_key_results` | List key results, grouped by objective or flat |
+| `get_meetings` | List meetings, newest first, with a summary preview (no notes/transcript) |
+| `get_meeting` | One meeting with notes; transcript on request |
+| `create_meeting` | Record a meeting from a transcript or notes |
+| `update_meeting` | Edit title, description, summary, date, or replace notes |
+| `append_meeting_notes` | Add to a meeting's notes without overwriting them |
 | `search` | Search across everything |
 
 ### Asking about the day

package/dist/index.js

@@ -106,6 +106,49 @@ function parseDateArg(raw) {
     }
     return parsed;
 }
+const SUMMARY_PREVIEW_CHARS = 400;
+const DEFAULT_MEETING_LIMIT = 30;
+/**
+ * A meeting row as it comes off the list read is ~3k characters of metadata
+ * plus the full transcript, summary and notes bodies — a single hour-long
+ * transcript is easily 50k+ characters, and the server offers no limit or
+ * projection. The list tool sends a compact row with a summary preview; the
+ * detail tool sends everything except the transcript unless asked.
+ */
+function meetingListRow(m) {
+    const summary = m.summary ?? null;
+    const truncated = summary !== null && summary.length > SUMMARY_PREVIEW_CHARS;
+    return {
+        id: m.id,
+        title: m.title,
+        description: m.description,
+        meetingDate: m.meetingDate,
+        createdAt: m.createdAt,
+        durationSeconds: m.durationSeconds ?? null,
+        participantCount: m.participantCount ?? null,
+        projectId: m.projectId,
+        project: m.project ?? null,
+        workspaceId: m.workspaceId,
+        archivedAt: m.archivedAt,
+        source: m.sourceIntegration?.provider ?? null,
+        participants: (m.participants ?? []).map((p) => ({ id: p.id, name: p.name, email: p.email })),
+        actions: m.actions ?? [],
+        summaryPreview: truncated ? summary.slice(0, SUMMARY_PREVIEW_CHARS) + '…' : summary,
+        summaryTruncated: truncated,
+        hasNotes: Boolean(m.notes),
+        hasTranscript: Boolean(m.transcription),
+    };
+}
+function meetingDetail(m, includeTranscript) {
+    // sentencesJson / analyticsJson are the server's internal processing
+    // artefacts; they are not part of the SDK type and never useful to a model.
+    const { transcription, sentencesJson, analyticsJson, ...rest } = m;
+    return {
+        ...rest,
+        hasTranscript: Boolean(transcription),
+        ...(includeTranscript ? { transcription } : {}),
+    };
+}
 // Tool definitions
 const TOOLS = [
     {
@@ -121,6 +164,64 @@ const TOOLS = [
             }
         }
     },
+    {
+        name: 'get_project',
+        description: 'Fetch one project with its relations: the objectives and key results it is linked to, DRI, team, dates, description, and linked meetings. get_projects returns none of the OKR links, so this is the tool for "what is this project driving?". It does NOT include the project\'s tasks — use get_actions with projectId for those. Accepts a project ID, a slug, or the slug-id form from app URLs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Project ID, slug, or the compound slug-id from an app URL'
+                }
+            },
+            required: ['id']
+        }
+    },
+    {
+        name: 'update_project',
+        description: 'Update a project: rename, change status or priority, edit the description, set dates, or re-link it to objectives / key results. Only the fields you pass are changed. goalIds and keyResultIds REPLACE the existing links wholesale — read get_project first and pass the full set you want to keep. An empty keyResultIds clears the key-result links; an empty goalIds is ignored by the server.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Project ID' },
+                name: { type: 'string', description: 'New name' },
+                description: {
+                    type: 'string',
+                    description: 'New description. Pass an empty string to blank it.'
+                },
+                status: {
+                    type: 'string',
+                    enum: ['ACTIVE', 'ON_HOLD', 'COMPLETED', 'CANCELLED'],
+                    description: 'New lifecycle status'
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['HIGH', 'MEDIUM', 'LOW', 'NONE'],
+                    description: 'New priority'
+                },
+                driId: {
+                    type: 'string',
+                    description: 'User ID of the directly responsible individual, or null to clear'
+                },
+                goalIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Objective IDs (integers, passed as strings) to link — replaces the current set'
+                },
+                keyResultIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Key result IDs to link — replaces the current set; [] clears'
+                },
+                startDate: { type: 'string', description: 'ISO datetime, or null to clear' },
+                endDate: { type: 'string', description: 'ISO datetime, or null to clear' },
+                reviewDate: { type: 'string', description: 'ISO datetime, or null to clear' },
+                nextActionDate: { type: 'string', description: 'ISO datetime, or null to clear' }
+            },
+            required: ['id']
+        }
+    },
     {
         name: 'get_actions',
         description: 'List actions/tasks, optionally filtered by project or status. This is a flat list with no date filtering — to answer "what should I work on today" or "what am I behind on", use get_todays_actions instead.',
@@ -260,17 +361,166 @@ const TOOLS = [
     },
     {
         name: 'get_goals',
-        description: 'List OKRs (Objectives and Key Results) with their progress',
+        description: "List objectives (goals). Each objective carries its linked projects, which is how work ladders up to an OKR: every action has a projectId. Objectives have INTEGER ids — key results, which are separate, have CUIDs (see get_key_results). Use tree: true for the annual → quarterly cascade.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: {
+                    type: 'string',
+                    description: 'Optional workspace ID. With it the list is workspace-wide (every member\'s objectives); without it you get your own.'
+                },
+                period: {
+                    type: 'string',
+                    description: 'Optional period filter, e.g. "Q3-2026" or "Annual-2026"'
+                },
+                status: {
+                    type: 'string',
+                    description: 'Optional status: planned, active, completed, archived, on-hold'
+                },
+                tree: {
+                    type: 'boolean',
+                    description: 'Return objectives nested parent → child (up to 5 levels), each with its projects and key results, instead of a flat list'
+                }
+            }
+        }
+    },
+    {
+        name: 'get_key_results',
+        description: "List key results — the measurable half of an OKR. By default groups them under their objectives (the richest read: one call for 'how is the quarter going'). Pass flat: true for a bare list. Key result ids are CUIDs; the goalId tying one to its objective is an integer.",
         inputSchema: {
             type: 'object',
             properties: {
                 workspaceId: {
                     type: 'string',
-                    description: 'Optional workspace ID'
+                    description: "Optional workspace ID. With it the list is workspace-wide (every member's key results); without it you get your own."
+                },
+                period: {
+                    type: 'string',
+                    description: 'Optional period filter, e.g. "Q3-2026"'
+                },
+                goalId: {
+                    type: 'number',
+                    description: 'Optional objective ID (an integer). Only applies with flat: true.'
+                },
+                status: {
+                    type: 'string',
+                    description: 'Optional status: not-started, on-track, at-risk, off-track, achieved. Only applies with flat: true.'
+                },
+                flat: {
+                    type: 'boolean',
+                    description: 'Return a flat list of key results rather than grouping them by objective'
+                }
+            }
+        }
+    },
+    {
+        name: 'get_meetings',
+        description: 'List meetings the user can see — ones they own or attended, plus those on their projects and workspaces — newest first. Each row has metadata, participants, linked actions and a short preview of the AI summary; the full summary, notes and transcript are only in get_meeting. Use this to answer "when did I last meet Y" or to find a meeting ID, then get_meeting for what was actually said.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: {
+                    type: 'string',
+                    description: 'Optional workspace ID to restrict to one workspace'
+                },
+                meetingType: {
+                    type: 'string',
+                    enum: ['all', 'mine', 'one_on_one'],
+                    description: 'all (default) — everything visible; mine — meetings the user owns or attended; one_on_one — exactly two participants'
+                },
+                includeArchived: {
+                    type: 'boolean',
+                    description: 'Include archived meetings (default false)'
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max meetings to return, newest first (default 30)'
                 }
             }
         }
     },
+    {
+        name: 'get_meeting',
+        description: 'Fetch one meeting in full: participants with speaker labels, linked actions, the AI summary, and the meeting notes. The raw transcript is omitted unless includeTranscript is true — it can be tens of thousands of characters, so only pull it when the summary and notes are not enough.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Meeting ID' },
+                includeTranscript: {
+                    type: 'boolean',
+                    description: 'Also return the raw transcript text (default false)'
+                }
+            },
+            required: ['id']
+        }
+    },
+    {
+        name: 'create_meeting',
+        description: 'Record a meeting in Exponential from a transcript or notes the user gives you. transcription is required by the server — if the user only has notes, put the notes text there too. A project-linked meeting inherits its project\'s workspace.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Meeting title' },
+                transcription: {
+                    type: 'string',
+                    description: 'Raw transcript text (required, at least one character)'
+                },
+                notes: { type: 'string', description: 'Meeting notes (Markdown)' },
+                description: { type: 'string', description: 'Short description' },
+                meetingDate: {
+                    type: 'string',
+                    description: 'When the meeting happened, as an ISO datetime (defaults to now)'
+                },
+                projectId: { type: 'string', description: 'Link to this project' },
+                workspaceId: { type: 'string', description: 'Workspace ID (ignored when projectId is set)' },
+                participants: {
+                    type: 'array',
+                    description: 'Who attended. Each entry needs at least one of userId, contactId, or email.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            userId: { type: 'string' },
+                            contactId: { type: 'string' },
+                            email: { type: 'string' },
+                            name: { type: 'string' }
+                        }
+                    }
+                }
+            },
+            required: ['title', 'transcription']
+        }
+    },
+    {
+        name: 'update_meeting',
+        description: 'Edit a meeting\'s title, description, summary, date, or REPLACE its notes wholesale. To add to existing notes without rewriting them, use append_meeting_notes instead. Only the fields you pass are changed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Meeting ID' },
+                title: { type: 'string', description: 'New title' },
+                description: { type: 'string', description: 'New description' },
+                summary: { type: 'string', description: 'New summary' },
+                notes: { type: 'string', description: 'Replacement notes body (Markdown)' },
+                meetingDate: {
+                    type: 'string',
+                    description: 'When the meeting happened, as an ISO datetime, or null to clear'
+                }
+            },
+            required: ['id']
+        }
+    },
+    {
+        name: 'append_meeting_notes',
+        description: 'Append a block of text to a meeting\'s notes, separated by a blank line, creating the notes if there are none yet. This is the safe way to add a follow-up, decision, or action list to a meeting without clobbering what is already there.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Meeting ID' },
+                text: { type: 'string', description: 'Text to append (Markdown)' }
+            },
+            required: ['id', 'text']
+        }
+    },
     {
         name: 'search',
         description: "Global text search across everything the user can access — projects, actions/tasks, goals, workspaces (and more entity types as the API grows). Same coverage as the app's Cmd+K palette. Returns typed results with ids, workspace, and app URL.",
@@ -339,6 +589,45 @@ async function main() {
                         ],
                     };
                 }
+                case 'get_project': {
+                    const project = await client.projects.get(args?.id);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(project, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'update_project': {
+                    // `null` clears driId; the string "null" is the JSON-as-text form the
+                    // model sometimes emits, same as parseDateArg handles for dates.
+                    const rawDri = args?.driId;
+                    const driId = rawDri === undefined ? undefined : rawDri === null || rawDri === 'null' ? null : rawDri;
+                    const project = await client.projects.update({
+                        id: args?.id,
+                        name: args?.name,
+                        description: args?.description,
+                        status: args?.status,
+                        priority: args?.priority,
+                        driId,
+                        goalIds: args?.goalIds,
+                        keyResultIds: args?.keyResultIds,
+                        startDate: parseDateArg(args?.startDate),
+                        endDate: parseDateArg(args?.endDate),
+                        reviewDate: parseDateArg(args?.reviewDate),
+                        nextActionDate: parseDateArg(args?.nextActionDate),
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Updated project: ${project.name} (ID: ${project.id})`,
+                            },
+                        ],
+                    };
+                }
                 case 'get_actions': {
                     const status = args?.status;
                     const projectId = args?.projectId;
@@ -465,15 +754,124 @@ async function main() {
                         ],
                     };
                 }
+                // Goes through the SDK's GoalsApi rather than a raw tRPC path. The old
+                // implementation called `goal.list`, which does not exist — the tool
+                // hard-errored with `No procedure found on path "goal.list"` on every
+                // invocation.
                 case 'get_goals': {
-                    const goals = await trpcClient.goal.list.query({
+                    const workspaceId = args?.workspaceId;
+                    const period = args?.period;
+                    const status = args?.status;
+                    const goals = args?.tree
+                        ? await client.goals.tree({ workspaceId, status })
+                        : await client.goals.list({ workspaceId, period, status });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(goals, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'get_key_results': {
+                    const workspaceId = args?.workspaceId;
+                    const period = args?.period;
+                    const keyResults = args?.flat
+                        ? await client.goals.keyResults.list({
+                            workspaceId,
+                            period,
+                            goalId: args?.goalId,
+                            status: args?.status,
+                        })
+                        : await client.goals.keyResults.byObjective({ workspaceId, period });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(keyResults, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'get_meetings': {
+                    const meetings = await client.meetings.list({
                         workspaceId: args?.workspaceId,
+                        meetingType: args?.meetingType,
+                        includeArchived: args?.includeArchived,
                     });
+                    const limit = Math.max(1, Number(args?.limit) || DEFAULT_MEETING_LIMIT);
+                    const when = (m) => new Date(m.meetingDate ?? m.createdAt).getTime();
+                    const rows = [...meetings]
+                        .sort((a, b) => when(b) - when(a))
+                        .slice(0, limit)
+                        .map(meetingListRow);
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: JSON.stringify(goals, null, 2),
+                                text: JSON.stringify({ total: meetings.length, returned: rows.length, meetings: rows }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'get_meeting': {
+                    const meeting = await client.meetings.get(args?.id);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(meetingDetail(meeting, Boolean(args?.includeTranscript)), null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'create_meeting': {
+                    const meetingDate = parseDateArg(args?.meetingDate);
+                    const meeting = await client.meetings.create({
+                        title: args?.title,
+                        transcription: args?.transcription,
+                        notes: args?.notes,
+                        description: args?.description,
+                        meetingDate: meetingDate ?? undefined,
+                        projectId: args?.projectId,
+                        workspaceId: args?.workspaceId,
+                        participants: args?.participants,
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Created meeting: ${meeting.title ?? '(untitled)'} (ID: ${meeting.id})`,
+                            },
+                        ],
+                    };
+                }
+                case 'update_meeting': {
+                    const meeting = await client.meetings.update({
+                        id: args?.id,
+                        title: args?.title,
+                        description: args?.description,
+                        summary: args?.summary,
+                        notes: args?.notes,
+                        meetingDate: parseDateArg(args?.meetingDate),
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Updated meeting: ${meeting.title ?? '(untitled)'} (ID: ${meeting.id})`,
+                            },
+                        ],
+                    };
+                }
+                case 'append_meeting_notes': {
+                    const meeting = await client.meetings.appendNotes(args?.id, args?.text);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Appended to notes of: ${meeting.title ?? '(untitled)'} (ID: ${meeting.id})`,
                             },
                         ],
                     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exponential-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "MCP server for Exponential - connect Claude to your projects, actions, and goals",
   "main": "dist/index.js",
   "bin": {
@@ -26,7 +26,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^12.0.0",
-    "exponential-sdk": "^1.11.0",
+    "exponential-sdk": "^1.16.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {

package/dist/api.d.ts

@@ -1,84 +0,0 @@
-/**
- * Exponential API Client
- * Handles authenticated requests to the Exponential API
- */
-export interface ExponentialConfig {
-    apiKey: string;
-    baseUrl?: string;
-}
-export interface Project {
-    id: string;
-    name: string;
-    description?: string;
-    status: string;
-    priority: string;
-    progress: number;
-}
-export interface Action {
-    id: string;
-    name: string;
-    description?: string;
-    status: string;
-    priority: string;
-    dueDate?: string;
-    projectId?: string;
-    project?: {
-        name: string;
-    };
-}
-export interface Goal {
-    id: number;
-    title: string;
-    description?: string;
-    period?: string;
-    keyResults: KeyResult[];
-}
-export interface KeyResult {
-    id: string;
-    title: string;
-    targetValue?: number;
-    currentValue?: number;
-    status: string;
-}
-export interface Workspace {
-    id: string;
-    name: string;
-    slug: string;
-}
-export declare class ExponentialAPI {
-    private apiKey;
-    private baseUrl;
-    constructor(config: ExponentialConfig);
-    private request;
-    private trpcQuery;
-    private trpcMutation;
-    getWorkspaces(): Promise<Workspace[]>;
-    getProjects(workspaceId?: string): Promise<Project[]>;
-    getProject(id: string): Promise<Project>;
-    getActions(params?: {
-        projectId?: string;
-        status?: string;
-    }): Promise<Action[]>;
-    createAction(data: {
-        name: string;
-        description?: string;
-        projectId?: string;
-        priority?: string;
-        dueDate?: string;
-    }): Promise<Action>;
-    updateAction(id: string, data: {
-        name?: string;
-        status?: string;
-        priority?: string;
-        dueDate?: string;
-    }): Promise<Action>;
-    completeAction(id: string): Promise<Action>;
-    getGoals(workspaceId?: string): Promise<Goal[]>;
-    getGoal(id: number): Promise<Goal>;
-    quickCreateAction(text: string): Promise<Action>;
-    search(query: string): Promise<{
-        projects: Project[];
-        actions: Action[];
-        goals: Goal[];
-    }>;
-}

package/dist/api.js

@@ -1,82 +0,0 @@
-/**
- * Exponential API Client
- * Handles authenticated requests to the Exponential API
- */
-const DEFAULT_BASE_URL = 'https://www.exponential.im';
-export class ExponentialAPI {
-    apiKey;
-    baseUrl;
-    constructor(config) {
-        this.apiKey = config.apiKey;
-        this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
-    }
-    async request(endpoint, options = {}) {
-        const url = `${this.baseUrl}${endpoint}`;
-        const response = await fetch(url, {
-            ...options,
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                'Content-Type': 'application/json',
-                ...options.headers,
-            },
-        });
-        if (!response.ok) {
-            const error = await response.text();
-            throw new Error(`Exponential API error (${response.status}): ${error}`);
-        }
-        return response.json();
-    }
-    // tRPC-style calls
-    async trpcQuery(procedure, input) {
-        const inputStr = input ? encodeURIComponent(JSON.stringify(input)) : '';
-        const url = `/api/trpc/${procedure}${inputStr ? `?input=${inputStr}` : ''}`;
-        return this.request(url).then(r => r.result.data);
-    }
-    async trpcMutation(procedure, input) {
-        const url = `/api/trpc/${procedure}`;
-        return this.request(url, {
-            method: 'POST',
-            body: JSON.stringify(input),
-        }).then(r => r.result.data);
-    }
-    // === Workspace ===
-    async getWorkspaces() {
-        return this.trpcQuery('workspace.list');
-    }
-    // === Projects ===
-    async getProjects(workspaceId) {
-        return this.trpcQuery('project.list', { workspaceId });
-    }
-    async getProject(id) {
-        return this.trpcQuery('project.get', { id });
-    }
-    // === Actions ===
-    async getActions(params) {
-        return this.trpcQuery('action.list', params);
-    }
-    async createAction(data) {
-        return this.trpcMutation('action.create', data);
-    }
-    async updateAction(id, data) {
-        return this.trpcMutation('action.update', { id, ...data });
-    }
-    async completeAction(id) {
-        return this.updateAction(id, { status: 'COMPLETED' });
-    }
-    // === Goals (OKRs) ===
-    async getGoals(workspaceId) {
-        return this.trpcQuery('goal.list', { workspaceId });
-    }
-    async getGoal(id) {
-        return this.trpcQuery('goal.get', { id });
-    }
-    // === Quick Actions ===
-    async quickCreateAction(text) {
-        // Uses natural language parsing (dates, project names, etc.)
-        return this.trpcMutation('action.quickCreate', { text });
-    }
-    // === Search ===
-    async search(query) {
-        return this.trpcQuery('search.global', { query });
-    }
-}