todoist-mcp

Instructions

Implementation Reference

• src/utils/handlers.ts:92-145 (handler)

  Core handler logic for API tools like get_sections_list: builds path from template, validates params, calls todoistApi.get('/sections', {project_id}) and returns result

  const handler = async (args: z.infer<z.ZodObject<T>>): Promise<R> => {
      let finalPath = options.path;
      const pathParams: Record<string, string> = {};
  
      // Extract path parameters (e.g., {id}) and replace them with actual values
      const pathParamRegex = /{([^}]+)}/g;
      let match;
  
      while ((match = pathParamRegex.exec(options.path)) !== null) {
          const fullMatch = match[0]; // e.g., "{id}"
          const paramName = match[1]; // e.g., "id"
  
          if (args[paramName] === undefined) {
              throw new Error(`Path parameter ${paramName} is required but not provided`);
          }
  
          // Validate and encode path parameter using the centralized security function
          const safeParamValue = validatePathParameter(args[paramName], paramName);
          finalPath = finalPath.replace(fullMatch, safeParamValue);
          pathParams[paramName] = String(args[paramName]);
      }
  
      // Collect non-path parameters for query string or request body
      const otherParams = Object.entries(args).reduce(
          (acc, [key, value]) => {
              if (value !== undefined && !pathParams[key]) {
                  acc[key] = value;
              }
              return acc;
          },
          {} as Record<string, any>
      );
  
      // Apply custom parameter transformation if provided
      const finalParams = options.transformParams ? options.transformParams(args) : otherParams;
  
      // Execute the API request based on HTTP method
      let result;
      switch (options.method) {
          case 'GET':
              result = await todoistApi.get(finalPath, finalParams);
              break;
          case 'POST':
              log('POST', finalPath, finalParams);
              result = await todoistApi.post(finalPath, finalParams);
              break;
          case 'DELETE':
              result = await todoistApi.delete(finalPath);
              break;
      }
  
      // Apply result post-processing if provided
      return options.processResult ? options.processResult(result, args) : result;
  };

• src/tools/sections.ts:4-12 (registration)

  Registers the 'get_sections_list' tool with MCP server via createApiHandler, specifying name, description, input schema, HTTP method GET, and Todoist API path /sections

  createApiHandler({
      name: 'get_sections_list',
      description: 'Get sections list from Todoist',
      schemaShape: {
          project_id: z.string().optional(),
      },
      method: 'GET',
      path: '/sections',
  });

• src/tools/sections.ts:7-9 (schema)

  Zod schema for tool input: optional project_id string to filter sections by project

  schemaShape: {
      project_id: z.string().optional(),
  },

• src/utils/TodoistClient.ts:51-74 (helper)

  TodoistClient.get method that performs the actual HTTP GET request to https://api.todoist.com/rest/v2/sections?project_id=...

  async get(endpoint: string, params: Record<string, string> = {}): Promise<any> {
      let url = `${API_BASE_URL}${endpoint}`;
  
      const queryParams = new URLSearchParams();
      for (const [key, value] of Object.entries(params)) {
          if (value) {
              queryParams.append(key, value);
          }
      }
  
      const queryString = queryParams.toString();
      if (queryString) {
          url += `?${queryString}`;
      }
  
      log(`Making GET request to: ${url}`);
  
      const response = await fetch(url, {
          method: 'GET',
          headers: this.getHeaders(),
      });
  
      return this.handleResponse(response);
  }