Carbon Voice

Instructions

Implementation Reference

• src/server.ts:584-612 (handler)

  The MCP tool registration includes the inline handler function for 'get_root_folders'. The handler takes args and authInfo, calls simplifiedApi.getAllRootFolders with authentication header, formats the response, and handles errors.

  server.registerTool(
    'get_root_folders',
    {
      description:
        'Lists all root folders for a given workspace, including their names, IDs, and basic structure, ' +
        'but does not provide aggregate counts.(Required to inform message type:voicememo,prerecorded)',
      inputSchema: getAllRootFoldersQueryParams.shape,
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
      },
    },
    async (
      args: GetAllRootFoldersParams,
      { authInfo },
    ): Promise<McpToolResponse> => {
      try {
        return formatToMCPToolResponse(
          await simplifiedApi.getAllRootFolders(
            args,
            setCarbonVoiceAuthHeader(authInfo?.token),
          ),
        );
      } catch (error) {
        logger.error('Error listing root folders:', { error });
        return formatToMCPToolResponse(error);
      }
    },
  );

• src/generated/carbon-voice-api/CarbonVoiceSimplifiedAPI.zod.ts:977-983 (schema)

  Zod schema definition for input parameters to getAllRootFolders, used as inputSchema in the tool registration. Defines required 'type' and optional fields for filtering and sorting root folders.

  export const getAllRootFoldersQueryParams = zod.object({
    "type": zod.enum(['voicememo', 'prerecorded']).describe('Folder Type'),
    "include_all_tree": zod.boolean().optional().describe('Return all folders tree'),
    "workspace_id": zod.string().optional().describe('Workspace ID'),
    "sort_direction": zod.enum(['ASC', 'DESC']).default(getAllRootFoldersQuerySortDirectionDefault).describe('Sort order direction'),
    "sort_by": zod.enum(['created_at', 'last_updated_at', 'name']).default(getAllRootFoldersQuerySortByDefault).describe('Field to sort by')
  })

• src/generated/carbon-voice-api.ts:519-527 (helper)

  Generated API helper function that performs the HTTP GET request to '/simplified/folders' with query params to fetch root folders, called by the MCP tool handler.

  const getAllRootFolders = (
    params: GetAllRootFoldersParams,
    options?: SecondParameter<typeof mutator>,
  ) => {
    return mutator<ListFoldersResponse>(
      { url: `/simplified/folders`, method: 'GET', params },
      options,
    );
  };

• src/generated/models/GetAllRootFoldersParams.ts:83-104 (schema)

  TypeScript type definition for GetAllRootFoldersParams, used in the handler signature and API function.

  export type GetAllRootFoldersParams = {
    /**
     * Folder Type
     */
    type: GetAllRootFoldersType;
    /**
     * Return all folders tree
     */
    include_all_tree?: boolean;
    /**
     * Workspace ID
     */
    workspace_id?: string;
    /**
     * Sort order direction
     */
    sort_direction?: GetAllRootFoldersSortDirection;
    /**
     * Field to sort by
     */
    sort_by?: GetAllRootFoldersSortBy;
  };