exponential-mcp 0.7.0 → 0.8.0

package/dist/index.js

@@ -12,6 +12,7 @@ import { homedir } from 'os';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { DOMAINS, runDomainTool, toolDefinition } from './domains/index.js';
+import { RUN_TOOLS, RUN_TOOL_NAMES, runContextFromEnv, runRunTool } from './runTools.js';
 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;
@@ -73,23 +74,29 @@ function migrateLegacyConfig() {
     }
 }
 function loadClientConfig() {
+    // An explicit key in the environment wins over the stored config: a process
+    // that starts this server for a specific principal — `exponential runner
+    // start` launching it for an Assistant run with the Assistant's agent key —
+    // must act as that principal, not as whoever last ran `init` here.
+    const envToken = process.env.EXPONENTIAL_API_KEY || process.env.EXPONENTIAL_API_TOKEN;
+    if (envToken) {
+        assertTokenIsUsable(envToken, 'EXPONENTIAL_API_KEY');
+        return {
+            token: envToken,
+            apiUrl: process.env.EXPONENTIAL_API_URL ||
+                process.env.EXPONENTIAL_BASE_URL ||
+                'https://www.exponential.im',
+        };
+    }
     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;
-    const apiUrl = process.env.EXPONENTIAL_API_URL ||
-        process.env.EXPONENTIAL_BASE_URL ||
-        'https://www.exponential.im';
-    if (!token) {
-        console.error('Error: No API key found.');
-        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 };
+    console.error('Error: No API key found.');
+    console.error('Run "npx exponential-mcp init" to set up, or set EXPONENTIAL_API_KEY env var.');
+    process.exit(1);
 }
 /**
  * `undefined` = leave the field alone, `null` = clear it, otherwise a Date.
@@ -569,13 +576,20 @@ async function main() {
         },
     });
     // List available tools
+    // Started for an Agent run (`exponential runner start` sets EXPONENTIAL_RUN_ID):
+    // the session gets the three run tools on top of everything else.
+    const runContext = runContextFromEnv();
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: [...TOOLS, ...[...DOMAINS.values()].map(toolDefinition)],
+        tools: [...(runContext ? RUN_TOOLS : []), ...TOOLS, ...[...DOMAINS.values()].map(toolDefinition)],
     }));
     // Handle tool calls
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         try {
+            if (runContext && RUN_TOOL_NAMES.has(name)) {
+                const result = await runRunTool(client, runContext, name, args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
             const domain = DOMAINS.get(name);
             if (domain) {
                 const result = await runDomainTool(domain, client, args);

package/dist/runTools.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Run tools (Exponential ADR-0067, Agent PRD V2): how a session the local
+ * runner spawned talks to its Agent run. They exist only when the server was
+ * started for a run — `EXPONENTIAL_RUN_ID` set in the environment by
+ * `exponential runner start` (which also passes the Assistant's agent key as
+ * `EXPONENTIAL_API_KEY` and its name as `EXPONENTIAL_RUNNER_ID`). Outside a
+ * run they are not listed, so an ordinary MCP session never sees them.
+ *
+ * - `report_progress` — a one-line note for the run's transcript. The runner
+ *   records it from the session's own tool stream, so this tool only
+ *   acknowledges; nothing is written from here.
+ * - `ask_owner` — asks the owner and PAUSES the run: the app posts the question
+ *   as a comment mentioning the owner and parks the run; the owner's reply
+ *   starts a new run. The session must stop after calling it.
+ * - `finish_run` — closes the run with a public summary and whether the action
+ *   is ready for the owner to confirm. The run never completes the action.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { ExponentialClient } from 'exponential-sdk';
+export interface RunContext {
+    runId: string;
+    runnerId?: string;
+}
+/** The run this server was started for, if any. */
+export declare function runContextFromEnv(env?: NodeJS.ProcessEnv): RunContext | null;
+export declare const RUN_TOOLS: Tool[];
+export declare const RUN_TOOL_NAMES: Set<string>;
+/** Dispatch one run tool. The caller has already checked `RUN_TOOL_NAMES.has(name)`. */
+export declare function runRunTool(client: Pick<ExponentialClient, 'agentRuns'>, context: RunContext, name: string, args: Record<string, unknown> | undefined): Promise<unknown>;

package/dist/runTools.js

