exponential-mcp 0.6.0 → 0.8.0

package/dist/domains/tickets.js

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import { id, op } from './framework.js';
+const TICKET_STATUSES = [
+    'BACKLOG',
+    'NEEDS_REFINEMENT',
+    'READY_TO_PLAN',
+    'COMMITTED',
+    'IN_PROGRESS',
+    'BLOCKED',
+    'QA',
+    'DONE',
+    'DEPLOYED',
+    'ARCHIVED',
+];
+const TICKET_TYPES = ['BUG', 'FEATURE', 'CHORE', 'IMPROVEMENT', 'SPIKE', 'RESEARCH'];
+const ticketId = z.string().describe('Ticket ID (the CUID, not the shortId or number — find it with `search`)');
+const url = (what) => z.string().url().max(500).describe(`${what} URL`);
+const clearable = (schema, what) => schema.nullable().optional().describe(`${what} (null to clear)`);
+export const tickets = {
+    name: 'tickets',
+    description: 'Tickets: the unit of work in a product backlog, with blocking dependencies and linked actions. Always product-scoped (see `products`); they can point at a feature (`features`), scope (`scopes`), epic (`epics`) and cycle. Ticket comments are in the `comments` tool and labels in `labels`.',
+    operations: {
+        list: op({
+            summary: 'List every ticket in one product with full fields (body included), optionally filtered. No workspace-wide query — call once per product. prUrl/branchName are exact-match filters applied after the fetch.',
+            params: z.object({
+                productId: id('Product'),
+                status: z.enum(TICKET_STATUSES).optional(),
+                type: z.enum(TICKET_TYPES).optional(),
+                featureId: id('Feature').optional(),
+                epicId: id('Epic').optional(),
+                cycleId: id('Cycle').optional(),
+                assigneeId: id('User').optional(),
+                prUrl: z.string().optional().describe('Exact match on the ticket’s PR URL'),
+                branchName: z.string().optional().describe('Exact match on the ticket’s branch name'),
+            }),
+            run: (client, params) => client.tickets.list(params),
+        }),
+        get: op({
+            summary: 'Get one ticket in full: body, product, dependencies (dependsOn / requiredFor), linked actions and comments (newest first).',
+            params: z.object({ id: ticketId }),
+            run: (client, { id }) => client.tickets.get(id),
+        }),
+        create: op({
+            summary: 'Create a ticket in a product. Number and shortId are assigned server-side.',
+            params: z.object({
+                productId: id('Product'),
+                title: z.string().min(1).max(300),
+                body: z.string().optional().describe('Markdown body. Omit with templateId to start from the template’s body'),
+                type: z.enum(TICKET_TYPES).optional(),
+                status: z.enum(TICKET_STATUSES).optional(),
+                priority: z.number().int().min(0).max(4).optional().describe('0–4; lower is higher priority'),
+                points: z.number().optional(),
+                branchName: z.string().optional(),
+                prUrl: url('Pull request').optional(),
+                designUrl: url('Design').optional(),
+                specUrl: url('Spec').optional(),
+                links: z.record(z.string()).optional().describe('Extra named links, label → URL'),
+                epicId: id('Epic').optional(),
+                featureId: id('Feature').optional(),
+                cycleId: id('Cycle').optional(),
+                scopeId: id('Feature scope').optional(),
+                assigneeId: id('User').optional().describe('User ID; must be a member of the product’s workspace'),
+                templateId: id('Ticket template').optional(),
+            }),
+            run: (client, params) => client.tickets.create(params),
+        }),
+        update: op({
+            summary: 'Update a ticket. Only the fields you pass change.',
+            params: z.object({
+                id: ticketId,
+                title: z.string().min(1).max(300).optional(),
+                body: z.string().optional().describe('Markdown body; replaces the whole body'),
+                type: z.enum(TICKET_TYPES).optional(),
+                status: z.enum(TICKET_STATUSES).optional(),
+                priority: clearable(z.number().int().min(0).max(4), 'Priority 0–4, lower is higher'),
+                points: clearable(z.number(), 'Story points'),
+                branchName: clearable(z.string(), 'Branch name'),
+                prUrl: clearable(z.string().url().max(500), 'Pull request URL'),
+                designUrl: clearable(z.string().url().max(500), 'Design URL'),
+                specUrl: clearable(z.string().url().max(500), 'Spec URL'),
+                links: clearable(z.record(z.string()), 'Named links, label → URL; replaces the whole map'),
+                epicId: clearable(z.string(), 'Epic ID'),
+                featureId: clearable(z.string(), 'Feature ID'),
+                cycleId: clearable(z.string(), 'Cycle ID'),
+                scopeId: clearable(z.string(), 'Feature scope ID'),
+                assigneeId: clearable(z.string(), 'Assignee user ID'),
+            }),
+            run: (client, params) => client.tickets.update(params),
+        }),
+        delete: op({
+            summary: 'Delete a ticket permanently, with its comments and dependency edges. Linked actions are kept but unlinked.',
+            params: z.object({ id: ticketId }),
+            run: (client, { id }) => client.tickets.delete(id),
+        }),
+        search: op({
+            summary: 'Quick picker search within one product: matches title, shortId or ticket number and returns slim rows (id, number, shortId, title, status, priority, assignee), most recently updated first. Use `list` for full tickets or field filters.',
+            params: z.object({
+                productId: id('Product'),
+                query: z.string().max(200).optional().describe('Title substring, shortId, or a bare ticket number'),
+                excludeTicketId: id('Ticket to leave out of the results').optional(),
+                limit: z.number().int().min(1).max(50).optional().describe('Default 20'),
+            }),
+            run: (client, params) => client.tickets.search(params),
+        }),
+        add_dependency: op({
+            summary: 'Mark ticketId as blocked by dependsOnId. Both must be in the same product; rejects self-dependencies and cycles. Idempotent.',
+            params: z.object({
+                ticketId: id('Blocked ticket'),
+                dependsOnId: id('Blocking ticket'),
+            }),
+            run: (client, { ticketId, dependsOnId }) => client.tickets.addDependency(ticketId, dependsOnId),
+        }),
+        remove_dependency: op({
+            summary: 'Remove a "ticketId is blocked by dependsOnId" edge. Succeeds even if no such edge exists.',
+            params: z.object({
+                ticketId: id('Blocked ticket'),
+                dependsOnId: id('Blocking ticket'),
+            }),
+            run: (client, { ticketId, dependsOnId }) => client.tickets.removeDependency(ticketId, dependsOnId),
+        }),
+        link_action: op({
+            summary: 'Attach one of your own actions to a ticket (an action belongs to at most one ticket, so this moves it if already linked).',
+            params: z.object({
+                ticketId: id('Ticket'),
+                actionId: id('Action'),
+            }),
+            run: (client, { ticketId, actionId }) => client.tickets.linkAction(ticketId, actionId),
+        }),
+        unlink_action: op({
+            summary: 'Detach one of your own actions from whatever ticket it is linked to.',
+            params: z.object({ actionId: id('Action') }),
+            run: (client, { actionId }) => client.tickets.unlinkAction(actionId),
+        }),
+    },
+};

