exponential-mcp 0.2.0 → 0.4.0

package/README.md

@@ -106,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

@@ -9,21 +9,63 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { ExponentialClient, createConfigStore } from 'exponential-sdk';
 import { readFileSync, existsSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 const LEGACY_CONFIG_PATH = join(homedir(), '.config', 'exponential-mcp', 'config.json');
+// Report the real package version rather than a hand-maintained literal that drifts.
+const PKG_VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8')).version;
 const configStore = createConfigStore({ projectName: 'exponential-mcp' });
+/**
+ * Read the `exp` claim out of a JWT, without verifying the signature — we only
+ * want to know whether it is worth sending, not whether it is trustworthy.
+ *
+ * Returns null for opaque tokens (`exp_agent_…` keys, which never expire) and
+ * for anything that does not parse as a JWT.
+ */
+function getTokenExpiry(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+        return typeof payload?.exp === 'number' ? new Date(payload.exp * 1000) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function assertTokenIsUsable(token, source) {
+    const expiry = getTokenExpiry(token);
+    if (!expiry || expiry.getTime() > Date.now()) {
+        return;
+    }
+    console.error(`Error: token expired on ${expiry.toISOString().slice(0, 10)} (${source}).`);
+    console.error('Run "npx exponential-mcp init" to store a fresh token.');
+    process.exit(1);
+}
 function migrateLegacyConfig() {
     if (configStore.isAuthenticated() || !existsSync(LEGACY_CONFIG_PATH)) {
         return;
     }
     try {
         const legacy = JSON.parse(readFileSync(LEGACY_CONFIG_PATH, 'utf-8'));
-        if (legacy?.apiKey) {
-            configStore.saveConfig({
-                token: legacy.apiKey,
-                apiUrl: legacy.baseUrl || 'https://www.exponential.im',
-            });
+        if (!legacy?.apiKey) {
+            return;
+        }
+        // Don't resurrect a dead token: the legacy file long outlives the JWT in it,
+        // so migrating one blindly turns every config reset into a silent 401.
+        const expiry = getTokenExpiry(legacy.apiKey);
+        if (expiry && expiry.getTime() <= Date.now()) {
+            console.error(`Note: ignoring legacy config at ${LEGACY_CONFIG_PATH} — its token expired on ${expiry
+                .toISOString()
+                .slice(0, 10)}.`);
+            return;
         }
+        configStore.saveConfig({
+            token: legacy.apiKey,
+            apiUrl: legacy.baseUrl || 'https://www.exponential.im',
+        });
     }
     catch {
         // Ignore legacy config parsing errors.
@@ -33,6 +75,7 @@ function loadClientConfig() {
     migrateLegacyConfig();
     if (configStore.isAuthenticated()) {
         const config = configStore.loadConfig();
+        assertTokenIsUsable(config.token, 'stored config');
         return { token: config.token, apiUrl: config.apiUrl };
     }
     const token = process.env.EXPONENTIAL_API_KEY || process.env.EXPONENTIAL_API_TOKEN;
@@ -44,8 +87,25 @@ function loadClientConfig() {
         console.error('Run "npx exponential-mcp init" to set up, or set EXPONENTIAL_API_KEY env var.');
         process.exit(1);
     }
+    assertTokenIsUsable(token, 'EXPONENTIAL_API_KEY');
     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 +123,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 +139,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.',
@@ -160,7 +311,7 @@ async function main() {
     const trpcClient = client.client;
     const server = new Server({
         name: 'exponential-mcp',
-        version: '0.1.0',
+        version: PKG_VERSION,
     }, {
         capabilities: {
             tools: {},
@@ -216,10 +367,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: [
@@ -230,9 +405,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',
                     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exponential-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server for Exponential - connect Claude to your projects, actions, and goals",
   "main": "dist/index.js",
   "bin": {
@@ -11,7 +11,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "cli": "node dist/cli.js"
+    "cli": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "mcp",
@@ -23,9 +24,9 @@
   "author": "Exponential",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^12.0.0",
-    "exponential-sdk": "^1.0.0",
+    "exponential-sdk": "^1.11.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {