TickTick MCP Server

Instructions

Implementation Reference

• src/index.ts:39-51 (registration)

  Registration of the 'get_tasks' tool in the ListTools response, including name, description, and input schema definition.

  {
    name: 'get_tasks',
    description: 'Get all tasks or tasks from a specific project',
    inputSchema: {
      type: 'object',
      properties: {
        projectId: {
          type: 'string',
          description: 'Optional project ID to filter tasks',
        },
      },
    },
  },

• src/index.ts:225-234 (handler)

  Handler for the 'get_tasks' tool in the CallToolRequestSchema switch statement. It calls TickTickClient.getTasks and returns the tasks as JSON text content.

  case 'get_tasks':
    const tasks = await this.ticktickClient!.getTasks(args?.projectId as string);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(tasks, null, 2),
        },
      ],
    };

• src/ticktick-client.ts:170-223 (helper)

  Main helper function implementing the task retrieval logic from TickTick API, handling both project-specific and all tasks, with inbox handling and error management.

  async getTasks(projectId?: string): Promise<TickTickTask[]> {
    await this.ensureAuthenticated();
    
    try {
      if (projectId) {
        // Get tasks from a specific project using project data endpoint
        const response = await this.client.get(`/project/${projectId}/data`);
        const tasks = response.data?.tasks || [];
        return tasks.map((task: TickTickTask) => enhanceTaskForDisplay(task));
      } else {
        // Get all tasks by getting all projects and their tasks
        const projects = await this.getProjects();
        const allTasks: TickTickTask[] = [];
        
        for (const project of projects) {
          try {
            // Some special handling may be needed for inbox project
            const projectResponse = await this.client.get(`/project/${project.id}/data`);
            const projectTasks = projectResponse.data?.tasks || [];
            allTasks.push(...projectTasks);
          } catch (error) {
            // Skip projects that can't be accessed, but log more details
            console.warn(`Could not access tasks for project ${project.id} (${project.name}):`, error);
          }
        }
        
        // Also try to get inbox tasks specifically if inbox wasn't included
        try {
          const inboxResponse = await this.client.get('/project/inbox/data');
          const inboxTasks = inboxResponse.data?.tasks || [];
          allTasks.push(...inboxTasks);
        } catch (error) {
          // Inbox might not be accessible this way, try alternative
          try {
            const inboxResponse = await this.client.get('/task?projectId=inbox');
            const inboxTasks = inboxResponse.data || [];
            allTasks.push(...inboxTasks);
          } catch (inboxError) {
            console.warn('Could not access inbox tasks:', inboxError);
          }
        }
        
        return allTasks.map(task => enhanceTaskForDisplay(task));
      }
    } catch (error) {
      // Log more detailed error information
      if (error instanceof Error && 'response' in error) {
        const axiosError = error as any;
        const errorData = axiosError.response?.data ? JSON.stringify(axiosError.response.data) : axiosError.message;
        throw new Error(`Failed to get tasks: ${axiosError.response?.status} ${axiosError.response?.statusText} - ${errorData}`);
      }
      throw new Error(`Failed to get tasks: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• src/ticktick-client.ts:5-33 (helper)

  Helper utility function used by getTasks to enhance task objects with human-readable priority text.

  function enhanceTaskForDisplay(task: TickTickTask): any {
    const enhanced = { ...task };
    
    // Add human-readable priority
    let priorityText = 'None';
    switch (task.priority) {
      case 0:
        priorityText = 'None';
        break;
      case 1:
        priorityText = 'Low';
        break;
      case 3:
        priorityText = 'Medium';
        break;
      case 5:
        priorityText = 'High';
        break;
      default:
        priorityText = task.priority ? `Custom (${task.priority})` : 'None';
    }
    
    return {
      ...enhanced,
      priorityText,
      // Keep original dates for display - they should show correctly
      dueDate: task.dueDate
    };
  }