package/dist/domains/time.d.ts

@@ -0,0 +1,2 @@
+import { type Domain } from './framework.js';
+export declare const time: Domain;

package/dist/domains/time.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { date, id, op } from './framework.js';
+const TIME_ENTRY_STATUSES = ['PROPOSED', 'CONFIRMED'];
+const WRITABLE_SOURCES = ['manual', 'claude-desktop', 'agent-run'];
+const day = z
+    .string()
+    .describe("Calendar day as YYYY-MM-DD (or an ISO timestamp); resolved to local midnight in the MCP server's timezone");
+const optionalWorkspaceId = z
+    .string()
+    .optional()
+    .describe('Workspace ID (see the `workspaces` tool); omit for all workspaces');
+const entryFields = {
+    actionId: id('Action'),
+    startedAt: date('Start'),
+    endedAt: date('End (must be after startedAt)'),
+    source: z
+        .enum(WRITABLE_SOURCES)
+        .optional()
+        .describe('Defaults to manual. claude-desktop = Daily worklog proposed time; agent-run = unattended agent time'),
+    status: z
+        .enum(TIME_ENTRY_STATUSES)
+        .optional()
+        .describe('Defaults to CONFIRMED for a human; ignored (always PROPOSED) under an agent key'),
+    sourceRef: z
+        .string()
+        .optional()
+        .describe('Idempotency key, e.g. `claude-session:<sessionId>#<segmentIndex>`; makes the write an upsert'),
+    note: z.string().max(1000).optional().describe('One line shown in the day view'),
+};
+const partialEntry = z.object(entryFields).partial();
+export const time = {
+    name: 'time',
+    description: 'Time entries logged against actions (the Daily worklog write path). An entry always belongs to the person whose time it was: under an agent key it is owned by the agent’s owner and forced to PROPOSED until they confirm the day. Actions live in the `actions` tool.',
+    operations: {
+        log: op({
+            summary: 'Log one completed entry with explicit bounds; never touches the running Timer. With sourceRef it upserts per owner (updates a PROPOSED entry, leaves a CONFIRMED one); without, every call creates a row. Outcome: created / updated / left / merged / dropped.',
+            params: z.object(entryFields),
+            run: (client, params) => client.time.log(params),
+        }),
+        log_batch: op({
+            summary: 'Log many entries in order, one call each; a failure is reported per entry ({ index, success, error }) instead of failing the batch. `defaults` fill fields an entry omits.',
+            params: z.object({
+                entries: z.array(partialEntry).describe('Entries; each needs actionId, startedAt, endedAt after defaults apply'),
+                defaults: partialEntry.optional(),
+            }),
+            run: (client, { entries, defaults }) => client.time.logBatch(entries, defaults),
+        }),
+        confirm_day: op({
+            summary: 'Flip every PROPOSED entry of yours starting on that day to CONFIRMED, moving the actions’ spent time. Human only — agent keys are FORBIDDEN. Returns { confirmed }.',
+            params: z.object({ date: day, workspaceId: optionalWorkspaceId }),
+            run: (client, { date, workspaceId }) => client.time.confirmDay(date, workspaceId),
+        }),
+        day_report: op({
+            summary: 'One day’s time as the /time Day tab shows it: entries joined to action/ticket/project/product, attention vs session vs agent-run minutes, per-product and per-action roll-ups. Under an agent key it is the owner’s day.',
+            params: z.object({ date: day, workspaceId: optionalWorkspaceId }),
+            run: (client, { date, workspaceId }) => client.time.dayReport(date, workspaceId),
+        }),
+        list: op({
+            summary: 'Your raw time entries touching one day, oldest first, each with its status.',
+            params: z.object({ date: day, workspaceId: optionalWorkspaceId }),
+            run: (client, { date, workspaceId }) => client.time.list(date, workspaceId),
+        }),
+    },
+};

