addTaskManager MCP Server

Instructions

Implementation Reference

• src/services/CloudKitService.ts:454-463 (handler)

  The core handler function implementing the tool logic: queries CloudKit Task records where contextRecordName equals the input parameter, sorts by endDate ascending, returns ZenTaskticTask[]

  async getTasksByContext(contextRecordName: string): Promise<ZenTaskticTask[]> {
    return this.queryRecords<ZenTaskticTask>('Task', {
      filterBy: [{ 
        fieldName: 'contextRecordName', 
        fieldValue: contextRecordName,
        comparator: 'EQUALS' 
      }],
      sortBy: [{ fieldName: 'endDate', ascending: true }]
    });
  }

• src/index.ts:1273-1303 (handler)

  MCP server wrapper handler for get_tasks_by_context tool: calls CloudKitService.getTasksByContext in production mode, formats results into MCP response, falls back to mock in dev

  private async getTasksByContext(contextRecordName: string) {
    return this.withCloudKitOrMock(
      'getTasksByContext',
      async () => {
        // CloudKit production implementation
        const tasks = await this.cloudKitService.getTasksByContext(contextRecordName);
        
        let response = `Tasks for context ${contextRecordName}:\n`;
        if (tasks.length === 0) {
          response += 'No tasks found for this context. 📋';
        } else {
          response += tasks.map((task: any) => {
            const name = task.fields?.taskName?.value || 'Unnamed Task';
            const realmId = task.fields?.realmId?.value || 1;
            const realmName = realmId === 1 ? 'Assess' : realmId === 2 ? 'Decide' : realmId === 3 ? 'Do' : 'Unknown';
            const priority = task.fields?.taskPriority?.value || 3;
            const priorityIcon = priority === 1 ? '🔴' : priority === 2 ? '🟡' : '🟢';
            
            return `- ${name} (${task.recordName}) [${realmName}] ${priorityIcon}`;
          }).join('\n');
        }
        
        return { content: [{ type: 'text', text: response }] };
      },
      async () => {
        // Mock implementation
        const mockTasks = [{ recordName: 'task_abc', taskName: 'Task with specific context' }];
        return { content: [{ type: 'text', text: `Found ${mockTasks.length} tasks for context ${contextRecordName}:\n${mockTasks.map(t => `- ${t.taskName} (${t.recordName})`).join('\n')}` }] };
      }
    );
  }

• src/index.ts:592-602 (schema)

  Input schema definition for the get_tasks_by_context tool in ListTools response

  {
    name: 'get_tasks_by_context',
    description: 'Filter by context.',
    inputSchema: {
      type: 'object',
      properties: {
        contextRecordName: { type: 'string', description: 'Record name of the context to filter by' }
      },
      required: ['contextRecordName']
    }
  },

• src/index.ts:760-762 (registration)

  Tool registration/dispatch in CallToolRequestSchema switch statement: validates args and delegates to getTasksByContext method

    this.validateArgs(args, ['contextRecordName']);
    return await this.getTasksByContext(args.contextRecordName);
  case 'get_stalled_items_in_decide':

• src/index.ts:73-108 (schema)

  Type/schema definition for ZenTaskticTask returned by the handler (also likely in src/types/cloudkit.ts)

  export interface ZenTaskticTask {
    recordName?: string; // CloudKit record name (UUID string, typically)
    recordType: 'Task';
    fields: {
      taskName: { value: string }; // Max 1000 chars, combines original title & body
      realmId: { value: number }; // 1 (Assess), 2 (Decide), 3 (Do)
      uniqueId: { value: string }; // UUID string, primary key in CoreData model
      
      // Core Data model fields
      taskId?: { value: number }; // Integer 16, default 0
      contextId?: { value: number }; // Integer 16, default 0 (legacy field)
      taskAudioRecordId?: { value: number }; // Integer 16, default 0
      taskPictureId?: { value: number }; // Integer 16, default 0
      orderInParent?: { value: number }; // Integer 16, default 0
      taskPriority?: { value: number }; // Integer 16, 1-5, default 3
      
      // References (relationships in Core Data)
      context?: { value: CKReference }; // Reference to a Contexts record
      projects?: { value: CKReference }; // Reference to a Projects record (renamed from project)
      collection?: { value: CKReference }; // Reference to a Collections record
      ideas?: { value: CKReference }; // Reference to an Ideas record (if task derived from idea)
      realms?: { value: CKReference }; // Reference to Realms record
      
      // Dates
      startDate?: { value: number }; // Timestamp (milliseconds since epoch)
      endDate?: { value: number }; // Timestamp (due date, or completion date)
      lastModified: { value: number }; // Timestamp
      
      // Task-specific fields
      localNotification?: { value: string }; // Alert date/trigger (max 100 chars)
      taskParentId?: { value: string }; // UUID string of parent Task/Project/Idea
      taskParentType?: { value: string }; // 'Task', 'Project', 'Idea'
      
      // removed isCompleted, completion handled by setting endDate & potentially realm
    };
  }