exponential-mcp 0.1.1 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # Exponential MCP
 
+[![npm version](https://img.shields.io/npm/v/exponential-mcp.svg)](https://www.npmjs.com/package/exponential-mcp)
+
 Connect Claude to your [Exponential](https://exponential.im) workspace. Manage projects, actions, and OKRs directly from Claude.
 
 ## Quick Start
@@ -104,12 +106,31 @@ exponential-mcp serve
 |------|-------------|
 | `get_workspaces` | List all workspaces |
 | `get_projects` | List projects (optionally by workspace) |
-| `get_actions` | List actions/tasks (filter by project or status) |
+| `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 |
 | `create_action` | Create a new task (supports natural language) |
+| `update_action` | Rename, re-prioritise, move project, or set dates (incl. `scheduledStart`) |
+| `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 |
 | `search` | Search across everything |
 
+### Asking about the day
+
+Use **`get_todays_actions`**, not `get_actions`, for anything about today,
+priorities, or what the user is behind on. `get_actions` has no date filtering
+at all, so it cannot distinguish overdue work from anything else.
+
+When there is a lot of overdue work, follow up with **`get_overdue_triage`**
+before proposing what to do. A large overdue count is usually a few bulk writes
+— a generated project plan stamped every row with one timestamp — not a large
+number of missed commitments. Those are **cohorts**, and the honest disposition
+is `defer_actions` (amnesty); `reschedule_actions` would just re-inflict the
+same pile tomorrow. Individually-dated **loose** actions are the ones that
+deserve a real decision.
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -46,6 +46,22 @@ function loadClientConfig() {
     }
     return { token, apiUrl };
 }
+/**
+ * `undefined` = leave the field alone, `null` = clear it, otherwise a Date.
+ * MCP arguments arrive as JSON, so an explicit clear can be either a real null
+ * or the string "null" depending on how the model emits it.
+ */
+function parseDateArg(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === null || raw === 'null')
+        return null;
+    const parsed = new Date(raw);
+    if (isNaN(parsed.getTime())) {
+        throw new Error(`Invalid date "${String(raw)}". Use an ISO datetime, or null to clear.`);
+    }
+    return parsed;
+}
 // Tool definitions
 const TOOLS = [
     {
@@ -63,7 +79,7 @@ const TOOLS = [
     },
     {
         name: 'get_actions',
-        description: 'List actions/tasks. Can filter by project or status.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -79,6 +95,97 @@ const TOOLS = [
             }
         }
     },
+    {
+        name: 'get_todays_actions',
+        description: "What is on the user's plate right now, split into overdue / today / inbox. This is the same set the /today page renders, across all workspaces. Use this FIRST for any question about today, this week, priorities, what to work on, or what the user is behind on — it is the only tool that surfaces overdue work. Returns action IDs, so pair it with update_action, defer_actions, or reschedule_actions to act on what it finds.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: {
+                    type: 'string',
+                    description: 'Optional workspace ID. Omit to span all workspaces (usually what you want).'
+                }
+            }
+        }
+    },
+    {
+        name: 'get_overdue_triage',
+        description: 'Explain WHY the overdue pile is the size it is, before proposing what to do about it. Splits overdue actions into "cohorts" — groups sharing one exact timestamp, the fingerprint of a bulk write like a generated project plan, which were almost certainly never individually due — and "loose" individually-dated actions, which are real missed commitments. Use this whenever the user has a lot of overdue work: recommend defer_actions (amnesty) for cohorts and a real decision for loose items. Rescheduling a cohort just re-inflicts the pile tomorrow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: {
+                    type: 'string',
+                    description: 'Optional workspace ID. Omit to span all workspaces.'
+                }
+            }
+        }
+    },
+    {
+        name: 'update_action',
+        description: 'Update an action: rename, re-prioritise, move project, change status, or set its dates. scheduledStart is the "do date" — when the user plans to work on it — and it is what /today partitions on, taking precedence over dueDate. To move something out of the overdue bucket you must set scheduledStart; changing dueDate alone will not do it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Action ID' },
+                name: { type: 'string', description: 'New name' },
+                description: { type: 'string', description: 'New description' },
+                projectId: { type: 'string', description: 'Move to this project ID' },
+                status: {
+                    type: 'string',
+                    enum: ['ACTIVE', 'COMPLETED', 'CANCELLED'],
+                    description: 'New status'
+                },
+                dueDate: {
+                    type: 'string',
+                    description: 'Deadline as an ISO datetime, or null to clear'
+                },
+                scheduledStart: {
+                    type: 'string',
+                    description: 'Do-date as an ISO datetime (e.g. 2026-08-05T09:00:00Z), or null to clear'
+                },
+                scheduledEnd: {
+                    type: 'string',
+                    description: 'End of the time block as an ISO datetime, or null to clear'
+                }
+            },
+            required: ['id']
+        }
+    },
+    {
+        name: 'defer_actions',
+        description: 'Amnesty: clear the dates on these actions so they fall back to their project backlog untimed. Use for work that was never really due on the date it carries — most often a bulk-created cohort from get_overdue_triage. The actions stay ACTIVE and are not deleted or archived; they simply stop counting as overdue. Prefer this over reschedule_actions when the dates were never a real commitment.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                actionIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Action IDs to defer'
+                }
+            },
+            required: ['actionIds']
+        }
+    },
+    {
+        name: 'reschedule_actions',
+        description: 'Move actions to a new do-date, for work that genuinely is still due, just later. Sets scheduledStart, pushing dueDate forward only where it would otherwise fall before it. If the actions were bulk-created and never individually due, use defer_actions instead — rescheduling them only re-inflicts the same pile tomorrow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                actionIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Action IDs to reschedule'
+                },
+                date: {
+                    type: 'string',
+                    description: 'New do-date as an ISO datetime (e.g. 2026-08-05T09:00:00Z)'
+                }
+            },
+            required: ['actionIds', 'date']
+        }
+    },
     {
         name: 'create_action',
         description: 'Create a new action/task. Supports natural language with dates and project names.',
@@ -122,13 +229,21 @@ const TOOLS = [
     },
     {
         name: 'search',
-        description: 'Search across projects, actions, and goals',
+        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.",
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
                     description: 'Search query'
+                },
+                workspaceId: {
+                    type: 'string',
+                    description: 'Optional workspace ID to restrict results to one workspace'
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results per entity type (1-25, default 10)'
                 }
             },
             required: ['query']
