@critical-path/mcp 0.11.6 → 0.11.8

package/src/tools/definitions.ts

@@ -1,472 +0,0 @@
-import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
-import type { CriticalPathEngine } from '@critical-path/core';
-import type { CriticalPathClient } from '@critical-path/client';
-
-export type BackendContext = CriticalPathEngine | CriticalPathClient;
-
-export interface ToolDefinition<TParams = any, TResult = any> {
-  name: string;
-  title: string;
-  description: string;
-  zodSchema: z.ZodObject<any>;
-  /** JSON Schema shown to MCP clients. Generated from `zodSchema` by `defineTool`. */
-  inputSchema: Record<string, unknown>;
-  annotations?: {
-    readOnlyHint?: boolean;
-    requiresConfirmation?: boolean;
-  };
-  execute: (args: TParams, target: BackendContext, ambientContext?: { projectId?: string }) => Promise<TResult>;
-}
-
-/**
- * Declares a tool, generating its JSON Schema `inputSchema` from `zodSchema` so the schema the
- * model sees and the one arguments are validated against cannot drift apart.
- */
-export function defineTool<TParams = any, TResult = any>(
-  spec: Omit<ToolDefinition<TParams, TResult>, 'inputSchema'>
-): ToolDefinition<TParams, TResult> {
-  const { $schema: _schema, ...inputSchema } = zodToJsonSchema(spec.zodSchema, { $refStrategy: 'none' }) as Record<string, unknown>;
-  return { ...spec, inputSchema };
-}
-
-export class ToolArgumentError extends Error {
-  constructor(toolName: string, details: string) {
-    super(`Invalid arguments for tool "${toolName}": ${details}`);
-    this.name = 'ToolArgumentError';
-  }
-}
-
-/**
- * Validates raw tool arguments against the tool's zod schema. Unknown keys are rejected,
- * so callers cannot pass fields the tool does not declare.
- */
-export function parseToolArgs<TParams>(tool: ToolDefinition<TParams>, args: unknown): TParams {
-  // Strict: unknown arguments are reported to the model instead of being silently dropped.
-  const result = tool.zodSchema.strict().safeParse(args ?? {});
-  if (!result.success) {
-    const details = result.error.issues
-      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
-      .join('; ');
-    throw new ToolArgumentError(tool.name, details);
-  }
-  return result.data as TParams;
-}
-
-// Helper to normalize calling engine vs client
-export async function resolveBackend(target: BackendContext) {
-  const isEngine = 'store' in target && typeof (target as any).store === 'object';
-  return { isEngine };
-}
-
-export const listProjectsTool = defineTool({
-  name: 'list_projects',
-  title: 'List Projects',
-  description: 'Retrieve all projects in the workspace.',
-  zodSchema: z.object({}),
-  annotations: { readOnlyHint: true },
-  execute: async (_args, target) => {
-    return target.getProjects();
-  }
-});
-
-export const getProjectTool = defineTool<{ id: string }>({
-  name: 'get_project',
-  title: 'Get Project',
-  description: 'Get details of a specific project by its ID.',
-  zodSchema: z.object({
-    id: z.string().describe('The project ID')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target) => {
-    return target.getProject(args.id);
-  }
-});
-
-export const createProjectTool = defineTool<{ name: string; description?: string; key?: string }>({
-  name: 'create_project',
-  title: 'Create Project',
-  description: 'Create a new project workspace.',
-  zodSchema: z.object({
-    name: z.string().describe('Name of the project'),
-    description: z.string().optional().describe('Description of the project'),
-    key: z.string().optional().describe('Short project key/prefix (e.g. "PROJ")')
-  }),
-  execute: async (args, target) => {
-    return target.createProject(args);
-  }
-});
-
-export const listTasksTool = defineTool<{
-  projectId?: string;
-  status?: string;
-  priority?: string;
-  assigneeId?: string;
-  iterationId?: string;
-  limit?: number;
-  cursor?: string;
-}>({
-  name: 'list_tasks',
-  title: 'List Tasks',
-  description:
-    'List tasks (oldest first), optionally filtered by project, status, priority, assignee or iteration. Returns { tasks, nextCursor }; pass nextCursor back as cursor to get the next page.',
-  zodSchema: z.object({
-    projectId: z.string().optional().describe('Filter by project ID'),
-    status: z.string().optional().describe('Filter by task status key'),
-    priority: z.enum(['urgent', 'high', 'medium', 'low', 'none']).optional().describe('Filter by priority'),
-    assigneeId: z.string().optional().describe('Filter by assignee ID'),
-    iterationId: z.string().optional().describe('Filter by iteration (sprint) ID'),
-    limit: z.number().int().min(1).max(500).optional().describe('Page size (default 100)'),
-    cursor: z.string().optional().describe('nextCursor from a previous call')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target, ambientContext) => {
-    const page = await target.queryTasks({
-      projectId: args.projectId || ambientContext?.projectId,
-      status: args.status ? [args.status] : undefined,
-      priority: args.priority ? [args.priority] : undefined,
-      assigneeId: args.assigneeId,
-      iterationId: args.iterationId,
-      limit: args.limit,
-      cursor: args.cursor
-    });
-    return { tasks: page.items, nextCursor: page.nextCursor };
-  }
-});
-
-export const getTaskTool = defineTool<{ id: string }>({
-  name: 'get_task',
-  title: 'Get Task',
-  description: 'Get task details by ID.',
-  zodSchema: z.object({
-    id: z.string().describe('The task ID')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target) => {
-    return target.getTask(args.id);
-  }
-});
-
-export const createTaskTool = defineTool<{
-  projectId?: string;
-  title: string;
-  description?: string;
-  status?: string;
-  priority?: 'urgent' | 'high' | 'medium' | 'low' | 'none';
-  assigneeId?: string;
-  dueDate?: string;
-  tags?: string[];
-  estimatedHours?: number;
-  isBlocked?: boolean;
-  blockedReason?: string;
-}>({
-  name: 'create_task',
-  title: 'Create Task',
-  description: 'Create a new task within a project.',
-  zodSchema: z.object({
-    projectId: z.string().optional().describe('Project ID (inferred from active view in browser if omitted)'),
-    title: z.string().describe('Title of the task'),
-    description: z.string().optional().describe('Detailed description / markdown'),
-    status: z.string().optional().describe('Status (defaults to "todo" or first workflow status)'),
-    priority: z.enum(['urgent', 'high', 'medium', 'low', 'none']).optional().default('none').describe('Task priority'),
-    assigneeId: z.string().optional().describe('User ID to assign task to'),
-    dueDate: z.string().optional().describe('Due date (ISO string)'),
-    tags: z.array(z.string()).optional().describe('Tags for categorization'),
-    estimatedHours: z.number().optional().describe('Estimated hours to complete'),
-    isBlocked: z.boolean().optional().describe('Whether the task is blocked'),
-    blockedReason: z.string().optional().describe('Reason why the task is blocked')
-  }),
-  execute: async (args, target, ambientContext) => {
-    const projectId = args.projectId || ambientContext?.projectId;
-    if (!projectId) {
-      throw new Error('projectId is required to create a task, but none was provided or active in context.');
-    }
-    const input: any = {
-      projectId,
-      title: args.title,
-      description: args.description,
-      status: args.status || 'todo',
-      priority: args.priority || 'none',
-      assigneeId: args.assigneeId,
-      dueDate: args.dueDate,
-      tags: args.tags || [],
-      estimatedHours: args.estimatedHours,
-      isBlocked: args.isBlocked,
-      blockedReason: args.blockedReason
-    };
-    return target.createTask(input);
-  }
-});
-
-export const updateTaskTool = defineTool<{
-  id: string;
-  title?: string;
-  description?: string;
-  status?: string;
-  priority?: 'urgent' | 'high' | 'medium' | 'low' | 'none';
-  assigneeId?: string;
-  dueDate?: string;
-  tags?: string[];
-  estimatedHours?: number;
-  loggedHours?: number;
-  isBlocked?: boolean;
-  blockedReason?: string;
-}>({
-  name: 'update_task',
-  title: 'Update Task',
-  description: 'Update fields of an existing task (e.g. title, status, priority, assignee).',
-  zodSchema: z.object({
-    id: z.string().describe('The task ID'),
-    title: z.string().optional(),
-    description: z.string().optional(),
-    status: z.string().optional(),
-    priority: z.enum(['urgent', 'high', 'medium', 'low', 'none']).optional(),
-    assigneeId: z.string().optional(),
-    dueDate: z.string().optional(),
-    tags: z.array(z.string()).optional(),
-    estimatedHours: z.number().optional(),
-    loggedHours: z.number().optional(),
-    isBlocked: z.boolean().optional().describe('Whether the task is blocked'),
-    blockedReason: z.string().optional().describe('Reason why the task is blocked')
-  }),
-  execute: async (args, target) => {
-    const { id, ...updates } = args;
-    return target.updateTask(id, updates);
-  }
-});
-
-export const deleteTaskTool = defineTool<{ id: string }>({
-  name: 'delete_task',
-  title: 'Delete Task',
-  description: 'Delete a task by ID.',
-  zodSchema: z.object({
-    id: z.string().describe('The task ID to delete')
-  }),
-  annotations: { requiresConfirmation: true },
-  execute: async (args, target) => {
-    const success = await target.deleteTask(args.id);
-    return { success };
-  }
-});
-
-export const listDeliverablesTool = defineTool<{ projectId?: string }>({
-  name: 'list_deliverables',
-  title: 'List Deliverables',
-  description: 'List deliverables/milestones for a project.',
-  zodSchema: z.object({
-    projectId: z.string().optional().describe('Project ID')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target, ambientContext) => {
-    const projectId = args.projectId || ambientContext?.projectId;
-    if (!projectId) throw new Error('projectId is required to list deliverables.');
-    if ('getDeliverables' in target && typeof (target as any).getDeliverables === 'function') {
-      return (target as any).getDeliverables(projectId);
-    }
-    return [];
-  }
-});
-
-export const createDeliverableTool = defineTool<{
-  projectId?: string;
-  title: string;
-  description?: string;
-  dueDate?: string;
-  taskIds?: string[];
-}>({
-  name: 'create_deliverable',
-  title: 'Create Deliverable',
-  description: 'Create a milestone deliverable within a project.',
-  zodSchema: z.object({
-    projectId: z.string().optional(),
-    title: z.string(),
-    description: z.string().optional(),
-    dueDate: z.string().optional(),
-    taskIds: z.array(z.string()).optional()
-  }),
-  execute: async (args, target, ambientContext) => {
-    const projectId = args.projectId || ambientContext?.projectId;
-    if (!projectId) throw new Error('projectId is required to create a deliverable.');
-    if ('createDeliverable' in target && typeof (target as any).createDeliverable === 'function') {
-      return (target as any).createDeliverable({
-        ...args,
-        projectId
-      });
-    }
-    throw new Error('createDeliverable is not supported by this backend target.');
-  }
-});
-
-export const listCommentsTool = defineTool<{ taskId: string }>({
-  name: 'list_comments',
-  title: 'List Comments',
-  description: 'List comments associated with a task.',
-  zodSchema: z.object({
-    taskId: z.string().describe('The task ID')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target) => {
-    if ('getComments' in target && typeof (target as any).getComments === 'function') {
-      return (target as any).getComments(args.taskId);
-    }
-    return [];
-  }
-});
-
-export const addCommentTool = defineTool<{ taskId: string; content: string }>({
-  name: 'add_comment',
-  title: 'Add Comment',
-  description: 'Add a comment to a task. The comment is attributed to the identity this MCP server runs as.',
-  zodSchema: z.object({
-    taskId: z.string().describe('The task ID'),
-    content: z.string().describe('Comment body/markdown')
-  }),
-  execute: async (args, target) => {
-    return target.addComment({ taskId: args.taskId, content: args.content });
-  }
-});
-
-export const calculateCriticalPathTool = defineTool<{ projectId?: string }>({
-  name: 'calculate_critical_path',
-  title: 'Calculate Critical Path',
-  description: 'Calculate Critical Path Method (CPM) schedule, early/late start and finish, total slack, and critical bottlenecks for a project.',
-  zodSchema: z.object({
-    projectId: z.string().optional().describe('Project ID (falls back to ambient context if omitted)')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target, ambientContext) => {
-    const projectId = args.projectId || ambientContext?.projectId;
-    if (!projectId) {
-      throw new Error('projectId is required to calculate critical path.');
-    }
-    return (target as any).calculateCriticalPath(projectId);
-  }
-});
-
-export const getTimelineLadderTool = defineTool<{
-  projectId?: string;
-  level?: 'macro' | 'standard' | 'concrete' | 'all';
-  containerId?: string;
-  iterationId?: string;
-}>({
-  name: 'get_timeline_ladder',
-  title: 'Get Timeline Ladder of Abstraction',
-  description: 'Retrieve Ladder of Abstraction for a project timeline across macro phase envelopes, standard Gantt tasks & CPM, and concrete deliverables/time/attachments.',
-  zodSchema: z.object({
-    projectId: z.string().optional().describe('Project ID (falls back to ambient context if omitted)'),
-    level: z.enum(['macro', 'standard', 'concrete', 'all']).optional().describe('Abstraction level (macro, standard, concrete, or all)'),
-    containerId: z.string().optional().describe('Optional container ID filter'),
-    iterationId: z.string().optional().describe('Optional iteration/sprint ID filter')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target, ambientContext) => {
-    const projectId = args.projectId || ambientContext?.projectId;
-    if (!projectId) {
-      throw new Error('projectId is required to get timeline ladder.');
-    }
-    return (target as any).getTimelineLadder(projectId, {
-      level: args.level,
-      containerId: args.containerId,
-      iterationId: args.iterationId
-    });
-  }
-});
-
-export const getTaskLadderTool = defineTool<{ taskId: string }>({
-  name: 'get_task_ladder',
-  title: 'Get Task Ladder View',
-  description: 'Retrieve multi-scale ladder view for a single task, connecting its macro phase, standard CPM timeline position, and concrete work evidence.',
-  zodSchema: z.object({
-    taskId: z.string().describe('The task ID')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target) => {
-    return (target as any).getTaskLadder(args.taskId);
-  }
-});
-
-export const getTaskMetricsTool = defineTool<{ taskId: string }>({
-  name: 'get_task_metrics',
-  title: 'Get Task Metrics',
-  description: 'Retrieve multi-dimensional task metrics including inferred actuals, active working duration, effort/duration/schedule variances, progress inference, and Earned Value Management (EVM) metrics.',
-  zodSchema: z.object({
-    taskId: z.string().describe('The task ID')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target) => {
-    return (target as any).getTaskMetrics(args.taskId);
-  }
-});
-
-export const getTaskProgressHistoryTool = defineTool<{ taskId: string }>({
-  name: 'get_task_progress_history',
-  title: 'Get Task Progress History',
-  description: 'Retrieve time-series progress data points and curve shape classification (linear, s_curve, early_surge, late_rush, stalled) for a task.',
-  zodSchema: z.object({
-    taskId: z.string().describe('The task ID')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target) => {
-    return (target as any).getTaskProgressHistory(args.taskId);
-  }
-});
-
-export const getWorkloadDistributionTool = defineTool<{
-  projectId?: string;
-  startDate?: string;
-  endDate?: string;
-  interval?: 'day' | 'week' | 'month';
-  groupBy?: 'assignee' | 'team' | 'taskType' | 'priority' | 'status';
-  metric?: 'scheduled' | 'logged' | 'remaining' | 'blended';
-  defaultWeeklyCapacityHours?: number;
-}>({
-  name: 'get_workload_distribution',
-  title: 'Get Workload Distribution',
-  description: 'Retrieve time-series workload and capacity distribution suitable for streamgraphs, stacked charts, and team capacity planning.',
-  zodSchema: z.object({
-    projectId: z.string().optional().describe('Project ID (optional, defaults to workspace-wide or ambient project)'),
-    startDate: z.string().optional().describe('Start date ISO (YYYY-MM-DD)'),
-    endDate: z.string().optional().describe('End date ISO (YYYY-MM-DD)'),
-    interval: z.enum(['day', 'week', 'month']).optional().describe('Bucket interval (day, week, month)'),
-    groupBy: z.enum(['assignee', 'team', 'taskType', 'priority', 'status']).optional().describe('Dimension to segment by'),
-    metric: z.enum(['scheduled', 'logged', 'remaining', 'blended']).optional().describe('Effort metric mode'),
-    defaultWeeklyCapacityHours: z.number().optional().describe('Default weekly capacity hours per person (default 40)')
-  }),
-  annotations: { readOnlyHint: true },
-  execute: async (args, target, ambientContext) => {
-    const projectId = args.projectId || ambientContext?.projectId;
-    return (target as any).getWorkloadDistribution(projectId, {
-      startDate: args.startDate,
-      endDate: args.endDate,
-      interval: args.interval,
-      groupBy: args.groupBy,
-      metric: args.metric,
-      defaultWeeklyCapacityHours: args.defaultWeeklyCapacityHours
-    });
-  }
-});
-
-export const ALL_TOOLS: ToolDefinition[] = [
-  listProjectsTool,
-  getProjectTool,
-  createProjectTool,
-  listTasksTool,
-  getTaskTool,
-  createTaskTool,
-  updateTaskTool,
-  deleteTaskTool,
-  listDeliverablesTool,
-  createDeliverableTool,
-  listCommentsTool,
-  addCommentTool,
-  calculateCriticalPathTool,
-  getTimelineLadderTool,
-  getTaskLadderTool,
-  getTaskMetricsTool,
-  getTaskProgressHistoryTool,
-  getWorkloadDistributionTool
-];
-
-export const TOOL_MAP = new Map<string, ToolDefinition>(
-  ALL_TOOLS.map((tool) => [tool.name, tool])
-);

package/src/web/index.ts

@@ -1,162 +0,0 @@
-import type { CriticalPathClient } from '@critical-path/client';
-import { ALL_TOOLS, parseToolArgs, type ToolDefinition } from '../tools/definitions.js';
-
-export interface WebMcpToolRegistration {
-  name: string;
-  title?: string;
-  description: string;
-  inputSchema: Record<string, unknown>;
-  annotations?: {
-    readOnlyHint?: boolean;
-  };
-  execute: (input: any) => Promise<any>;
-}
-
-export interface ModelContextInterface {
-  registerTool: (tool: WebMcpToolRegistration, options?: { signal?: AbortSignal }) => Promise<void> | void;
-  unregisterTool?: (toolName: string) => void;
-  getTools?: () => Promise<WebMcpToolRegistration[]> | WebMcpToolRegistration[];
-  executeTool?: (name: string, input?: any) => Promise<any>;
-}
-
-export interface RegisterWebMcpOptions {
-  client: CriticalPathClient;
-  projectId?: string;
-  tools?: string[];
-  signal?: AbortSignal;
-  document?: any;
-  navigator?: any;
-  window?: any;
-  onToolExecuted?: (toolName: string, input: any, result: any) => void;
-}
-
-export interface WebMcpRegistryHandle {
-  unregister: () => void;
-  getRegisteredTools: () => WebMcpToolRegistration[];
-}
-
-/**
- * Polyfill/shim a minimal ModelContextInterface onto the document/window if not natively present.
- */
-export function ensureModelContextShim(doc: any = typeof document !== 'undefined' ? document : null): ModelContextInterface | null {
-  if (!doc) return null;
-
-  if (!doc.modelContext) {
-    const registeredTools = new Map<string, WebMcpToolRegistration>();
-
-    const shim: ModelContextInterface = {
-      registerTool(tool, options) {
-        registeredTools.set(tool.name, tool);
-        if (options?.signal) {
-          options.signal.addEventListener('abort', () => {
-            registeredTools.delete(tool.name);
-          }, { once: true });
-        }
-      },
-      unregisterTool(toolName) {
-        registeredTools.delete(toolName);
-      },
-      async getTools() {
-        return Array.from(registeredTools.values());
-      },
-      async executeTool(name, input) {
-        const tool = registeredTools.get(name);
-        if (!tool) {
-          throw new Error(`Tool "${name}" is not registered on modelContext.`);
-        }
-        return tool.execute(input || {});
-      }
-    };
-
-    doc.modelContext = shim;
-  }
-
-  return doc.modelContext;
-}
-
-/**
- * Registers Critical Path tools with the browser's WebMCP modelContext.
- */
-export function registerWebMcpTools(options: RegisterWebMcpOptions): WebMcpRegistryHandle {
-  const doc = options.document ?? (typeof document !== 'undefined' ? document : null);
-  const nav = options.navigator ?? (typeof navigator !== 'undefined' ? navigator : null);
-  const win = options.window ?? (typeof window !== 'undefined' ? window : null);
-
-  // Target modelContext: document.modelContext (W3C standard draft) -> navigator.modelContext -> document shim
-  let modelContext: ModelContextInterface | undefined;
-  if (doc?.modelContext) {
-    modelContext = doc.modelContext;
-  } else if (nav?.modelContext) {
-    modelContext = nav.modelContext;
-  } else if (doc) {
-    modelContext = ensureModelContextShim(doc) ?? undefined;
-  }
-
-  const selectedTools: ToolDefinition[] = options.tools
-    ? ALL_TOOLS.filter((t) => options.tools!.includes(t.name))
-    : ALL_TOOLS;
-
-  const registeredTools: WebMcpToolRegistration[] = [];
-  const abortController = new AbortController();
-
-  // Combine caller signal with our internal abort controller
-  if (options.signal) {
-    options.signal.addEventListener('abort', () => abortController.abort(), { once: true });
-  }
-
-  for (const toolDef of selectedTools) {
-    const webTool: WebMcpToolRegistration = {
-      name: toolDef.name,
-      title: toolDef.title,
-      description: toolDef.description,
-      inputSchema: toolDef.inputSchema,
-      annotations: toolDef.annotations,
-      execute: async (input: any) => {
-        const ambientContext = options.projectId ? { projectId: options.projectId } : undefined;
-        const result = await toolDef.execute(parseToolArgs(toolDef, input), options.client, ambientContext);
-        options.onToolExecuted?.(toolDef.name, input, result);
-        return result;
-      }
-    };
-
-    registeredTools.push(webTool);
-
-    if (modelContext?.registerTool) {
-      try {
-        modelContext.registerTool(webTool, { signal: abortController.signal });
-      } catch (err) {
-        console.warn(`[Critical Path WebMCP] Failed to register tool "${webTool.name}":`, err);
-      }
-    }
-  }
-
-  // Also publish to window fallback registry for browser extensions & DevTools
-  if (win) {
-    win.__CRITICAL_PATH_WEBMCP__ = {
-      projectId: options.projectId,
-      tools: registeredTools,
-      execute: async (name: string, input: any) => {
-        const tool = registeredTools.find((t) => t.name === name);
-        if (!tool) throw new Error(`WebMCP tool "${name}" not found in Critical Path registry.`);
-        return tool.execute(input);
-      }
-    };
-  }
-
-  const unregister = () => {
-    abortController.abort();
-    if (modelContext?.unregisterTool) {
-      for (const t of registeredTools) {
-        modelContext.unregisterTool(t.name);
-      }
-    }
-    if (win && win.__CRITICAL_PATH_WEBMCP__?.tools === registeredTools) {
-      delete win.__CRITICAL_PATH_WEBMCP__;
-    }
-  };
-
-  return {
-    unregister,
-    getRegisteredTools: () => registeredTools
-  };
-}

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"]
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/index.test.ts","./src/index.ts","./src/bin/args.test.ts","./src/bin/args.ts","./src/bin/cli.ts","./src/server/index.ts","./src/tools/definitions.test.ts","./src/tools/definitions.ts","./src/web/index.ts"],"version":"5.9.3"}