motion_comments

Instructions

Implementation Reference

• src/handlers/CommentHandler.ts:1-74 (handler)

  Main handler for motion_comments tool. Implements two operations: 'list' (retrieves comments with pagination) and 'create' (creates new comments with content sanitization and validation). Extends BaseHandler and uses MotionService for API calls.

  import { BaseHandler } from './base/BaseHandler';
  import { McpToolResponse } from '../types/mcp';
  import { MotionCommentsArgs } from '../types/mcp-tool-args';
  import { CreateCommentData } from '../types/motion';
  import { formatCommentList, formatCommentDetail, LIMITS } from '../utils';
  import { sanitizeCommentContent } from '../utils/sanitize';
  
  export class CommentHandler extends BaseHandler {
    async handle(args: MotionCommentsArgs): Promise<McpToolResponse> {
      try {
        const { operation, taskId, content, cursor } = args;
  
        switch(operation) {
          case 'list':
            return await this.handleList(taskId, cursor);
          case 'create':
            return await this.handleCreate(taskId, content);
          default:
            return this.handleUnknownOperation(operation);
        }
      } catch (error: unknown) {
        return this.handleError(error);
      }
    }
  
    private async handleList(taskId?: string, cursor?: string): Promise<McpToolResponse> {
      if (!taskId) {
        return this.handleError(new Error('taskId is required for list operation'));
      }
  
      const commentsResponse = await this.motionService.getComments(taskId, cursor);
      const commentsResult = formatCommentList(commentsResponse.data);
  
      // Add pagination info if there's more data
      if (commentsResponse.meta.nextCursor && commentsResult.content[0]) {
        const firstContent = commentsResult.content[0];
        if ('text' in firstContent && typeof firstContent.text === 'string') {
          firstContent.text += `\n\n📄 More comments available. Use cursor: ${commentsResponse.meta.nextCursor}`;
        }
      }
  
      return commentsResult;
    }
  
    private async handleCreate(taskId?: string, content?: string): Promise<McpToolResponse> {
      if (!taskId) {
        return this.handleError(new Error('taskId is required for create operation'));
      }
      if (!content) {
        return this.handleError(new Error('content is required for create operation'));
      }
  
      // Reject oversized content before sanitization so the check is never dead code
      if (content.length > LIMITS.COMMENT_MAX_LENGTH) {
        return this.handleError(new Error(`Comment content exceeds maximum length of ${LIMITS.COMMENT_MAX_LENGTH} characters`));
      }
  
      // Sanitize and validate comment content
      const sanitizationResult = sanitizeCommentContent(content);
      if (!sanitizationResult.isValid) {
        return this.handleError(new Error(sanitizationResult.error || 'Invalid comment content'));
      }
  
      const sanitizedContent = sanitizationResult.sanitized;
  
      const commentData: CreateCommentData = {
        taskId,
        content: sanitizedContent
      };
  
      const newComment = await this.motionService.createComment(commentData);
      return formatCommentDetail(newComment);
    }
  }

• src/tools/ToolDefinitions.ts:261-287 (registration)

  Tool definition for motion_comments. Defines the tool name, description, and input schema with properties: operation (enum: list/create), taskId (required), content (for create), and cursor (for pagination).

  export const commentsToolDefinition: McpToolDefinition = {
    name: TOOL_NAMES.COMMENTS,
    description: "Manage comments on tasks",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["list", "create"],
          description: "Operation to perform"
        },
        taskId: {
          type: "string",
          description: "Task ID to comment on or fetch comments from (required)"
        },
        content: {
          type: "string",
          description: "Comment content (required for create operation)"
        },
        cursor: {
          type: "string",
          description: "Pagination cursor for list operation (optional)"
        }
      },
      required: ["operation", "taskId"]
    }
  };

• src/handlers/HandlerFactory.ts:27-38 (registration)

  Registers CommentHandler with the TOOL_NAMES.COMMENTS key ('motion_comments') in the handler factory, mapping the tool name to its handler class.

  private registerHandlers(): void {
    this.handlers.set(TOOL_NAMES.TASKS, TaskHandler);
    this.handlers.set(TOOL_NAMES.PROJECTS, ProjectHandler);
    this.handlers.set(TOOL_NAMES.WORKSPACES, WorkspaceHandler);
    this.handlers.set(TOOL_NAMES.USERS, UserHandler);
    this.handlers.set(TOOL_NAMES.SEARCH, SearchHandler);
    this.handlers.set(TOOL_NAMES.COMMENTS, CommentHandler);
    this.handlers.set(TOOL_NAMES.CUSTOM_FIELDS, CustomFieldHandler);
    this.handlers.set(TOOL_NAMES.RECURRING_TASKS, RecurringTaskHandler);
    this.handlers.set(TOOL_NAMES.SCHEDULES, ScheduleHandler);
    this.handlers.set(TOOL_NAMES.STATUSES, StatusHandler);
  }

• src/types/mcp-tool-args.ts:71-78 (schema)

  TypeScript interface for MotionCommentsArgs defining the operation type ('list' | 'create'), required taskId string, optional content string, and optional cursor for pagination.

  export type CommentsOperation = 'list' | 'create';
  
  export interface MotionCommentsArgs {
    operation: CommentsOperation;
    taskId: string;
    content?: string;
    cursor?: string;
  }

• src/utils/responseFormatters.ts:293-335 (helper)

  Helper functions for formatting comment responses: formatCommentList formats multiple comments with truncation and display limits, formatCommentDetail formats single comment creation responses with metadata.

  export function formatCommentList(comments: MotionComment[]): CallToolResult {
    if (comments.length === 0) {
      return formatMcpSuccess("No comments found.");
    }
    
    const commentFormatter = (comment: MotionComment) => {
      const location = `Task ${comment.taskId}`;
      const timestamp = comment.createdAt;
      const author = comment.creator.name || comment.creator.email || comment.creator.id;
      // Truncate long comments for display
      const displayContent = comment.content.length > LIMITS.COMMENT_DISPLAY_LENGTH 
        ? comment.content.substring(0, LIMITS.COMMENT_DISPLAY_LENGTH) + '...'
        : comment.content;
      // Keep as single line for proper list formatting
      return `- [${comment.id}] ${location} | Author: ${author} | ${timestamp} | "${displayContent}"`;
    };
    
    return formatListResponse(
      comments, 
      `Found ${comments.length} comment${comments.length === 1 ? '' : 's'}`,
      commentFormatter
    );
  }
  
  /**
   * Format single comment response  
   */
  export function formatCommentDetail(comment: MotionComment): CallToolResult {
    const location = `Task ${comment.taskId}`;
    const timestamp = comment.createdAt;
    const author = comment.creator.name || comment.creator.email || comment.creator.id;
    
    const details = [
      `Comment created successfully:`,
      `- ID: ${comment.id}`,
      `- Location: ${location}`,
      `- Author: ${author}`,
      `- Created: ${timestamp}`,
      `- Content: "${comment.content}"`
    ].join('\n');
    
    return formatMcpSuccess(details);
  }