@@ -208,10 +323,34 @@ async function main() {
                         ],
                     };
                 }
+                case 'get_todays_actions': {
+                    const todays = await client.actions.getTodaysActions(args?.workspaceId);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(todays, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'get_overdue_triage': {
+                    const triage = await client.actions.getOverdueTriage(args?.workspaceId);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(triage, null, 2),
+                            },
+                        ],
+                    };
+                }
                 case 'create_action': {
-                    // SDK does not yet expose quickCreate, so we use the underlying tRPC client.
+                    // quickCreate's input field is `name`, not `text` -- it parses natural
+                    // language out of the name itself (dates, project names) when
+                    // parseNaturalLanguage is on, which it is by default.
                     const action = await trpcClient.action.quickCreate.mutate({
-                        text: args?.text,
+                        name: args?.text,
                     });
                     return {
                         content: [
@@ -222,9 +361,54 @@ async function main() {
                         ],
                     };
                 }
+                case 'update_action': {
+                    const action = await client.actions.update({
+                        id: args?.id,
+                        name: args?.name,
+                        description: args?.description,
+                        projectId: args?.projectId,
+                        status: args?.status,
+                        dueDate: parseDateArg(args?.dueDate),
+                        scheduledStart: parseDateArg(args?.scheduledStart),
+                        scheduledEnd: parseDateArg(args?.scheduledEnd),
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Updated: ${action.name} (ID: ${action.id})`,
+                            },
+                        ],
+                    };
+                }
+                case 'defer_actions': {
+                    const result = await client.actions.bulkDefer(args?.actionIds);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: result.message,
+                            },
+                        ],
+                    };
+                }
+                case 'reschedule_actions': {
+                    const when = new Date(args?.date);
+                    if (isNaN(when.getTime())) {
+                        throw new Error(`Invalid date "${String(args?.date)}". Use an ISO datetime.`);
+                    }
+                    const result = await client.actions.bulkReschedule(args?.actionIds, when);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Rescheduled ${result.count} action${result.count === 1 ? '' : 's'} to ${when.toISOString()}`,
+                            },
+                        ],
+                    };
+                }
                 case 'complete_action': {
-                    // SDK does not yet expose action updates, so we use the underlying tRPC client.
-                    const action = await trpcClient.action.update.mutate({
+                    const action = await client.actions.update({
                         id: args?.id,
                         status: 'COMPLETED',
                     });
@@ -253,6 +437,8 @@ async function main() {
                 case 'search': {
                     const results = await trpcClient.search.global.query({
                         query: args?.query,
+                        workspaceId: args?.workspaceId,
+                        limit: args?.limit,
                     });
                     return {
                         content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exponential-mcp",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "MCP server for Exponential - connect Claude to your projects, actions, and goals",
   "main": "dist/index.js",
   "bin": {
@@ -25,7 +25,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "commander": "^12.0.0",
-    "exponential-sdk": "^1.0.0",
+    "exponential-sdk": "^1.10.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 });
-    }
-}