addTaskManager MCP Server

Instructions

Implementation Reference

• src/index.ts:1705-1776 (handler)

  MCP tool handler: Fetches and formats tasks due today in Do realm (realmId=3). Uses CloudKitService in production or mock data in dev. Handles response formatting with context, priority.

  private async getTasksTodayInDo() {
    return this.withCloudKitOrMock(
      'getTasksTodayInDo',
      async () => {
        // CloudKit production implementation
        const todaysTasks = await this.cloudKitService.getTasksInDoToday();
        
        let response = `Today's items in Do realm (due: ${new Date().toLocaleDateString()}):\n`;
        if (todaysTasks.length === 0) {
          response += 'No tasks scheduled for today in Do realm! 🎉 Time to move some ready items from Decide realm?';
        } else {
          response += todaysTasks.map((task: any) => {
            const name = task.fields?.taskName?.value || 'Unnamed Task';
            const contextRecordName = task.fields?.context?.value?.recordName;
            const contextName = contextRecordName?.replace('context_', '') || 'No context';
            const priority = task.fields?.taskPriority?.value || 3;
            const priorityIcon = priority === 1 ? '🔴 High' : priority === 2 ? '🟡 Medium' : '🟢 Low';
            
            return `- ${name} (${task.recordName}) - ${contextName} - ${priorityIcon}`;
          }).join('\n');
        }
        
        return { content: [{ type: 'text', text: response }] };
      },
      async () => {
        // Mock implementation
        const today = new Date();
        const todayStr = today.toISOString().split('T')[0];
        
        const mockTasks = [
          { 
            recordName: 'task_today_1', 
            taskName: 'Morning standup meeting', 
            realmId: 3, 
            endDate: todayStr,
            contextRecordName: 'context_work',
            priority: 1,
            timeEstimate: '30 minutes'
          },
          { 
            recordName: 'task_today_2', 
            taskName: 'Pick up groceries', 
            realmId: 3, 
            endDate: todayStr,
            contextRecordName: 'context_errands',
            priority: 2,
            timeEstimate: '45 minutes'
          },
          { 
            recordName: 'project_today_1', 
            projectName: 'Review quarterly goals', 
            realmId: 3, 
            endDate: todayStr,
            contextRecordName: 'context_work',
            priority: 1,
            timeEstimate: '2 hours'
          }
        ];
        
        let response = `Today's items in Do realm (due: ${today.toLocaleDateString()}):\n`;
        response += mockTasks.map(item => {
          const type = item.recordName.startsWith('task_') ? 'Task' : 'Project';
          const name = item.taskName || (item as any).projectName;
          const contextName = item.contextRecordName?.replace('context_', '') || 'No context';
          const priority = item.priority === 1 ? '🔴 High' : item.priority === 2 ? '🟡 Medium' : '🟢 Low';
          return `- ${name} (${item.recordName}) - ${contextName} - ${priority} - ~${item.timeEstimate}`;
        }).join('\n');
        
        return { content: [{ type: 'text', text: response }] };
      }
    );
  }

• src/services/CloudKitService.ts:342-355 (helper)

  Core production implementation: CloudKit query for Tasks in Do realm (realmId=3) with endDate between start/end of today, sorted by priority.

  async getTasksInDoToday(): Promise<ZenTaskticTask[]> {
    const today = new Date();
    const startOfDay = new Date(today.setHours(0, 0, 0, 0)).getTime();
    const endOfDay = new Date(today.setHours(23, 59, 59, 999)).getTime();
    
    return this.queryRecords<ZenTaskticTask>('Task', {
      filterBy: [
        { fieldName: 'realmId', fieldValue: 3, comparator: 'EQUALS' },
        { fieldName: 'endDate', fieldValue: startOfDay, comparator: 'GREATER_THAN_OR_EQUALS' },
        { fieldName: 'endDate', fieldValue: endOfDay, comparator: 'LESS_THAN_OR_EQUALS' }
      ],
      sortBy: [{ fieldName: 'taskPriority', ascending: true }] // High priority first
    });
  }

• src/index.ts:619-622 (registration)

  Tool registration and schema in MCP ListTools handler: defines name, description, empty input schema.

    name: 'get_tasks_today_in_do',
    description: 'Find tasks due today in Do realm.',
    inputSchema: { type: 'object', properties: {} }
  },

• src/index.ts:768-769 (handler)

  Dispatch in MCP CallToolRequestSchema switch statement: routes tool call to handler method.

  case 'get_tasks_today_in_do':
    return await this.getTasksTodayInDo();

• src/services/CloudKitService.ts:121-165 (helper)

  Generic helper: Performs CloudKit database query with filterBy, sortBy, handles errors and pagination.

  async queryRecords<T>(recordType: string, options?: QueryOptions): Promise<T[]> {
    this.ensureAuthenticated();
  
    const query: any = {
      recordType,
      resultsLimit: options?.resultsLimit || 200,
      desiredKeys: options?.desiredKeys
    };
  
    // Add filters
    if (options?.filterBy && options.filterBy.length > 0) {
      query.filterBy = options.filterBy.map(filter => ({
        fieldName: filter.fieldName,
        fieldValue: { value: filter.fieldValue },
        comparator: filter.comparator || 'EQUALS'
      }));
    }
  
    // Add sorting
    if (options?.sortBy && options.sortBy.length > 0) {
      query.sortBy = options.sortBy.map(sort => ({
        fieldName: sort.fieldName,
        ascending: sort.ascending
      }));
    }
  
    // Add zone ID if specified
    if (options?.zoneID) {
      query.zoneID = options.zoneID;
    }
  
    try {
      const response: CloudKitResponse<T> = await this.database.performQuery(query);
      
      if (response.hasErrors) {
        const error = response.errors?.[0];
        throw new Error(`CloudKit query failed: ${error?.reason} (${error?.serverErrorCode})`);
      }
  
      return response.records || [];
    } catch (error) {
      console.error('CloudKit query error:', error);
      throw error;
    }
  }