@@ -0,0 +1,98 @@
+/**
+ * Run tools (Exponential ADR-0067, Agent PRD V2): how a session the local
+ * runner spawned talks to its Agent run. They exist only when the server was
+ * started for a run — `EXPONENTIAL_RUN_ID` set in the environment by
+ * `exponential runner start` (which also passes the Assistant's agent key as
+ * `EXPONENTIAL_API_KEY` and its name as `EXPONENTIAL_RUNNER_ID`). Outside a
+ * run they are not listed, so an ordinary MCP session never sees them.
+ *
+ * - `report_progress` — a one-line note for the run's transcript. The runner
+ *   records it from the session's own tool stream, so this tool only
+ *   acknowledges; nothing is written from here.
+ * - `ask_owner` — asks the owner and PAUSES the run: the app posts the question
+ *   as a comment mentioning the owner and parks the run; the owner's reply
+ *   starts a new run. The session must stop after calling it.
+ * - `finish_run` — closes the run with a public summary and whether the action
+ *   is ready for the owner to confirm. The run never completes the action.
+ */
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+/** The run this server was started for, if any. */
+export function runContextFromEnv(env = process.env) {
+    const runId = env.EXPONENTIAL_RUN_ID?.trim();
+    if (!runId)
+        return null;
+    return { runId, runnerId: env.EXPONENTIAL_RUNNER_ID?.trim() || undefined };
+}
+const reportProgressParams = z.object({
+    text: z.string().min(1).max(500).describe('One line, present tense: what you are doing now'),
+});
+const askOwnerParams = z.object({
+    question: z
+        .string()
+        .min(1)
+        .max(10000)
+        .describe('The question, with enough context that the owner can answer from their inbox'),
+});
+const finishRunParams = z.object({
+    summary: z
+        .string()
+        .min(1)
+        .max(10000)
+        .describe('What you did, found or delegated. Public: the requester, the owner and their teammates read it'),
+    readyToClose: z
+        .boolean()
+        .describe('true when the work is done and the owner only needs to confirm; false when follow-up is needed'),
+});
+function schema(params) {
+    const { $schema: _ignored, ...rest } = zodToJsonSchema(params, {
+        target: 'jsonSchema7',
+        $refStrategy: 'none',
+    });
+    return rest;
+}
+export const RUN_TOOLS = [
+    {
+        name: 'report_progress',
+        description: 'Post a one-line progress note to this run\'s transcript (owner-visible only; nobody is notified). Use it when you move to a new phase of the work.',
+        inputSchema: schema(reportProgressParams),
+    },
+    {
+        name: 'ask_owner',
+        description: 'Ask your owner a question you cannot answer yourself and PAUSE this run. The question is posted on the action mentioning the owner; their reply resumes the work in a new run. This must be your LAST call: do not call finish_run after it and do not keep working — stop immediately.',
+        inputSchema: schema(askOwnerParams),
+    },
+    {
+        name: 'finish_run',
+        description: 'Finish this run. Call it exactly once, as your last action, with a public summary and whether the action is ready for the owner to close. Never mark the action complete yourself; the owner confirms from their inbox.',
+        inputSchema: schema(finishRunParams),
+    },
+];
+export const RUN_TOOL_NAMES = new Set(RUN_TOOLS.map((t) => t.name));
+/** Dispatch one run tool. The caller has already checked `RUN_TOOL_NAMES.has(name)`. */
+export async function runRunTool(client, context, name, args) {
+    switch (name) {
+        case 'report_progress': {
+            const { text } = reportProgressParams.parse(args ?? {});
+            return { ok: true, text };
+        }
+        case 'ask_owner': {
+            const { question } = askOwnerParams.parse(args ?? {});
+            const result = await client.agentRuns.finish(context.runId, { status: 'WAITING_ON_OWNER', question }, context.runnerId);
+            return {
+                ...result,
+                stop: true,
+                message: result.finished
+                    ? 'Your question was posted and the run is now waiting on your owner. Stop here: make no further tool calls and end your turn.'
+                    : 'The run is no longer running (it was cancelled); nothing was posted. Stop here.',
+            };
+        }
+        case 'finish_run': {
+            const { summary, readyToClose } = finishRunParams.parse(args ?? {});
+            const result = await client.agentRuns.finish(context.runId, { status: 'SUCCEEDED', summary, readyToClose }, context.runnerId);
+            return { ...result, message: result.finished ? 'Run finished. End your turn.' : 'The run had already ended; nothing changed. End your turn.' };
+        }
+        default:
+            throw new Error(`Unknown run tool "${name}"`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exponential-mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "MCP server for Exponential - connect Claude to your projects, actions, goals, CRM, tickets and more",
   "main": "dist/index.js",
   "bin": {
@@ -26,7 +26,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^12.0.0",
-    "exponential-sdk": "^1.20.1",
+    "exponential-sdk": "^1.21.0",
     "zod": "^3.22.0",
     "zod-to-json-schema": "^3.25.2"
   },