todoist-mcp

Instructions

Implementation Reference

• src/tools/labels.ts:80-86 (registration)

  Registration of the 'get_shared_labels' tool. It uses createApiHandler to register a tool that makes a GET request to the Todoist API endpoint '/labels/shared' with no input parameters.

  createApiHandler({
      name: 'get_shared_labels',
      description: 'Get all shared labels from Todoist',
      schemaShape: {},
      method: 'GET',
      path: '/labels/shared',
  });

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

  The core handler logic for the tool, instantiated by createApiHandler. For get_shared_labels, it resolves the path to '/labels/shared' (no path params), uses empty finalParams, executes todoistApi.get('/labels/shared', {}), and returns the result directly.

  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/labels.ts:83-83 (schema)

  Input schema for the tool: empty object, indicating no parameters are required.

  schemaShape: {},

• src/utils/handlers.ts:83-148 (helper)

  The createApiHandler factory function that generates and registers the tool handler based on the provided API endpoint configuration.

  export function createApiHandler<T extends z.ZodRawShape, R = any>(options: {
      name: string;
      description: string;
      schemaShape: T;
      method: HttpMethod;
      path: string;
      transformParams?: ParamTransformer<z.infer<z.ZodObject<T>>>;
      processResult?: ResultProcessor<z.infer<z.ZodObject<T>>, R>;
  }) {
      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;
      };
  
      return createHandler(options.name, options.description, options.schemaShape, handler);
  }