package/dist/domains/workspaces.d.ts

@@ -0,0 +1,2 @@
+import { type Domain } from './framework.js';
+export declare const workspaces: Domain;

package/dist/domains/workspaces.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { op, workspaceId } from './framework.js';
+export const workspaces = {
+    name: 'workspaces',
+    description: 'Workspaces the user belongs to, and their members. Most other tools take a workspaceId from here; use list_members to resolve people for mentions and assignment.',
+    operations: {
+        list: op({
+            summary: 'List the workspaces you belong to.',
+            params: z.object({}),
+            run: (client) => client.workspaces.list(),
+        }),
+        list_members: op({
+            summary: 'Everyone in a workspace — direct members plus those with access via a linked team. Each row carries `mentionSyntax` to paste into a comment body.',
+            params: z.object({ workspaceId }),
+            run: (client, { workspaceId }) => client.workspaces.listMembers(workspaceId),
+        }),
+    },
+};

package/dist/index.js

@@ -11,6 +11,8 @@ import { readFileSync, existsSync } from 'fs';
 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;
@@ -72,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.
@@ -568,13 +576,32 @@ 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,
+        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);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
             switch (name) {
                 case 'get_projects': {
                     const projects = await client.projects.list({
@@ -877,7 +904,7 @@ async function main() {
                     };
                 }
                 case 'search': {
-                    const results = await trpcClient.search.global.query({
+                    const results = await client.search.global({
                         query: args?.query,
                         workspaceId: args?.workspaceId,
                         limit: args?.limit,

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,7 +1,7 @@
 {
   "name": "exponential-mcp",
-  "version": "0.6.0",
-  "description": "MCP server for Exponential - connect Claude to your projects, actions, and goals",
+  "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": {
     "exponential-mcp": "./dist/cli.js"
@@ -26,8 +26,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^12.0.0",
-    "exponential-sdk": "^1.16.0",
-    "zod": "^3.22.0"
+    "exponential-sdk": "^1.21.0",
+    "zod": "^3.22.0",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",